Selectors in OL Connect

Selectors are patterns used to select one or more HTML elements. They were originally developed to be able to define the layout of web pages without touching their content, through Cascading Style Sheets (CSS). In OL Connect, since each section in a template is in fact an HTML file (see Editing HTML), the very same selectors can be used in style sheets (see Styling templates with CSS files) and Standard Scripts (see Personalizing content and Writing your own scripts). Using selectors for scripting can increase the speed with which a template and data are merged; see Use an ID or class as selector.

Standard CSS selectors

Selectors are made up of one or more of the following components:

  • An HTML element. Type the HTML tag without the angle brackets (e.g. p) to select all elements of that type (pselects all paragraphs).

  • A class. Type the class name, preceded by a dot, e.g.: .green, to select HTML elements with that class.

  • An ID. Type the ID, preceded by #, e.g.: #intro, to select an HTML element with that ID.

    Note: In an HTML file, each ID should be unique. This means that a particular ID can be used only once in each section.

  • An attribute of an HTML element. Type the attribute and, optionally, its value, between square brackets, e.g.: [target], to select HTML elements with a matching attribute.

  • A pseudo-class. For example, tr:nth-child(even) selects all even table rows.

These components can be combined in different ways. For example, p div selects all paragraphs inside <div> elements, while p, div selects all paragraphs and all <div> elements.

A complete list of selectors and ways to combine them, and a tool that demonstrates their use can be found here: MDN Web Docs - CSS Selectors.

A video about CSS and Script Selectors, can be found here: Connect with Evie 6 - CSS and Script Selectors.

OL Connect classes and attributes

OL Connect itself sometimes adds a specific class or attribute to elements in a template. Capture OnTheGo widgets, for example, have a role attribute that allows the COTG library to dictate their behaviour. OL Connect-specific classes and attributes can be used in selectors, as will be explained and demonstrated below.

OL Connect-specific classes usually are invisible in the Designer. By opening the currently selected section in your default web browser (click the Preview HTML toolbar button) and using the browser's code or source inspector you can see most of the dynamically added classes.

Caution: Avoid using classes with the __ol prefix in your selectors. These dynamically added class names may change in future releases of the software.

Section selector

The Designer writes the name of each section to the section attribute of the <html> element. This attribute can be used in selectors.

Note: To make scripts run exclusively on certain sections, it is advised to put them in folders and set the execution scope of the scripts in a folder via the folder properties; see Execution scope.

Example: The following rule applies formatting to <h1> elements in sections of which the name starts with ‘Letter’:

[section^='Letter'] h1 {

color: brown;

}

Note: To target sections as well as Master Pages, use the body selector without the masterpage or section selector. For example:

  • Selector: body

  • Script: results.html('<div style="background:red;width:1in;height:2in">Hello World</div>');


In versions prior to 2019.2 the section selector would work on sections as well as Master Pages. As of version 2019.2 this is no longer the case. The section selector now only selects sections.

Master Page selector

The Designer writes the name of each Master Page to the masterpage attribute of the <html> element. This attribute can be used in selectors.

Note: In the output, content in Master Pages is affected by style rules targeting <html>, but not by style rules targeting the <body> element. This is because in the output, they are placed outside the <body> of the section to which they are applied.
When editing a Master Page, style rules targeting the <body> element will work, because the Master Page is not currently applied to a section, but they will have no effect in the output.

Examples

This script adds a box to the body of every Master Page.

  • Selector: [masterpage] body

  • Script: results.html('<div style="background:red;width:1in;height:2in">Hello World</div>');

The following script adds the box only to the Master Page called "Master Page 1".

  • Selector: [masterpage="Master page 1"] body

  • Script: results.html('<div style="background:red;width:1in;height:2in">Hello World</div>');

Sheet position selectors

In Print output, pages have a sheet position that depends on the options set in the Sheet Configuration dialog (e.g. the Duplex and Allow Content On options). Connect gives each page - or rather, the "MediaBox" div element on that page - a class depending on their sheet position:

  • .frontside

  • .backside (does not apply to simplex documents)

  • .contentpage

  • .nocontentpage

