Knowledge Base

An Introduction to Programmable Layouts

Last Modified:
18 Jun 2019
User Level:
Administrator

Programmable Layouts use server-side JavaScript to enhance your Content and Page Layouts so you can execute scripts at publish time that utilize TERMINALFOUR's native Java API. They are most commonly used to provide a logic and flexibility over the output of content that is not possible using standard T4 Tags .

With Programmable Layouts, you can use your existing JavaScript skills to access powerful features within TERMINALFOUR. Knowledge of Java will give you an added advantage since you can also call Java in the Programmable Layouts.

Here's an example of a Programmable Layout that is used in a Content Layout to determine the content that is published based on whether it's the first day of the month and what day of the week it is. A Content Type called 'News Item'  contains five elements:

  • Name - the name of the piece of content
  • Title – the news item title
  • News Review – a review of the previous month's posts
  • Long News – a long-form version of the news item
  • Short News – an abridged version of the news item

If it is the first day of the month the 'News Review' element is published. If it's not the first day of the month and it's a weekday and not a Friday then publish the 'Long News' element, otherwise publish the 'Short News' element.

This is what the Programmable Layout looks like:


try {
    var title = content.get('Title'); // A variable containing the 'Title' Content Element of the current Content Type.
    var monthNews = content.get('Review News'); // Get the 'Review News' Content Element of the current Content Type.
    var longNews = content.get('Long News'); // A variable containing the 'Long News' Content Element of the current Content Type.
    var shortNews = content.get('Short News'); // A variable containing the 'Short News' Content Element of the current Content Type.
    var todaysDate = new Date();

    if (todaysDate.getDate() === 1) {
        // If it's the first day of the month.
        document.write(title); // Publish the 'Title' content element.

        document.write(monthNews); // Publish the 'Review News' content element.

    } else {
        if ((todaysDate.getDay() !== 0) && (todaysDate.getDay() !== 6)) {
            // If it's a week day.
            document.write(title); // publish the 'Title'

            if (todaysDate.getDay() !== 5) { // If it's not Friday.
                document.write(longNews); // Publish the 'Long News' content element.
            } else {    
                document.write(shortNews);
                // Publish the 'Short News' content element.
            }
        }
    }
    var lastModified = content.getLastModified();
    document.write('This information was last modified on ' + lastModified); // Append and publish the last modified date for this piece of content.
}
catch (exception) {
    document.write (exception); // Catch any errors that the above code may throw 
}

When to Use Programmable Layouts

Programmable Layouts are ideal for executing simple conditional logic that may alter the published code depending on certain conditions. Since it is run at publish time, the conditional logic being used does not require JavaScript to be enabled on the user's browser. Typical scenarios may be:

  • If element x = y then output z
  • If element x is blank then output z
  • If element x = element y then output z
  • If this is the first content item in a group of content using a particular Content Type, then output z
  • If this is the last content item in a group of content using a particular Content Type, then output z

When Not to Use Programmable Layouts

Where logic is required to enhance a page (e.g., add or remove styling) but is not required for the page to display and function, standard JavaScript on the page may be a better solution.

If your page requires dynamic elements, based on user input (e.g. selecting an option, clicking a link, personalization based on GeoIP), then the page could possibly use a server-side scripting language (e.g., PHP) rather than use Programmable Layouts. Programmable Layouts will generate static pages, which are the same for all users unless a scripting language is used to provide different pages to different users.

When the same results can be achieved using a standard layout, avoid using Programmable Layouts. Similarly, if you are using a Programmable Layout to mimic the functionality of existing TERMINALFOUR features like Navigation Objects, Web Objects or Data Objects then just use those features instead of making life unnecessarily complicated.

Warnings about Programmable Layouts

This feature is very powerful. It is important that you follow the development best practice guidelines. We recommend that you thoroughly test any code on a development environment prior to moving the code to a production instance.

Bad practice, poor techniques or code errors can have a negative impact on overall system stability and performance. The investigation and resolution of problems introduced by this feature may be outside your support agreement.

Programmable Layouts use the TERMINALFOUR Java API (you'll need to log-in to the Community site to view) so when you upgrade TERMINALFOUR to a new version, the API  may change. This may cause your Programmable Layout code to no longer work so you will need to check them as part of your pre-upgrade testing

Since Programmable Layouts execute during publish, they can have an impact on publish performance. Always evaluate the publish times using the Publish Reports both before and after the Programmable Layout is added to ensure that it is not had a negative impact on the publish time. Using the caching features available within the API is important. When executing the same script multiple times it is possible to add the information to the publish cache. Both techniques will have a positive impact on performance.

When editing or creating Programmable Layouts, check the Tomcat catalina.out log file for any errors that are generated during preview and publish. If there are errors being generated to the logs, this can fill the log files and server space quickly.

It's useful to have errors printed to your pages in a standardized format. While you may not want to do this is in production you should do this in a testing environment, e.g.,

catch (exception) {
    document.write ("An error occurred publishing this page: " + exception);
}
Back to top