wiki:strata:reference
no way to compare when less than two revisions
Unterschiede
Hier werden die Unterschiede zwischen zwei Versionen der Seite angezeigt.
— | wiki:strata:reference [19.01.2020 03:02] (aktuell) – angelegt Dominik Rimpf | ||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
+ | ====== Strata: Structured Data Plugin====== | ||
+ | |||
+ | The strata plugin allows you to add data to your pages and to query that data from your pages. This manual is split into two parts: | ||
+ | |||
+ | * the [[#quick guide]] will get you started with a few examples, | ||
+ | * the [[# | ||
+ | |||
+ | |||
+ | ====== Quick Guide ====== | ||
+ | |||
+ | The quick guide will get you up and running with some examples of how to enter and query. More advanced uses are discussed in the reference guide. | ||
+ | |||
+ | A good way to get more experienced is to add some simple data to your wiki, and start querying it. Most error messages are descriptive enough to get some idea of what went wrong. | ||
+ | |||
+ | |||
+ | ===== Data Block ===== | ||
+ | |||
+ | Data entry is done with ''< | ||
+ | |||
+ | < | ||
+ | <data person> | ||
+ | Full Name: Jane Maria Doe | ||
+ | Birthday [date]: 1982-7-23 | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | **Simple Values**: You add simple values to the data block by adding a line like '' | ||
+ | |||
+ | **Classes**: | ||
+ | |||
+ | **Types**: You can add a [[# | ||
+ | |||
+ | The same example, but extended with more features: | ||
+ | < | ||
+ | <data person> | ||
+ | -- Simple field-value pairs | ||
+ | Full Name: Jane Maria Doe | ||
+ | Address: | ||
+ | |||
+ | -- Types and Type Hint | ||
+ | Birthday [date]: 1982-7-23 | ||
+ | Birthplace [page:: | ||
+ | |||
+ | -- Multiple values | ||
+ | Contact [link]*: j.doe@example.com, | ||
+ | Contact [link]: jane.doe@workmail.com | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | **Empty values**: Any field that doesn' | ||
+ | |||
+ | **Type hints**: You can change how a [[# | ||
+ | |||
+ | **Multiple Values**: You can have multiple values with a field. Do this by either putting a '' | ||
+ | |||
+ | **Comments** All lines that start with double dashes (i.e., '' | ||
+ | |||
+ | |||
+ | ===== Tables and Lists ===== | ||
+ | |||
+ | Queries are written inside ''< | ||
+ | |||
+ | < | ||
+ | <table ?p " | ||
+ | ?p is a: person | ||
+ | ?p Birthday [date]: ?b | ||
+ | ?b < 1990-1-1 | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | **Patterns**: | ||
+ | |||
+ | For example, ''? | ||
+ | |||
+ | Variables are indicated with the ''?'' | ||
+ | |||
+ | Literals can be written down verbatim, except for subject literals. These should be enclosed in '' | ||
+ | |||
+ | **Types**: In a query, you can use [[#types]]. You can use types for fields and values, and you can use them in the opening tag. Types are ' | ||
+ | |||
+ | **Comparisons**: | ||
+ | |||
+ | You can only compare variables that are used in a pattern. | ||
+ | |||
+ | **Captions**: | ||
+ | |||
+ | < | ||
+ | <table ?p " | ||
+ | ?p is a: person | ||
+ | |||
+ | optional { | ||
+ | ?p Address: ?address | ||
+ | } | ||
+ | |||
+ | minus { | ||
+ | ?p Contact: ?c | ||
+ | } | ||
+ | |||
+ | group { | ||
+ | ?p | ||
+ | } | ||
+ | sort { | ||
+ | ?address (desc) | ||
+ | } | ||
+ | ui { | ||
+ | Person { | ||
+ | filter: select | ||
+ | } | ||
+ | Address { | ||
+ | filter: text | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | **Aggregates**: | ||
+ | |||
+ | For more on aggregates, see [[# | ||
+ | |||
+ | **Optional matches**: Normally, all patterns must be matched for the results to be shown. You can use an '' | ||
+ | |||
+ | You can have multiple optional blocks. You can even have optional blocks inside optional blocks. | ||
+ | |||
+ | **Exclusions**: | ||
+ | |||
+ | **Grouping**: | ||
+ | |||
+ | **Sorting**: | ||
+ | |||
+ | **User Interface**: | ||
+ | |||
+ | **Comments**: | ||
+ | |||
+ | **Caching**: | ||
+ | |||
+ | |||
+ | ====== Reference Guide ====== | ||
+ | |||
+ | The reference guide is split up into four sections: | ||
+ | * [[#Data Entry]] | ||
+ | * [[#Query Language]] | ||
+ | * [[#Query Results]] | ||
+ | * [[#User Interface]] | ||
+ | * [[#Types & Aggregates]] | ||
+ | |||
+ | |||
+ | ===== Data Entry ===== | ||
+ | |||
+ | Entering data is done with the ''< | ||
+ | |||
+ | What follows is a generic pattern of the syntax of data entry | ||
+ | < | ||
+ | <data class1 class2 classN #fragment identifier> | ||
+ | Field [type:: | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | == Field-Value pairs == | ||
+ | |||
+ | The simplest form of data entry. Fields and values are also called predicates and objects. It is possible to leave out the value, then the field-value pair will not be stored, but you can easily fill in the missing value later. | ||
+ | |||
+ | * Field names can contain any character except the following: '':'' | ||
+ | * Values can contain any character, but values in a list of multiple values can't contain '','' | ||
+ | |||
+ | You can add multiple values in a single line by adding an asterisk after the type (or after the key, if it has no type). The values should be separated by '','' | ||
+ | |||
+ | There is a single magic value to indicate the empty value: '' | ||
+ | |||
+ | == Classes == | ||
+ | |||
+ | As a convenience, | ||
+ | |||
+ | Classes are not handled specially. This way of adding classes to the data is merely a convenience. You can achieve the same by adding values to field '' | ||
+ | |||
+ | * Class names in the header can contain any characters except spaces, ''#'', | ||
+ | |||
+ | == Entry Title == | ||
+ | |||
+ | Normally, the '' | ||
+ | |||
+ | The field is generated from the fragment identifier if it is available. If the block has no fragment identifier, the page title is used as entry title. If you want to override the entry title of a data block, you can do so by adding the '' | ||
+ | |||
+ | == Field Types == | ||
+ | |||
+ | You can add a [[# | ||
+ | |||
+ | You can add a type hint to any type you use. You do so by adding the type hint to the type with a ''::'' | ||
+ | |||
+ | == Comments == | ||
+ | |||
+ | You can add comments by starting a line with '' | ||
+ | |||
+ | |||
+ | ==== Data Fragments ==== | ||
+ | |||
+ | Instead of associating data directly with the page, you can put it in a fragment. A fragment is a piece of data that is not directly associated with the page itself, but instead is associated with part of the page. | ||
+ | |||
+ | A data fragment is not implicitly associated with the page it is defined on. If you want to add such a relation, you need to do this yourself. Note that the '' | ||
+ | |||
+ | == Fragment Identifiers == | ||
+ | |||
+ | A data block is associated with a fragment simply by adding a fragment identifier to the block' | ||
+ | |||
+ | * Fragment Identifiers can contain any character except ''>'' | ||
+ | |||
+ | |||
+ | ==== Split Data Entries ==== | ||
+ | |||
+ | Sometimes, it makes sense to have all data associated with a single page, but defined in multiple data blocks throughout the page. This is possible by simply splitting the data blocks into multiple blocks. | ||
+ | |||
+ | Note that the [[# | ||
+ | |||
+ | |||
+ | ===== Query Language ===== | ||
+ | |||
+ | Querying data is done through the ''< | ||
+ | |||
+ | The following sections contain short samples, each of these samples is situated inside a table or list block. It is possible to enclose the whole of the query (not including sorting, grouping, or other [[#Query Results]] related blocks) in a '' | ||
+ | |||
+ | The query blocks are [[# | ||
+ | |||
+ | |||
+ | ==== Patterns ==== | ||
+ | |||
+ | Patterns are the basic building block of all queries. They are constructed according to the following format: | ||
+ | |||
+ | subject predicate: object | ||
+ | |||
+ | You can use variables, indicated by starting with ''?'', | ||
+ | |||
+ | * Variables can contain any character except spaces or '':'' | ||
+ | * Subject literals must be enclosed in '' | ||
+ | * Predicate literals can contain any character except '':'' | ||
+ | * Object literals can contain any character | ||
+ | |||
+ | You can refer to 'the current page' with '' | ||
+ | |||
+ | |||
+ | ==== Typing ==== | ||
+ | |||
+ | You can use types to make sure the data is interpreted in the correct way, and to create a better looking result. | ||
+ | |||
+ | subject ?predicate [type:: | ||
+ | |||
+ | [[#Types]] can only be added to variables. A variable in the subject position will always be typed as [[# | ||
+ | |||
+ | Types are ' | ||
+ | |||
+ | Types are propagated according to the following rules: | ||
+ | * variables in the subject position are always of type [[# | ||
+ | * The first explicit mention of a type for a variable will stick that type to the variable | ||
+ | * unless the object is explicitly typed, a typed predicate will propagate its type to the object | ||
+ | |||
+ | |||
+ | ==== Filters ==== | ||
+ | |||
+ | You can use simple filters to refine any matches from a pattern. | ||
+ | |||
+ | left > right | ||
+ | |||
+ | It is possible to use both variables and literals for left and right, but there must be at least one variable present. You can only use variables that are used in a pattern in the same block or inner blocks (with the exception of [[#minus]] blocks, which don't bind any variables). | ||
+ | |||
+ | === Comparison Operators === | ||
+ | |||
+ | The following filters apply to all types of data: | ||
+ | ^ Generic ^^ | ||
+ | ^ Filter ^ Name ^ | ||
+ | | '' | ||
+ | | '' | ||
+ | |||
+ | These filters only make sense on numerical values: | ||
+ | ^ Numerical ^^ | ||
+ | ^ Filter ^ Name ^ | ||
+ | | ''>'' | ||
+ | | ''> | ||
+ | | ''<'' | ||
+ | | '' | ||
+ | |||
+ | These filters (usually) only make sense on textual values: | ||
+ | ^ Textual ^^ | ||
+ | ^ Filter ^ Name ^ | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | |||
+ | The '' | ||
+ | |||
+ | |||
+ | ==== Optional ==== | ||
+ | |||
+ | Optional blocks can be used to optionally match extra patterns. | ||
+ | |||
+ | optional { | ||
+ | ... | ||
+ | } | ||
+ | |||
+ | An optional block must contain at least a [[# | ||
+ | |||
+ | |||
+ | ==== Union ==== | ||
+ | |||
+ | You can tell the wiki to combine two patterns. | ||
+ | |||
+ | union { | ||
+ | { | ||
+ | ... | ||
+ | } | ||
+ | { | ||
+ | ... | ||
+ | } | ||
+ | } | ||
+ | |||
+ | An union block can contain more than two options, but must have at least two. All options must contain at least a pattern, but can contain filters and query blocks as well. | ||
+ | |||
+ | |||
+ | ==== Minus ==== | ||
+ | |||
+ | A minus block is used to exclude all results for which the patterns in the minus block match. | ||
+ | |||
+ | minus { | ||
+ | ... | ||
+ | } | ||
+ | |||
+ | A minus block must contain at least a pattern, but can contain filters and other query blocks. | ||
+ | |||
+ | |||
+ | ===== Query Results ===== | ||
+ | |||
+ | This section describes the options you have to control the output of the query. | ||
+ | |||
+ | The query result blocks are: [[# | ||
+ | |||
+ | |||
+ | ==== Sorting ==== | ||
+ | |||
+ | You can sort on one or more variables. | ||
+ | |||
+ | sort { | ||
+ | ?variable (direction) | ||
+ | } | ||
+ | |||
+ | The sort block takes a single variable per line, with an optional direction between parenthesis. Both full (ascending and descending) and abbreviated (asc and desc) are usable. | ||
+ | |||
+ | |||
+ | ==== Grouping ==== | ||
+ | |||
+ | Grouping on one or more variables allows you to create overviews. | ||
+ | |||
+ | group { | ||
+ | ?variable | ||
+ | } | ||
+ | |||
+ | Grouping allows you to collapse multiple results into a single result. All results that have the same value for all variables mentioned in the group block will be merged into a single result. Any variable in the merged result that is not mentioned in the group block will contain multiple values. | ||
+ | |||
+ | |||
+ | ==== Variable Projection ==== | ||
+ | |||
+ | To define the variables to display, you can use the shorthand or the long syntax: | ||
+ | |||
+ | <table ? | ||
+ | |||
+ | fields { | ||
+ | ? | ||
+ | } | ||
+ | |||
+ | All elements except the variable itself are optional. If left out, a reasonable guess or default is used. | ||
+ | |||
+ | * The default aggregate is to use no aggregation | ||
+ | * The default type is the type associated with the variable in the query | ||
+ | * The default caption is the variable name with a capital first letter | ||
+ | |||
+ | Any variables not mentioned in the projection are left out of consideration for determining what the results are. This might create a problem where simple results from a complex query seem incomplete, in that case try [[# | ||
+ | |||
+ | |||
+ | ==== Aggregation Functions ==== | ||
+ | |||
+ | Aggregation functions are used to process a variables captured values before display. These functions can be used for things like counting, summing up or reducing the values to only the unique values. | ||
+ | |||
+ | See [[# | ||
+ | |||
+ | |||
+ | ==== Considering fields ==== | ||
+ | |||
+ | If a variable is not mentioned as one of the displayed fields, it will be ignored. You can hint that some field needs to be considered, but not displayed. | ||
+ | |||
+ | consider { | ||
+ | ?variable | ||
+ | } | ||
+ | |||
+ | All variables mentioned will be considered to be relevant, even if they are not displayed. Since the queries use so called 'set semantics', | ||
+ | |||
+ | ===== User Interface ===== | ||
+ | The '' | ||
+ | |||
+ | < | ||
+ | ui { | ||
+ | ui: generic | ||
+ | sort: default | ||
+ | filter: text | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | The properties that can be specified, are explained in the following subsections. | ||
+ | |||
+ | Note: Users that have JavaScript disabled will not benefit from the user interface settings. | ||
+ | ==== UI ==== | ||
+ | The property '' | ||
+ | ==== Sorting ==== | ||
+ | Using '' | ||
+ | ==== Filtering ==== | ||
+ | Using '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | By default, columns are not filterable. | ||
+ | |||
+ | ==== Per column configuration ==== | ||
+ | The properties '' | ||
+ | < | ||
+ | < | ||
+ | fields { | ||
+ | Person 1: ?p1 | ||
+ | Relation: ?r | ||
+ | Person 2: ?p2 | ||
+ | } | ||
+ | ui { | ||
+ | filter: text | ||
+ | Relation { | ||
+ | filter: select | ||
+ | sort: none | ||
+ | } | ||
+ | } | ||
+ | ?p1 is a: person | ||
+ | ?p2 is a: person | ||
+ | ?p1 ?r: ?p2 | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Here, we use a block '' | ||
+ | |||
+ | Besides identifying columns by name, they can also be identified by number. For example, column '' | ||
+ | |||
+ | When multiple columns have the same name, settings are applied to all columns that have the given name. To identify specific columns, index them by number. If you use both a block with a name (e.g. '' | ||
+ | |||
+ | === Alternative column configuration === | ||
+ | Instead of using a block for each column, it is also possible to set all '' | ||
+ | < | ||
+ | < | ||
+ | fields { | ||
+ | Person 1: ?p1 | ||
+ | Relation: ?r | ||
+ | Person 2: ?p2 | ||
+ | } | ||
+ | ui { | ||
+ | filter*: text, select, text | ||
+ | sort*: no, yes, no | ||
+ | } | ||
+ | ?p1 is a: person | ||
+ | ?p2 is a: person | ||
+ | ?p1 ?r: ?p2 | ||
+ | </ | ||
+ | </ | ||
+ | By adding a '' | ||
+ | < | ||
+ | < | ||
+ | fields { | ||
+ | Person 1: ?p1 | ||
+ | Relation: ?r | ||
+ | Person 2: ?p2 | ||
+ | } | ||
+ | ui { | ||
+ | -- We specify the second column as block, so don't care about the values now | ||
+ | filter*: text, , text | ||
+ | sort*: no,,no | ||
+ | Relation { | ||
+ | filter: select | ||
+ | sort: no | ||
+ | } | ||
+ | } | ||
+ | ?p1 is a: person | ||
+ | ?p2 is a: person | ||
+ | ?p1 ?r: ?p2 | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | ==== UI with Aggregates ==== | ||
+ | |||
+ | In general, the UI is quite intuitive, but combining it with aggregates might give unexpected results (unless you use a table, in which case no special handling is needed). The example below shows the column '' | ||
+ | |||
+ | < | ||
+ | <list ?p " | ||
+ | ?p is a: person | ||
+ | |||
+ | optional { | ||
+ | ?p Address: ?address | ||
+ | } | ||
+ | |||
+ | group { | ||
+ | ?p | ||
+ | } | ||
+ | sort { | ||
+ | ?address (desc) | ||
+ | } | ||
+ | ui { | ||
+ | filter: text | ||
+ | } | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | As shown below, the above query can easily be converted to one which lists each column only once and, therefore, does have separate filters for the address count and the addresses. | ||
+ | |||
+ | < | ||
+ | <list ?p " | ||
+ | ?p is a: person | ||
+ | |||
+ | optional { | ||
+ | ?p Address: ?address | ||
+ | ?p Address: ? | ||
+ | ?address = ? | ||
+ | } | ||
+ | |||
+ | group { | ||
+ | ?p | ||
+ | } | ||
+ | sort { | ||
+ | ?address (desc) | ||
+ | } | ||
+ | ui { | ||
+ | filter: text | ||
+ | } | ||
+ | </ | ||
+ | </ | ||
+ | ===== Types & Aggregates ===== | ||
+ | |||
+ | Types and aggregates are used to control how data is stored and displayed. | ||
+ | |||
+ | Types are used with data entry to store data in the correct format. Types with queries are used for handling comparisons, | ||
+ | |||
+ | Aggregates are used to process values after a query, but before they are displayed. | ||
+ | |||
+ | |||
+ | ==== Types ==== | ||
+ | |||
+ | Types are normally indicated by putting them between '' | ||
+ | |||
+ | ~~INFO: | ||
+ | |||
+ | |||
+ | ==== Aggregates ==== | ||
+ | |||
+ | Aggregates are used on displays of variables. They are attached to the variable with '' | ||
+ | |||
+ | ~~INFO: | ||
+ | |||
+ | |||
+ | ===== Caching ===== | ||
+ | |||
+ | By default, strata does not disable caching. This can result in pages with queries not updating after you edit data somewhere else. | ||
+ | |||
+ | If you edit other pages, you'll need to refresh the page with the list yourself, or add '' | ||
Die hier im BuFaTa ET Wiki dargestellten Arbeitsdokumente sind Einzelbeiträge der jeweiligen Autoren und i.d.R. nicht repräsentativ für die BuFaTa ET als Organisation. Veröffentlichte Beschlüsse und Stellungnahmen der BuFaTa ET befinden sich ausschließlich auf der offiziellen Homepage.
wiki/strata/reference.txt · Zuletzt geändert: 19.01.2020 03:02 von Dominik Rimpf