Differences

This shows you the differences between two versions of the page.

--- plugin:struct:aggregation [2016-12-08 10:42] – [Table] grosse
+++ plugin:struct:aggregation [2024-03-13 18:17] (current) – [Special Columns] 91.89.222.218
@@ Line 2: / Line 2: @@
 ====== Struct Plugin: Aggregation ======
-Aggregation of structured data is the main purpose of the plugin. Aggregation is done through a simple syntax which will result in a dynamic table listing all pages and associated data matching certain criteria.
-The basic syntax looks like this:
+Aggregation of structured data is the main purpose of the plugin. Aggregation is done through simple syntax mechanisms that are used to collect, filter, sort and output data stored in schemas. Currently, there are three types of **aggregations**:
+  * [[plugin:struct:aggregation:table|Table]] -- tabular display of aggregated data
+  * [[plugin:struct:aggregation:list|List]] -- list display of aggregated data
+  * [[plugin:struct:aggregation:value|Value]] -- display of a single value((Strictly speaking this is not an aggregation but it is listed here since it allows the output of data))
+The editors for global and serial data are aggregations, too:
+  * [[plugin:struct:globaledit|Global Data]]
+  * [[plugin:struct:serialedit|Serial Data]]
+In addition to the above output types, there exist some syntax to add additional **controls** to the displayed aggregation data:
+  * [[plugin:struct:aggregation:filter|Filter]] -- filter displayed data via drop-down elements
+  * [[plugin:struct:cloud|Cloud]] -- filter displayed data via a tag cloud
+===== Aggregation Options =====
+All the above syntax modes (except [[plugin:struct:aggregation:value|Value]]) follow the same basic syntax containing a key-value list of options:
 <code wiki>
@@ Line 13: / Line 33: @@
 </code>
