Theme settings API

Almost every theme needs configurable options to handle user needs. Publii allows you to create theme-related and post-related options which allows users to customize the theme and posts layout.

Where to find theme settings?

Theme settings are available under "Theme" menu item in the Publii's sidebar. Under this view you will find "Basic settings" and "Custom settings" areas.

The basic settings area is defined by Publii and cannot be changed by theme. The custom settings area is fully configurable by the theme developer. All your custom settings will be grouped into tabs with options.

Theme settings API

Where to find post settings?

Post settings (if available in the theme) are placed as a last tab under custom settings in the Theme settings view. Under this tab called "Post options" user can define global values for the post settings to avoid unnecessary modifications of every posts to achieve a specific configuration.

E.g. if the user wants to disable displaying creation date for all posts, he can do it under "Post options" tab. But if few posts needs to have a creation date, it is possible to enable it in the post editor under "Other options" tab in the post editor sidebar.

Every option in that tab have usually three values:

Use global configuration
Disabled
Enabled

Use of the global configuration is the default setting.

How to create theme settings?

Theme settings can be defined under config.json file under customConfig field.

The theme settings allows you to use the following fields:

How to create post settings?

Post settings can be defined in the same way as theme settings, but should be placed under postConfig field.

At this moment post settings allows you to use the following fields:

The post settings fields at this moment do not support the group parameter which is used to create tabs for the theme's custom settings.

How looks a structure of the field under config.json file?

All fields uses a common structure of the field definition:

name: name of the field used to retrieve a value of the field
label: label used to easily recognize a field in the Publii's UI
group: field used to group fields (only for the theme settings fields). All fields with the same value will be placed under the same tabs, that value is also a tab label.
note: use this field to add additional informations for the user. It allows you to use the HTML code as a value
value: default value of the field
type: type of the field
dependencies: array of the rules used to specify if the field should be displayed or not
customCssClasses: defines one or more custom CSS class names to be applied to the field
[other]: other field-related fields - read a specific field documentation to get more details on it

Below there is an example of the field used for lazy load effects in our themes:

  {
      "name": "lazyLoadEffect",
      "label": "Lazy load effects",
      "group": "Additional",
      "note": "This option works only if the 'Media lazy load' option is enabled in the Website Speed tab under Site Settings",
      "value": "fadein",
      "type": "select",
      "options": [
          {
              "label": "Fade in",
              "value": "fadein"
          },
          {
              "label": "None",
              "value": "none"
          }
      ]
  }

Above field will be available under theme as:

{{ @config.custom.lazyLoadEffect }}

That field will be displayed under theme settings in the "Additional" tab as a dropdown field with the three options:

Fade in
Blur up
No LQIP

The default value will be "Fade in". Under the field user will see an additional note with link to the external documentation.

That field will be displayed in the UI only if the option lazyLoad will be set to true.

How to access option values of the theme settings in the theme?

Every theme option value is easily accessible through global @config variable. That variable contains the custom field which is an object where the key is the name field used in the definition of the option.

E.g. if you want to access a value of the option which uses as a name headerColor value, you should write in your theme:

{{ @config.custom.headerColor }}

Above code will output value of the headerColor option.

How to access option values of the post settings in the theme?

The post settings options are accessible in two ways:

through @config.post.* syntax which works in the same way as @config.custom.* syntax for the theme option
through postViewConfig object in the post item.

Warning! The @config.post.* syntax works only the single post templates. Under pages with post listings you have to use the postViewConfig object.

E.g. to get post option value defined with name headerColor you can use under the post.hbs file (and also under any custom post templates) the following syntax:

{{ @config.post.headerColor }}

If you want to get the same value under posts listing (e.g.: on the homepage) you should use:

{{ postViewConfig.headerColor }}

Inside the post item context:

