Article Content

  1. Screens
    1. Screen Properties
    2. Full Example


  2. Layouts
    1. Available layouts
    2. Common Primitive Properties
    3. Common Object Properties
  3. Fixed Grid
    1. Non-Promitive Config Properties
    2. Primitive Config Properties
    3. Full Example
  4. Flex Grid
    1. Principles
    2. Config Properties
    3. Values for Columns and Rows
    4. Why Is the Configs-Property an Array?
    5. Full Example
  5. Flexbox

Screens

Screens are used to specify which of the configured layouts is used for which screen size. A layout can be selected according to screen width, height and/or aspect ratio. The first screen that matches the conditions is selected. If no screen matches, the first layout is rendered as a fallback. Layouts require an id property to be able to be referenced by a screen.


Screen Properties

Property
Type
Description
Example Values
Default
layout
string
Specifies which layout to select if the conditions are met.
  "example_layout"

conditions
object
The set of conditions that need to be met, to select the before mentioned layout.
  {  
    "layout": "largeLayout",  
    "conditions": {    
      "aspectRatio": 1.7,    
      "forceRatio": true,    
      "maxScreenHeight": 790,   
      "maxScreenWidth": 800,   
      "minScreenHeight": 740,    
      "minScreenWidth": 600,  
      "ratioTolerance": 0.1,   
      "syncSets": {}  
    }
  }

conditions
.ratioTolerance

number
The tolerance for the aspect ratio.
0.2
0.1
conditions
.forceRatio

boolean
Should the aspect ratio be enforced?
true
false


Full Example

  "screens": [    
    {      
      "layout": "smallLayout",  
      "conditions": { 
        "minScreenHeight": 740,   
        "maxScreenHeight": 790,
        "maxScreenWidth": 600   
      } 
   },
   {
      "layout": "largeLayout",
      "conditions": {
        "minScreenHeight": 790,
        "maxScreenHeight": 9999,
        "minScreenWidth": 601,
        "aspectRatio": 0.5,
        "ratioTolerance": 0.2,
        "forceRatio": true
      }
    }
  ]



Layouts

In previous ONE DATA you had only one report layout available. This worked with dividing the available view port in equally sized units with given amount of units you wanted to have. In OD Markup language this will be further enhanced to give the possibility to choose from different layout systems ("layout types"). To be able to migrate old reports as good as possible, we already implemented a layout which behaves exactly like the old layout used to. This layout type is called "fixedGrid".


Available layouts

Name
Type
Purpose
Equivalent in classic ONE DATA reports
Fixed Grid
fixedGrid
Define a layout with dynamic width and height of cells based on fixed number of units for available space height and width.
This is the layout concept classic ONE DATA reports use exclusively
Flex Gridflexgrid

A layout system that allows you to create complex responsive wed design (Apps) layouts more easily and consistently across browsers.


Flexbox
flexboxThis layout flexibly distributes space along a single axis. 


Common Primitive Properties

Property
Type
Description
Example Value
Default
id
string
Specifies the unique name of the layout. It allows for the selection of the layout using screens[].layout
"layoutSmall"

type
string
Specifies the type of layout used
"fixedGrid"
"fixedGrid"
cellPadding
string
The padding pixels for a single placement.
"5px"
"5px"


Common Object Properties

Property
Type
Description
Default
config
object
The configuration of the layout.
Contains layout type specific configuration options
.
  "config": {
    "containers": [],
    "dim": {
      "x": 20,
      "y": 20,
      "z": 1
    }
  }

Example Value

  "config": {
    "containers": [
      {
        "id": "titleContainer",
        "pos": {
          "x": 1,
          "y": 1,
          "z": 1
        },
        "size": {
          "w": 4,
          "h": 4
        }
      }
    ],
    "dim": {
      "x": 20,
      "y": 20
    }
  }



Property 
Type
Description
Default
placements[]
object
Responsible for mapping a container specified in a layout to an element.
  "placements": [
    {
      "containerId": "",
      "elementId": ""
    }  
  ]

Example Value

  "placements": [
    {
      "containerId": "container1",
      "elementId": "element1Id"
    }
  ]



Property
Type
Description
Example Value
styles
object
Specify the default styles for all elements in the layout.
Visit section Sytles in Global article
columnStyles
object
Specify the default styles for selected table columns in the layout.
Visit section ColumnStyles in Global article



Fixed Grid

type = "fixedGrid"

To use a fixed grid, you have to define its dimensions (amount of x and y units) first. To actually place elements in this layout you have to add "containers" to the layout configuration. A container is then referenced in "placements[]" which provides the connection of a container to an element.


Non-Promitive Config Properties

