Web Designer Themes and Pluggable Objects: Introduction

Table of Contents

1. Environment

The Web Designer environment currently contains following web applications:

Table 1. Environment
Web App URL Main purpose

Web Designer

https://design-app-eu1.scripturaengage.com

Template design

Resource Browser

https://browse-app-eu1.scripturaengage.com

Management of Scriptura resources such as templates, themes and pluggable objects

2. Known limitations

  • Spaces and tabs inside of your Pluggable Object or theme are not removed from the output.

3. Templates

The Web Designer web application can be used to link the following to a template:

  • 1 or more themes to control the look and feel of the template.

  • 1 data model providing data fields and sample data to the template.

  • 1 or more languages for supporting multilanguage templates.

Web Designer templates support two classes of object types:

  • Built-in objects provided as part of the standard Web Designer product.

  • Customer specific pluggable objects that extend the Web Designer object collection.

4. Themes

Themes define the look and feel of a template but they can also include content. Content included in a template by applying a theme cannot be deleted and/or edited in Web Designer.

A theme can for example include a company logo and a standard header and footer as content. A template designer applying this theme to a template would not be able to change or delete these objects from the template using Web Designer.

no theme applied
Figure 1. A template with no theme applied
kodu theme applied
Figure 2. The same template with the Kodu theme applied

4.1. Manage Themes

The Manage Themes page is used to approve and reject themes in order to control availability of themes to the template designers. The page can be reached through the Workspace menu in the Web Designer top bar. Note that in order to access this page, the user needs to have the webdesigner:themes:manage permission.

Themes uploaded to the Design Studio will be available for approval on the Manage Themes page. A theme which is marked with the approved icon icon is approved and can be used in templates. Administrators will have the ability to reject a previously approved theme, and themes will also be automatically rejected if they are modified. A theme marked with the rejected icon icon is not approved and is therefore unavailable to template designers. Administrators can review and approve themes by pressing the approval button.

manage themes overview
Figure 3. The Manage Themes page

The Manage Themes page provides an overview of available themes along with their approval status.

1 The name of the theme as it will be shown to the template designers.
2 The location of the theme in the Scriptura Engage Cloud Platform.
3 The author of the theme.
4 The approval status of the theme.
5 Approve / Reject buttons

When approving or rejecting a theme it will be approved/rejected account-wide based on its contents. If there are other copies of the theme in different projects but within the same account they will automatically also be approved/rejected. This is to prevent you from having to reapprove themes each time they are reused.

4.2. Creating themes

A theme is defined by an HTML document containing specific metadata tags. The metadata tags should be the first children of the <head> element.

Table 2. Theme metadata
Name Description

scriptura:wbd:type

Identifies the HTML file as a theme and should have value html-theme

scriptura:wbd:name

Name of the theme

scriptura:wbd:author

Author of the theme

Minimal theme example
<html>
  <head>
    <meta name="scriptura:wbd:type" content="html-theme">
    <meta name="scriptura:wbd:name" content="My theme">
    <meta name="scriptura:wbd:author" content="John Doe">
  </head>
  <body>
    <p>This is my first theme</p>
  </body>
</html>

When designing themes you have to take into account a number of restrictions:

  • Only use absolute URLs to point to the CSS file to use. Do not use relative URLs.

  • Only use absolute URLs to point to images. As with CSS files, do not use relative URLs.

  • Do not use the HTML style attribute as this attribute will be removed from the theme automatically. Use styles and the HTML class attribute instead.

When you are done designing your theme, you can upload it to the Design Studio through the Resource Browser. The theme will automatically be listed on the Manage Themes page, where it can be approved. Once the theme is approved, it will be available to template designers.

4.2.1. Adding designer content in your theme

In order to integrate designer content into your theme, you can mark insertion points using the {{designer-content}} handlebars instruction.

