Template Datalist Formatter

Introduction

Template Datalist Formatter transforms normal tabular datalist rows to use a user-defined template.

Plugin Information

Plugins Available in the Bundle:

• Template Datalist Formatter Plugin
• Template Datalist Clear Cache Tool Plugin
• Template Datalist Formatter Usage Wrapper Plugin

This plugin bundle is compatible with Joget DX 9 and onwards.

Get Started

Where To Get The Plugin

You can download this plugin from the Releases

How To Install

1. Go to your Joget localhost or server. In the Joget Console, go to Admin Bar > Settings > Manage Plugins and click the Upload Plugins button.
   
2. Under Upload Plugin, select the plugin .jar file you downloaded and click Upload.
   
3. You can now view your new plugin in your List Builder.
4. Remember to uninstall the old plugin before uploading a new version.
5. The Joget Knowledge Base has more information on managing and developing plugins.

How To Use It

1. Open your app in App Composer and go to the list you want to format (or create a new list via List Builder).
   
2. Click on the column you want to format.
   
3. Under Formatter, select Template Datalist Formatter from the dropdown.
   
4. Under Configure Template Datalist Formatter, write your custom layout in the Template field using HTML, referencing each column with the syntax {column_N::field_name}, where N is the column's index in the list and field_name is a label of your choice.
   
5. As you reference columns in the Template (or in the CSS/JavaScript/Custom Header, if used), they will automatically appear under Columns Selection, confirming which columns are being pulled into the row.
6. Optionally, enable Rich Content to add supporting CSS and JavaScript for styling and interactivity (e.g., highlighting the current step in a status flow, or coloring star ratings based on value), and a Custom Header for hidden markup used by your JavaScript (e.g., a modal).
   
7. Optionally, configure the Caching section if you want rendered content stored for performance; refer to the Configure Properties section.
   
8. Click Apply Change > Save.
9. Launch the app from the UI Builder. The list now displays your custom template layout instead of the default table.
   

Configure Template Datalist Formatter Properties

Fields to configure:

• Columns Selection: Lists the other columns available in the list, minus the column the formatter is applied to (referencing itself would cause an infinite loop). Click a column to insert its {column_id::field_name} reference into the Template.
• Template: The HTML markup used to render each row/record in the list. Reference a column's value using {column_id::field_name}, for example {column_0::name}. The value inserted is already formatted by that column's own formatter, and hash variables are supported.
• Rich Content: When checked, wraps the rendered row in a content container and enables the CSS, JavaScript, and Custom Header fields below for additional styling and scripting support. Enabled by default.
• CSS: Custom CSS code, printed out in the first row of the list. Only shown when Rich Content is enabled.
• JavaScript: Custom JavaScript code, printed out in the first row of the list. Only shown when Rich Content is enabled.
• Custom Header: HTML code that is hidden by default (e.g. for use in a modal), intended to be used by your JavaScript. The code is printed out in the first row of the list. Only shown when Rich Content is enabled.
• Enable Caching: When editing in List Builder, uncheck Enable Caching to see template changes immediately. When checked, the formatter caches the rendered template output for 10 minutes instead of regenerating it on every page load. Content is cached per tenant, app, list, and record.
  • Select Form to Store Content: Optional. When set, the generated content is also written to the selected field of this form, on the record matching the row's ID, whenever the cache is updated. If the cache key is no longer in memory, enabling Fetch Cache from Form Data allows the content to be retrieved from the stored form data and re-cached.
  • Store Field to Store Content: The specific field (within the selected form) where the cached content is stored. Use a field large enough to hold the full HTML, and not one that your template displays.
  • Fetch Cache from Form Data: When checked, allows cached content to be fetched from the stored form data (instead of memory) and re-cached, if the cache key is no longer available. Only shown once a store field has been selected.
  • Debug Mode: When checked, logs cache get/set messages and their source (cache or form data) to the server log. Only shown when Enable Caching is checked, and should be turned off in production.

Configure Template Datalist Clear Cache Tool Properties

This tool clears the cached content of the record the running process is bound to.

Fields to configure:

• List: The list containing the column that uses the Template Datalist Formatter. Required.
• Select Form Storing Content: Optional. Set to the same form as the formatter's Select Form to Store Content, so the stored form data is cleared too.
• Field Storing Content: The field used by the formatter to store the content. Only shown once a form has been selected.
• Debug Mode: When checked, logs cache-clearing messages to the server log.

Expected Outcome

The list displays records using your custom HTML template instead of the default table format; for example, a card-style layout showing the record's name, team, upload date, a horizontal status-flow indicator (New > Clarification > Closed > Waiting) that highlights the current stage, an estimated delivery date, and a star rating, with an Edit action alongside each record.

Download Sample App