Chapter
This
Use the following menu options to navigate the SL1 user interface:
- To view a pop-out list of menu options, click the menu icon (
). - To view a page containing all the menu options, click the Advanced menu icon (
).
This
What is Gluecode?
Gluecode is PHP code that is executed by the report engine when the report is generated. The gluecode must:
- Process the inputs from the Input Form.
- Make queries to the database or use other methods to gather the required data.
- Format the data so it can be populated into the Output Template.
You can add and edit gluecode on the Report Management page (Reports > Management > Report Manager).
Processing Input Form Options
The values selected by the end user in the input form for a report are passed to the gluecode for that report in the $input array. The keys in the $input array are the values from the Input name field for all form input components and custom report components on the input form.
For a form input component, the value at the corresponding array key is:
- Checkbox. Either 0 (unchecked) or 1 (checked).
- Dropdown Select. The value from the Option Values array for the selected label.
- Hidden. The static value supplied in the configuration or the value from the input component selected in the configuration.
- Multiple Checkboxes. A non-associative array of values. The array values are the values from the Checkbox Values array for the checkboxes that were selected by the user. The array does not include information about checkboxes that were not selected by the user.
- Multiple Select. A non-associative array of values. The array values are the values from the Option Values array for the labels that were selected by the user. The array does not include information about labels that were not selected by the user.
- Multiple Select with Category. A non-associative array of values. The array values are the values from the Option Values array for the labels that were selected by the user. The array does not include information about labels that were not selected by the user.
- Radio Buttons. The value from the Radio Button Values array for radio button select by the user.
- Text Area. The string entered by the end-user in the text area.
- Text Field. The string entered by the end-user in the text field.
For custom report components, the Input name of the custom report component will point to an array. That array will contain an item for each child input element. Each item in the array will use the Input name of the child input element as its key.
Available Resources
The following resources can be used by gluecode:
- The $db object, which provides methods for querying the primary database in SL1. For more information, see the Database Methods section.
- The data engine class, which provides methods for fetching performance data collected by SL1. For more information, see the Data Engine section.
- The debugging functions described in the Debugging Reports section.
Output
There are two different methods by which gluecode can output values to the output template. The structure of the output template is the same for both methods. Every report must use only one of the two methods:
- The $output array. This option passes the entire data set to the output template when the gluecode has finished executing. This method is easier to use. However, the PHP memory limit for the execution of a single report is 3 MB, which typically translates to a row-limit of 10,000.Large reports will generate a memory error and fail to execute when using the $output array.
- The $em7_report object. When using this option, output is passed incrementally using a set of methods associated with the $em7_report object. This method typically requires more lines of code in the gluecode. However, this option does not require the entire data set to reside in memory.
Output Templates and Output Directives
An Output Template is an Open Office Spreadsheet file (.ods file) that defines the format of the generated report. An Output Template defines the formatting and table structure you want to use for the generated report.
An output template includes one or more output directives. An output template directive indicates how output provided by report gluecode should be laid out. There are four general types of output directives:
- Array Binding Directives. These output template directives define a section of the output template (a cell, a row, a table, or an entire sheet) that will be repeated for each item in an array outputted by the gluecode. For example, suppose a report outputs a list of tickets, with one ticket on each row. The gluecode for the report outputs an array of tickets. The output template would include the bindrow output template directive, specifying the name of that array, to indicate the row that should be repeated for each ticket in the output.
- Conditional Directives. These output template directives include or exclude sections of the output template (e.g. columns, rows, tables, etc) based on the output from the gluecode. For example, suppose a report has an option that can be used to include or exclude certain columns. The glucode for the report would output a boolean value for each optional column, indicating whether the column should be included. The output template would include the ifcol output template directive in each column to indicate that the inclusion of that column is controlled by the boolean value.
- Style Directives. These output template directives can be used to dynamically apply styles to cells in the output. For example, suppose a report outputs a color-coded list of tickets, with the colors applied based on the severity of the ticket. The gluecode for the report would include the color that is associated with each ticket in the output. The output template would include the applystyle output template directive in the appropriate cell(s) to select the style that matches that color.
- Image and Chart Directives. These output template directives can be used to place images and charts in the output.
Using the $output Array
To use the $output array to pass data to the output template, you must assign an array of values, typically multi-dimensional, to $output before the gluecode finishes executing. When SL1 processes the output template, the output directives are used to traverse the keys in the $output array and place corresponding values on the output template.
The values in the first dimension of the $output array are:
- Single values used to output static elements on a report. For example, $output might include 'date' as an array key, the value of which is the date the report was generated. The output template would include a directive to place the date in a static location in the output.
- Single values used to control behavior. For example, $output might include 'opt_cols' as an array key, the value of which is a boolean that controls whether the user wants optional columns in the report. The output template would include a directive to include or exclude certain columns based on the boolean value.
- One or more arrays that contain information for a repeated element in the report. Repeated elements include sheets, tables, rows, and cells. The number of times the element is repeated is equal to the number of elements in an array. For example, $output might include 'rows' as an array key, which is used to repeat a row multiple times. A row is inserted for each key in the $output['rows'] array. The value assigned to each key in the $output['rows'] array determines that values that are placed on that row. The key for a row in the $output['rows'] array can also be placed on the row, but this is not required (i.e. it can be any arbitrary value). Typically, the value assigned to each key in the $output['rows'] array is an array of values, one for each column.
If an array is included as a value in the $output array, that second-dimension array can include arrays as values, etc. Additional dimensions can be used to nest repeated elements within other repeated elements, for example:
- The $output array includes the key 'sheets', which is used to repeat a sheet in the output multiple times. An array of values is assigned to $output['sheets'], which includes one key for each sheet that will be added to the output. This example uses an arbitrary key for each sheet; human-readable key values could be used and optionally included in the output, e.g. to label each sheet. The $output array now looks like this:
- Each value in the $output['sheets'] is an array that includes the key 'tables'. This key is used to repeat a table within each sheet. An array of values is assigned to the 'tables' key, which includes one key for each table that will be added to that sheet. This example uses an arbitrary key for each table; human-readable key values could be used and optionally included in the output, e.g. to label each table. The $output array now looks like this:
- Each value in each array of tables is an array that includes the key 'rows'. This key is used to repeat a row within each table within each sheet. An array of values is assigned to the 'rows' key, which includes one key for each row that will be added to that table within that sheet. This example uses an arbitrary key for each row; human-readable key values could be used and optionally included in the output, e.g. as the first value in each row. The $output array now looks like this:
- Each value in each array of rows is assigned an array of column values. The keys in this array are used in the output template to indicate where to place the values in the array within each row. For example, suppose the tables have the columns "id", "device", and "availability". The $output array now looks like this:
- In this example, there are multiple arrays that include only one key (sheets, tables, rows). These arrays can include additional values, which can be any of the three types of values described for the first dimension in the $output array. For example, the array for each sheet, which in this example includes only the key 'sheet', could also include the key 'name', the values of which can be used to label each sheet.
[sheets] => Array
(
[0]
[1]
.
.
)
[sheets] => Array
(
[0] => Array
{
[tables] => Array
{
[0]
[1]
.
.
}
}
[1] => Array
{
[tables] => Array
{
[0]
[1]
.
.
}
}
.
.
)
[sheets] => Array
(
[0] => Array
{
[tables] => Array
{
[0] => Array
{
[rows] => Array
{
[0] =>
[1]
.
.
}
}
[1] => Array
{
[rows] => Array
{
[0]
[1]
.
.
}
}
.
.
}
}
[1] => Array
{
[tables] => Array
{
[0] => Array
{
[rows] => Array
{
[0]
[1]
.
.
}
}
[1] => Array
{
[rows] => Array
{
[0]
[1]
.
.
}
}
.
.
}
}
.
.
}
[sheets] => Array
(
[0] => Array
{
[tables] => Array
{
[0] => Array
{
[rows] => Array
{
[0] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
[1] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
.
.
}
}
[1] => Array
{
[rows] => Array
{
[0] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
[1] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
.
.
}
}
.
.
}
}
[1] => Array
{
[tables] => Array
{
[0] => Array
{
[rows] => Array
{
[0] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
[1] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
.
.
}
}
[1] => Array
{
[rows] => Array
{
[0] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
[1] => Array
{
[id] => <id value>
[device] => <device value>
[availability] => <availability value>
}
.
.
}
}
.
.
}
}
.
.
}
Using the $em7_report object
The $em7_report object is instantiated automatically for all gluecode. To use the $em7_report object to pass output to the output template, use the following methods:
- set_token_value(string token, string value). This method outputs single values for static elements or to control behavior on a report. The token parameter must match the parameter supplied in the output directive that places this value in the output template. The value parameter is the value you want to supply to the output directive.
- get_token(string token). This method returns a token object that references either a [bindrow:token] or [bindtable:token] output directive. The token parameter must match the parameter supplied in the output directive. The token object returned by this method can then be used to populate data in the tables or rows.
Token objects have the following methods:
- new_table(string token). Use this method only on tokens that reference a [bindtable:token] output directive. This method returns a token object that references an instance of a table inside a [bindtable:token] output directive. The token parameter must be unique to this table and can be used in the output in the {##} output directive. The token object returned by this method can then be used to populate data in the tables or rows.
- get_token(string token). Use this method only on tokens that reference an instance of a table inside a [bindtable:token] output directive, i.e. a token returned by the new_table(string token) method. This method returns a token object that references a [bindrow:token] output directive inside the instance of a table. The token object returned by this method can then be used to create new rows.
- new_row(string token). Use this method only on tokens that reference a [bindrow:token] output directive, i.e.a token returned by the get_token(string token) method. This method returns a token object that references an instance of a row inside a [bindrow:token] output directive. The token parameter must be unique to this row and can be used in the output in the {##} output directive. The token object returned by this method can then be used to populate data in the rows.
- set_value(array values). Use this method only on tokens that reference an instance of a row inside a [bindrow:token] output directive, i.e. a token returned by the new_row(string token) method. This method populates the row with data. The array keys in the values parameter must match the output directives that add values to each column.
- set_token_value(string token, string value). This method can be used:
- On tokens that reference an instance of a row inside a [bindrow:token] output directive, i.e. a token returned by the new_row(string token) method. The data associated with a row is an array with one entry for each column. This method populates a single entry in the data array. The token parameter is the array key and must match an output directive on one of the columns in the row. The value parameter is the value to add to that column.
- On tokens that reference an instance of a table inside a [bindtable:token] output directive, i.e. a token returned by the new_table(string token) method. This method can be used to supply data for the table in addition to the row data, i.e. values for output directives that appear inside the [bindtable:token] directive but outside the [bindrow:token] directive. For example, you could supply a title for each table using this method. The token parameter must match an output directive parameter. The value parameter is the value to supply for that directive.
- close_row(). Use this method only on tokens that reference an instance of a row inside a [bindrowtoken] output directive, i.e. a token returned by the new_row(string token) method. This method saves the row. You must use this method on every row created in the gluecode; a row is not passed to the output template and removed from memory until it is closed. You cannot edit a closed row.
- close_table(). Use this method only on tokens that reference an instance of a table inside a [bindrowtoken] output directive, i.e. a token returned by the new_table(string token) method. This method saves the table. You must use this method on every table created in the gluecode; a table is not passed to the output template and removed from memory until it is closed. You cannot edit a closed table.
For example, suppose your output template is configured with output directives that specify repeated rows inside repeated tables. Suppose that:
- tables are added to the output template using the output directive [bindtable:organizations].
- rows are added to the output template using the output directive [bindrow:devices].
To start populating data in the output template, you would first get a token object that references the [bindtable:organizations] directive:
$organization_tables = $em7_report->get_token('organizations');
The gluecode would then include a loop. Suppose that on each iteration of the loop, the key for each table is stored in the variable $org. On each iteration of the loop, a new table is added to the output using the token that was returned by the previous method:
$org_table = $organization_tables->new_table($org);
The token for each table is then used to get a token that references the [bindrow:devices] directive within that table:
$devices = $org_table->get_token('devices');
The gluecode would include a second loop within the current loop. Suppose that on each iteration of the second loop, the key for each row is stored in he $did variable and an array of column values for that row is stored in the $device variable. On each iteration of the second loop, the $devices token, which references the [bindrow:devices] directive, is used to add a row:
$device_row = $devices->new_row($did);
$device_row->set_value($device);
$device_row->close_row();
After the second loop completes, the current table is closed:
$org_table->close_table();