Using a theme with a single insertion point for designer content
<html>
  <head>
    <meta name="scriptura:wbd:type" content="html-theme">
    <meta name="scriptura:wbd:name" content="My theme">
    <meta name="scriptura:wbd:author" content="John Doe">
  </head>
  <body>
    {{designer-content}}
  </body>
</html>

It is possible to add multiple designer content insertion points in your theme, provided you specify a unique name attribute for each of them. When there is only one insertion point, the name attribute can be omitted.

Using a theme with multiple named insertion points for designer content
<html>
  <head>
    <meta name="scriptura:wbd:type" content="html-theme">
    <meta name="scriptura:wbd:name" content="My theme">
    <meta name="scriptura:wbd:author" content="John Doe">
  </head>
  <body>
    <div class="banner">
      {{designer-content name="banner"}}
    </div>
    <div class="body">
      {{designer-content name="body"}}
    </div>
    <div class="footer">
      {{designer-content name="footer"}}
    </div>
  </body>
</html>

4.2.2. Using data in your theme

Themes can also refer to data within the currently linked data model. To do this, simply add references to data fields between {{ and }}. As soon as the theme is loaded, the data will be resolved relative to the root of the chosen data model.

However, note that the Web Designer does not enforce a coupling between the theme and the chosen data model. It is possible that template designers choose an incompatible data model which will result in the data fields being resolved to empty data.

Using data in theme
<html>
  <head>
    <meta name="scriptura:wbd:type" content="html-theme">
    <meta name="scriptura:wbd:name" content="My theme">
    <meta name="scriptura:wbd:author" content="John Doe">
  </head>
  <body>
    <div class="banner">
      <img src="{{company.logo}}">
    </div>
    <div class="body">
      {{designer-content name="body"}}
    </div>
    <div class="footer">
      <p>{{company.address.street}}</p>
      <p>{{company.address.zip}} {{company.address.city}}</p>
    </div>
  </body>
</html>

4.2.3. Defining styles in your theme

A theme could define a set of styles. The template designers can then choose a style to change the look and feel of the template. If your theme does not provide any styles, the default list is used.

Defining custom styles

You define a style by adding a comment to your CSS in the following format:

Name Description

@scriptura:wbd:style:name

Human readable name for the style

@scriptura:wbd:style:requires (optional)

Comma separated list of valid objects types. Possible values: Text, Container, Image, ReusableComponent, <Pluggable object id from component definition>

@scriptura:wbd:style:class (optional)

You can optionally define a class. When no class is provided we will extract it from the following rule provided it is a simple class selector.

example
<html>
  <head>
    <style>
      /*
        @scriptura:wbd:style:name = Header 1
        @scriptura:wbd:style:requires = Text
        @scriptura:wbd:style:class = header-1
        @scriptura:wbd:style:name = Header 2
        @scriptura:wbd:style:requires = Text
        @scriptura:wbd:style:class = header-2
        @scriptura:wbd:style:name = Header 3
        @scriptura:wbd:style:requires = Text
        @scriptura:wbd:style:class = header-3
      */

      /*
        @scriptura:wbd:style:name = Footer
        @scriptura:wbd:style:requires = Container, pluggable-object-section
      */
      .footer {
        color: blue;
      }
    </style>
  </head>
  <body>
    {{designer-content}}
  </body>
</html>

We only parse embedded styles, so this will not work with style sheets hosted on a remote server. You can work around this by hosting the style sheet on the remote server and adding a style tag with all your styles defined in one comment.

4.2.4. Using responsive images

HTML5 offers a number of features to support responsive images such as srcset, sizes and picture. See https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images for more information.

Using images with different DPIs in PDF output

The srcset feature of HTML5 and image-set CSS function can be leveraged to select images with the correct DPI when generating PDF output. This can be useful when for example you want to generate previews with low DPI images and the final output with high DPI images. To do this, first enable the required feature (HTML or CSS version) in the theme definition. Then define the set of images using the srcset attribute and set the Device pixel ratio property to the corresponding value when generating PDF output depending on which image you want.

