Marfeel Docs

# Extensibility

Two techniques are available to extend the markup of MarfeelUI Components. Shadowing for completely replacing the theme's default, or inserting template parts for adding content.

# Shadowing

All MarfeelUI components can be shadowed to be customized. Following the concept introduced by Gatsby (opens new window), when using a Marfeel theme, it is possible to customize the markup of any given template.

Marfeel templates are written in JSP, to be compiled on server-side.

For example, to customize the badge appearing on Premium articles, you need to:

  1. Identify the path of the template in MarfeelTenant. Here, marfeel/themes/default/articleDetailPremiumBadge.jsp
  2. Create a file in the tenant's repository using the same path. Here, example.com/themes/default/articleDetailPremiumBadge.jsp

This is enough to shadow the component.

WARNING

By shadowing top-level MarfeelUI Components, you lose backward compatibility. Shadowing should be kept for minor templates. To customize complex templates' markup, you can inject theme parts.

# Injecting theme parts

To customize the markup of major MarfeelUI Components such as the footer, Marfeel templates import theme parts, which by default are empty. It is up to each Tenant to choose what content to inject if any.

For example in the default theme's mosaicFooter.jsp, two extension points are open:

<jsp:attribute name="topExtras">
    <div class="mrf-customFooter__topExtras">
        <dali:importThemePart url="customFooter__topExtras.jsp"/>
    </div>
</jsp:attribute>

and

<jsp:attribute name="extra">
    <div class="mrf-customFooter__extras">
        <dali:importThemePart url="customFooter__extras.jsp"/>
    </div>
</jsp:attribute>

They are respectively inserted at the very top and the very bottom of the footer.

# File resolution

When extending a theme or a layout, if there is no JSP or JSON file defined for the requested theme and section, a fallback is performed from a more specific to more general path to find the best suitable file.

For example, if we request the following JSON layout:

themes/mediaBlog/layoutsDescriptor/comida.json
        │                           │
        theme                       section

The following paths are searched until it finds an existing file:

  1. themes/mediaBlog/layoutsDescriptor/comida.json
  2. themes/mediaBlog/layoutsDescriptor/default.json
  3. themes/default/layoutsDescriptor/comida.json
  4. themes/default/layoutsDescriptor/default.json

Marfeel themes provide empty templates (empty JSP files), which exist only for shadowing. Before shadowing a template containing logic, look for those.

For example, the footer has 2 open extension points, inserted respectively at the top and bottom of the footer:

  • marfeel/themes/default/customFooter__topExtras.jsp
  • marfeel/themes/default/customFooter__extras.jsp

To insert content on all mosaic pages, you can use:

  • marfeel/themes/default/mosaicTopBox.jsp

← layoutDescriptor.json →