Style with Attributes

Every element has a set of attributes, which are properties that define the element's characteristics. For each attribute, there is a value, and by changing the value, you can control how Paligo uses the element.

Some common examples of how you can use the element attributes are:

Set the width attribute of an imageobject to control its size in the output, for example, width: 50%
Set the role attribute of a section to accordion so that the section appears as a collapsible section in the output
Set the audience attribute of para to developer so that the paragraph only appears in content aimed at developers.

Style with Attributes are handled in the Element Attributes Panel. You can use the advanced search to find components that contain specific attributes and profiling values, see Search for Attributes.

By selecting the element, currently applied attributes and values are shown in the Element Attributes Panel (1). You can add extra attributes from the Add attribute drop-down menu (2). If you add an attribute, you also need to set its value in the field next to the attribute name (1). You can also use the fields to change any existing attribute values. To find out more, see Add Attributes.

1 = Element attributes panel, 2 = Add attribute drop-down menu

Tip

If a topic contains information about several products, it can be suitable to create Favorite Profiles that contain certain filters and variables to switch on when viewing content or sending content to reviewers or contributors.

Supported Attributes

Paligo is based on DocBook 5.1 and supports most of the attributes that are included in that content model. Read more about DocBook 5.1. But there are some differences to consider that Paligo:

Uses the <article> element for publication topics, see Supported Info Elements.
Uses the <section> for topics.
Does not support other root-level elements such as <book> and <set>.

Caution

Paligo also supports some "internal attributes" such as xinfo:image, xinfo:resource, and xinfo:text. These "internal attributes" are created and maintained automatically by Paligo and are used for allocating IDs to elements. You should not edit them.

Filter Attributes to include or exclude content, see Filtering / Profiling and Create Profiling Values.
Width attributes for adjusting image sizes.
Role attributes for various features, including collapsible sections and adding class names to HTML, see Role Attribute Values.

Element attributes panel. The td element is selected and it has a style attribute. The value of the style attribute is set to background-color:bg1

Above Style is the attribute and background-color:bg1 is the value.

Paligo supports the Filter Attributes as well as the following attributes:

Attribute	Description
depth	Use on the `imagedata` element to set the image depth (height) value in relation to the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
contentdepth	Use on the `imagedata` element to set the image depth (height) value and has no effect on the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
contentwidth	Use on the `imagedata` element to set the image width value and has no effect on the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
continuation	To get a continued numbering in sidebars, see Use Numbering in Sidebars.
label	Use on a topic's `section` element to prevent it being numbered in a PDF output (a value of `0` means no numbering).
language	Use on a `programlisting` element to set the language for a code sample, see Syntax Highlighting.
role	Use the role attribute with specific values to set Paligo to provide particular functionality, see Role Attribute Values
scalefit	Allows an image to be scaled up or down to fit within available space. If `scalefit="1"` the image is scaled (with the same factor in both dimensions) so that the graphic will just fit within the available height or width (whichever is more constraining). If any other image size attribute is specified, those attributes determine the graphic size and `scalefit` will be ignored.
style	Style the background colors for individual individual table cells (`td` or `th`) for PDF output, see Style Table Body (PDF).
tabstyle	Style the `table` element to use compact paragraph spacing, see Set Table Cell Paragraph Spacing.
width	Use on the `imagedata` element to set the image width value in relation to the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
xinfo:appid	Use on the `section` element when setting up context-sensitive help, see Context-Sensitive Help. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:chunk	Use on the `section` element to instruct Paligo to keep a topic as a separate page in HTML outputs, see Create Subsections. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:keep-together	To control the flow of elements over two pages in PDF outputs, see Soft Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:keep-with-next	To control the flow of elements over two pages in PDF outputs, see Soft Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:outname	Use on the `section` element to control the URL for the topic when it is converted into a page for HTML outputs. The value that you enter is used as the URL, see Topic File Names. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:pagebreak	To set a hard page break in PDF outputs, see Hard Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xlink:href	To make images work as links, see Turn Images and Other Elements into Links.
xlink:show	To override the default link behavior for individual links, see Update Individual Link Behavior.

Tip

To learn how to add an element attribute, see Add Attributes.

Role Attribute Values

You can use the role attribute with specific values to set Paligo to provide particular functionality. There are many possibilities, including adding class names to HTML outputs, adding extra-responsive features to HTML tables and controlling wrapping in PDF output.

Element attributes panel. The role attribute is added and it has a value of extra-responsive

Tip

If you already have a role attribute, separate the values with a semi-colon.

The following table shows the role attributes and values that you can use in Paligo.

