XalokNext Documentation

Appearance

HTML modules ​

Intro ​

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

For example:

html
<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:

    html
    <!-- 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

    html
    <!-- 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. 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-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 :

    html
    <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:

    html
    <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 roled 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.

    html
    <!-- 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>

  • wf-tab and wf-tab-detail

    html
    <div class="tabs">
    <div class="titles">
        <p wf-module="wfed/body_text/inline"
            wf-use-placeholder="true"
            wf-tab
            >Tab</p>
    </div>
    <div class="body">
        <div wf-module="wfed/composite/page"
            wf-tab-detail
            >
            <div wf-module="wfed/body_text/block"
                wf-role="title"
                >
        </div>
    </div>
</div>

    For each module with wf-tab that is added in the .tabs .titles selector, it creates a different .tabs .body selector where you can add modules to be displayed on that tab

  • 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.

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

Options for wfed/body_text modules ​

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

    html
    <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:

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

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

    html
    <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

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

Useful for modules with settings only.

  • 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/image modules ​

  • wf-filter: the avalanche filter (widthxheight) of this image. The value of this option must be configured in app/config/misc/avalanche.yml

Options for wfed/collection modules ​

  • wf-content-type

    html
    <div wf-module="wfed/slider/simple"
     wf-new>
    <div class="slider-pane">
        <div wf-module="wfed/composite/module"
             wf-toolbar-position="none"
             wf-content-type="image"
                >
            <div class="image">
                <div wf-module="wfed/image/simple"
                     wf-filter="article_related_item"
                        ></div>
            </div>
            <div class="caption">
                <p wf-module="wfed/body_text/block"></p>
            </div>
        </div>
    </div>
</div>

    Allowed (builtin) values: image, video, audio, page, poll, file, listing There's also the special "type" none - for sliders where the edit button should be hidden and the slides' contents should be edited manually (e.g.: a slider where each slide should have multiple boxes/articles) Add wf-content-type to the slide's definition. This adds the "edit" button on the toolbar of the slider, allowing the editor to select multiple wf-content-type - when the editor presses "OK", a slide for each wf-content-type is created and added to the slider.

  • wf-slider-options-> value should be a hash

  • wf-max-items -> value should be an string number

  • wf-submodule-add -> value should be true/false; default is true

  • wf-submodule-delete-> value should be true/false; default is true

    html
    <div wf-module="wfed/slider/simple"
     wf-slider-options='{"perPage": "5", "slideSize": "1"}'
     wf-max-items="10"
     wf-submodule-add="false"
     wf-submodule-add="true"
     wf-new>
    <div class="slider-pane">
         ...
    </div>
</div>

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/composite/page module ​

  • wf-allow-edit: Setting to show or hide the button to select an article. By default it is true - the button is shown
<div wf-module="wfed/composite/page"
     wf-allow-edit="false"
>...</div>

Options for wfed/body_text/published_at module ​

  • wf-format: Setting to set the format in witch the date/time is displayed. Parsed with momentjs. Escaped strings should be enclosed in square brackets: [escaped string]
<div wf-module="wfed/body_text/published_at"
     wf-format="[Latest published at:] HH:mm"
></div>

Options for wfed/image/picture module ​

Adds a picture tag that includes, besides the default <img> tag, <source> tags for different resolutions. The wf-filter option can define multiple avalanche filters, separated by |. The filter name can also include the max-width, used for media query:

<picture wf-module="wfed/image/picture"
         wf-filter="desktop|mobile:320|tablet:728">
</picture>

This outputs:

<picture>
  <source srcset="/files/mobile/image.jpg" media="max-width: 320px" />
  <source srcset="/files/tablet/image.jpg" media="max-width: 320px" />
  <img src="/files/desktop/image.jpg" />
</picture>