HTML modules

Intro

Starting with v2.1.0 you can define and configure the modules available in a template using HTML markup.

For example:

<p wf-module="wfed/body_text/page_epigraph"></p>

Important:

• the modules should always be in their own container, without mixing them with "static" HTML. For example:

  <!-- BAD -->
  <div>
      <p wf-module="wfed/body_text/page_epigraph"></p>
      <div class="static-html">HTML Content that is not a module</div>
  </div>
  
  <!-- GOOD -->
  <div>
      <div class="modules">
          <p wf-module="wfed/body_text/page_epigraph"></p>
      </div>
      <div class="static-html">HTML Content that is not a module</div>
  </div>

• The modules' container should always have a unique (in the current document) class associated

  <!-- BAD because the container doesn't have any class -->
  <div>
      <p wf-module="wfed/body_text/page_epigraph"></p>
  </div>
  
  <!-- BAD because there are two containers with the same class -->
  <div class="text">
      <p wf-module="wfed/body_text/page_epigraph"></p>
  </div>
  <div class="text">
      <p wf-module="wfed/body_text/page_epigraph"></p>
  </div>
  
  <!--
  GOOD - the CMS uses the unique class,
  even though the containers share the "text" class
  -->
  <div class="text paragraphs-1">
      <p wf-module="wfed/body_text/page_epigraph"></p>
  </div>
  <div class="text paragraphs-2">
      <p wf-module="wfed/body_text/page_epigraph"></p>
  </div>

Available options, available to all modules:

• wf-role: Use in the article's template to determine the role of this module (required). The role can be any string. The following list of roles has a special meaning, as it is used throughout XalokNext:

  • title: the title
  • supra: the line above the title
  • epigraph: the introductory paragraph (short description)
  • author: the name of the author
  • categoryTitle: the section
  • signature: the field containing the signature (editor's name, agency)
  • location: the location (if available) where the news happened
  • image: the main image of the article. The image chosen in this module is used to auto-populate the image modules of page captioned modules when this article is selected in a board
  • image_captioned: use this instead of the image if the main image has a caption
  • paragraph: use this for the normal paragraph (body text)

• wf-toolbar-position: Controls the position of the toolbar with regard to the current module. Use one of top, left, right, bottom or none

• wf-toolbar-css-class: use <p wf-toolbar-css-class="sub"></p> to display a thinner toolbar than the default. This class is automatically added to submodules of a composite

• wf-toolbar-tooltips-position: When wf-group is used (switching modules) a tooltip is displayed if available. Put an image in __ADMIN_BUNDLE_/Resources/public/images/modules/__MODULE_ID__.png. The name of the file is converted by replacing the '/' with double underscore. E.g. admin/composite/video_image should have a thumbnail named admin__composite__video_image.png. Possible values: top, left, right, bottom or none. Default equals the value of wf-toolbar-position

• wf-collapse-switch: Always show the switch module as a popover. By default, XalokNext tries to fit on the module's toolbar as many switch module buttons as the toolbar's width allows, to allow switching to a different module with a single click. If there are any buttons that don't fit, a "more" button is added, showing a popover with the remaining buttons. Adding wf-collapse-switch option to a module means all the buttons will be displayed in the "more" popover, no matter how much space is available.

• wf-allow: Available values:

  • +-: allow both adding another module and deleting the current module
  • +: allow adding modules below this one but not deleting this module
  • -: allow deleting this module
  • (empty string): this module is "fixed", don't allow adding any other modules nor deleting this one.

  For example: in the article template, there should be only one title :

  <h1 wf-module="wfed/title/page_title" wf-allow="" />

• wf-new: This attribute's value is optional. If present, the current module will be added automatically when a new page with this template is created.

  For example, the page title module in the article template should always be present, add the wf-new module to it and set its wf-allow attribute to an empty string:

  <h1 wf-module="wfed/title/page_title" wf-allow="" wf-new />

  Optionally, you can specify a number as the value, if you want the same module repeated a few times:

  <p wf-module="wfed/body_text/paragraph" wf-new="3" />

• wf-serializable: Avaialble only for top level modules and only for text modules (for now, at least). This attribute adds the value of the module in the serialized content of the article, allowing to import this module's value in a board module.

  The default group where the value will be serialized is listing.

  <!-- in article's template -->
  <p wf-module="wfed/body_text/block"
      wf-role="special-flag-of-article"
      wf-serializable></p>
  
  <!-- in boards's template -->
  <div wf-module="wfed/composite/page">
      <div wf-module="wfed/body_text/block"
          wf-role="special-flag-of-article">
      </div>
  </div>

  The group can be changed by supplying a value wf-serializable="othergroup":

  <!-- in article's template -->
  <p wf-module="wfed/body_text/block"
      wf-role="special-flag-of-article"
      wf-serializable="othergroup"></p>

  Multiple groups can be added wf-serializable="group1, group2":

   <!-- in article's template -->
   <p wf-module="wfed/body_text/block"
       wf-role="special-flag-of-article"
       wf-serializable="group1, group2"></p>

  Assigning the list group to a module's wf-serializable would add the contents of the module (if available) to the search results used when embedding an article in a board.

  Also, there is a $page->getHTML($serializationGroup) that returns an array with the HTMLs of all the modules belonging to that serialization group.

• wf-required: make the given module required (the user must fill something for this module). Enter the error message that should appear as the value of the attribute.

  <p wf-module="wfed/body_text/block"
     wf-role="epigraph"
     wf-required="The epigraph is required"
     ></p>

• wf-not-sortable: don't include this module in the module sorting dialog

  Note: the behavior controlled by this attribute can now be controlled through the UI (only for ROLE_ADMIN users). To do so, create a file in the following path: __PROJECT__/src/__PROJECT_NAMESPACE__/Bundle/CmsAdminBundle/Resources/public/javascripts/sortable-config.json and make it writable by the web server. This file should be included in the repository to make sure changes made on PRE can be (easily) committed and deployed on PRO. To avoid merge conflicts, it's recommendable to only enable edition (make it writable by the user used to run the web server) on a single environment, PRE, for example.

  This attribute has two modes of operation:

  • no value remove the module and all of its children

    <p wf-module="wfed/body_text/block"
       wf-role="epigraph"
       wf-not-sortable
       ></p>

  • self remove only the current module, but raise its children one level in the sorting dialog:

    <div wf-module="wfed/composite/module"
         wf-role="related_composite">
        <div wf-module="wfed/composite/module"
             wf-role="related_collection"
             wf-not-sortable="self"
             >
            <p wf-module="wfed/body_text/block"
               wf-role="title"
               ></p>
         </div>
     </div>

    This would still allow sorting the individual elements ("title") but would trim one level from the sorting hierarchy. So, instead of having related_composite->related_collection->title1,title2 it would be related_composite->title1,title2

Options for text modules (wfed/body_text/title and wfed/body_text/module modules)

• wf-maxlength: Prevent the editor from entering more than maxlength characters. A char count is displayed on the toolbar, so make sure you display the toolbar if wf-maxlength or wf-soft-maxlength is set

• wf-soft-maxlength: Displays an warning when the editor exceeds entering this many characters, but allows them to continue.

Options for wfed/body_text/title module

• wf-break-on-cr: allow ENTER key (break the title in multiple lines). Default true, you can make it false wf-break-on-cr="false" or wf-break-on-cr="0"

Options for wfed/body_text/module module

• wf-formattings: controls what options are displayed to format the text.

  <p wf-formattings="b,i,u"></p>

  displays bold, italic and underline buttons

  Available formattings:

  • b: bold
  • u: underline
  • i: italic
  • ol: ordered list
  • ul: unordered list
  • a: link
  • s: strikethrough

  There are also some shorthands available:

  • short: bold, underline, italic, strikethrough, link
  • lists: ordered and unordered lists
  • extended: includes short + lists

  You can combine these options in any way you want:

  <p wf-formattings="b,i,lists"></p>

• wf-styles: Displays a dropdown on the list where editors can mark selected text with given classes

  <p wf-styles="red-text,blue-text"></p>

  displays a dropdown allowing the editors to add a <span class="red-text"></span> (or "blue-text") around the selection

• wf-use-placeholder: Displays the module even if no text has been changed in it

  <p wf-use-placeholder="true"></p>

Useful for modules with settings only.

• wf-break-on-cr: when it's set to true, pressing ENTER breaks the current module and adds a new one after it. Without this, there's also a CTRL+ENTER shortcut to do the same. Default false.

Options for wfed/dynamic/board module

• wf-slugs: Container for slug elements which have at value the slugs of the included boards

<div wf-module="wfed/dynamic/board">
    <wf-slugs>
        <slug value="x">X</slug>
        <slug value="y">Y</slug>
    </wf-slugs>
</div>

Options for wfed/dynamic/generic module

• wf-url: the url that should be rendered inside this module

<div wf-module="wfed/dynamic/generic"
     wf-role="sidebar"
     wf-url="{{ path('wf_sidebar', {id: "__id__"}) }}"
     wf-bind="urlParams:id|currentPage_id"
>
</div>