9. Properties

Properties are single values which are exposed by the core and layout layers and set in all subsequent layers to configure aspects of a style. Properties can be of any primitive type as well as any class which provides both an as_string() function which returns a string representation of its data and a constructor function named after the class which accepts a string as a parameter and returns an object based on that string.

The purpose of properties is to expose certain configuration settings of a style such that they can be set from a friendly “wizard”-like interface.

9.1. Declaration

Properties are defined using the following syntax:

property int page_recent_items { des = "Number of journal entries to show on recent entry page";
      min = 5;
      max = 50;

The key and value pairs within the braces are known as attributes. These are used by the host application for various uses, including the presentation of a friendly customization interface.

9.1.1. Standard Properties

The following attributes are available for all properties:

Required - A textual description of this property.
A string setting the acceptable values of this property, along with a natural language description of each, in the format "value1|Description1|value2|Description2" and so on.
An example of what might be put in this field. Can be used when it's not obvious what the value should look like.
A note to be displayed with the field to enter this value.
Suppresses the display of this property in the editing GUI.

There are also attributes only available for specific types of property, as described in the following sections. Attributes for integer properties
The maximum value permitted.
The minimum value permitted. Attributes for string properties
The maximum amount of characters this property can contain.
The size (in characters) of text widget which should be used to set this property from an interface.

9.2. Setting

The set command is used to set the values of properties from all layers:

set text_read_comment = "Read 1 comment";

The value set by the highest layer will be used.

9.3. Use

In order to use a property from the core layer in a layout, you should first tell the system that you are going to use it. This makes it appear in the customization UI if applicable.

property use property_name;

All layers can use properties as variables as described in the variables section above:

print $*property_name;