RealObjects Nimbudocs Editor 3.0.3929_Beta1

Guide: Style Templates


About Style Templates

Style Templates are formatting operations created from CSS and transformed into editor actions. This allows integrators and end-users alike to apply a vast amount of CSS styles to different elements of their document.

The chapter Overview provides an introduction to the Style Templates system and how it works in principle.

To learn how to define Style Templates via CSS see the Chapter Style Template CSS. It contains information about necessary properties and existing limitations.

Overview

How a Style Template Works - In a Nutshell

A Style Template is a CSS style rule that is interpreted by Nimbudocs Editor as a formatting operation for single DOM elements. Applying a Style Template means changing the element in a way that makes it fit the Style Template selector.

Template Definition

Selector

The selector defines to which elements the style rule applies. For Style Templates, it also describes how the formatting of the element will be modified in order to fit the selector. Nimbudocs Editor interprets the selector by splitting it up and sorting the selector parts into one of two categories: Requirements and Transformation Steps.

Requirements are those parts of the selector that need to exist on an element in order for the Style Template to be applied to it. Transformation Steps are changes that need to be done in order for the element to fit the selector. Which parts of the selector are considered requirements and which parts are not depends on the element type of Style Template defined inside the style declaration. More information on this topic is given in the chapter Style Template CSS - The Selector.

Style Declaration

The style declaration mainly defines what an element will look like that matches the style rule's selector. In case of Style Templates this means the style declaration defines the look of the Style Template.

Besides the visual properties the style declaration also needs to contain at least one special property (-ro-style-template) to tag the style rule as Style Template. This property also defines the element type of the Style Template and thus the basic formatting behavior. For more information which properties there are to create and configure Style Templates and how they work see the chapter Style Template CSS - Properties.

Formatting Behavior

Formatted Element Types

The Style Template definition made with CSS is automatically translated into Java actions. Throughout this translation, information from the Style Template properties is used to define how these actions are composed. The most important information during translation is the element type the Style Template should handle.

Currently the capabilities of this translation are limited. Not all of the element types supported by Nimudocs Editor are also supported by the Style Template functionality:

Nimbudocs Editor element types & Support for Style Templates

Style Template element type Description Corresponding HTML elements Support for Style Templates
inline Inline nodes with content. span, strong, ... supported
inline-element Empty inline nodes. img supported
empty block Block nodes with no content. hr currently unsupported
paragraph Block nodes defined as paragraphs. p, h1, ... supported
container Block nodes defined as container. div supported
table Block nodes defined as tables. table supported
table-row Table rows. tr supported
table-cell Table cells. th, td supported
table-caption Table captions. caption supported
list Lists. ol, ul supported
document The root element of the document. body currently unsupported

Mutual Exclusion

Style Templates are always part of a group. In this group, they are mutually exclusive to one another. If one of them is applied, the others are removed.

A Style Template created with the -ro-style-template property belongs to a group named after itself. That means it is not mutually exclusive to any other Style Template and can be applied without any other being removed. To assign it to a different group the -ro-style-template-group property is used. For more information on grouping see the chapter Style Template CSS - Properties.

Context Relations

Every Style Template only works in one or more contexts. Usually the contexts are document-wide so they can be used everywhere. It is possible to narrow down that context through using -ro-style-template-context. More information on contexts is revealed in the chapter Style Template CSS - Properties.

Generated Actions

A Style Template may be translated into multiple actions all applying the same format but working differently according to their configuration.

Currently only two kinds of actions are supported.

Toggle Actions

Toggle Actions will alternate between applying and removing a Style Template at the current Caret context. This allows creating a single bold button as well as a group of text align buttons for a tool bar (where toggle behavior is expected).

Setter Actions

Setter Actions will only apply a Style Template at the current Caret context. Removal is handled through an action of it's own, the default action. This allows creating a list or menu (where toggle behavior isn't expected).

A default action is automatically generated and therefore does not need a Style Template declaration. However, it is possible to create a default Style Template via CSS to apply additional settings to it.

Style Template CSS

A Style Template is created from a single style rule in CSS. The style rule can be divided into the selector and the style declaration which contains the Style Template properties.

