Table of Contents

Extending Master Templates in Swift

DynamicWeb’s CMS, in conjunction with Swift, operates on a hierarchical structure of websites, pages, rows, and paragraphs. Each of these elements can have an item type attached, extending the system’s flexibility and capabilities.

In Swift, the master template (/Templates/Designs/Swift-v2/Swift-v2_Master.cshtml) acts as the overarching wrapper for various page types. It defines the basic HTML structure, including the <head> and <body> sections, and integrates the default layout template (/Templates/Designs/Swift-v2/Swift-v2_Page.cshtml).

Master

The associated item type (/System/Items/Swift-v2_Master.xml) includes fields and settings to control aspects like meta tags, header and footer links, external resource inclusions, and behavior configurations such as off-canvas mini-carts.

Extending the Master Template

Page layout templates in Swift define the master template they use through the @MasterPageFile("Swift-v2_Master.cshtml") directive in the code of the layout template (/Templates/Designs/Swift-v2/Swift-v2/Page.cshtml):

@inherits Dynamicweb.Rendering.ViewModelTemplate<Dynamicweb.Frontend.PageViewModel>
@MasterPageFile("Swift-v2_Master.cshtml")  <------- This directive

This directive explicitly links a page layout template to its master template. To determine the correct master template to alter for a given page item type, locate the master template specified in the layout template for that page.

Usually, the master template is not a typical extensibility point within Swift. However, in advanced scenarios, it makes sense to modify or extend it to meet specific frontend requirements. Extending the master template involves customizing its structure or functionality to better fit the frontend’s requirements.

Below are key areas and examples of customization:

1. Changing the markup

You can modify the markup in Swift-v2_Master.cshtml to reflect new design patterns or structure. For instance:

  • Add custom <div> wrappers for new sections.
  • Integrate third-party scripts or stylesheets.
  • Enhance SEO by adding structured data (JSON-LD).

2. Adding new Settings

To extend the functionality, you can introduce new fields to the master item type (Swift-v2_Master.xml). Item types are usually edited through the user interface, as described in the Dynamicweb documentation. When edited in the UI, changes are reflected in the corresponding item type XML file. For example:

  • Add a checkbox field to enable or disable a cookie consent banner.
  • Include a dropdown to configure additional tracking codes.
  • Provide a text field for custom meta descriptions.

Example:

<field name="Custom Meta Description" systemName="CustomMetaDescription" type="System.String, System.Private.CoreLib">
  <editor type="Dynamicweb.Content.Items.Editors.TextEditor, Dynamicweb">
    <editorConfuguration />
  </editor>
</field>

After adding this to the item type, you can reference it in the master template:

<meta name="description" content="@Model.Area?.Item?.GetValue("CustomMetaDescription")">

3. Adding custom scripts and styles

You might need to add JavaScript libraries or CSS files. This can be achieved by editing the <head> section of the master template:

<link rel="stylesheet" href="/Files/Templates/Designs/Swift-v2/Assets/css/custom-styles.css">
<script src="/Files/Templates/Designs/Swift-v2/Assets/js/custom-script.js" defer></script>

You can further enhance this by creating fields in the item type to dynamically manage these resources.

4. Custom meta tags

To include additional meta tags for services like Open Graph or Twitter Cards, you can leverage the fields already present in the item type. For example:

<meta property="og:type" content="@Model.Area?.Item?.GetValue("Open_Graph_Type")">
<meta property="og:image" content="@Model.Area?.Item?.GetValue("Open_Graph_Image")">

Approaches to customization

There are two main approaches to extending the master template:

The item type can be customized from the UI under Settings > Item Types using the item type customize feature. This process automatically replaces all existing uses of Swift-v2_Master with a custom version Swift-v2_Master_Custom, ensuring that your changes are applied without impacting the original item type.

  • Pros:
    • Protects customizations from being overwritten.
    • Easier to maintain if updates frequently change the default templates.
  • Cons:
    • Increased maintenance effort.
    • Potential for duplicate work if the source template evolves.

Example: Create a copy of the master template (Swift-v2_Master_Custom.cshtml) and its item type (Swift-v2_Master_Custom.xml). Update the system to reference these files instead of the defaults.

2. Modify the existing template and item type

Modifying the master template simply involves changing the content of the Swift-v2_Master.cshtml file or updating the fields and settings of the associated master item type (Swift-v2_Master.xml).

  • Pros:
    • Minimal duplication.
    • Keeps changes centralized.
  • Cons:
    • Updates to Swift may overwrite your customizations.
    • Requires careful merging during updates.

Conclusion

Extending the master template is a powerful way to tailor Swift to project-specific needs. By understanding the underlying architecture and carefully planning your customizations, you can create a scalable and maintainable solution. Evaluate the pros and cons of modifying existing files versus creating custom copies, particularly in the context of regular updates to the Swift framework.

Improve this doc
To top