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).
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 |
Margins | Margins | - | |
Border | Border | - | |
Condition PRO | Condition | - |
Detail
Type Required
- Type: String
-
Explanation: The type of the component which has to be
Text
Text Required
- Type:String
- Explanation: The text which will be displayed as content.
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
- Type: String
-
Explanation: The type of the component which has to be
Image
URL
- Type:String
- Explanation: The URL of the image to display. Can be local or online. Required if no mode URL keys are specified.
LightModeURL
- Type:String
-
Explanation: If you want to propose a different image depending on the mode, you can specify here the image URL for the light mode.
Required if
DarkModeURL
is specified
DarktModeURL
- Type: String
-
Explanation: If you want to propose a different image depending on the mode, you can specify here the image URL for the dark mode.
Required if
LightModeURL
is specified
ShouldFillSpace
- Type: String
-
Explanation: 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. Default isfalse
.
Height
- Type: Number
-
Explanation: 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.
Is ignored if
ShouldFillSpace
is set totrue
. If noHeight
and noShouldFillSpace
keys are specified, the maximum height is 200
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>${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.
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
- Type: String
-
Explanation: The type of the component which has to be
Web
.
URL Required
- Type:String
- Explanation: The URL of the web page to display. Can be local or online.
IsScrollDisabled
- Type: Boolean
-
Explanation: Lets you deactivate totally the scroll bars of the web view. Default is
false
.
IsHorizontalScrollBarHidden
- Type: Boolean
-
Explanation: Lets you hide or show the horizontal scroll bar in the web view. Default is
true
.
IsVerticalScrollBarHidden
- Type: Boolean
-
Explanation: 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.
Keys
Summary
Name | Type | Possible values | Required |
---|---|---|---|
Type | String | Button |
Required |
Text | String | - | Required with the "Simple" value for the Style key. |
Style | String | Simple , Info |
Required |
Color | Color | - | |
Alignment | String | Left , Center , Right |
|
OnClick | Array(ActionSet) | - | |
Popover PRO | Popover | - | |
Margins | Margins | - | |
Border | Border | - | |
Condition PRO | Condition | - |
Detail
Type Required
- Type: String
-
Explanation: The type of the component which has to be
Button
Text
- Type: String
-
Explanation: Text displayed on the button. Required if
Style
is set to "Simple".
Style Required
- Type: String
-
Explanation: Choose the way the button appears.
Simple
will display the text you provide.Info
will display an info icon with no background.
Color
- Type: Color
- Explanation: The text color of the button, or the color of the info icon.
Alignment
- Type:
Left
,Center
,Right
- Explanation: Align the button in its container.
OnClick
Popover PRO
- Type: Popover
- Explanation: A popover markdown text will be displayed when the user clicks the button.
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
- Type: String
-
Explanation: The markdown text to display. The markdown formatting used is CommonMark.
Required if noFilePath
is provided.
FilePath
- Type: String
-
Explanation: If specified, Octory will display the content of the markdown file rather than the
Text
key. The markdown formatting used is CommonMark.
Required if noText
is provided.
Edge Required
- Type: String
- Possible values:
Left
,Top
,Right
,Bottom
- Explanation: The edge where the popover arrow will point to.
Font
- Type: Font
-
Explanation: The Font used to display the text.
For the font
Name
key, you should only specify the name and not the postscript name. For example just writeAvenirNext
and notAvenirNext-Regular
.
Size
- Type: Array(ActionSet)
- Explanation:The size of the popover view. Default is 300x400
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
- Type: String
-
Explanation: The type of the component which has to be
Spacer
.
Height
- Type: Number
-
Explanation: If specified, the spacer will have a fixed height in points. Otherwise, it will use all the available height.
The available height is equally used by all
Spacer
components which do not have a fixed 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 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:
- ● Not installed
- ● Installing
- ● Installed
- ● Error while installing
Keys
Summary
Name | Type | Possible values | Required |
---|---|---|---|
Type | String | AppMonitor |
Required |
NameFontConfiguration | Font | Button |
|
DetailFontConfiguration | Font | - | |
IsMandatory | Boolean | ||
WaitForApplicationTo BeInstalledWarningText |
String | - | |
Margins | Margins | - | |
Border | Border | - | |
Condition PRO | Condition | - |
Detail
Type Required
- Type: String
-
Explanation: The type of the component which has to be
AppMonitor
.
NameFontConfiguration
- Type: Font
- Explanation: The font used to display the name text of the monitor.
DetailFontConfiguration
- Type: Font
- Explanation: The font used to display the detail text of the monitor.
IsMandatory
- Type: Boolean
-
Explanation: If set to
true
, the slide will be invalid until all applications are installed, and an alert will be shown
WaitForApplicationToBeInstalledWarningText
- Type: String
-
Explanation: Let you customize the text which will be displayed in the alert when shown,
if
IsMandatory
is set totrue
.
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:
- when the end user goes to the previous or next slide
- when you have configured a Button component with a
SaveInputs
action and the end user clicks the button - when the app will terminate
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 | - | ||
Distribution | String | Fit , Center |
|
PercentWidth | Number | 0...1 | |
Placeholder | String | ||
Validation | Input Text validation | ||
Margins | Margins | - | |
Border | Border | - | |
Condition PRO | Condition | - |
Detail
Type Required
- Type: String
-
Explanation: The type of the component which has to be
InputComponent
InputType Required
- Type: String
-
Explanation: The type of the component which has to be
Text
Variable Required
- Type:String
- Explanation: The variable used within the application and as a key in the input file Octory will create to let you retrieve the user inputs.
Label
- Type:String
-
Explanation: 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
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, give the
Label
a whitespace for value.
LabelFontConfiguration
- Type:
- Explanation: Let you specify the font configuration to use. Default is "DefaultPrimary" if specified in the Font styles in the configuration file, or system font otherwise.
Distribution
- Type: String
- Possible values:
Fit
,Center
-
Explanation: Specify how the label and the input field are stacked.
Fit
gives 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.
PercentWidth
- Type: Number
- Possible values: 0...1
- Explanation: This value allows you to give more width to an input component, by specifying the percentage width it should take in its container. Default is most often 0.4.
Placeholder
- Type: Number
- Explanation: Text which appears in the text field to show to the end user what king of value is needed.
Validation
- Type: Input Text validation
- Explanation: Text which appears in the text field to show to the end user what king of value is needed.
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
- Type: String
- Explanation: The text to display to the user when the input is empty or its value is incorrect. Default is "Incorrect or empty value".
FontConfiguration
- Type: Font
- Explanation: The font configuration to use for the warning text.
Regex Required
- Type: String
- Explanation: 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.
Keys
Summary
Name | Type | Possible values | Required |
---|---|---|---|
Type | String | Input |
Required |
InputType | String | List |
Required |
Variable | String | - | Required |
Label | String | - | |
LabelFontConfiguration | - | ||
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
- Type: String
-
Explanation: The type of the component which has to be
InputComponent
InputType Required
- Type: String
-
Explanation: The type of the component which has to be
List
Variable Required
- Type:String
- Explanation: The variable used within the application and as a key in the input file Octory will create to let you retrieve the user inputs.
Label
- Type:String
-
Explanation: 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
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, give the
Label
a whitespace for value.
LabelFontConfiguration
- Type:
- Explanation: Let you specify the font configuration to use. Default is "DefaultPrimary" if specified in the Font styles in the configuration file, or system font otherwise.
Distribution
- Type: String
- Possible values:
Fit
,Center
-
Explanation: Specify how the label and the input field are stacked.
Fit
gives 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 allows several input components to be aligned, although it may crop the text label.
PercentWidth
- Type: Number
- Possible values: 0...1
- Explanation: This value allows you to give more width to an input component, by specifying the percentage width it should take in its container. Default is most often 0.4.
Items Required
- Type: Array(String) or Array(Number)
- Explanation: Array of choices to propose to the end user. All the values need to have the same type to let Octory infer it. You can chose an array of String or Number. If Number is chosen, you can write Int or Real values, but you cannot mix them.
Validation
- Type: List Input validation
- Explanation: Let you force the user to choose a value.
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
- Type: String
- Default: "Incorrect or empty value"
- Explanation: The text to display to the user when the input is empty or its value is incorrect.
FontConfiguration
- Type: Font
- Explanation: The font configuration to use for the warning text.
Instruction Required
- Type: String
- Explanation: The text to display as an instruction to the user. This text will disappear when the user has 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.
Keys
Summary
Name | Type | Possible values | Required |
---|---|---|---|
Type | String | Input |
Required |
InputType | String | Checkboxes |
Required |
Variable | String | - | Required |
Label | String | - | |
LabelFontConfiguration | - | ||
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
- Type: String
-
Explanation: The type of the component which has to be
InputComponent
InputType Required
- Type: String
-
Explanation: The type of the component which has to be
Checkboxes
Variable Required
- Type:String
- Explanation: The variable used within the application and as a key in the input file Octory will create to let you retrieve the user inputs.
Label
- Type:String
-
Explanation: 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
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, give the
Label
a whitespace for value.
LabelFontConfiguration
- Type:
- Explanation: Let you specify the font configuration to use. Default is "DefaultPrimary" if specified in the Font styles in the configuration file, or system font otherwise.
Distribution
- Type: String
- Possible values:
Fit
,Center
-
Explanation: Specify how the label and the input field are stacked.
Fit
gives 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 allows several input components to be aligned, although it may crop the text label.
PercentWidth
- Type: Number
- Possible values: 0...1
- Explanation: This value allows you to give more width to an input component, by specifying the percentage width it should take in its container. Default is most often 0.4.
Items Required
- Type: Array(String) or Array(Number)
- Explanation: Array of choices to propose to the end user. All the values need to have the same type to let Octory infer it. You can chose an array of String or Number. If Number is chosen, you can write Int or Real values, but you cannot mix them.
Validation
- Type: Input Checkboxes validation
- Explanation: Let you force the user to check all boxes.
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
- Type: String
- Explanation: The text to display to the user when the input is empty or its value is incorrect. Default is "Incorrect or empty value".
FontConfiguration
- Type: Font
- Explanation: The font configuration to use for the warning text.
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