The first part of chapter The Selector will help with choosing the right selector for a Style Template and how the selector affects what the Style Template action created from the style rule does.

The second part The Properties lines up all of the available properties that define, group and configure Style Templates.

The third part The Style Rule demonstrates how the style rule is composed from both selector and properties.

The last part The default Style Template tells how to add custom configuration to the default action by creating a default Style Template.

The Selector

This section deals with creating selectors for Style Templates. A Style Template selector may consist of those CSS 2.1 selectors presented within the table below. Selectors missing from that table are currently not supported.

As already mentioned in the chapter Overview selectors are interpreted by Nimbudocs Editor and divided into two different meanings according to the Style Template's element type. How a certain selector is interpreted is explained in the table below as well.

Supported CSS 2.1 Selectors and their formatting behavior

Selector Pattern Further description Style Template formatting behavior
* Universal selector

Using this selector will make every DOM element match this style rule.

However since Style Templates are limited to a certain type the Style Template will only appear to be applied to those elements that match this type. Applying or removing it is not possible since the style rule always applies.

A combination of this selector with another one will make the Style Template applicable on any element that matches the Style Templates type.

In case of an inline type, the inserted DOM element will be a span element.

In case of a paragraph type, the inserted DOM element wrapped around an anonymous paragraph will be a default paragraph element. Inline type Style Templates will use a default inline element, lists will use a default list element.

E Type selectors

This selector works as a Requirement or Transformation Step depending on the element type.

As Requirement:

Style Templates of the container, table, table row, table cell, table caption and document type are only applicable on DOM elements of the given name.

As Transformation Step:

Inline, Paragraph and List Elements will transform the DOM node the Style Template is applied on into a DOM node of the given name.

E[attributeName] Attribute selectors

This selector works as a Transformation Step for all types:

Applying a Style Template of this kind will add an empty attribute of the given name to the formatted element.

E[attributeName=‚Äč"attributeValue"] Attribute selectors

This selector works as a Transformation Step for all types:

Applying a Style Template of this kind will add an attribute of the given name with the specified value to the formatted element.

E.className Class selectors

Language Specific: This selector is specific to the HTML language.

This selector works as a Transformation Step for all types:

Applying a Style Template of this kind will add a class attribute if there is none yet and adds the specified class name to it's value list.

The Properties

This chapter deals with the description of each property used to define and configure Style Templates as well as with the way how they need to be defined.

-ro-style-template
Value: <string> || <type> | default | inherit
Initial: none
Applies to: depending on the element type
Inherited: no
Percentages: N/A
Media: all
Computed value: as specified

The property -ro-style-template makes a CSS style rule a Style Template. The property defines the name and type of the template.

If no additional -ro-style-template-group is defined the Style Template will be sorted into a group with the same name as the template.

<string>

The <string> defines the name of the Style Template. It should be unique since it identifies the Style Template inside Nimbudocs Editor. The case of <string> is regarded.

<type>

The <type> is used to define which elements the Style Template will handle and how this is done. The following values are available, they are corresponding to the elements described in the chapter Formatted Element Types:

Property Description
inline Used for inline elements.
paragraph Used for paragraph elements.
container Used for container elements.
table Used for table root elements.
table-row Used for table row elements.
table-cell Used for table cell elements.
table-caption Used for table caption elements.
list Used for list root elements.
document Used for document elements.
default This value is used to create a default Style Template for a group. For more information on this topic see the chapter Style Template CSS - The default Style Template.

Declaring Style Templates

This is an inline type Style Template. Using it will create a span on the selected text with the "important" class resulting in making the letters red and bold.

span.important {
    -ro-style-template: "Important" inline;
    color: red;
    font-weight: bold;
}

Here is a paragraph Style Template. It transforms any paragraph element into a first-level heading. The additional styles attached to the element add a chapter number in front of it.

h1 {
    -ro-style-template: "Heading 1" paragraph;
}
h1:before {
    content: counter(chapter) ". ";
}

This list type Style Template transforms a numbered list into a bullet list while a bullet list remains unaffected of this transformation. The resulting bullet list receives a class attribute value of "circle". The application of this Style Template results in a bullet list with circle bullets.

