Components

Components can be used to display different form of content to the end user. This content can either be read-only (e.g. text component) or interactive (e.g. list input component).

The following keys are available and/or required in all components.

Key Type Possible values Explanation Is Required
Type String Text, Image, Web, Button, AppMonitor, Input Identify the component you want to use ⚠️
Margins Margins - Add padding to the component

Display Components

These allow you to display content to the end user.

Text component

This component allows you to display a short message to the end user.

Key Type Explanation Is Required
Text String The component text, which will be displayed as content ⚠️
TextFontConfiguration FontConfiguration Lets you configure how the text should appear
Example

    <dict>
        <key>Type</key>
        <string>Text</string>
        <key>Text</key>
        <string>Lorem ipsum dolor sit amet...</string>
    </dict>
    

Image component

Displays an image at a given URL.

Key Type values Explanation Is Required
URL String The URL of the image to display. Can be local or online.
Note: required if no mode URL keys are specified
LightModeURL String If you want to propose a different image depending on the mode, you can specify here the image URL for the light mode.
Note: if this key is specified, is is required to specify the DarkModeURL key too
DarkModeURL String If you want to propose a different image depending on the mode, you can specify here the image URL for the dark mode.
Note: if this key is specified, is is required to specify the LightModeURL key too
ShouldFillSpace Boolean If set to true, the image will take all the available space in the container, while keeping its ratio, and it will stop when the maximum width or height is reached. Then, you can change the size of the window to leave no space surrounding the image. Useful when displaying only on image component in a container for example.
Height Number (Integer or Real) The height of the image component. The width is fixed as the available space within the container. The image will fill the overall available width or height, depending of which one is the smallest, to keep its dimensions.
Note Is ignored if ShouldFillSpace is set to true. If no Height and no ShouldFillSpace keys are specified, the maximum height is 200
Examples

Image with an online URL


    <dict>
        <key>Type</key>
        <string>Image</string>
        <key>URL</key>
        <string>https://www.amaris.com/wp-content/uploads/2019/03/logo-amaris-consulting.png</string>
    </dict>
    

Image with a variable Images in its local URL


    <dict>
        <key>Type</key>
        <string>Image</string>
        <key>URL</key>
        <string>${Images}/CompanyLogo.png</string>
    </dict>
    

Image with different URLs depending on the mode


    <dict>
        <key>Type</key>
        <string>Image</string>
        <key>DarkModeURL</key>
        <string>${ResourcesFolderPath}/Images/AmarisLogo_White.png</string>
        <key>LightModeURL</key>
        <string>${ResourcesFolderPath}/Images/AmarisLogo_Black.png</string>
        <key>ShouldFillSpace</key>
        <true/>
    </dict>
    

Web component

This component allows you to display a web page.

Key Type Explanation Is Required
URL String The URL of the web page to display. Can be local or online ⚠️
IsScrollDisabled Boolean Lets you deactivate totally the scroll bars of the web view. Default is false
IsHorizontalScrollBarHidden Boolean Lets you hide or show the horizontal scroll bar in the web view. Default is true
IsVerticalScrollBarHidden Boolean Lets you hide or show the vertical scroll bar in the web view. Default is false
Examples

Online web page


    <dict>
        <key>Type</key>
        <string>Web</string>
        <key>URL</key>
        <string>https://www.google.com</string>
    </dict>
    

Locale web page with a variable ResourcesFolderPath in its URL


    <dict>
        <key>Type</key>
        <string>Web</string>
        <key>URL</key>
        <string>${ResourcesFolderPath}/index.html</string>
    </dict>
    

Button component

This component allows you to display a button to trigger actions you specify.

Key Type Explanation Is Required
Text String Text displayed on the button ⚠️
TextColor Color The text color of the button

Examples

Button displaying "Send" with a SaveInputs action triggered when the end user clicks.


    <dict>
        <key>Type</key>
        <string>Button</string>
        <key>Text</key>
        <string>Log</string>
        <key>OnClick</key>
        <dict>
            <key>Actions</key>
            <array>
                <dict>
                    <key>Type</key>
                    <string>SaveInputs</string>
                </dict>
            </array>
        </dict>
    </dict>
    

Spacer component

