Customize the layout of a workbook in code representation (Beta)
Customize the layout of a workbook in code representation (Beta)
This documentation describes one or more private beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.
This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see Beta features.
If you are interested in joining a limited test group and enabling this feature in your Sigma organization, contact Support or reach out to your Account Executive.
You can customize the layout of a workbook page in the code representation using the document.layout field. The layout field is an XML string that controls which page each element belongs to, and the size and position of each element on that page using a 24-column grid system. To control how elements are arranged on a page when you create or update a workbook using the API, specify the layout in the representation.
When you retrieve the representation of an existing workbook using the Get the code representation of a workbook endpoint, the layout field populates automatically based on the arrangement of elements on each page in the published version.
The layout field is required. Every element in document.elements must be placed in the layout, because the layout is what assigns an element to a page. A representation with an element the layout never references is rejected with an error naming that element, such as elements[0]: element 'ammWveJOET' is not placed in layout.
Example representation with layout
The following example shows a YAML representation of a workbook with a table and a bar chart. Both elements span the full width of the page and are stacked vertically, one above the other.
YAML representation with layout
Representing layout
In this example representation, the layout for Page 1 is defined in the layout field.
Layout representation
The layout field contains one <Page> element per workbook page. The id attribute of <Page> must match the id of the corresponding page in the document.pages array. Inside <Page>, each <Element> entry places one element on that page — the elementId attribute must match the id of the corresponding element in the document.elements array.
The gridColumn attribute controls the horizontal position and width of an element. The grid is 1-indexed across 24 columns, where 1 is the left edge and 25 is the right edge. For example, "1 / 25" spans the full width, "1 / 13" spans the left half, and "13 / 25" spans the right half.
The gridRow attribute controls the vertical position and height of an element. In this example, "1 / 21" places the table at the top of the page and "21 / 41" places the bar chart directly below it.
Layout tags
The layout field supports the following tags:
The following example places a table and a pivot table inside a container:
The container and both nested elements are siblings in the flat document.elements array; only the layout expresses that the table and pivot table sit inside the container.