-The aggregation-syntax is very similar to that of the [[plugin:data#data_table_output|data plugin]]. The main difference is that you have to specify a schema name (or more than one). :!:
-The keyword before the colon is a configuration option and the value after it is the actual setting. To make it more fault tolerant, multiple option names are frequently possible. Here is a list of all available options:
+The keyword before the colon is a configuration option and the value after it is the actual setting. To make it more fault tolerant, multiple option names are frequently possible. Not all options are available for all aggregations and control mechanisms, but every one of them **requires** at least the ''schema'' and ''cols'' options (See [[#Schema and Column Selection]] below).
-^ Option(s)                         ^ Required?  ^ Description                                                                                                                               ^
-| schema\\ from                     | yes        | These are the schemas from which you want to display the data.                                                                            |
-| cols\\ select                     | yes        | These are the attributes you want to display. These are the same //names// you used in the Data Entry part                                |
-| head\\ header\\ headers           | no         | If specified, these names will be used in the table headers instead of the column names                                                   |
-| max\\ limit                       | no         | How many rows should be displayed. If more rows are available the table will be made browsable. If not given all matching rows are shown  |
-| sort\\ order                      | no         | By what column should the table be sorted initially? Prepend a ''%%^%%'' to reverse the sorting                                           |
-| filter\\ where\\ filterand\\ and  | no         | Filter by a column value. You may specify this more than once, multiple filters will be ANDed. (see also [[plugin:struct:filters]])       |
-| filteror\\ or                     | no         | Like filter, but multiple instances will be ORed (see also [[plugin:struct:filters]])                                                     |
-| dynfilters                        | no         | Set to ''1'' to enable a row of input fields for dynamically filtering the table                                                          |
-| summarize                         | no         | Set to ''1'' to calculate sum of columns                                                                                                  |
-| align                             | no         | List of column alignments. The alignments can be ''left'' (''l''), ''center'' (''c'') or ''right'' (''r'')                                |
-| rownumbers                        | no         | Set to ''1'' to show row numbers                                                                                                          |
-| width\\ widths                    | no         | Comma-separated list of column widths to use. CSS units and percentages can be given                                                      |
-| csv                               | no         | Set to ''0'' to disable the [[plugin:struct:csvexport|CSV export]] for this aggregation                                                   |
-Please note that you can join data from multiple page schemas (as long as they are assigned on the same pages), but can only run aggregations on a single lookup schema.
+^ Option(s)                         ^ Description                                                                                                                                                                                                        ^ Available in                                     ^
-===== Aliases =====
+| schema\\ from                     | These are the schemas from which you want to display the data. Multiple schemas are not supported in all aggregations and controls.                                                                                | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| cols\\ select                     | These are the attributes you want to display. These are the same //names// you used in the Data Entry part. You may use ''*'' to select all columns. This can be combined with Special Names e.g. ''%pageid%, *''  | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| align                             | List of column alignments in table output. The alignments can be ''left'' (''l''), ''center'' (''c'') or ''right'' (''r'')                                                                                         | table\\ global\\ serial                          |
+| class\\ classes                   | Allows to configure a comma separated list of CSS classes aggregation should have. This makes custom styling easier.                                                                                               | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| csv                               | Set to ''0'' to disable the [[plugin:struct:csvexport|CSV export]] for this aggregation                                                                                                                            | table\\ global\\ serial                          |
+| dynfilters                        | Set to ''1'' to enable a row of input fields for dynamically filtering a table                                                                                                                                     | table\\ global\\ serial                          |
+| filter\\ where\\ filterand\\ and  | Filter by a column value. You may specify this more than once, multiple filters will be ANDed. (see also [[plugin:struct:filters]])                                                                                | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| filteror\\ or                     | Like filter, but multiple instances will be ORed (see also [[plugin:struct:filters]])                                                                                                                              | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| head\\ header\\ headers           | A comma separated list of labels. If specified, these names will be used in the table headers instead of the field labels                                                                                          | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| index                             | Number of letters to use to create an alphabetical index for lists                                                                                                                                                 | list                                             |
+| max\\ limit                       | How many results should be displayed. Tables will be paginated, other aggregations and controls will ignore additional reaults                                                                                     | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| nesting\\ nest                    | Number of levels to nest list results                                                                                                                                                                              | list                                             |
+| rownumbers                        | Set to ''1'' to show row numbers                                                                                                                                                                                   | table                             |
+| sepbyheaders                      | Set to ''1'' to include headers in list output                                                                                                                                                                     | list                                             |
+| sort\\ order                      | By what column should the table be sorted initially? Prepend a ''%%^%%'' to reverse the sorting                                                                                                                    | table\\ list\\ global\\ serial\\ filter\\ cloud  |
+| summarize                         | Set to ''1'' to calculate sum of columns                                                                                                                                                                           | table\\ global\\ serial                          |
+| target\\ page                     | The page to which filter links should point to. If not specified, the current page is used.                                                                                                                        | filter\\ cloud                                   |
+| width\\ widths                    | Comma-separated list of column widths to use. CSS units and percentages can be given                                                                                                                               | table\\ global\\ serial                          |
+===== Schema and Column Selection =====
+As mentioned above, all aggregations and controls require at least the ''schema'' and ''cols'' options.
+Where multiple schemas can be given, resulting rows will be **joined on their page ID**. The aggregation will list pages which have **all the given schemas** assigned. This of course means that you can never include a global data schema when using multiple schemas, because global data has no page id. Joining serial data may return unexpected results.
+==== All Fields ====
+You can select all fields available in the given schemas by using an asterisk ''*'' as column name. You can also combine it with special columns.
+<code>
+---- struct table ----
+schema: schema1, schema2
+cols: %pageid%, *
+----
+</code>
+==== Aliases ====
 When selecting data from multiple schemas which contain the same field names, you have to prefix them with the schema name:
@@ Line 44: / Line 86: @@
 </code>
-You can use aliases to reference schemas to type less. Aliases are separated by a space from the schema name:
+You can use aliases as shortcodes to reference schemas in order to reduce your typing. Aliases are separated by a space from the schema name:
 <code>
@@ Line 56: / Line 98: @@
-===== Special Columns =====
+==== Special Columns ====
 The following special column names can be used to access non-field columns:
-^ Special Name      ^ Description                                                 ^
+^ Special Name       ^ Description                                                 ^
-| ''%pageid%''      | The page name of the page holding the matching struct data  |
+| ''%pageid%''       | The page name of the page holding the matching struct data, if any  |
-| ''%title%''       | The title (first heading) of the above page                 |
+| ''%title%''        | The title (first heading) of the above page                 |
-| ''%lastupdate%''  | The date and time when the page or data was last updated    |
+| ''%rowid%''        | The number of the row in the database (meaningful only for global and serial data)      |
-| ''%lasteditor%''  | The user that last changed the page                         |
+| ''%lastupdate%''   | The date and time when the page or data was last updated    |
+| ''%lasteditor%''   | The user that last changed the page                         |
+| ''%lastsummary%''  | The last edit summary of the page                           |
+In order to use them in templates, add another percent sign infront of the special name. E.g. for ''%pageid%'' use ''%%pageid%''
-===== List =====
-As an alternative to the table, you can also aggregate the data in list form. This is largely analogous to [[plugin:data#data_list_output|Data Lists of the data-plugins]]
-The basic syntax for list aggregations is very similar to table aggregations and looks like this:
-<code>
----- struct list ----
-schema: schema_name
-cols: %pageid%, other, cols
-----
-</code>
-Lists support a new option: ''sepbyheaders''. If you set this option to ''1'' and define headers for the columns, than each column will be prefaced with their header.
-Several options from the table-aggregation are not supported for the list-aggregation:
-^ Option                            ^ supported for lists          ^
-| schema\\ from                     | yes                          |
-| cols\\ select                     | yes                          |
-| head\\ header\\ headers           | with ''sepbyheader'' option  |
-| max\\ limit                       | yes                          |
-| sort\\ order                      | yes                          |
-| filter\\ where\\ filterand\\ and  | yes                          |
-| filteror\\ or                     | yes                          |
-| dynfilters                        | no                           |
-| summarize                         | no                           |
-| align                             | no                           |
-| rownumbers                        | no                           |
-| width\\ widths                    | no                           |
-| csv                               | no                           |