Custom Modules (AKA WebApps)
Custom Modules can be used to construct simple or complex data structures as a way to dynamically manage the content on your site or web application.
From a simple staff profile listing, detailed image gallery, to a complex real estate directory, Custom modules help you display data sets consistently, allowing content administrators ease of management and even provide an opportunity for user-submitted content in a secure way.
Use Cases
If coming from Business Catalyst these are much like WebApps, although Custom Modules are much more powerful and flexible.
There are several aspects which make Custom Modules so much more flexible:
- Better management and easier access to multiple layout views for both Detail view and List view layouts.
- Ability to control various aspects of how items are listed and managed within the admin, such as enabling or disabling; multiple detail views, release and expiry dates, weighting, categories, tags and author, among many other settings.
- Flexibility to create nested items, combining Custom Modules with other Custom Modules with the ability to add/edit nested item from within either of the lists views. Making complex content management easier, more structured and more intuitive for your client or administrator.
See 'Advanced Settings' in the 'Settings' section below for more details. - Fast item searching (based on both item name and item URL).
- SEO and Meta data management along with AMP (Accelerated Mobile Pages) configurations.
Creating a new Custom Module
To create a new Custom Module and configure the settings, expand the 'Custom Modules' item in the left hand menu and click "+ Add New module". Then progress through the tabbed section to configure your Custom Module.
Below are further explanation of the available options.
Custom Module Settings
From the Custom Modules item list view, click the " EDIT SETTINGS" button to display a context menu for further options, as detailed below.
Settings
These settings relate to the overall Custom Modules options and functionality and how content might be managed by site administrators.
Item Properties
Here you can define the various options that might be available when creating Custom Module items, such as the system data fields to be used, default expiry, SEO settings, custom fields, and more...
Layouts
Layouts are the containers for an item's data to be rendered into, along with your custom markup. They are output by way of their associated component tag.
eg:
{% component type: "module", source: "Custom Module Name", layout: "List" %}
When the component is output it loops through all of its relevant items and renders their data into the specified Layout, as defined by the layout parameter of the component tag.
In other words, the Layout acts as a type of template for displaying the Custom Modules data.
You create your HTML markup or custom code and insert something similar to “data merge tags” by way of Liquid objects (eg: {{this['name']}} would render the item’s name).
List Layouts
Layouts of type ‘List’ are typically used for rendering repeating data sets. So, if the component you've configured retrieves 3 Custom Modules, the List Layout will be rendered 3 times, each with a different item’s data being inserted within a defined markup.
Here is a simple example of how the Layout works, rendering a heading with the item's name as a link:
<div>
<h2><a href="{{this['Url']}}">{{this['Name']}}</a></h2>
</div>
Using the example above of 3 items, the result on the website's front-end would look something like this:
<div>
<h2><a href="/module-url/custom-module-item-1">Custom Module Item 1</a></h2>
</div>
<div>
<h2><a href="/module-url/custom-module-item-2">Custom Module Item 2</a></h2>
</div>
<div>
<h2><a href="/module-url/custom-module-item-3">Custom Module Item 3</a></h2>
</div>
Detail Layouts
Layouts of type ‘Detail’ are typically used for rendering a single item's detail view, as displayed when browsing to that item’s unique URL.
Here is a simple example of how the detail Layout could look, rendering a heading with the item's name and the item's description field:
<div>
<h2>{{this['Name']}}</h2>
<div>
{{this['Description']}}
</div>
</div>
So, as per the example above, if viewing the first Custom Module, the Layout would render something like this:
<div>
<h2>Custom Module Item 1</h2>
<div>
This is the description content of Custom Module Item 1.
</div>
</div>
Adding/Editing Layouts
You have the freedom of editing these layouts as you need to, with any HTML, CSS or JS as appropriate for your project. As well as creating unlimited, additional layouts.
Click the 'ADD NEW LAYOUT' button at the top to create additional list or detail layouts.
You can then add your custom markup and insert dynamic Liquid objects into your layout. Using the ' Properties' manager (found at the top right of the editor), simply click on the desired Liquid object name from the list to have it inserted at your cursors position within your markup, or click on the copy icon () to copy it to your clipboard.
Additionally, you can even add other modules inside of these Layouts, just as you might insert them onto a regular page. Simply click on the ' Components' manager (found at the top right of the editor) and follow the prompts to configure any additional component tags for the desired data output.
Table
This setting allows you to customise the column headers in the table/list view of module items in the admin. Allowing you to provide a better editing experience for you and the site admins.
For example, looking at a list of products, you’d likely want to see, and sort by, different columns of data than you would for a list of gallery slides or a list of staff members.
Reposition or Remove Table Columns
The Tables interface shows a representation of the current column headers which can be repositioned (via drag and drop), or deleted (via the x () icon, shown on hover).
Any changes made to the headers here are saved automatically.
Editing Table Columns
You can add additional columns to your module list view by clicking the “Add New Column” button, or you can edit existing ones via the pencil () icon (shown next to the column label on hover).
Column options are as follows:
Duplicating a Custom Module
This option allows you to copy an entire module setup, including all of it's settings and properties, but excluding it's individual items (these can be exported and re-imported into the new module if needed). You'll be prompted for a new module name and URL during the duplication process.
This option is accessed when editing a module's settings via the duplicate icon found next to the module name at the top of the 'Settings' screen.
Duplication of modules is available on the PRO plan and higher.
Duplication of built-in system modules is available, however, they will be converted to regular Custom Modules void of their specific System Properties.
ReIndexing Custom Module Items
This option allows you to re-index all module items for site and module searching functions.
This option is accessed when editing a module's settings via the re-index icon found next to the module name at the top of the screen.
Populating Custom Module Items
From the Custom Modules item list view, click the “CREATE NEW” button at the top to start creating a new item.
You can also import/export data into/from your module via the context menu (3 dots icon ) where you can update your items in bulk using a spreadsheet program and import item data from an Excel file.
Export the current items in order to get a template import file you can use for importing new data. If you're starting from scratch, first create a dummy item with some sample data so you can see the import format needed.
There are 3 different list views your Custom Module items can be configured to display in, or switched to via the icons ( ) in the top right of the item view.
Depending on how the module is configured, some or all of these icons may be visible and the default view may be different to that of how other modules display.
List View ()
A direct listing of all the current module items, in a tabular layout, which can be clicked on to access their content. A typical view for singular, self contained modules.
Tree View ()
Relevant for nested module structures, this view shows all current module items, in a tabular layout, as folders (parent items) which can be clicked into to access a List View of their child module items.
Simplified Tree View ()
Relevant for nested module structures, this view shows all current module items (parent items) in a simplified list of items only. These can be reordered or nested via drag and drop or further edited via the context menu () visible on hover.
For more details on these view options see the module ‘Advanced Settings’ section above.
Regardless of the initial view, once editing an item you have access to the following options.
Settings
Parent/Child
This tab will only be visible when the module is in a nested configuration, with a parent and child module grouping, and when the child module allows ‘multiple parent items’ in its advanced settings.
The tab will carry the name of the parent/child module, depending on which module you are viewing.
See module Advanced Setting above for more details on this configuration.
This page will display the items from the Parent/Child module and allows you to assign Parent/Child to the current Custom Module item - by dragging and dropping from the available items on the left into the assigned list on the right. Or you can remove Parent/Child from the Custom Module by moving them from right to left.
Additionally, the directional arrows in the middle can be used to move selected items right or left, or to move ALL items together right or left (using the double arrow buttons). This can be useful to clear all assigned Parent/Child from the Custom Module quickly, for example.
SEO
Displaying Custom Module Items
You can render Custom Module items to your website front-end in a variety of ways and places such as; pages, layouts, templates, emails and just about anywhere else that supports Liquid.
Most commonly though, we would use a standard web page to render to and we would insert a Liquid component tag to define the data that is to be displayed there.
You can use the Component Manager to configure your Custom Module component tag and insert it into the editor, or you can manually configure them by coding the desired parameters directly into the tag.
Using the Component Manager
Found at the top right of the content editor section, clicking the ‘ Components’ button will reveal a list of available modules and other system items.
Expanding the 'Custom Modules' section and selecting 'List of items' to open the component configuration panel.
Follow the prompts to configure the way you'd like to retrieve Custom Modules then click the blue link/s at the end to copy the constructed component code to your clipboard. Now you can paste this code into your page content or where otherwise required.
Component Tag Advanced Customisation
See here for more detailed documentation on manually configuring the Custom Module component tag.
Related Articles
- module (Custom Modules)
This module component fetches data relating to Custom Modules. {% capture data %} {% raw...
External Resources
Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.
Questions?
We are always happy to help with any questions you may have.
Send us a message at support@treepl.co and we will consult you as soon as possible.