Selectors in 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 Connect, since each section in a Connect 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 template scripts (see Personalizing Content and Writing your own scripts). Selectors can increase the speed with which a template and data are merged; see Use an ID 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 (p selects 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.
    • 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 at W3Schools: https://www.w3schools.com/cssref/css_selectors.asp.

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

    Connect classes and attributes

    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. Connect classes and attributes can be used in selectors, as will be explained and demonstrated below.

    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.

    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.

    Example

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

    [section^='Letter'] h1 {

    	color: brown;

    }
    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.

    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).

    Conditionally formatting Master Page objects

    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 as background image).

    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 its page attribute 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:

    .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:

    .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.

    .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:

    .DESIGN .clearzone {

    	background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAAFUlEQVQImWNgQAL/70z7TyqHgYEBANRfDcEzmlBaAAAAAElFTkSuQmCC) repeat;

    }
    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;

    }