App Templates Reference

Code samples will appear here!

{
  "value":"hello world"
}

Where you see several periods "...." some code has been excluded to keep the example short.

3D Issue apps use a templating system to customise and display pages within your app. Templates are built using JSON. If you aren't familiar with JSON we reccommend you take a look at this documentation before going any further.

Templates

A basic template looks something like this:

{
    "template":{
        "resources":[
      {
        "type":"IMAGE",
        "name":"helloworld",
        "url":"https://....."
      },
      {
         "type":"FONT",
        "name":"prettyFont",
        "url":"https://....."
      }
    ],
    "indexPage":{
      "layouts":[
        {
          "layout":"placeholderlayout"
        }
      ]
    },
    "articlePage":{....},
        "layouts":[
            {
                "type":"linear", 
                "id":"placeholderlayout",
                "style":{
                    "width":"fill",
                    "height":"fill",
                    "backgroundColor":"#fbfbfb"
              },
                "components":[
                    {
                        "type":"image",
                        "id":"someImage",
                        "style":{
              "width":"200px",
              "height":"200px",
              "image":"helloworld"
                        }
                    },
          {
            "type":"text",
            "id":"helloWorldText",
            "text":"Hello World",
            "style":{
              "fontFace":"prettyFont",
              "fontSize":17,
              "color":"#000000",
              "height":"auto",
              "width":"auto"
            }
          }
                ]
            }
        ]
    }
}

Make sure to use proper JSON syntax, or your template might not load correctly.

All templates are contained in a template object. Templates include a number of required and optional objects; resources, pages, layouts, components and styles. Different objects are required depending on the type of app you are designing the template for, or the type of navigation you'd like your app to use. For example, your app should at the very least provide a means of change section (homePage or sidePanel) a way of listing articles (homePage or indexPage) and a way of displaying articles (articlePage).

Object	Brief description
Resources	A list of images and fonts used within the template.
Pages	The pages of your app. There are predefined pages you must use while building your template.
Layouts	Layouts provide the view information to pages.
Components	Components display information and provide interaction, such as showing an image or letting a user scroll through a list of items.
Styles	Provide information about sizing, colours and other attributes to layouts and their components.

Required objects

Some objects are required by all app types. They are;

Object	Type	Brief description
Resrouces	Array	A list of images and fonts used within the template.
Layouts	Array	A list of reusable layouts. Any layout in the layouts array can be referenced by id in any other layout or page.
Styles	Array	A list of reusable styles. Any style in the styles array can be used by any layout or component.

Some page types are required depending on the type of app you are designing or the type of navigation you require.

Page Type	Brief description
Article Page	`Required for all Standard apps.` The article page display article contents.
Parent Menu Page	`Required for all parent apps.` This page displays a parent app menu.
Index Page	`Required for most apps. Not required if a home page that displays articles is used.` Displays a list of articles.
Home page	`Not always required.` Normally provides a means of displaying section information.
Side panel	`Required if no home screen is present` Provides a means of display section information.

Data Binding

To display information base on your app's content templates support data bindings. The bindings correlate to content of sections and items within the app. All bindings are text based.
Bindings refer to values for the current item represented by the layout. This representation is automatic based on the page type and context of the layout. Data bindings are used by simply inserting them into the values of components and styles.
For example, the home page within the app represents the entire app. A list component can then display sections and the items within the list are then bound to the articles or items within the section.

The following are the available data bindings within the app.

$title

Title

{
    "text":"$title"
}

The title of the current item.

$summary

Summary

{
    "text":"$summary"
}

The summary of the current item.

$color

Color

{
    "color":"$color",
    "backgroundColor":"$color",
    "borderColor":"$color"
}

The color value of the current item.

$image

Image

{
    "image":"$image"
}

The image url of the current item.

$author

Author

{
    "text":"$author"
}

The author of the current item (Author or website).

$date

Date

{
    "text":"$date"
}

The timestamp of the current item.

$parentTitle

Parent Title

{
    "text":"$parentTitle"
}

The title of the current item's owner. For example if the layout is bound to an article, this would return the owning section's title.

