-
Notifications
You must be signed in to change notification settings - Fork 0
EN: Table Slice
| Version added | 1.0.0 |
|---|
The table slice is used to display a data table in the pboml document.
In a pboml document, the table slice is represented using many fields.
Many of those fields are included already in the List of fields common to all types of slice. However, there are fields that are specific to the table slice.
| field name | type | optionality | Description |
|---|---|---|---|
type |
String | Required | Must be set to table
|
variables |
Variables objects | Required | Contains all the variables of the table and their relevant information (contains the element of the stub of the table) |
content |
YAML array | Required | Contains variable objects with there associated values (contains the data of the table) |
To simplify the explanation of the different fields, this section will rely on the following table example:
|
Department |
Total government |
Department of National Defense |
Royal Canadian Mounted Police |
Canadian Revenue Agency |
Employment Social Development Canada |
Public Health Agency of Canada |
Canada Border and Services Agency |
|
|---|---|---|---|---|---|---|---|---|
| 2016-2017 |
Total $ millions |
27,484 | 6,719 | 2,362 | 2,668 | 1,463 | 174 | 972 |
|
Per FTE $ |
79,473 | 75,860 | 80,978 | 68,881 | 67,025 | 82,062 | 71,806 | |
| 2017-2018 |
Total $ millions |
29,189 | 7,075 | 2,476 | 2,941 | 1,563 | 179 | 985 |
|
Per FTE $ |
82,354 | 78,788 | 83,766 | 73,968 | 68,579 | 86,223 | 72,797 | |
| 2018-2019 |
Total $ millions |
30,912 | 7,358 | 2,559 | 2,973 | 1,632 | 184 | 1,293 |
|
Per FTE $ |
83,956 | 80,005 | 85,678 | 71,493 | 68,579 | 86,223 | 92,703 |
- Sources
Receiver General for Canada
Office of the Parliamentary Budget Officer
The variables object is where the each variable object's definition is given. Even though they are generally represented as rows by the pboml renderer, they function exactly like the columns/structure of a relational database.
Variables are conceptually distinct from content objects in as such:
- They represent the distinct pieces of information or attributes that are being stored for each record (
contentobject) in the table. - Each variable has a specific data type that defines the kind of data it can hold, such as markdown or number. One variable can only define a single content type (e.g. numbers, markdown fields, etc.).
- Variables serve as placeholders for specific types of information and provide a structured way to store data in a table.
- For example, in a table representing information about people, variables could include "Name," "Age," "Gender," and "Location.".
In the variables object, each variable is keyed by a unique key that will be used in the content objects to provide a value for said variable. That key is therefore not explicitly present in the variable object itself but must be present.
| field name | type | optionality | Description |
|---|---|---|---|
label |
Localised String Object | Required | Describes the variable to the user |
group |
Localised String Object | Optional | When provided, will present variables with the same group name together. |
units |
Localised String Object | Optional | Custom unit of the values that are represented by the variable |
type |
String | Optional | Describe the type of value that is represented by the variable (number or markdown) |
emphasize |
Boolean | Optional | Allows to add a emphasis on the values of the variable (e.g. highlight a given row with a different background color). |
is_descriptive |
Boolean | Optional | Indicates that the values of a given variable are descriptive. |
A variable is structured as such:
{variable_key}:
label:
en: {label_in_english}
fr: {label_in_french}
group:
en: {group_name}
fr: {group_name}
unit:
en: {units_used}
fr: {units_used}
type: {number or markdown}
emphasize: {true or false}
is_descriptive: {true or false}In the Example Table, The variables are: "Department" and all the different "Totals" and "Per FTE" that are grouped by year.
In the pboml document, this is how it looks:
- type:table
content:
...
variables:
department:
label:
en: Department
fr: Ministère
is_descriptive: true
total20162017:
label:
en: Total
fr: Total
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $ millions
fr: Millions de $
perfte20162017:
label:
en: Per FTE
fr: Par ETP
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $
fr: $
total20172019:
label:
en: Total
fr: Total
type: number
group:
en: 2017-2018
fr: 2017-2018
unit:
en: $ millions
fr: Millions de $
perfte20172018:
label:
en: Per FTE
fr: Par ETP
type: number
group:
en: 2017-2018
fr: 2017-2018
unit:
en: $
fr: $
total20182019:
label:
en: Total
fr: Total
type: number
group:
en: 2018-2019
fr: 2018-2019
unit:
en: $ millions
fr: Millions de $
perfte20182019:
label:
en: Per FTE
fr: Par ETP
type: number
group:
en: 2018-2019
fr: 2018-2019
unit:
en: $
fr: $The label field is required in order to properly render the table. It is represented by a Localized String Object.
The group field is optional. In order to allows the renderer to group rows into a complex structure, it is necessary to reuse exact same group field for each grouped variable. This field is represented by a Localized String Object.
In the Table Example, the variables total20162017 and perfte20162017 are grouped together because they have the same group field.
In the pboml document, this is how it looks:
...
variables:
department:
label:
en: Department
fr: Ministère
is_descriptive: true
total20162017:
label:
en: Total
fr: Total
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $ millions
fr: Millions de $
perfte20162017:
label:
en: Per FTE
fr: Par ETP
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $
fr: $
... The unit field is optional. It describes the type of unit that is used to represented the values of their respected variable. The units are represented by a Localized String Object.
In the Table Example, the variables department doesn't have any unit while the variable total20162017 has the unit $ millions.
When only one variable presents a unit or when all variables with a unit share the same unit in a slice, the renderer will display that unit outside of the table, above it. When more than one unit is used in the same table, each variable will show that unit independently, under each variable's label.
In the pboml document, this is how it looks:
...
variables:
department:
label:
en: Department
fr: Ministère
is_descriptive: true
total20162017:
label:
en: Total
fr: Total
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $ millions
fr: Millions de $
...The type field is required. It describes the type of value that is used to represented the values of their respected variable. As of version 1.0.0 of pboml, there are currently only two different types of values: number and markdown. The units are represented by a Localized String Object.
In the Table Example, the type of the variables are department is set to markdown and for the variable total20162017 it is set to number.
In the pboml document, this is how it looks:
...
variables:
department:
label:
en: Department
fr: Ministère
is_descriptive: true
type: markdown
total20162017:
label:
en: Total
fr: Total
type: number
group:
en: 2016-2017
fr: 2016-2017
unit:
en: $ millions
fr: Millions de $
...The emphasize field is optional. It is describe by a boolean. If set to true, the renderer will emphasize the variable and all its respective values. If this field is absent, it would be the same as if it where set to false and no emphasize will be rendered.
The is_descriptive field is optional. It is described by a boolean. Think of descriptive variables as a primary key column on a relational database's table. If set to true, the renderer will render the content of that variable as a <th /> cell.
Once the variables have been defined in the variables field, the content can be added to the content field as an object part of a YAML Array.
The structure of a content object relies entirely on the variables that were defined in the variables field. Each field contained in a content object is keyed by a corresponding key on the variables object. In a typical table, each content object is rendered as a column, sequentially from left to right on the table.
To illustrate, see the Table Example: the values inside the first two colomns ("Total government" and "Department of National Defense") are defined in the table slice as follows:
...
content:
- department:
fr: Total du gouvernement
en: Total government
total20162017: 27484
perfte20162017: 79473
total20172019: 29189
perfte20172018: 82354
total20182019: 30912
perfte20182019: 83956
- department:
fr: Ministère de la Défense nationale
en: Department of National Defense
total20162017: 6719
perfte20162017: 75860
total20172019: 7075
perfte20172018: 78788
total20182019: 7358
perfte20182019: 80005
...