Property
Type
Description
Default
containers[]
object[]
The actual containers holding the elements. The mapping from container to elements happens in `placements[]`
  "containers": [
    {
      "pos": {
        "x": 1,
        "y": 1,
        "z": 1
      },
      "size": {
        "w": 4,
        "h": 4
      }
    }
  ]


Example Value:

  {
    "id": "chart_1",
    "pos": {
      "x": 1,  
      "y": 1,
      "z": 1
    },
    "size": {
      "w": 24,
      "h": 4
    }  
  }


Primitive Config Properties

Property
Type
Description
Example Value
Default
dim.x
number
Amount of horizontal units to divide the available space width.
24
24
dim.y
number
Amount of vertical units to divide the available space height.
24
24
containers.id
string
The id of the container.
1
1
containers[].pos.x
number
The x coordinate of the upper left corner of the container.1
1
containers[].pos.y
number
The y coordinate of the upper left corner of the container.
1
1
containers[].pos.z
number
The z coordinate (z-index) of the container.
2
1
containers[].size.h
number
The number of units the container should span on the y axis.
"chart1"
""
containers[].size.w
number
The number of units the container should span on the x axis.
24
2


Full Example

  "layouts": [
    {
      "type": "fixedGrid",
      "config": {
        "dim": {
          "x": 24,
          "y": 24
        },
        "containers": [
          {
            "id": "container1",
            "pos": {
              "x": 1,
              "y": 1,
              "z": 1
            },
            "size": {
              "w": 24,
              "h": 4
            }
          }
        ]
      },
      "cellPadding": "5px",
      "placements": [
        {
          "containerId": "container1",
          "elementId": "element1"
        }
      ]
    }
  ]


Flex Grid

type = "flexGrid"