$srcFrame

Source Frame

{
    "frame":"$srcFrame"
}

The source frame of the triggering view relative to the display. This binding only applies to animations being triggered by user interaction. See style.frame

Pages

The pages of your app. pages tell your app which layouts to display and how the layouts respond to screen size and orientation. There are currently five pages types, all with their own roles and use cases. This section will cover each page in detail.

Pages are added to the root of the template (The template object). They are added automatically by the 3D issue apps dashboard.

Page Properties

Pages use some properties to provide transition and orientation information.

page.supportedOrientations

    "homePage":{
        ....
        "supportedOrientations":"all"
    }

Type: enum - string

Supported Orientations allows the template to define what device orientations the page supports. Valid values are; * all * portrait * landscape

page.transitionIn & page.transitionOut

    "homePage":{
        ....
        "transitionIn":{
            "type":"fade",
            "duration":200,
            "delay":0
        },
        "transitionOut":{
            "type":"fade",
            "duration":200,
            "delay":0
        }
    }

Type: object

Transition In and Transition Out allow you to specify the animation type and duration when the page comes into view.
You can also set a delay if you wish to delay a page opening for another animation to finish.

page.transition.type

Sets the animation type to use.
Type: enum - string
Valid values are;

fade
slide
slideVertical

page.transition.duration

Sets the duration of the animation in milliseconds.

Type: Integer
Min: 0
Default: 180

page.transition.delay

Sets the start delay of the animation in milliseconds.

Type: Integer
Min: 0
Default: 0

Home Page

Home Page

{
    "template":{
        "homePage":{
            "layout":{
                ....
            },
            "supportedOrientations":"all"
        }
    }
}

The home page is multi purpose. It can handle multiple use-cases allowing your app to house most of your navigation in one place.
The home page by default recieves the full list of app sections and their contents. Templates can utilise tabs, lists and grids to display both sections and articles on the home page.
Common uses of the home page would include;

A landing page showing a list of sections
A Summary style page showling a list of sections and some of their articles
A tab view allowing the user to switch between sections without leaving the current screen.
A list of articles from each section.

homePage.layout

Defines the layout to be used by the Home page.

Type: Layout Object or Layout Id

Index Page

Index Page

{
    "template":{
        "indexPage":{
            "layouts":[
                {
                    ....
                }
            ],
            "supportedOrientations":"all"
        }
    }
}

indexPage.layouts

A list of layouts to be used in the indexPage. The first layout is used by default.
Other layouts in the array can be mapped to sections within the app via the 3D Issue apps dashboard.When the index page opens a mapped section it will use the corresponding layout.

Type: Array
Items: Layout Object or Layout Id

Side Panel

Side Panel

{
    "template":{
        "sidePanel":{
            "layout":[
                ....
                "style":{
                    "width":"200px"
                }
            ]
        }
    }
}

The side panel provides an always present navigation option. The sidepanel can be opened by swiping left to right anywhere in the app. The sidepanel can include static options such as buttons for Home, Settings or Parent Menu as well as displaying a list of app sections. The sidepanel is only supported in Standard apps and will be disabled while viewing the Parent Menu.

Normally the root layout of a page will always have a size of width=fill and height=fill.
The sidepanel is the one exception to this rule as it uses the width value of its root layout to determine the opening width of the sidepanel (how much of the screen it uses when the user swipes it open).

sidePanel.layout

Defines the layout to be used by the Side Panel.

Type: Layout Object or Layout Id

Article Page

Article Page

{
    "template":{
        "articlePage":{
            "layouts":[
                ....
            ],
            "supportedOrientations":"all"
        }
    }
}

articlePage.layouts

A list of layouts to be used in the articlePage. The first layout is used by default.
Other layouts in the array can be mapped to sections or individual articles or sources within the app via the 3D Issue apps dashboard. When the index page opens a mapped item it will use the corresponding layout.

Article page layouts should contain a html component for displaying article content.

Type: Array
Items: Layout Object or Layout Id

Parent Menu Page

{
    "template":{
        "parentMenuPage":{
            "layouts":[
                ....
            ],
            "supportedOrientations":"all"
        }
    }
}