The MediaBox contains the Master Page objects and section backgrounds. This means that these classes can only be used to format a Master Page and section background. They do not let you change the formatting of elements residing in the main text flow (e.g. a <h1> element on page 3).

Formatting Master Page objects depending on the sheet position

The following CSS rule sets the color of <h1> elements on a Master Page when that Master Page is present on the front of a sheet.

.frontside h1 {
	color: green;
}

The next style rule is a bit more specific: it colors <h1> elements on a Master Page when that Master Page is applied to the front of a sheet in Section 1:

[section='Section 1'] .frontside h1 {
	color: green;
}

The following rule hides <h1> elements on the back of a sheet on which no content (from the main text) is allowed.

.backside.nocontentpage .h1 {
	display: none;
}

Print section background selector

When you inspect a Print section in a browser, you will see that it has a <div id="pages"> element as the first child of the <body> element. Inside this <div> there are one or more MediaBoxes: elements with the class page_mediabox. Each MediaBox contains the Media, section background and Master Page that apply to one page (see Media, Master Pages and Using a PDF file or other image as background).

In the MediaBox, a Print section background is an <img> element with the ol_pdf_datamapper_input class. Its src attribute references the PDF file that contains the image and the page parameter is used to select a specific page in that PDF (as a PDF can contain more than one page).
For example:
<img src="file:/C:/Users/MyUser/Pictures/mixed.pdf?page=1" class="ol_pdf_datamapper_input">.
You can use the ol_pdf_datamapper_input class as a selector to target the section background in a style rule or script.

Placing the section background in front of the Master Page

The stacking order of elements inside each MediaBox, from bottom to top, is:

  1. Media

  2. Section background

  3. Master Page elements

Using the .page_mediabox selector, you could change this stacking order and place the section background on top of the elements on the Master Page. Set the z-index property to a value larger than 0 (zero) and add !important to make this style rule override the inline style declaration that normally puts the section background behind the Master Page elements:

Copy 
.page_mediabox img.ol_pdf_datamapper_input {    
    z-index: 10 !important;
}

Scaling the section background

The rule below downscales the section background image and keeps it in the centre of the page:

Copy 
.page_mediabox img.ol_pdf_datamapper_input {    
    transform: translate(-50%, -50%) scale(1.5, 1.5) !important;
}

View selectors

In the Designer, sections can be viewed on different tabs: Source, Design, Preview and - if it is a Web section - Live. In each view mode (except Source) a specific CSS class is added to the <html> element. The view-specific classes are:

  • .DESIGN

  • .PREVIEW

  • .OUTPUT

.OUTPUT is used when viewing the current section on the Live tab or in an external browser, and when generating output.

View selectors allow you to apply formatting to elements in a certain view, for example to highlight or show elements. The Designer itself does this, for example, to highlight all boxes in the Design view, when the Show Edges icon is clicked.

Adding an outline

The following style rule wraps every element that has the class address-block with a purple dashed outline in Design mode. The outline is not visible in other views or when outputting the document.

Copy 
.DESIGN .address-block {    
    outline: 1px dashed purple;
}

Adding a background pattern

The Postcard template wizard (in the Basic Print templates group) uses the .DESIGN class to mark areas that are reserved for postal use and should not contain text or images. These areas were added to the Master Page as absolute positioned boxes that have been given the class clearzone. The following style rule assigns a background pattern to elements with that class in the Design view:

Copy 
.DESIGN .clearzone {    
    background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAAFUlEQVQImWNgQAL/70z7TyqHgYEBANRfDcEzmlBaAAAAAElFTkSuQmCC) repeat;
}

Note: The pattern image was created on www.patternify.com and is added as a data URI (see Data URIs).

Showing hidden Foundation elements

In Capture OnTheGo templates based on the Foundation framework the .DESIGN selector can be used to show elements that would otherwise be hidden in the Design view.
For example, to expand accordion elements and show validation errors in Design view, you could add the following style rules to your template:

.DESIGN .accordion .accordion-navigation > .content {
	display: block;
}
.DESIGN small.error {
	display: block;
	margin-top: -20px;
}