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 on any component.

Margins

Border

Condition PRO



Display Components

These allow you to display content to the end user. You can find the display components list on the left.


Text component

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

Keys

Summary
Name Type Possible values Required
Type String Text Required
Text String - Required
TextFontConfiguration Font -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

Text Required

TextFontConfiguration

Example

The following display an innovative stub text.

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

Keys

Summary
Name Type Possible values Required
Type String Image Required
URL String - Required
if no mode URL keys are specified.
LightModeURL String - Required
if DarkModeURL is specified.
DarkModeURL String - Required
if LightModeURL is specified.
ShouldFillSpace Boolean -
Height Number -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

URL

LightModeURL

DarktModeURL

ShouldFillSpace

Height

Example

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. Note the usage of the Images variable.

<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>${Resources}/Images/AmarisLogo_White.png</string>
    <key>LightModeURL</key>
    <string>${Resources}/Images/AmarisLogo_Black.png</string>
    <key>ShouldFillSpace</key>
    <true/>
</dict>


Web component

This component allows you to display a web page.

Keys

Summary
Name Type Possible values Required
Type String Web Required
URL String - Required
IsScrollDisabled Boolean -
IsHorizontalScrollBarHidden Boolean -
IsVerticalScrollBarHidden Boolean -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

URL Required

IsScrollDisabled

IsHorizontalScrollBarHidden

IsVerticalScrollBarHidden

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 Resources in its URL.

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


PDF component

This component wil display a PDF document for the given URL (online or local).

Availability: 2.0.6+

Keys

Summary
Name Type Possible values Required
Type String PDF Required
URL String - Required
LinksAreEnabled Boolean -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

URL Required

LinksAreEnabled

Examples

Online PDF

<dict>
    <key>Type</key>
    <string>PDF</string>
    <key>URL</key>
    <string>https://www.octory.io/terms-and-conditions.pdf</string>
</dict>

Locale web page with a variable Resources in its URL. For instance, Resource could be /Users/jappleseed/Application Support/Octory/Resources. The links are enabled.

<dict>
    <key>Type</key>
    <string>PDF</string>
    <key>URL</key>
    <string>${Resources}/welcome.pdf</string>
    <key>LinksAreEnabled</key>
    <true/>
</dict>


Video component

Play a local or online video with custom behaviors.

Availability: 2.0.6+

Keys

Summary
Name Type Possible values Required
Type String Video Required
URL String - Required
HideControls Boolean -
AutomaticStart PRO Boolean -
Repeat PRO Boolean -
IsMuted Boolean -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

URL Required

HideControls

AutomaticStart PRO

Repeat PRO

IsMuted

Examples

Player for an online video

<dict>
    <key>Type</key>
    <string>Video</string>
    <key>URL</key>
    <string>https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_adv_example_hevc/master.m3u8</string>
</dict>

Locale web page with a variable Resources in its URL. For instance, Resource could be /Users/jappleseed/Application Support/Octory/Resources. Controls are hidden and the video will start automatically when it appears.

<dict>
    <key>Type</key>
    <string>Video</string>
    <key>URL</key>
    <string>${Resources}/Videos/onboarding.mov</string>
    <key>AutomaticStart</key>
    <true/>
    <key>HideControls</key>
    <true/>
</dict>


Button component

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

Keys

Summary
Name Type Possible values Required
Type String Button Required
Style String Simple, Info Required
Text String -
Color Color -
Alignment String Left, Center, Right
OnClick Array(ActionSet) -
Trigger String -
Popover PRO Popover -
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

Style Required

Text

Color

Alignment

OnClick

Trigger

Popover PRO


Popover PRO

You can setup a popover window to appear when the user clicks the button. Here is the popover configuration.

Keys

Summary
Name Type Possible values Required
Text String Required
if no FilePath is provided
FilePath String - Required
if no Text is provided
Edge Left, Top,
Right, Bottom		 - Required
Font Font
Size Size -
Detail

Text

FilePath

Edge Required

Font

Size

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>

Button with an Info style (image of a “i” letter inside a circle) which displays a popover when clicked. The markdown popover has a header and a simple text line. It uses the Avenir font. The color of the info image is set as the Secondary color defined in the ColorStyles section.

