Outlast

Content - Section templates

Note: You should read the information on creating page templates before you read on!

Section types

When you first add the content plugin, there will be a few default page section types already defined. This may be enough, but you might choose to add more.

As mentioned before, ContentPageSection‘s are a mashup of WordPress widgets, shortcodes, and various WP plugins like SimpleFields. They allow you to define custom data and editors which can then be set in the admin and displayed on the public site.

Each section type will have the following:

a type id defined in the config
name, description, and icon defined in the lang
an HTML view template that defines what the admin editor looks like
an HTML view template that defines what it looks like on the public site
a controller to load any additional data (optional)

So let’s look at these one by one.

Section type configuration

Say we want to add a new section type, banner. To add a new page type you’ll need to modify content.conf.ini and add the type to any of the pages’ contentpagesection_types keys. If a type id exists in at least one page, you should create everything that is needed for that type to function properly.

The resulting file should look something like this:

[contentpage]
# This is a comma-separated list of available page types.
contentpage_types = page,article

# ....
[contentpagesection_article]
contentpagesection_panels = 1
contentpagesection_types = header,textarea,gallery,banner

You should have already read how to set up content pages. If not, see the docs on this topic.

Section type name and icon

Now copy the plugin-level contentpagesection.lang.*.ini to the app-level. As with pages, this should be for your admin locale, so whatever $zajconf['locale_admin'] is set to. Note that you do not need to create this for all site locales – just admin ones!

You should create a new [contentpagesection_*] section for your type:

[contentpagesection_banner]
contentpagesection_name = Banner
contentpagesection_description = A banner ad
contentpagesection_icon = list-alt

Note that icons should use font-awesome id’s, but without the fa- prefix!

Section admin template

All section types require an admin template. Not only does this define what the admin sees, it also defines what data is saved and how.

The location of admin templates is in /view/admin/contentpagesection/_*.html.

These templates are like any other admin template: you need to take content from the current contentpagesection object and display it in a form so the user can edit it. The difference is in the name of the form elements (inputs, textareas, etc.) – this needs to be in a very particular form so that the admin interface can properly save it when the data is sent.

The format of input names is as follows: contentpagesection[...contentpagesection.id...][textcontent]. Generating this may be a pain, so fortunately we have the nameprefix property: {{content.contentpagesection.nameprefix}}.

Here is a basic example create a text data type:

Notice that instead of using an input tag ourselves we instead use the system-level input fields. This is the prefered way (if there is a relevant system data field type).

In other cases you will need a completely custom interface…the same example again without using the system field html:

Storing complex data in sections

The examples above show storing simple text data.

But the ContentPageSection model has some built in fields (textcontent, photocontent, filecontent, jsoncontent) which are useful for storing various forms of more complex data. Check out /view/admin/contentpagesection/_gallery.html for an example of storing photos.

In addition, you may need to connect other data to the section, such as related Product objects, etc. In this case you need to create a manytoone or manytomany connection in an extended app-level ContentPageSection model and then update your html to display this connection field.

Section public template

All section types require a public template. This will define the way that users see the section on the public site.

The location for public templates is in /view/contentpagesection/_*.html. For our banner example this would be /view/contentpagesection/_banner.html. Notice the underscore (_) prefix – this is because content page sections are by their definition partials, so they follow the partial template naming convention.

As for the data, the template will be able to access the current contentpagesection object via {{content.contentpagesection}}. So a simple banner template may look like this:

For more examples, you should also take a look at the built-in content page section templates. You’ll find them under /plugins/content/view/contentpagesection/*.html.

Section controller

Some sections may require additional data to be loaded before the template is shown. Similar to ContentPage controllers, in this case you can optionally add a section controller. Again, the naming is important here – you need to add it to /controller/contentpagesection/*.ctl.php so in the case of our banner example the file would go in /controller/contentpagesection/banner.ctl.php.

Section controllers will follow this format:

…and the __before() method will be called magically before the section template is loaded.

Important! Make sure to not overuse section controllers as these are run each time a section is loaded – which may be several times a page is rendered.

Plugins