parentMenuPage.layouts

A list of layouts to be used in the Parent menu. The first layout is used by default.
Other layouts in the array can be mapped to menus within the app via the 3D Issue apps dashboard.

Parent menu layouts should contain a list or grid allowing the displaying of the children type.

Type: Array
Items: Layout Object or Layout Id

Layouts

Layouts are containers that are used to display and position components or other layouts.
3D Issue templates currently use three types of layout;

Linear
Relative
Tab Layout

The type of the layout determines how it positions and sizes nested layouts or components.

Linear Layouts

Define a linear layout

{
    ....
    "layout":{
        "type":"linear",
        ...
    }
}

Linear layouts display items in a flow style fashion, placing items one after the other and wrapping when the available space has been filled.
The layout direction can be set via the direction value of the layout's style.

Relative Layouts

Define a relative layout

{
    ....
    "layout":{
        "type":"relative",
        ...
    }
}

Relative layouts display items relative to each other, or to the layout's edges. The positioning and sizing information comes from the style of each item contained in the layout.
The style values that control this include;
top, bottom, left, right, above, below, rightOf, leftOf
Full details of those style values can be found in the styles section.

Tab Layout

A tab layout

{
    "type": "tabView",
    "style": {....},
    "content": {
        "type": "relative",
        ....
    },
    "tabBar": {
        "type": "tabBar",
        ....
    }
}

The tab layout is a type of layout designed for showing tabbed content using a tabBar and content layout.
Tab layout differs from other layouts in that it does not use the components array which is replaced by the content layout item and tabBar layout item.
The tabBar layout’s root item must be a tab bar component.
The content layout can be any layout type but should be able to show articles, with a grid for example.

tabView.gesturesEnabled

Boolean (true / false), Enables or disables swipe gestures on the tabLayout content.

tabView.tabBar

The Tab Bar layout. Root item must be a tab bar component.

tabView.content

The Content layout.

tabView.style.barPosition

The position of the tab bar in the layout. (top / bottom).
Default: bottom.

tabView.style.barHeight

The px height of the tabBar.
Default: 60px

Nesting Layouts

Nesting a relative layout beside a text component

{
    ....
    "layout":{
        "type":"relative",
        "components":[
            {
                "type":"relative"
                ....
            },
            {
                "type":"text"
                ....
            }
        ],
        ...
    }
}

Layouts can be nested to allow the creation of more complex view structures.
To nest a layout within another simply add it as a component to the component's array of the parent layout. Style attributes for positioning and sizing can be added to the child layout as though it where a normal component.

Layout Properties

layout.type

The type of the current layout.
Valid values are;

linear
relative

layout.id

The id of the layout, can be used for relative layouts, or for reusing a layout from the layouts list.

layout.components

An array of components or nested layouts to display within the current layout.

layout.style

The style to be used by the current component
See the Styles section for details

layout.action

The action to trigger when the view is tapped.
See the actions section for details

layout.animations

An array of animations to be applied to the layout. See the animations section for further info.

Layout Variations

A layout with some variations.

{
    "type":"relative",
    "id":"someLayoutWithVariations",
    "style":{
        "backgroundColor":"#ff0000",
        "width":"fill",
        "height":"fill"
    },
    "components":[
        {
            "type":"circle",
            "style":{....}
        }
    ],
    "variations":[
        {
            "style":{
                "backgroundColor":"#00ff00"
            },
            "components":[
                {
                "type":"square",
                "style":{....}
                }
            ]
        },
        {
            "style":{
                "backgroundColor":"#0000ff"
            },
            "components":[
                {
                "type":"image",
                "style":{....}
                }
            ]
        }
    ]

}

Variations of a layout can be added via the layout.variations property. Variations can override any attribute for a layout, including components. Variations allow the changing of appearance of layouts as they are generated in the app.

Variations are intended to be used in list and grid components as their items, headers & footers. Variations are used in a round robin like fashion with the default values of the layout being used as the first variation.

Components

Components are views used to display content and information and to provide various forms of user interaction.