ul.circle {
    -ro-style-template: "Circle Bullet List" list;
    list-style-type: circle;
}

The following Style Template is used on table elements to make their borders look like a simple grid. The additional rule below the Style Template rule ensures that not only the table has a simple black border but the cells also have.

Note that this time it is not a value added to the "class" attribute. Instead an attribute ("presentation") is being set if the Style Template is applied.

table[presentation="simple"] {
    -ro-style-template: "Simple Table" table;
    border: 1px solid black;
    border-collapse: collapse;
}
table[presentation="simple"] > tr > td {
    border: 1px solid black;
}

Style Templates for table row and cell elements are created the same way as those of a table. The following rules describe how an alternating table row visualization might be created with Style Templateswithout resorting to the CSS3 :nth-child() pseudo class which automatically handles this.

tr.even {
    -ro-style-template: "Even Row" table-row;
    background-color: white;
}
tr.odd {
    -ro-style-template: "Odd Row" table-row;
    background-color: gray;
}

Both of these table row Style Templates should be mutually exclusive, since a row can only have one background color. Nonetheless both could be applied individually one without having an effect. To prevent the table row element to have both classes added these templates should be grouped with the -ro-style-template-group property.

-ro-style-template-group
Value: <string> | inherit
Initial: none
Applies to: depends on element type, see -ro-style-template
Inherited: no
Percentages: N/A
Media: all
Computed value: as specified

The optional property -ro-style-template-group describes which group the Style Template is in. A group makes its Style Template members mutually exclusive, meaning only one of the group's members can be applied.

If this property is not set a Style Template is put into a group with the same name as the template itself.

Some things need to be considered on grouping Style Templates:

  • All Style Templates should have the same element type.

    Actions will be created for those Style Templates only whose element type belongs to the majority of present element types in that group.

  • Style Template with same selectors should not be inside the same group

    If inside a group the selector of one matches another template's selector the selected state of one of both Style Template's actions will be wrong. Even though the Style Template is applied one of both actions won't be selected. It is a restriction that comes with the design principle of mutually exclusive members of the Style Template group.

<string>

The name of the group. It identifies the Style Template group inside Nimbudocs Editor. The case of this <string> is regarded.

Declaring a Style Template Group

The following inline styles belong to the "Severity Marker" group. It's members are not mutually exclusive to members the default inline type group. They exclude only each other.

This allows a user to mark a passage of text as important or unimportant but not both at the same time. These Style Templates can be applied in addition to others of the inline element type.

span.important {
    -ro-style-template: "Important" inline;
    -ro-style-template-group: "Severity Marker";
    color: red;
}
span.unimportant {
    -ro-style-template: "Unimportant" inline;
    -ro-style-template-group: "Severity Marker";
    color: gray;
}
-ro-style-template-context
Value: document | none | [<string>] | inherit
Initial: document
Applies to: depends on type, see -ro-style-template
Inherited: no
Percentages: N/A
Media: all
Computed value: as specified

The optional property -ro-style-template-context describes what context the Style Template may be used in. A context limits the Style Template to be used only on elements whose value of the -ro-context property equals one of those defined with this property.

document

The Style Template may be used throughout the whole document. This value is used by default.

none

The Style Template may not be used in the entire document. This option allows disabling Style Templates permanently.

string

The name of a context the Style Template may be used in. This context name refers to the context names defined via -ro-context-property.

Mutually exclusive Style Templates:

The container div.code creates a context "Code Box". The mutually exclusive paragraph Style Templates "Source Code" and "Commentary" should be made available exclusively inside this context.

div.code {
    -ro-context: "Code Box";
    background-color: gray;
}
p.code {
    -ro-style-template: "Source Code" paragraph;
    -ro-style-template-group: "Code Paragraphs";
    -ro-style-template-context: "Code Box";
    font-family: monospace;
    color: green;
}
p.commentary {
    -ro-style-template: "Commentary" paragraph;
    -ro-style-template-group: "Code Paragraphs";
    -ro-style-template-context: "Code Box";
    font-family: monospace;
    color: blue;
}
p.commentary:before {
    content: "//";
}
-ro-style-template-toggle-id & -ro-style-template-setter-id
Value: <string> | inherit
Initial: none
Applies to: depends on type, see -ro-style-template
Inherited: no
Percentages: N/A
Media: all
Computed value: as specified