Lets you space out your layout with a component. It will use all the available height if you do not specify the Height key. And if other spacers are present with no Height key in the same container, they will have the same height. This is useful when you want to center components vertically: just add a spacer at the first place and one at the end of the container component's array, with no Height given.

Key Type Explanation Is Required
Height Number If specified, the spacer will have a fixed height in points. Otherwise, it will use all the available space.
Examples

Spacer with no height.


    <dict>
        <key>Type</key>
        <string>Spacer</string>
    </dict>
    

Spacer with fixed height.


    <dict>
        <key>Type</key>
        <string>Spacer</string>
        <key>Height</key>
        <integer>15</integer>
    </dict>
    

App monitoring component

This component informs the end user about the state of the installation of the applications or packages specified in the Monitor key whose types are Application (see Monitoring for further information). On each row, a color indicates the state of the installation process; the app icon (or a generic one), the application/package name and the detail text (if any specified) will be displayed. For now, the installation states and the colors are:

Key Type Explanation Is Required
NameFontConfiguration Font configuration The font used to display the name text of the monitor
DetailFontConfiguration Font configuration The font used to display the detail text of the monitor
IsMandatory Boolean If set to true, the slide will be invalid until all applications are installed, and an alert will be shown
WaitForApplicationToBeInstalledWarningText String Let you customize the text which will be displayed in the alert when shown, if IsMandatory is set to true
Examples

AppMonitor component with Name font configuration to be "Body" and a text color to be "Main", also a Detail font configuration to be 'Body" and a text color to be "Secondary"


    <dict>
        <key>Type</key>
        <string>AppMonitor</string>
        <key>NameFontConfiguration</key>
        <dict>
            <key>Style</key>
            <string>Body</string>
            <key>Color</key>
            <dict>
                <key>Style</key>
                <string>Main</string>
            </dict>
        </dict>
        <key>DetailFontConfiguration</key>
        <dict>
            <key>Style</key>
            <string>Body</string>
            <key>Color</key>
            <dict>
                <key>Style</key>
                <string>Secondary</string>
            </dict>
        </dict>
    </dict>
    

Input Components

These components let you ask for end user input. You choose a variable name in the variable key. This variable will be used as a key to let you find the value entered by the end user. All those input values will be available in a single JSON or XML file. You can choose the format and the path of this file in the Input configuration as well as the path of this file. Ceremony will override the content of the file or create one only if the end user has entered at least one input (or if an input component has a default value). This saving action will be executed at three times:

The following keys are available and/or required in all the input components

Key Type Possible values Explanation Is Required
InputType String Text, List, Checkboxes Specify the input component to use ⚠️
Variable String - The variable used as a key in the input variables file Ceremony will create to let you retrieve the end user inputs ⚠️
Label String - The label lets you give some insight to the end user about the value they need to enter. Its text will generally be placed on the left side of the input field
Note If you do not specify a label, the input field will be centered. To keep the alignment with other input components which have a label, specify the Label with a whitespace for value
LabelFontConfiguration FontConfiguration - Let you specify the font configuration to use. Default is DefaultPrimary if specified in the Font styles dictionary in the configuration file, or system font otherwise.
Distribution String Fit, Center Specify how the label and the input field are stacked. Fit give them as much space as they need, but the input component will not be aligned with the other ones. Center align the label and the input field in the horizontal middle of its container. This allow several input components to be aligned, although it may crop the text label.

After the end user entered an input, you can use it like a variable in Ceremony. The name of the variable will be the value of the Variable key, or a composition with the input field(s) when necessary. Refer to the input component to know when a composition happens.


Validation

You can add validation to an input component. It's a Dictionary in which you insert the keys to validate the input entered by the user. When adding a Validation key, the input component will be considered as Mandatory by Ceremony. The slide will be unvalid (the user will not be able to go the next slide) until he didn't correctly fill all Mandatory fields.

The keys to validate the input will differ depending on the InputType. That said, the following keys are available in all the input components validation dictionary.

Key Type Explanation Is Required
WarningText String The text to display to the user when the input is empty or its value is incorrect. Default is "Incorrect or empty value"
FontConfiguration FontConfiguration The font configuration to use for the warning text

Here are the available input components.


Text input component

Lets you ask to the user to enter some text.

Key Type Explanation Is Required
Placeholder String Text which appears in the text field to show to the end user what king of value is needed