Common component attributes

All components share a few common attributes.

Attribute	Description
style	The component's style
id	The component's id. Components should ideally all have an id so that they are easily identifiable.
animations	Any animations to be applied to the view. See the animations section for further info.
action	The action triggered by the view's touch event. See the actions section for further info.

Text

Text Component with custom font

{
    ....
    "components":[
        {
            "type":"text",
            "text":"hello world!",
            "style":{
                "fontFace":"prettyFont",
                "fontSize":12,
                "maxLines":3,
                "color":"#000000",
                ....
            }
        }
    ]
}

The text component displays text values.
The value can be fixed, in the template or bound to some data using a data binding

Font Style
The default app for templates is Roboto. However external fonts can be included in the template resources. Font style is customised via the fontFace property of the component's style, using the name of the required font resource. Font sizing is set via the fontSize property of the style. The font size defaults to 17. Font color is set through the color property of the style.

Text Sizing
Text components size similarly to other components with one addition;
maxLines: Max-lines allows you to control the maximum number of lines the label will wrap to before ellipsizing the text. While 0 is unlimited any other value will result in the label auto-sizing to its maximum width (either pixels of the full width of its parent layout) and then expanding its height (downwards unless position relative to the bottom).

Text Background Colour
Text Components may have a background color that applies to its lines of text only, text.style.textBackgroundColor.
See the style attribute here.

Image Component

Image Component

{
    ....
    "components":[
        {
            "type":"image",
            "style":
            {
                "image":"animageResource",
                ....
            }
        }
    ]
}

Images display images in the app.
Image components allow adding of static images from the resources array and from the web or the $image data binding.
The source is provided by means of the image style property. This can be the image name or url or binding value.
As not all images are created equal, image components allow you to specify the scaling type to be used on the image via the imageScale style property image.style.imageScale
See the image scale style property for more info.

Grid

A Grid Component

{
    ....
    "components":[
        {
            "type":"grid",
            "displaysType":"articles",
            "item":{...},
            "paginate":false,
            "dynamicLoading":true,
            "style":{
                "leadingPattern":{},
                "pattern":{}
            }
        }
    ]
}

The grid component allows the binding of items to layouts and displaying them in a scrollable view.
Grid components use a number of additional properties for helping define how they should be laid out.

grid.displaysType

Displays type tells the app which data the grid should be bound to.

Value	Description
articles	Binds the grid items to all the articles of the current section, or the first section if no section binding can be determined.
sections	Binds the grid items to all the sections of the app.
children	Binds the grid items to all the Options from a parent menu.
articlesAndSections	Binds the grid header and footer layouts to sections and items to articles.

grid.dynamicLoading

Sets if the app should automatically load additional items for the grid as the user scrolls (in addition to the items downloaded at the start of the app run).

grid.paginate

Sets if the grid should create "pages" out of the grid items.

grid.item

Defining an item layout.

"item":{
    "type":"linear",
    ....
}

The layout to be used for items displayed in the grid. See layouts and layout id

grid.onScrollX & grid.onScrollY

Scroll Events . See Scroll Events

grid.header

The layout to used for section headers in the grid. See layouts and layout id

The layout to used for section footers in the grid. See layouts and layout id

grid.style.pattern

The grid pattern allows for creating more dynamic layouts for grid items (Pattern does not affect headers or footers).
The "pattern" attribute of the grid style is an array of pattern objects, these patterns are cycled through to create varying blocks of items in the grid.

Pattern Object

The rows and columns of a pattern are described as

{"rows":1, "columns":1}

Each pattern object describes the number of blocks the pattern will use and then describe how many of these blocks an item in the grid will use. The sizes of each block are based on the width and height of the grid vs the number of rows and columns.

A simple 2 x 2 pattern would look something like this:

{
    "rows":2, "columns":2, 
    "pattern":[
    {"x":0, "y":0, "width":1,  "height":1},
    {"x":1, "y":0, "width":1,  "height":1},
    {"x":0, "y":1, "width":1,  "height":1},
    {"x":1, "y":1, "width":1,  "height":1},
    ]
}