This works for both the Xribe Output API and the Web Designer output step.

Example usage:

...
<head>
  <script id="theme-definition" type="application/json">
    {
      "profile": {
        "pdf": {
          "src-set": true,
          "image-set": true
        }
      }
    }
  </script>
  <meta charset="utf-8">
  <meta name="scriptura:wbd:type" content="html-theme">
  <meta name="scriptura:wbd:name" content="My theme">
  ...
  <style>
    body {
      background-image: image-set(
        url('http://example.com/img/lores.png') 1x,
        url('http://example.com/img/hires.png') 2x
      );
    }
  </style>
</head>
<body>
...
  <picture>
    <img
      srcset="http://example.com/img/lores.png 1x, http://example.com/img/hires.png 2x"
      src="http://example.com/img/lores.png"
      alt="My image" />
  </picture>
...

You can also use the browser specific versions -webkit-image-set() and -moz-image-set().

The sizes attribute, dpi-descriptors, w-descriptors and other absolute units are not supported. Only x-descriptors to indicate display resolution are supported.

For more information on how to set the Device pixel ratio property, refer to the Xribe Output API documentation or the Scriptura documentation that came with the Web Designer output step extension.

We recommend to only enable the option that you need as these can have a performance impact when generating PDF output for larger templates.

4.3. Styling built-in objects

4.3.1. Spacer

A Spacer is useful for creating space between objects. To provide support in email clients, the Spacer will be rendered using a table element when creating email output. It is allowed to style the Spacer object by using the spacer-object class in a theme, but styles relying on the corresponding element type and its possible child elements are not supported. Those change depending on output type. Additionally, this is implementation.

Example of styling a Spacer object
.spacer-object {
  /* providing extra margin */
  margin: 16px;
}

4.3.2. Divider

A Divider is useful for dividing several objects. The Divider object consists of a hr element wrapped in a div. It is supported to style both the div and the containing hr element using the divider-object class in a theme.

Example of styling a Divider object
.divider-object hr {
  /* making the Divider a red line */
  border-top: 1px solid red;
}

4.3.3. QR Code

A QR code object allows template designers to encode data in the form of a QR code. The actual QR Code is generated as an SVG image, wrapped with a div element. Because of the SVG format, a QR code will not be rendered when creating email output. Styling of the svg element is not supported, but the surrounding container can be styled by using the qr-code-object class name. As an example, making a QR code centered on the page:

Example of styling a QR Code object
.qr-code-object {
  /* centering the QR code */
  text-align: center;
}

4.3.4. Table

A table object is a built-in object that allows template designers to represent information in the form of a table. The table object does not contain any styling apart from a margin and a 100% width. Since we render the table object as a regular HTML table, you can use regular CSS rules to style the rendered table.

Example of styling a table object
table,
th,
td {
  border: 1px solid #c6c8cb;
}

table {
  border-spacing: 0;
  border-collapse: collapse;
  width: 100%;
  table-layout: fixed;
}

table tr {
  margin: 0;
  padding: 0;
}

table th,
table td {
  border-right-width: 0;
  border-bottom-width: 0;
  vertical-align: top;
  padding: 8px;
}

4.3.5. Using headless content theme

Design Studio supports defining headless output properties which can be used to generate headless content that can be consumed by backend systems. In order to define headless output properties, add a new script tag to your existing HTML theme with the special marker ID output-properties-definition. It is best practice to mark the type of this script element’s contents as application/json. An example of the headless output properties definition can be found below.

Example of the headless theme (include some comments to explain the structure).

