Post / Page config options
Post/Page config options allow us to add custom elements to our content. Such options are available in the right-sidebar of the Edit Post / Edit Page screen, under Other Options:
Something worth noting; the options that appear in this section also appear in the Theme Settings screen in the Post Options / Page Options section; the settings in this section are taken as the default values that all posts will use which can then be modified individually for each post in the Other Options section mentioned above.
How to add a custom option?
There are several Post/Page Config options available, which we can include or exclude from our settings in the postConfig/pageConfig section of the config.json file.
For example, if we want to add a select element to enable/disable an option such as the post title on the post page, we can do so using the following.
"postConfig": [
{
"name": "displayPostTitle",
"label": "Display post title",
"value": 1,
"type": "select",
"options": [
{
"label": "Enabled",
"value": 1
},
{
"label": "Disabled",
"value": 0
}
]
}So what’s happening in the above code? Let’s take a look:
- We specified the name of the variable using the Name attribute.
- The Label attribute provides the name of the option as it will appear in the sidebar.
- With the Value attribute, we set the default behaviour; using 1 here means that the option will be enabled by default.
- Setting Type to select creates a select element with drop-down list.
- The individual items defined in the Options section define each option that should be available in the drop-down list, and what variables it will change; we can see that the ‘Enabled’ label changes the Value to 1, while ‘Disabled’ changes the Value to 0.
Where can it be used?
Obviously you can use Post/Page Config options on the post/page, but you can also use it on other pages where a post may be viewed e.g. in listings; the only difference is in the markup.
To use the option on the post page we can use the following markup:
{{#if @config.post.displayPostTitle}}
{{title}}
{{/if}}Whereas on other pages we should use the postViewConfig object:
{{#if postViewConfig.displayPostTitle}}
{{title}}
{{/if}}And now, when we change the option to Disabled the title will not be displayed.
Note: all options can be used within conditions (i.e. if statements)
What other config options are available?
The above example uses only one option, but Publii includes a few different elements that can be used to expand the post content. Let’s take a look at these options one-by-one, so we can see how they would be used.
The available option types are:
- text
- textarea
- select
- colorpicker
- separator
- image upload
Text
The Text field can be used to provide additional content to your post page, such as a subtitle. To enable the option, we can use the following code in the config.json file:
"postConfig": [
{
"name": "displayText",
"label": "Display your content",
"value": "",
"type": "text"
}
And the following markup in your theme file:
{{title}}
<p>{{@config.post.displayText}}</p>Doing this will provide the following results::
<h1>Post title</h1>
<p>Subtitle</p>Textarea
This option functions similarly to the Text option, but provides a larger area for your additional content. Once again, we need to add the following code to the config.json:
"postConfig": [
{
"name": "displayTextarea",
"label": "Display your content",
"value": "",
"type": "textarea"
}
And add this markup to the theme file:
<div>{{@config.post.displayTextarea}}</div>Select
This option creates a select input with a drop-down list that allows users to define a set of values for the available options. For example, to create an option that lets users switch between different column layouts, we would add the following code to the config.json:
"postConfig": [
{
"name": "layouts",
"label": "Select layout type",
"value": "layout--col2",
"type": "select",
"options": [
{
"label": "1 column",
"value": "layout--col1"
},
{
"label": "2 columns",
"value": "layout--col2"
},
{
"label": "3 columns",
"value": "layout-col3"
}
]
}And in the theme file we add the following markup:
<div class=”{{@config.post.layouts}}”>
...
</div>
Which will provide the following results:
<div class=”layout--col2”>
...
</div>
As you can see, by default it displays the default value that was defined by us in the code; in this case the .layout--col2 class; when the user changes the select option, the class will change too.
Color Picker
The next helpful option allows the colour picker to be displayed; we can use this to, for example, to change the colour of the page background for each post individually. We can set this option with the following code:
"postConfig": [
{
"name": "bgColor",
"label": "Change background color",
"value": "#000",
"type": "colorpicker"
}
And add this markup to the theme file:
<article style="background-color:{{@config.post.bgColor}}">
…
</article>
It will provide the following results:
<article style="background-color:#000">
…
</article>Separator
This option adds a separator; very helpful if you want to separate options for better readability; it may take the form of an empty space, label or horizontal line.
Example 1
{
"name": "separator1",
"label": "Separate",
"type": "separator",
"note": "Donec ullamcorper nulla non metus auctor fringilla."
}
Example 2
{
"name": "separator",
"label": "Separate",
"type": "separator"
}
Example 3
{
"name": "separator",
"label": "",
"type": "separator",
"note": "Donec ullamcorper nulla non metus auctor fringilla. "
}
Example 4
{
"name": "separator",
"label": "",
"type": "separator"
}
Image upload
The subsequent enhancement introduces the ability to upload images, offering an invaluable tool for incorporating alternative featured images or visually enriching your posts. This functionality can be particularly advantageous for specifying unique images on a per-post basis, thereby elevating the visual storytelling within your content. To implement this option, we employ the following configuration:
"postConfig": [
{
"name": "displayImage",
"label": "Upload image",
"value": "",
"type": "image"
},The Handlebars template syntax for such an inclusion is as follows:
<figure>
<img
src="{{@config.post.displayImage}}"
{{imageDimensions @config.post.displayImage}}>
</figure>
This markup not only references the uploaded image through {{@config.post.displayImage}} but also displays its dimensions with the utility of the {{imageDimensions}} helper.
Furthermore, should the site be configured to utilize responsive images, you can use the {{responsiveImageAttributes}} helper to ensure the image is displayed optimally across various devices.
<figure>
<img
src="{{@config.post.displayImage}}"
{{imageDimensions @config.post.displayImage }}
{{#if @config.site.responsiveImages}}
{{responsiveImageAttributes @config.post.displayImage}}
{{/if}}>
</figure>Please note: It is essential to note that thumbnails generated for these images adhere to the specifications defined for contentImages. This alignment guarantees that thumbnails, particularly for post content, are produced following the predetermined criteria concerning the size and quality of images uploaded to the post body.