Another way to write the same pattern would be:

{
    "rows":4, "columns":4, 
    "pattern":[
        {"x":0, "y":0, "width":2,  "height":2},
        {"x":2, "y":0, "width":2,  "height":2},
        {"x":0, "y":2, "width":2,  "height":2},
        {"x":2, "y":2, "width":2,  "height":2},
    ]
}

Each item in the pattern then describes the position and sizing of the item in the grid. This allows items to span multiple columns and rows.

grid.style.leadingPattern

The Leading Pattern "leadingPattern" attribute is a pattern object and is only used on the first iteration of the pattern, all other iterations are taken from the pattern array. The leading pattern is optional. See grid.style.pattern.

grid.style.trailingPattern

A pattern to be applied to the last set of items to be displayed in the grid. See grid.style.pattern.

List

A List Component

{
    ....
    "components":[
        {
            "type":"list",
            "displaysType":"sections",
            "item":{...},
            "dynamicLoading":true,
            "style":{
                "itemHeight":"150px"
            }
        }
    ]
}

The list component allows the binding of items to layouts and displaying them in a scrollable view.
The list component is a simplified version of the grid component, in that it only has one column and not patterning.
Items in the list always have width=fill and their height is determined by the value at list.style.itemHeight

list.style.itemHeight
Pixel dimension of the required item Height. Default: 100px

dynamicLoading
Sets if the app should automatically load additional items for the list as the user scrolls (in addition to the items downloaded at the start of the app run)

list.onScrollX & list.onScrollY
Scroll Events . See Scroll Events

Tab Bar

A tab bar component in a tab view

 {
    "type": "tabView",
    "style": {....},
    "content": {....},
    "tabBar": {
        "type": "tabBar",
        "item": {....},
        "selectedItem": {....},
        "style": {
            "justifyItems": true,
            "width": "fill",
            "edgePadding": "10px",
        }
    }
}

The Tab Bar (tabBar) is used to display a list of selectable sections as a horizontally scrolling list in a Tab Layout. When an item is selected from this list the parent tab layout will load its content.

tabBar.item

The layout for displaying an individual tab (section). An Item layout is required.

tabBar.selectedItem

Selecteditem provides a layout for displaying the currently selected section. A Selected layout is optional however it provides a means of telling the user which tab(section) is currently open in the parent tab layout. The selected layout is used in place of the item layout when a tab bar item is selected.

tabBar.style.justifyItems

Boolean (true / false) When enabled if the total items and their layouts are less that the tab bar width, the tab bar will fill all available horizontal space and adding additional padding between the items of the tab bar.
Default: false

tabBar.style.edgePadding

A pixel value of padding between the left edge and the first tab and the right edge and the last tab.
Default:0px

Circle

Circle Component

{
    ....
    "components":[
        {
            "type":"circle",
            "style":{
                "backgroundColor":"#ff0000",
                "radius":20
            }
        }
    ]
}

The circle component draws a circle on screen. The size of the circle is determined by circle.style.radius.

Ellipse

Ellipse Component

{
    ....
    "components":[
        {
            "type":"ellipse",
            "style":{
                "backgroundColor":"#ff0000",
                "width":"80px",
                "height":"40px"
            }
        }
    ]
}

The ellipse component draws an ellipse on screen. The size of the ellipse is determined by ellipse.style.width and ellipse.style.height.

Square

Square Component

{
    ....
    "components":[
        {
            "type":"square",
            "style":{
                "backgroundColor":"#ff0000",
                "edgeLength":"80px"
            }
        }
    ]
}

The square component draws a square on screen. The size of the square is determined by square.style.edgeLength.

Rectangle

Rectangle Component

{
    ....
    "components":[
        {
            "type":"rectangle",
            "style":{
                "backgroundColor":"#ff0000",
                "width":"80px",
                "height":"40px"
            }
        }
    ]
}

The rectangle component draws a rectangle on screen. The size of the rectangle is determined by square.style.width and square.style.height.

Html Component

Html Component

{
    ....
    "components":[
        {
            "type":"html",
            "css":"{some css}",
            "elements":[
                ....
            ],
            "style":{
                ....
            }
        }
    ]
}