Attribute value	Description
accordion	Use to create a collapsible `section`. The section title is shown and when the user selects it, the section expands to reveal the content, see Accordions (Collapsible Sections).
column-count	Use to set the number of columns in a `sidebar` element in PDFs, see Enable Multi-Columns (PDF).
column-gap	Use to set the amount of space between columns in a `sidebar` element for PDFs, see Enable Multi-Columns (PDF)).
extra-responsive	Use on `table` elements to set them to add a sticky header and column filter to a table for HTML5 outputs, see Enable Column Filter and Sticky Header.
font-size	Use to set the size of the lettering on a verbatim element, such as `programlisting` , see Verbatim (code and software).
<free text>	Can be used on any element and you can enter any text as the value, for example, role: online-image. The value is used as a class name in HTML outputs. This only applies if the HTML layout is set to include the role attribute as a class name, see Classes and Attributes HTML5.
img-thumbnail	Use on `mediaobject` elements to set them as small "thumbnail" images in HTML outputs, see Thumbnail Images.
img-thumbnail-reset	Use on `mediaobject` elements to prevent them from being presented as small "thumbnail" images in HTML outputs, see Thumbnail Images.
multi-publication-portal	Use on `article` elements when publishing multiple publications to the same help center, see Multi-Publication Portal.
notintoc	Use on `section` elements to prevent a topic from appearing in the table of contents in PDF outputs, see PDF Layout Editor Options.
portal-category	Use on the `section` element to create category panels for topics in HTML help center outputs, see Topics for Category Panels.
promoted-content	Use on the `section` element to set a topic as "featured content", see Topics for Featured Content.
reuse-range	Use on `procedure` and `orderedlist` elements when you want the steps/items to continue the numbering sequence of a previous procedure or list, see Reuse Items in a List.
swagger-topic	Use on the `section` element when embedding Swagger/Open API content in Paligo for publishing to: HTML help center, see Embed Swagger OpenAPI Zendesk, see Embed Swagger OpenAPI for Zendesk
top-nav-link	Use on the `section` element to add a link to a topic from the top-navigation menu, see Add Top-Navigation Links to Topics.
wrap-option	Use on verbatim elements, such as `programlisting`, to control line wrapping, see Verbatim (code and software).

Add Multiple Values to an Attribute

Element attributes are properties that you can add to an element, such as a section or table. There are many different attributes you can use, and you add them in the Element attributes panel (see Style with Attributes). When you add an element attribute, you also have to set its value. Typically, they have one value, but you can add multiple values when needed.

For example, if you want to use the role attribute to assign a class name to a section and also make it collapsible, you would need to add two values. In this case, "accordion" to make it collapsible and then another value for the class name.

To add multiple values:

Use the Element attributes panel to add an attribute to an element.
Enter the values in the field next to the attribute. Separate the values like this:
- Use a semi-colon to separate values. For example, here, the role attribute is given two role values: accordion and subsection. A semi-colon is used to separate the values.
```
role="accordion;subsection;"
```
- Use a colon to separate "keys" from values. "Keys" are properties that can have values. They are only suitable for certain attributes, such as the style attribute that you can give to a table element. For example:
```
style="border-style:solid 2px;border-color:blue;"
```
  Here, the attribute is style. The first key is border-style and it is separated from its value (solid 2px) by a colon (:). The second key is border-color and it is separated from its value (blue) by a colon (:). Each key and value pair is separated from the next by a semi-colon (;).
Select Save.

Note

Some attributes allow the space character as a separator. For example, if you add a role attribute and set its value to "specifications table", it will get two class names in HTML when it is published. In the HTML, it will appear as class="specifications table" which means "specifications" is a class and "table" is a different class.

For this reason, it is best practice to avoid using spaces inside a value that you want to become one class. For example, use "specifications-table" as this will be one class, rather than "specifications table" which will be two classes.

Prevent Numbering (HTML5)

You can choose to have numbered headings, such as "1.2 Power up the device" in your HTML5 output.

Typically, you apply numbering to all sections (by enabling General > TOC and Chunking > Section Numbering in the Layout Editor) or not using numbered headings at all.

But there may be times when you need a mix of numbered headings and headings without numbering and for that, you can use the element attribute label with its value set to 0.

When you publish topics that use this element attribute, Paligo will not apply numbering to its heading, even if the publication is set to use numbered headings. The heading will appear as text-only, both in the topic itself and in the table of contents.

To prevent a topic from being auto-numbered:

Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Select the section element in the Element Structure Menu.
Select Go to element.
Add the label attribute in the Element Attributes Panel.

The 0 value instructs Paligo to avoid using numbering for this section.
Set the value to 0.
Select Save.

Note

To enable numbering again, remove the label attribute.

Add your Own Class Names