<dict>
    <key>Type</key>
    <string>Button</string>
    <key>Style</key>
    <string>Info</string>
    <key>Color</key>
    <dict>
        <key>Style</key>
        <string>Secondary</string>
    </dict>
    <key>Alignment</key>
    <string>Right</string>
    <key>Popover</key>
    <dict>
        <key>Text</key>
        <string># Informative text
      This is informative text</string>
        <key>Edge</key>
        <string>Bottom</string>
        <key>Font</key>
        <dict>
            <key>Name</key>
            <string>Avenir</string>
        </dict>
    </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.

Keys

Summary
Name Type Possible values Required
Type String Spacer Required
Height Number
Margins Margins -
Border Border -
Condition PRO Condition -
Detail

Type Required

Height

Examples

Spacer with no fixed 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 symbol or a spinner 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.

Keys

Summary
Name Type Possible values Required
Type String AppMonitor Required
NameFontConfiguration Font -
DetailFontConfiguration Font -
IsMandatory Boolean
WaitForApplicationTo
BeInstalledWarningText		 String -
Margins Margins -
Border Border -
Condition PRO Condition -
ShowScroller Bool -

Detail

Type Required

NameFontConfiguration

DetailFontConfiguration

IsMandatory

WaitForApplicationToBeInstalledWarningText

ShowScroller

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 Plist file. You can choose the format and the path of this file in the Input configuration as well as the path of this file. Octory 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:

You can find the list of input components on the left

After the end user entered an input, you can use it like a variable in Octory. 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 Octory. The slide will be unvalid (the user will not be able to go the next slide or to quit the app) until all Mandatory fields are not filled correctly.



Text input component

Lets you ask to the user to enter some text.

Keys

Summary
Name Type Possible values Required
Type String Input Required
InputType String Text Required
Variable String - Required
Label String -
LabelFontConfiguration Font -
Distribution String Fit, Center
PercentWidth Number 0...1
Placeholder String
Validation Input Text validation
Margins Margins -
Border Border -
Condition PRO Condition -

Detail

Type Required

InputType Required

Variable Required

Label

LabelFontConfiguration

Distribution

PercentWidth

Placeholder

Validation


Input Text validation

Allows to validate the value entered in the TextInput Component.

Name Type Required
WarningText String
FontConfiguration Font
Regex String Required
Detail

WarningText

FontConfiguration

Regex Required


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.

Keys

Summary
Name Type Possible values Required
Type String Input Required
InputType String List Required
Variable String - Required
Label String -
LabelFontConfiguration Font -
Distribution String Fit, Center
PercentWidth Number 0...1
Items Array(String) or Array(Number) Required
Validation Input List validation
Margins Margins -
Border Border -
Condition PRO Condition -

Detail

Type Required

InputType Required

Variable Required

Label

LabelFontConfiguration

Distribution

PercentWidth

Items Required

Validation


Input List validation

Let you force the user to choose a value in a ListInput Component.

Name Type Required
WarningText String
FontConfiguration Font
Instruction String Required
Detail

WarningText

FontConfiguration

Instruction Required

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.

Keys

Summary
Name Type Possible values Required
Type String Input Required
InputType String Checkboxes Required
Variable String - Required
Label String -
LabelFontConfiguration Font -
Distribution String Fit, Center
PercentWidth Number 0...1
Items Array(String) or Array(Number) Required
Validation Input checkboxes Validation
Margins Margins -
Border Border -
Condition PRO Condition -

Detail

Type Required

InputType Required

Variable Required

Label

LabelFontConfiguration

Distribution

PercentWidth

Items Required

Validation


Checkboxes Input validation

Let you force the user to check all boxes of a CheckboxesInput Component.

Name Type Required
WarningText String
FontConfiguration Font
Detail

WarningText

FontConfiguration

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>

About checkboxes input component variable

As the checkboxes input component can have two states for each of its item, Octory will create a variable for each item, with the state as value (true/false for check/uncheck). With the first example, Octory will create 3 variables with the index of the checkbox and the variable name:
- UserAdjectives-0 for the Impatient option
- UserAdjectives-1 for the Ready to start option
- UserAdjectives-2 for the Nervous option