{{#each posts}}
    <h2 style="color: {{ postViewConfig.headercolor }};">
        {{ title }}
    </h2>
{{/each}}

Above code will display the posts listing with use of the text color specified per post.

How to create post template-related post settings?

It is possible to create post options which will be displayed only if the specific post template is used (if the post templates are available in your theme).

You have to use the postTemplates parameter. It can be defined as a single post template name:

 
{
     "name": "displayAuthor",
     "label": "Display author name",
     "value": 1,
     "type": "select",
     "postTemplates": "alternative",
     "options": [
          {
              "label": "Enabled",
              "value": 1
          },
          {
              "label": "Disabled",
              "value": 0
          }
    ]
}

or as multiple post templates names (separated by comma):

...
"postTemplates": "alternative,test,portfolio", 
...

if you need to hide a specific post options for the given post templates names - prefix the postTemplates parameter value with exclamaition mark:

...
"postTemplates": "!alternative,test,portfolio", 
...

In the above example, the specified post setting won't be displayed for the alternative and portfolio post templates.

Internal linking between options

It is possible to create internal linking between options using note fields.

To create internal links please create links with data-internal-link attribute:

<a href="#" data-internal-link="Fonts">Link A</a>
<a href="#" data-internal-link="Fonts#headings">Link B</a>

Link A will lead to a group named Fonts, while Link B will lead to an option which contains anchor field set as "headings":

{
     "anchor": "headings",
     "name": "separator",
     "type": "separator",
     "label": "Headings",
     "group": "Fonts",
     "note": "Please note: not all of the font weights are working with the fonts listed above.",
     "size": "big"
}

Custom CSS Classes for Fields

To enhance the flexibility and customization of Publii's UI, we have introduced the customCssClasses attribute for fields within plugins, themes, and repeaters. This feature allows developers to assign one or more custom CSS classes to a specific field, providing greater control over the styling of individual UI components.

Adding a Single Custom CSS Class

To add a single custom CSS class to a field, use the customCssClasses property in the field's JSON configuration. Specify the class name as the value of this property. For example:

{
  "name": "exampleField",
  "label": "Example Field",
  "type": "text",
  "customCssClasses": "unique-class-name"
}

This will apply the unique-class-name CSS class to the exampleField element in the Publii UI.

Adding Multiple Custom CSS Classes

You can also assign multiple CSS classes to a field by separating class names with a space. This allows for even more detailed customization of field styling. For instance:

{
  "name": "exampleField",
  "label": "Example Field",
  "type": "text",
  "customCssClasses": "unique1-class-name unique2-class-name unique3-class-name"
}

In this example, the exampleField element will have three separate CSS classes applied: unique1-class-name, unique2-class-name, and unique3-class-name. This enables the application of multiple styling rules to the same field for more complex and varied visual effects.

Usage Notes

Ensure that the custom CSS classes you define are properly declared in your theme's or plugin's CSS files. Undefined classes will not affect the field's appearance.
The customCssClasses attribute can be used with any field type, providing a versatile tool for UI customization across your Publii site.
Combining multiple classes allows for a granular and layered approach to styling, creating a more polished and user-friendly interface.

By leveraging the customCssClasses attribute, developers can significantly enhance the appearance and user experience of the Publii theme settings interface. This attribute allows adding one or more custom CSS classes to individual settings fields, providing a direct method for applying specific styling choices. Such customization ensures that the interface for theme settings aligns perfectly with the developer's design vision, facilitating a more intuitive and visually cohesive user configuration experience. This capability underscores the flexibility and adaptability of Publii, enabling developers to create highly customized and user-friendly theme settings panels.

Enhancing Theme Settings UI with Custom CSS

Publii introduces a powerful feature that allows theme developers to customize the appearance of theme options further through custom CSS classes. This enhancement is not limited to themes alone but extends to plugins and repeaters, ensuring a uniform and visually appealing user interface.

With the customThemeOptionsCss feature enabled within the supportedFeatures setting, Publii now allows for loading a theme-options.css file directly from the theme's main directory. This dedicated CSS file provides a centralized approach to styling theme settings, making it easier for developers to manage and update the visual presentation of their theme's configurable options.

The theme-options.css file should be placed in the theme's main directory, following this path:

\Documents\Publii\sites\your-siteName\input\themes\your-theme-name\

For example, if your theme is named Simple, the structure would look like this:

- input
  |- themes
     |- simple
        |- theme-options.css
        |- index.hbs
        ...

This file path ensures that the theme-options.css file is properly loaded and applied to the theme settings in the Publii interface. To make use of this feature, you must explicitly enable it in your theme's configuration. Include the following code in your theme's config.json file under the supportedFeatures section:

"supportedFeatures": {
    "customThemeOptionsCss": true
}