(Available from version 1.82.0 // 1.59.1 and upwards)

In previous version of Apps you only had the Fixed Grid layout available.
Now we introduce Flex Grid. A layout system that allows you to create complex responsive wed design (Apps) layouts more easily and consistently across browsers.


Principles

In contrast to fixed grid, where you define a relative but fixed width and fixed height for your containers, flex grid will also adjust to the size of the content of the containers. This allows to give containers enough size to always show all content without wasting much space.

But it also means that it won't cut off content or let it overflow. Keep in mind, that even when you configure a size to an absolute value like 200px and your content needs 300px, it will result in 300px. If you nevertheless want your content to overflow or to be cut off, you need to define your value as a maximum with minmax().


Config Properties

PropertyTypeDescriptionExample Value
configobjectThe configuration of the layout. Contains layout type specific configuration options.
  "config": {
    "grid": {
      "configs": [
        // Configuration 
        // options
        ]
      },
    "containers": [
      // Containers
    ]
  }
gridobjectGrid in which the containers are placed. The grids are structured in columns and rows.
  "grid": {
      "maxWidth": "1920px",
      "noPadding":  false,
      "configs": [
        // Configuration
        // options
      ]
  }
maxWidthstringDefine the maximum width of your app with px, e.g. 1920px.
  "maxWidth": "1920px"
noPaddingbooleanIf set to true, padding to the bottom, left and right of the grid will be removed.
  "noPadding": false
configsarrayConfiguration of grids. It's actually configs ("s") because you can configure multiple grids.

Why is the config property an array?
"configs": [
    {
      "columns": "1fr",
      "rows": "max-content 
               max-content
               max-content
               max-content
               max-content
               max-content
               1fr",
      "gap": "5px",
      "template": [
        "Container1",
        "Container2",
        "Container3",
        "Container4",
        "Container5",
        "Container6",
        "Container7"
      ]
    },
    {
      "minWidth": "1000px",
      "columns": "repeat(1fr, 3)",
      "rows": "max-content
               max-content 
               max-content 1fr",
      "gap": "10px",
      "template": [
        "Container1 Container1
         Container2",
        "Container3 Container4
         Container5",
        "Container3 Container4
         Container6",
        "Container7 Container7
         Container7"
      ]
    }
  ]
minWidthstringNumber of pixel in width needed until this configuration applies.
  "appearance": [
    {
    "minWidth": "1000px"
    }
  ]
columnsstringDefines the number and the size of the columns in the grid.
  "columns": "1fr 1fr 1fr"
rowsstringDefines the number and the size of the rows in the grid.
  "rows": "max-content
         max-content
         max-content 1fr"
gapstringDefine the gap between containers with px, e.g. 10px.
  "gap": "10px"
templatearrayDefines the arrangement of the containers within the grid.
  "configs": [
     {
      "template": [
         "Container1 Container2 .",
        "Container1 Container2 .",
        ". . Container5",
        "Container6 . Container7"
      ]
    }
  ]
containersarrayThe actual containers holding the elements. The mapping from container to elements happens in placements[].
  "containers": [
    {
      "id": "Container1",
      "appearance": [
        {
          "show": true,
          "minWidth": "1000px"
        }
      ],
      "background": "white",
      "shadow": true,
      "sticky": "top",
      "zIndex": 1,
      "horizontalAlignContent":
      "left",
      "verticalAlignContent":
      "top"
      "horizontalAlignBox":
      "left",
      "verticalAlignBox": "top"
    }
  ]
containers[].idstringThe unique ID of the container.
  "containers": [
     {
      "id": "Container1"
    }
  ]
containers[].
appearence
arrayThe appearance of the container. Takes an array of configuration objects, with a similar approach regarding responsiveness like in the configs-property.
Why is the configs-property an array? 

Additional appearence Properties:

Besides the special properties listed above, appearance may also take every prop on root level of the Flex Grid containers that is listed below with containers[]. This includes

  • background
  • horizontalAlignBox
  • verticalAlignBox
  • horizontalAlignContent
  • verticalAlignContent
  • shadow
  • sticky
  • zIndex

  "appearance": [
     {
      "hide": false,
      "show": true,
      "minWidth": "800px",
      "column": "2",
      "row": "2"
    }
  ]


In this example content will be centered small viewports, but will be left aligned on larger viewports: 

  "appearance": [
    {
      "horizontalAlignContent":
      "center"
    },
    {
      "minWidth": "800px",
      "horizontalAlignContent":
      "left"
    }
  ]
containers[].
appearence.
minWidth
stringNumber of pixel in width needed until this configuration applies.
  "minWidth": "1000px"
containers[].
appearence.
column
stringPosition in terms of column of the container that overlays another container.
  "column": "2"
containers[].
appearence.
row
stringPosition in terms of row of the container that overlays another container.
  "row": "1"
containers[].
appearence.
hide
booleanHide a container in a responsive context. Imagine a mobile layout where you concentrate on the most important information. In a mobile layout you do not want to show (hide) this container. In higher resolution layouts (e.g. desktop) you want to show it appearance.show. Use this property together with different mobile queries (break points).
  "hide": true
containers[].
appearence.
show
booleanShow a hidden container again in a responsive context. In a mobile (small screen) layout you do not want to show (hide) this container. In higher resolution layouts (e.g. desktop) you want to show it.
  "show": true
containers[].
background
stringSets the background color of the container.
  "background": "white"
containers[].
horizontal

AlignBox
stringSets the horizontal alignment of the box's children. The box when used in grid will then just be of the size of it's content.

Options: "left", "center", "right"
  "horizontalAlignBox": "right"
containers[].
vertical

AlignBox
stringSets the vertical alignment of the box. The box when used in grid will then just be of the size of it's content.

Options: "top", "center", "bottom"
  "verticalAlignBox": "top"
containers[].
vertical

AlignContent
stringSets the vertical alignment of the box's children.

Options: "top", "center", "bottom"
  "horizontalAlignContent": "top"
containers[].
horizontal

AlignContent
stringSets the horizontal alignment of the box's children.

Options: "left", "center", "right"
  "verticalAlignContent": "top"
containers[].
shadow
booleanToggles a container shadow.
  "shadow": true
containers[].
sticky
booleanMakes the container sticky.
  "sticky": "top"


Values for Columns and Rows

You can pass a CSS track sizing as a string to the grid and use the values you need to realize your sizing behavior. Take advantage of the functional notations like "minmax", "repeat" and new values like "min-content" and "max-content" to meet your layout goals.


Value
Description
fr
The fr unit (a “fraction”) can be used when defining grids like any other CSS length such as %, px or em. 
Imagine a four column grid. We are setting each of our four columns to one fraction (which happens to be 25%). But the advantage of fr is that if you have a gap between the columns there is no overflow on the x-axis anymore because setting each column to 1fr takes the gap automatically into account and subtracts it from the total width available for each column.
max-content
Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.
min-content
Is a keyword representing the largest minimal content contribution of the grid items occupying the grid track.
minmax(min, max)
Is a functional notation that defines a size range greater than or equal to min and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min-content. As a maximum, a <flex> value sets the track’s flex factor. It is invalid as a minimum.
repeat
Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form.


Why Is the Configs-Property an Array?

You can pass multiple config objects to configure different layouts for different min-widths to create a responsive grid.
The configuration will be transformed to CSS, wrapped in media queries. The first one will always be the default layout without media query restriction, so there's always a configuration applicable. If you provide a "minWidth" in the first config object, it'll be ignored.
The media queries will follow a mobile first approach and the attributes omitted in the configurations with "min-Width" restriction will apply the attributes defined in the default (the first) config object.
Imagine a layout where small viewports have 1 column and 7 rows, a mid-size viewports with 2 columns and 5 rows, and larger viewports with 3 columns and 4 rows.


Multiple configs by minWidth are implemented in CSS media queries

Important: They take action on the window/viewport width, not the width of the preview area in split mode. You should use a seperate preview window to check your layout then.


  "configs": [
       {
        //options: fr, max-content, min-content, minmax(min, max), repeat
        "columns": "1fr",
        // options: fr, max-content, min-content,
        // minmax(min, max), repeat, px, %, ...
        "rows": "1fr 1fr 1fr 1fr 1fr 1fr 1fr",
         "gap": "5px",
        "template": [
          "Container1",
          "Container2",
          "Container3",
          "Container4",
          "Container5",
          "Container6",
          "Container7"
        ]
      },
      {
         "minWidth": "800px",
         "columns": "1fr 1fr",
         "rows": "1fr 1fr 1fr 1fr 1fr",
         "gap": "10px",
         "template": [
           "Container1 Container1",
           "Container2 Container2",
           "Container3 Container4",
           "Container5 Container6",
           "Container7 Container7"
        ]
      },
      {
        "minWidth": "1600px",
         "columns": "1fr 1fr 1fr",
         "rows": "1fr 1fr 1fr 1fr",
         "gap": "10px",
         "template": [
           "Container1 Container1 Container2",
           "Container3 Container4 Container5",
           "Container3 Container4 Container6",
           "Container7 Container7 Container6"
        ]
      }
    ]


Full Example

  "layouts": [
    {
      "type": "flexGrid",
      "config": {
        "grid": {
          "maxWidth": "1920px",
          "noPadding": false,
          "configs": [
            {
              "columns": "1fr",
              "rows": "max-content max-content max-content max-content
                       max-content max-content 1fr",
              "gap": "5px",
              "template": [
                "Container1",
                "Container2",
                "Container3",
                "Container4",
                "Container5",
                "Container6",
                "Container7"
              ]
            },
            {
              "minWidth": "1000px",
              "columns": "repeat(1fr, 3)",
              "rows": "max-content max-content max-content 1fr",
              "gap": "10px",
              "template": [
                "Container1 Container1 Container2",
                "Container3 Container4 Container5",
                "Container3 Container4 Container6",
                "Container7 Container7 Container7"
              ]
            }
          ]
        },
        "containers": [
          {
            "id": "Container1",
            "sticky": true,
            "background": "black",
            "shadow": true
          },
          {
            "id": "Container2"
          },
          {
            "id": "Container3"
          },
          {
            "id": "Container4"
          },
          {
            "id": "Container5"
          },
          {
            "id": "Container6"
          },
          {
            "id": "Container7"
          },
          {
            "id": "Container8",
            "appearance": [
              {
                "hide": true,
                "column": "1",
                "row": "1"
              },
              {
                "minWidth": "1000px",
                "show": true,
                "column": "2",
                "row": "1"
              }
            ],
            "verticalAlignContent": "top",
            "horizontalAlignContent": "center",
            "horizontalAlignBox": "right",
            "verticalAlignBox": "top"
          }
        ]
      },
      "placements": [
        {
          "containerId": "Container1",
          "elementId": "element1"
        }
      ]
    }
  ]


Flexbox

The Flexbox Layout is highly experimental and not bugfree. As soon as we reach a stable state here, it will be communicated.


type = "flexbox"

To use a fixed grid, you have to define a direction in which the items are dynamically arranged. To actually place elements in this layout you have to add a "container_id" to the layout configuration. This container is then referenced in "placements[]" which provides the connection of a container to an element.


Layout Config Properties 

Property
Type
Description
Example Values
Default
direction
string
Sets how items are placed in the layout container defining the main axis and the direction (normal or reversed).
"row", "row-reverse",
"column", "column-reverse"
"column"
wrap
string
Specifies whether or not overflowing items should wrap.
"nowrap", "wrap",
"wrap-reverse"
"nowrap"
h
string
Sets the height of the layout."200px", "50%"

w
string
Sets the width of the layout.
"300px", "80%"

alignContent
string
Specifies how items are aligned on the cross-axis.
"flex-start", "flex-end", "center", "space-between", "space-around", "stretch", "normal"
"normal"



Item Config Properties

Property
Type
Description
Example Values
Default
h
string
Sets the height of the layout.
"200px", "50%"

w
string
Sets the width of the layout.
"300px", "80%"

basis
string
Sets the initial main size of a flex item. has priority over width/height.
"auto", "0", "200px"
"auto"
grow
string
This factor specifies how much of the remaining space in the layout should be assigned to this item.
0, 1, 2
0
shrink
string
Specifies how the item will shrink relative to the rest of the items inside the same container.
0, 1, 2
1