Validation

Insert the following keys in the Validation key dictionary to validate the value in Text input component.

Key Type Explanation Is Required
Regex String The pattern regular expression to use to validate the user input. To know more about regular expressions, checkout Regular expressions ⚠️
Examples

Text input component to ask for the user's Mac asset tag, with a validation to authorize patterns like 3 groups of 3 alphanumeric characters, separated by hyphens.


    <dict>
        <key>Type</key>
        <string>Input</string>
        <key>InputType</key>
        <string>Text</string>
        <key>Label</key>
        <string>What is your Mac asset tag ?</string>
        <key>Variable</key>
        <string>AssetTag</string>
        <key>Placeholder</key>
        <string>AE1785</string>
        <key>Validation</key>
        <dict>
          <key>Regex</key>
          <string>[a-zA-Z0-9]{3}-[a-zA-Z0-9]{3}-[a-zA-Z0-9]{3}</string>
          <key>WarningText</key>
          <string>Empty or incorrect format</string>
        </dict>
    </dict>
    

List input component

Shows several values to the end user in a pop-up menu for them to chose from. The variable value will be the selected item among the items you provided. The type of the value will depend on the ones you specified.

Key Type Possible values Explanation Is Required
Items Array String or Number array Array of choices to propose to the end user. All the values need to have the same type to let Ceremony infer it. You can chose an array of String or Number. If Number is chosen, you can write Int or Double values, but you cannot mix them. ⚠️

Validation

Insert the following keys in the Validation key dictionary to validate the value in List input component.

Key Type Explanation Is Required
Instruction String The text to display as an instruction to the user. This text will disappear when the user selected an item ⚠️
Examples

List input component to choose a value among {Apprentice, Intermediate, Master, Expert, Legend} and a validation which prevents the user from going to the next slide until he has selected an item. A "Choose" instruction is displayed at first.


    <dict>
        <key>Type</key>
        <string>Input</string>
        <key>InputType</key>
        <string>List</string>
        <key>Variable</key>
        <string>UserLevel</string>
        <key>Items</key>
        <array>
            <string>Apprentice</string>
            <string>Intermediate</string>
            <string>Master</string>
            <string>Expert</string>
            <string>Legend</string>
        </array>
        <key>Validation</key>
        <dict>
          <key>WarningText</key>
          <string>Please choose a value</string>
          <key>Instruction</key>
          <string>Choose</string>
        </dict>
    </dict>
    

Checkboxes input component

Shows one or several checkboxes with text on the right.

Key Type Possible values Explanation Is Required
Items Array String or Number array Array of choices to propose to the end user. All the values need to have the same type to let Ceremony infer it. You can chose an array of String or Number. If Number is chosen, you can write Int or Double values, but you cannot mix them. ⚠️

Validation

No additional keys are required for the Checkboxes input component. Adding a Validation key is enough. This will ensure that all the checkboxes are checked to validate.

Examples

Checkboxes to ask to the user to describe his feelings. Each box is optional.


    <dict>
      <key>Type</key>
      <string>Input</string>
      <key>InputType</key>
      <string>Checkboxes</string>
      <key>Variable</key>
      <string>UserAdjectives</string>
      <key>Label</key>
      <string>How are you feeling?</string>
      <key>Items</key>
      <array>
          <string>Impatient</string>
          <string>Ready to start</string>
          <string>Nervous</string>
      </array>
    </dict>
    

Checkboxes which needs to be checked by the user to validate.


    <dict>
      <key>Type</key>
      <string>Input</string>
      <key>InputType</key>
      <string>Checkboxes</string>
      <key>Variable</key>
      <string>SecretSpy</string>
      <key>Validation</key>
      <dict>
        <key>WarningText</key>
        <string>Please agree, M. Hunt.</string>
      </dict>
      <key>Items</key>
      <array>
        <string>I acknowledge that my activity would be denied by the government if I was arrested</string>
      </array>
    </dict>
    

Variable

As the checkboxes input component can have two states for each of its item, Ceremony will create a variable for each item, with the state as value (true/false for check/uncheck). With the first example, Ceremony will create 3 variables, replacing spaces with underscores: UserAdjectives.Impatient, UserAdjectives.Ready_to_start, UserAdjectives.Nervous.