The optional properties -ro-style-template-toggle-id and -ro-style-template-setter-id specify the ID of the Java actions created from this Style Template. The -ro-style-template-toggle-id stands for toggle actions created from the Style Template while -ro-style-template-setter-id stands for setter actions.

If one of these properties is not defined the related action's ID is generated and may change when Style Templates are (re)loaded. With a fixed ID an action created from a Style Template can be made part of a fixed user interface that retrieves the action by its ID.

<string>

The ID value the action created from the Style Template will receive.

Creating a Style Template for Inline Elements

The following Style Template will allow to create actions that inserts a span element with the "important" class set on it. The identifier of the toggle action will be "action-important" while the setter action would receive a generated ID.

span.important {
    -ro-style-template: "Important" inline;
    -ro-style-template-toggle-id: "action-important";
}

The Style Rule

There are certain rules for a style rule that need to be followed in order to create working Style Templates.

Selector Grouping

A Style Template can only be created from a style rule with a single selector or selector combination. Grouping of selectors is not supported.

/* Allowed for template definition */
h1.green {
    -ro-style-template: ... 
}
h1.red {
    -ro-style-template: ... 
}
/* Not allowed for template definition */
h1.green, h1.red {
    -ro-style-template: ...
}

Single Definition

The -ro-style-template property is the primary property for Style Template creation. Every other Style Template property  needs to be defined inside the same style declaration as the primary property.

/* Will create a template "Green Heading 1" with group and context */
h1.green {
    -ro-style-template: "Green Heading 1" paragraph;
    -ro-style-template-group: ...
    -ro-style-template-context: ...
}
/* Will create a template "Red Heading 1" with group */
h1.red {
    -ro-style-template: "Red Heading 1" paragraph;
    -ro-style-template-group: ...}
/* Will not add a context to "Red Heading 1" template */
h1.red {
    -ro-style-template-context: ...
}

Override as a whole

Overriding a Style Template cannot be done property by property. A Style Template can only be replaced as a whole. To identify the Style Template to be overridden the value of the -ro-style-template needs to stay the same. Otherwise the definition would just create a new Style Template.

/* Template definition */
h1.green {
    -ro-style-template: "Heading 1 green" paragraph;
    -ro-style-template-group: "Special Headings";
}
/* Does not override the group property */
h1.green {
    -ro-style-template-group: "Headings";
}
/* Overrides the group property */
h1.green {
    -ro-style-template: "Heading 1 green" paragraph;
    -ro-style-template-group: "Headings";
}

The default Style Template

A default action is a special setter action created explicitly to enable removing Style Templates from one group of Style Templates. This default action is usually created automatically but sometimes it is necessary to make additional settings for it. This is done by declaring a default Style Template from which a replacement default action will be generated.

Creating a default Style Template via CSS is much like creating other Style Templates. The same rules apply to it but there are additional rules for it's definition:

The :not(*) selector is intended to never apply on any element of the document. The default action's style rule exists purely for configuration purpose of the default action created from it. The name identifier default indicates that this is a special Style Template that is to be created from this style rule. The group name is declared to assign the default Style Template to a group.

A default Style Template will create a default action, which is retrieved like any other setter action but no toggle action will be available for it.

Using default Style Templates

The following example shows a group of Style Templates named Highlighter. Yellow and Green are the two highlighting Style Templates that should mark a text with colored background.

The default action declared below "Yellow" and "Green" is intended to remove this colored background. It may contain additional properties for configuration purpose.

Three Style Templates will be created from this CSS, the default action, Yellow and Green.

/* A group of Style Templates */
span.yellow {
    -ro-style-template: "Yellow" inline;
    -ro-style-template-group: "Highlighter";
    background-color: yellow;
}
span.green {
    -ro-style-template: "Green" inline;
    -ro-style-template-group: "Highlighter";
    background-color: green;
}
/* The group's default action */
:not(*) {
    -ro-style-template: default;
    -ro-style-template-group: "Highlighter";
    ...
}