The html component integrates html components into app templates.

html.elements
The elements property of the html component can either be a string or array of hybrid-components.

html.css
The css property is a plain text string of css to be applied to the html component and its elements.

html.style.parallax
see style.parallax

html.style.loadingIndicatorPosition
see style.loadingIndicatorPosition

html.style.loadingIndicatorColor
see style.loadingIndicatorColor

html.onScrollX & html.onScrollY
Scroll Events . See Scroll Events

Hybrid Components

Hybrid components are essentially JSON versions of html elements.
The element type is inserted as the component type and an array attributes holds the various attributes for the element. This gets read and processed by the app to display content with a little more freedom.
If the html element is supported by iOS and Android then it should work here.
The code sample here should give you a good indication of how hybrid elements are composed.

A html component containing hybrid elements

{
    "type": "html",
    "id": "webview",
    "css": "{some css}",
    "style": {
        "width": "fill",
        "bottom": "0px",
        "below": "menuBar"
    },
    "elements": [
        {
            "type": "div",
            "id": "mainContainer",
            "attributes": [
                {
                "class": "main-container"
                }
            ],
            "elements": [
                {
                "type": "div",
                "id": "topimage",
                "attributes": [
                    {
                    "class": "image-container"
                    },
                    {
                    "style": "background-image:url($image); background-size:cover; width:100%; height:273px; content:'';"
                    }
                ]
                }
            ]
        }
    ]
}

Styles

Every layout and component has a style (weather you add one or not). The style defines the appearance, positioning(if in a relative layout) and sizing.
A complete list of style values is below, some are specific to certain components.

Landscape & Portrait Styles (Nested Styles)

A style using a landscape nested style.

{
    "type":"linear",
    "style":{
        "backgroundColor":"#ff0000",
        "landscape":{
            "backgroundColor":"#0000ff"
        }
    }
    ....
}

The layout above will be red coloured in portrait and blue coloured in landscape.

To manage differences between landscape and portrait orientations styles can include a nested style using the landscape or portrait keys.

Values in those styles will override values in the parent style when the device is using the corresponding orientation.

style.direction

Direction

{
    "direction":"horizontal"
}

Type
enum: vertical horizontal
default:vertical

Description
The layout or scroll direction of the layout or component

style.backgroundColor

Background Color

{
    "backgroundColor":"#ff0000"
}

Type
Color

Description
The background color of the view

style.textBackgroundColor

Text background color

{
    "textBackgroundColor":"#ff0000"
}

Type
Color

Description
The background color of text lines in a text component

style.shadowColor

Shadow Color

{
    "shadowColor":"#dedede"
}

Type
Color

Description
The shadow color of the view

style.color

Color

{
    "color":"#00ff00"
}

Type
Color
Default:#000000

Description
The fill color of the view, on an image it can change the color (if png) and changes text color in text components.

style.borderColor

Border Color

{
    "borderColor":"#efefef"
}

Type
Color

Description
The border color of the view.

style.cornerRadius

Corner radius

{
    "cornerRadius":3
}

Type
integer [0;∞]

Description
Add rounded corners to the view

style.borderWidth

Border Width

{
    "borderWidth":"1px"
}

Type
Dimension

Description
The width of the view border

style.width

Width

{
    "width":"fill"
}

Type
Dimension

Description
The width of the view

style.height

Height

{
    "height":"fill"
}

Type
Dimension

Description
The height of the view

style.top

Top

{
    "top":"0px"
}

Type
Dimension

Description
The distance from the top edge of the parent layout. (Child layouts and components only)

style.bottom

Bottom

{
    "bottom":"0px"
}

Type
Dimension

Description
The distance from the bottom edge of the parent layout. (Child layouts and components only)

style.right

Right

{
    "right":"0px"
}

Type
Dimension

Description
The distance from the right edge of the parent layout. (Child layouts and components only)

style.left

Left

{
    "left":"0px"
}

Type
Dimension

Description
The distance from the left edge of the parent layout. (Child layouts and components only)