.. include:: /Includes.rst.txt .. _migration-from-fluid-layouts: ==================== Layouts and partials ==================== Fluid's layout system — :fluid:``, :fluid:``, and :fluid:`` — is one of the first things developers look for when switching template engines. EXT:handlebars ships an equivalent mechanism implemented as the :handlebars:`extend`, :handlebars:`block`, and :handlebars:`content` helpers, modelled after the `handlebars-layouts `_ convention. .. contents:: :local: :depth: 1 .. _migration-from-fluid-layouts-concept: How the systems compare ======================= Fluid uses a **push** model: a child template declares which layout it inherits and then *pushes* named sections into the layout's named slots. Handlebars uses the same model, but the building blocks are ordinary helpers rather than dedicated language constructs. +------------------------------------------------+--------------------------------------------------------+ | Fluid | Handlebars | +================================================+========================================================+ | :fluid:`` | :handlebars:`{{#extend "default"}} … {{/extend}}` | +------------------------------------------------+--------------------------------------------------------+ | :fluid:`` (in layout) | :handlebars:`{{#block "main"}} … {{/block}}` | +------------------------------------------------+--------------------------------------------------------+ | :fluid:`` (in template) | :handlebars:`{{#content "main"}} … {{/content}}` | +------------------------------------------------+--------------------------------------------------------+ The :handlebars:`content` helper supports an optional :handlebars:`mode` hash argument (:handlebars:`replace` / :handlebars:`append` / :handlebars:`prepend`) that controls how the child's content is merged with the layout block's default. :handlebars:`replace` is the default and matches Fluid's behaviour. .. _migration-from-fluid-layouts-example: Side-by-side example ==================== **Layout file — Fluid**: .. code-block:: html :caption: EXT:my_extension/Resources/Private/Layouts/Default.html

**Layout file — Handlebars**: .. code-block:: handlebars :caption: EXT:my_extension/Resources/Private/Partials/default.hbs {{#block "head"}}{{/block}}

---- **Child template — Fluid**: .. code-block:: html :caption: EXT:my_extension/Resources/Private/Templates/MyElement.html {header}

{header}

{bodytext}

**Child template — Handlebars**: .. code-block:: handlebars :caption: EXT:my_extension/Resources/Private/Templates/my-element.hbs {{#extend "Main"}} {{#content "head"}} {{header}} {{/content}} {{#content "header"}}

{{/content}} {{/extend}} .. note:: Handlebars layouts are resolved as *partials*, so the layout file must be placed in one of the configured partial root paths, not in the template root paths. By convention, :file:`default.hbs` lives under :file:`Resources/Private/Partials/`. .. _migration-from-fluid-layouts-default-content: Default content in blocks ========================== A :handlebars:`{{#block}}` can hold default markup that is used verbatim when the child provides no matching :handlebars:`{{#content}}` for that slot. This is the equivalent of Fluid's :fluid:`optional="true"` on :fluid:`` combined with a fallback in the layout. .. code-block:: handlebars :caption: EXT:my_extension/Resources/Private/Partials/Main.hbs A child template that does not declare a :handlebars:`{{#content "footer"}}` block will render the default copyright line automatically. .. _migration-from-fluid-layouts-append-prepend: Appending and prepending content ================================= The :handlebars:`mode` argument lets a child *add* to a block rather than replace it. This has no direct Fluid equivalent and is often used for accumulating :html:`