v4+Board groups

Intro

Board groups allow the editor to add and order a series of boards. To add a board group:

    {{ wf_cms_board_group('SLUG_OF_THE_BOARD_GROUP', [
        {
            template: 'board/breaking-news',
            title: 'Breaking news',
            type: 'homepage'
        },
        {
            template: 'board/homepage-opening',
            title: 'Homepage opening',
            type: 'homepage'
        }
    }}

wf_cms_board_group takes two arguments:

• SLUG_OF_THE_BOARD_GROUP is a unique identifier for the board group
• an array with the definitions of boards allowed in this group. Each definition should contain:
  • template: the path to the template file, relative to __CMS_BUNDLE__/Resources/views/Templates
  • title: the text to be shown in the list of possible boards to be added
  • type: can be one of board (generic), homepage or metatags. The metatags type is special since it uses a custom renderer to render the metatags in public. homepage is only saved in the database as page_type, but not used for other purposes.

When rendering a board group, a button will appear in the bottom right corner of the browser allowing the editor to add/order as many boards as they want using the defined templates.

Note: In development mode the board group automatically caps the number of boards to 3 to avoid high refresh times.

board_fixtures.yml

In app/config/cms/board_fixtures.yml contains definitions of boards that can be rendered in the CMS. Each of these definitions will correspond to a single entry in the database.

homepage:
    type: homepage
    boards:
        metatags:
            type: metatags
            title: Homepage metatags
            template: board/metatags
            slug: homepage-metatags
            preview: wf_homepage
        opening:
            title: Homepage opening
            template: board/homepage-opening
            slug: homepage-opening
            preview: wf_homepage

• type: can be one of board (generic), homepage or metatags. The metatags type is special since it uses a custom renderer to render the metatags in public. homepage is only saved in the database as page_type, but not used for other purposes.

  Note: In the example above, the type: homepage is inherited by default by the opening definition, as it doesn't define its own type

• title: the title that will be displayed in the admin when the board is not published

• template: the path to the template file, relative to __CMS_BUNDLE__/Resources/views/Templates

• slug: the slug of this board. Used to save the record in the database and to render it

To render these boards, use the wf_cms_render_page twig function:

{{ wf_cms_render_page('homepage-metatags') }}
{{ wf_cms_render_page('homepage-opening') }}

board_templates.yml

In app/config/cms/board_templates.yml contains definitions of templates of boards. Unlike board fixtures, a template definition can be used multiple times, to create multiple boards in the database using that template, for example one board for each category.

category:
    type: board
    boards:
        metatags:
            type: metatags
            title: %category.title% Metatags
            template: board/metatags
            slug: category-metatags
        main:
            title: %category.title% main articles
            template: board/category/main
            slug: category-main
tag:
    type: tag
    boards:
        metatags:
            type: metatags
            title: %tag.title% Metatags
            template: board/metatags
            slug: tag-metatags
        opening:
            title: %tag.title% details
            template: board/tag/tag_detail
            slug: opening
article:
    type: board
    boards:
        sidebar:
            title: %article.title% sidebar
            template: board/home/boardUrg
            slug: sidebar

The keys of the definition are the same as for board_fixtures.yml. The main difference here is for rendering.

{{ wf_cms_render_page(category.slug ~ '/category-metatags') }}
{{ wf_cms_render_page(category.slug ~ '/category-opening') }}

{{ wf_cms_render_page(tag.slug ~ '-tag-metatags') }}
{{ wf_cms_render_page(tag.slug ~ '-opening') }}

{{ wf_cms_render_page('article-' ~ article.id ~ '-sidebar') }}

Few important notes:

• only the category uses /__DEFINED_SLUG__, for tag it's -__DEFINED_SLUG__ (hyphen instead of slash).

• article uses article-__ID__ of the article instead of its slug - the slug of the article can already have the maximum length of the column, appending the slug from the template definition to it can exceed the maximum length of the column.

• both article and category use type: board

Using a single published board as a board template (v4)

The above board_templates.yml allows you to have an individual board published for each category/tag/article (we'll further refer to only category boards, but it applies for all the other types of board templates). This means that the editor must enter the admin for each category, edit its respective board and publish it. When the board includes an automated listing usually all boards for all categories are configured the same way. So the editor must edit the given board for each of the categories, apply the same settings and publish. This is a repetitive and error-prone task.

To avoid having to do this, you can use a single board saved to the database as a template for all others.

You can opt-in for individual boards by passing useTemplate: true:

{{ wf_cms_render_page(category.slug ~ "/category-secondary", {useTemplate: true}) }}

Or, you can opt-in globally, by setting wf_cms.board_templates.enabled parameter - and then it’ll apply for all board_templates.yml boards - except the ones where the developer is already handling “templating” (e.g. the case of category metatags), where wf_cms_render_page is called with an array of slugs.

When the template feature is enabled through either of the options above, trying to edit actualidad/category-secondary will give the editor the option to edit either actualidad/cateogry-secondary or category-secondary - this is the template. If they edit the template, all changes made to it will be available to all the categories unless the editor specifically overwrites the specific board (e.g.: they can overwrite deportes/category-secondary - for deportes category it'll use this, for all other categories it will use the template).

Using board inheritance

wf_cms_render_page accepts an array of slugs as its first argument. In this case, the first board that's published will be rendered on public. In admin a dropdown will be displayed to allow the editor to pick either of them for editing.

  {{ wf_cms_render_page(['mobile-board-slug', 'desktop-board-slug']); }}

Query passthrough

In case of not using AJAX for listings' pagination, or for search listings, the query variables coming from the top request would have to be passed through the board including that listing. The automated listing module would then pass through the query variables to the action that generates the contents of that listing. To do so:

{{ wf_cms_render_page('search-articles', { queryPassThrough: true} }}