When you publish to an HTML-based output, Paligo automatically adds class names or IDs to many of the HTML elements in the output. This is so that they can be styled using CSS.

But you can also add your own class names if needed. This is especially useful if you want some elements to be styled differently. For example, you can add it to:

a table element to create different-looking tables (such as information tables and parameter definition tables).
a mediaobject element if you want different types of images to behave differently.

There are two ways to add class names:

Add a role attribute and its value becomes the class name, see below.
Use taxonomies, see Taxonomies as HTML Classes and Custom Class Names for Images - Taxonomy Tag.

Note

You do not add class names directly to the HTML. Instead, you add class names to the Paligo XML that becomes the HTML when you publish. Paligo then includes your class name when it generates the HTML output.

Warning

Only add your own class names if there is no other way. Otherwise, you might end up with unstructured content as every topic can have unique roles.

To style elements with your own class name:

Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Select the element that you want to style in the Element Structure Menu.

For example, to style a table differently from other tables, select its table element.
Add the role attribute in Element Attributes Panel and enter the class name as the value.

Note

Use a role class name that does not clash with any of the other names already used by Paligo, see Role Attribute Values.

We recommend that you create unique names that are easy to understand and are specific to your organization, for example, "acme-leadtable". This will help to avoid clashes with existing or future class names.
Select Save.
Repeat this process for any other elements that you want to style differently.
Publish your content to generate an output with your custom class name(s) included.

When you publish, Paligo will add the class name to the HTML element. You can then use CSS to style that class, see Style with CSS.

Context-Sensitive Help

With Context-Sensitive Help (CSH), your users can select a part of your product interface to display the relevant help page. For example, with a software product, you could have an "Info" icon next to a "Balance" option. When the user selects the "info" icon, the help page about the "Balance" feature is opened automatically, so they are taken directly to the relevant information.

Traditionally, context-sensitive help is made by creating a mapping file. The mapping file, sometimes known as a header file, is used to match an id in your product to the id of a page in your documentation. Paligo uses this type of approach for HTML5 outputs and creates the mapping file automatically, as long as you have certain attributes in place.

To set up context-sensitive help, we recommend that you first Create a Mapping File for CSH and then Create a Fallback Page for CSH.

Note

If you need to publish any other type of context-sensitive help, please contact support for assistance.

Create a Mapping File for CSH

To get Paligo to automatically create the mapping file for context-sensitive help:

Get the ids for the application components in your product.
Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Select the section element in the Element Structure Menu.
Select Go to element.
Add xinfo:appid attribute in Element Attributes Panel and enter the id of the relevant application component in your product.

If there are multiple components calling the same topic, separate them with semicolons. For example: imagedialog_123;imagebrowser_234

Tip

Adding the xinfo:appid attribute to the top section element is the typical use case. It is also possible to put xinfo:appid on a sub section inside a topic. The only requirement is that the sub section also has an xml:id, which it would normally have by default.

If you mark up a sub section, the context sensitive help will open the topic at that location on the page, rather than at the top.
Select Save.
Publish your publication. This creates a JSON file that automatically maps any url requests to the relevant topic.
In your product, your developers can call the context-sensitive help using the internal application id's as a string parameter. For example:

www.youronlinehelp.com/en/index-en.html?contextId=imagedialog_123

where:
- www.youronlinehelp.com is the domain where you host your published documentation. In reality, you will have something different, such as your organization's website URL.
- en/index-en.html is the folder and index file for an English version of your documentation.
- ?contextId=imagedialog_123 is the context-sensitive help reference.
The call needs to specify the language folder and the help's index file before the context-sensitive help reference.

Note

To test the context-sensitive help, either:

Publish it to your server or a test server (local or web server). This is because the function of fetching data from JSON requires the content to be on a server for browser security requirements.
Select to enable local context-sensitive help in the Layout Editor (under General). You can enable this temporarily while testing, and then disable it again when you are ready to publish to your server.

Create a Fallback Page for CSH

We recommend that you create a fallback page, in case there is a problem with one of your context-sensitive help links or pages. The fallback page will be shown if the target page of the context-sensitive link cannot be found.

To create a fallback page for context-sensitive help:

Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Select the section element in the Element Structure Menu.
Select Go to element.
Add the attribute xinfo:appid in the Element Attributes Panel and set the value to not_found.
Add the attribute role in the Element Attributes Panel and set the value to notintoc.

This role will prevent the fallback page from appearing in the table of contents.

Note

This is an optional, but recommended step.
Select Save.
Publish your publication.

When you publish your publication, the topic will be used as the fallback page. If the browser cannot find the topic for a context-sensitive help link, it will display the fallback page instead.

Articles in this section

Tip