<html>
  <head>
      <meta name="scriptura:wbd:type" content="html-theme">
      <meta name="scriptura:wbd:name" content="headless_theme_1">
      <meta name="scriptura:wbd:author" content="John Doe">
      <script id="output-properties-definition" type="application/json">
          {
              "name": "Headless",
              "output": {
                  /* The target will be used to determine the ID of the final output containing the headless output properties. */
                  /* When generating output using the Compose Runtime, the target will be the name of the output in the deliverable. */
                  /* On the other hand, when generating output using the Scriptura Engage Document Flow step, */
                  /* the target will be available in the property data source of the output flow object containing the output properties. */
                  "target": "headless"
              },
              "definition":
              [
                {

                  /* A unique ID identifying the spec entry */
                  "id": "title",

                  /* Label supports multilingual labels or single string */
                  "label": {
                      "en": "Title (required)",
                      "nl": "Titel (gewenste)"
                  },

                  /* 1 or more targets specify the location(s) in the final output where the rendered*/
                  /* content for this entry will be injected*/
                  "targets": [
                      "message.title",
                      "push.title"
                  ],

                  /* The resulting JSON type. Possible values are “string”, “boolean”, “number” or “array”.*/
                  /* In the case of an “array” type, the item type must be specified as well. */
                  /* When omitted, the resulting type will fallback to string.*/
                  "resultType": "string",

                  /* Priority specifies whether the field is "required", "important" (shown by default) or*/
                  /* "optional" (hidden by default but shows when expanded)*/
                  "priority": "required",

                  /* Specifies whether the entry is language sensitive. The default value is true.*/
                  "languageSensitive": false,

                  /* Support multiline content. When omitted or false, the entry will be single line*/
                  "multiline": false,

                  /* Specifies how many text lines will be showing if "multiline": true else*/
                  /* default text object is showing with 1 text line*/
                  "rows": 6
                },
                {
                  "id": "remark",
                  "label": {
                      "en": "Remark (optional)",
                      "nl": "Opmerking (optioneel)"
                  },
                  "targets": [
                      "message.remark",
                      "push.remark"
                  ],
                  "resultType": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      }
                  },
                  "priority": "optional",
                  "languageSensitive": false,
                  "multiline": true,
                  "rows": 6
              }
            ]
          }
      </script>
  </head>
<body>
    {{designer-content name="abc"}}
</body>
</html>

The actual example of the headless theme.

<html>
  <head>
    <meta name="scriptura:wbd:type" content="html-theme">
    <meta name="scriptura:wbd:name" content="headless_theme_1">
    <meta name="scriptura:wbd:author" content="John Doe">
    <script id="output-properties-definition" type="application/json">
      {
        "name": "Headless",
        "output": {
            "target": "headless"
        },
        "definition":
          [
            {
              "id": "title",
              "label": {
                  "en": "Title (required)",
                  "nl": "Titel (gewenste)"
              },
              "targets": [
                  "message.title",
                  "push.title"
              ],
              "resultType": "string",
              "priority": "required",
              "languageSensitive": false,
              "multiline": false,
              "rows": 6
            },
            {
              "id": "remark",
              "label": {
                  "en": "Remark (optional)",
                  "nl": "Opmerking (optioneel)"
              },
              "targets": [
                  "message.remark",
                  "push.remark"
              ],
              "resultType": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
              },
              "priority": "optional",
              "languageSensitive": false,
              "multiline": true,
              "rows": 6
          }
        ]
      }
    </script>
  </head>
  <body>
      {{designer-content name="abc"}}
  </body>
</html>

After the theme is approved and used in a template, the template designer will show additional text fields above the template allowing the user to specify the output properties content.

headless theme demo

Additional input fields are rendered based on the headless ouptut-properties-definition script tag.

When generating output with the Compose Runtime API, JSON output result are generated, for example:

{
        "message":{
              "title":"abc",
              "remark": ["xyz1"]
        },
        "push":{
              "title":"abc",
              "remark": ["xyz1"]
        }
}

5. Pluggable objects

5.1. Introduction

Web Designer includes four builtin object types:

  • Text objects.

  • Image objects.

  • Container objects.

  • Table objects

Other object types listed in the Add Object panel are customer developed pluggable objects, highlighted in the following figure.