Documentation for the ConfiDoc plugin Plugin for Confluence
| Info |
|---|
See also tutorials for easy to follow examples on how to use ConfiDoc in different scenarios |
TableView:
confidoc-table
ListView:
confidoc-list
CardView:
confidoc-card
| The confidoc-table, confidoc-list, and confidoc-card macros are used to present the |
ConfiDoc TableView confidoc-table | Macro to visualize your REST service content (or RSS, CSV, XML) as table, with filtering and data sorting/ordering | Name of the service to use | serviceId | Services are defined by Confluence administrators using ConfiDoc plugin configuration |
|---|
| Root element to use | root | Use it when you need an additional filter over returned JSON. Accepts field names as an input. |
|---|
| Sorting/Ordering | sort | See examples below |
|---|
| Filter to apply on returned data | filter | See examples below |
|---|
| Cache resources locally (30 minutes, by default) | useCache | You requests are cached locally, in Confluence cache. Useful when you want to improve page loading times and reduce number of requests to external servers |
|---|
| Show lookup dialog for service | enableLookup | Users will be able to set own parameters for configured service request |
|---|
| Labels to use for lookup parameters | lookupLabels | Key-values, separated by & (as in URL), where key - is parameter name, and value is the text you want to use as label |
|---|
| Caption for action button in lookup dialog | lookupBtnLabel | |
|---|
|
ConfiDoc ListView confidoc-list | Macro to visualize your REST service content (or RSS, CSV, XML) |
in WYSIWYG view (also supports as a table, list (WYSIWYG), or card, each with filtering and data sorting/ordering |
) to use | serviceId | Services are defined by the Confluence |
|---|
|
administrators ConfiDoc | the plugin's configuration screen | | Root element |
|---|
|
to useUse it when you need an additional filter over returned JSON. Accepts | Apply additional filters to the returned JSON data using field names as |
|
an input.| inputs | | Sorting/Ordering | sort | See examples below |
|---|
| Filter |
|---|
|
to apply | filter | Apply a filter on returned data |
|---|
|
filter | See | ; see examples below | | Cache resources locally |
|---|
|
(30 minutes, by default)You requests are cached locally, in Confluence cache. Useful when you want | Request results can be stored locally in the Confluence cache in order to improve page loading times and to reduce the number of requests to external servers; default local cache duration is 30 minutes | | Show |
|---|
|
lookup | service configuration dialog |
|---|
|
for service | enableLookup | Users will be able to |
|---|
|
set | configure their own parameters for a configured service request |
|
Labels to use for lookup | Define configuration parameters | lookupLabels |
|---|
|
Key-values| Define labels for the configuration dialog using key-value pairs, separated by "&" (as in URL notation), where key |
|
- | is the parameter name, and value is the text |
|
you want use | be used as the label | | Caption for |
|---|
|
action in lookup dialoglookupBtnLabel | | ConfiDoc CardView confidoc-card | Macro to visualize your REST service content (or RSS, CSV, XML) as card (vertical table), with filtering and data sorting/ordering | Name of the service to use | serviceId | Services are defined by Confluence administrators using ConfiDoc plugin configuration |
|---|
| Root element to use | root | Use it when you need an additional filter over returned JSON. Accepts field names as an input. |
|---|
| Sorting/Ordering | sort | See examples below |
|---|
| Filter to apply on returned data | filter | See examples below |
|---|
| Cache resources locally (30 minutes, by default) | useCache | You requests are cached locally, in Confluence cache. Useful when you want to improve page loading times and reduce number of requests to external servers |
|---|
| Show lookup dialog for service | enableLookup | Users will be able to set own parameters for configured service request |
|---|
| Labels to use for lookup parameters | lookupLabels | Key-values, separated by & (as in URL), where key - is parameter name, and value is the text you want to use as label |
|---|
| Caption for action button in lookup dialog | lookupBtnLabel | |
|---|
|
| lookupBtnLabel | Provide a helpful pointer under the configuration dialog submit button |
|---|
| Set HTML element ID | elementId | Useful, when you want to have a predictable and constant element id in HTML for generated content. Important: "_viewport" will be added to the name |
|---|
|
ConfiDoc Field confidoc-field |
Macro to define This macro defines a field to |
show display returned data within the ConfiDoc TableView or |
ConfiDoc Name to show (based on returned ConfiDoc ConfiDoc )Label to use, when showing this field | The label for the field to be displayed inside the table or list |
|
Choose for the fieldThere is a set of field types supported| Choose the field type from these supported formats: |
|
Or ), so - : the value will be shown without
|
|
any transformations, but as-isUseful when you have a date values you need to transform in more readable format| Define the format in a returned data field in order to reformat using Output format (below), for example, to transform returned date values into more readable form | | Output format | outputFormat |
|---|
|
Output format takes what was prepared by 'Input format' and tries to apply the formatting rules given on this value | | CSS to apply on field value | css | CSS to apply on a rendered field |
|---|
| Define the transformation rules for Output to be applied to data in the Input format (above) | | CSS | css | Define CSS rules to be applied on returned data in a rendered field |
|---|
| Access control | restrictions | Control access to this field with a comma |
|---|
|
Visible only to groups/users | restrictions | Comma names/usernames this field is visible to. Leave | - or user names; leave blank if there are no restrictions | | Set HTML element ID | elementId | Useful, when you want to have a predictable and constant element id in HTML for generated content |
|---|
|
ConfiDoc Excerpt confidoc-excerpt |
Macro Use this macro to include in the Confluence page the HTML or binary content |
from any webserver inside your Confluence page(such as images) from an external webserver |
to use | serviceId | Services are defined by Confluence administrators |
|---|
|
using | with the ConfiDoc plugin configuration | | Selector | root | A CSS-like selector, but limited to a form: element attribute="value".
To select elements by name |
|---|
|
- just give a tag name. Example: div - , give the element's name; for example: div will select all the divs |
|
from in the page To select all div elements in the page with |
|
'' class name, use: div class="myclass" | | Download and cache resources |
|---|
|
(images) Downloads external resources locally, | You can: - leave links to external resources "as is"
- download external resources (such as images) to the Confluence server and adds them as attachments
|
|
.- to the page
- proxy external resources though local proxy
| | Cache resources locally |
|---|
|
(30 minutes, by default)You are cached , . Useful when you want | to improve page-loading times and to reduce the number of requests to external |
|
servers| servers (default cache duration is 30 minutes) | | Content Type | contentType |
|---|
|
Will force | Force ConfiDoc to use the given content type | | Custom CSS styles |
|---|
|
to apply on rendered element styles | rules to apply on the rendered element | | Include as | type | This option provides a way to control how the macro outputs the returned data. |
|---|
|
Caption for link, when loaded as binaryAvailable types include: - Link
- Date
- Number
- Image
- 'as-is' (blank: the value will be shown without transformation)
| | Show service configuration dialog | enableLookup | Users will be able to configure their own parameters for a configured service request |
|---|
| Define configuration parameters | lookupLabels | Define labels for the configuration dialog using key-value pairs, separated by "&" (as in URL notation), where key is the parameter name, and value is the text to be used as the label |
|---|
| Caption for configuration button | lookupBtnLabel | Provide a helpful pointer under the configuration dialog submit button |
|---|
| Caption | downloadBtnLabel | When the content to be loaded is binary, a download link will be rendered |
|---|
|
. This parameter set''s it''s caption| ; this parameter sets the label on that link | | Set HTML element ID | elementId | Useful, when you want to have a predictable and constant element id in HTML for generated content. Important: "_viewport" will be added to the name |
|---|
|
ConfiDoc Excerpt Anchor confidoc-excerpt-anchor |
Macro This macro helps you to group |
some content elements inside a block and easily reference this block later |
by with the ConfiDoc Excerpt macro | Alphanumeric AnchorID (no spaces) | anchorId |
|---|
|
You will be able to reference it from | Reference this block from the ConfiDoc Excerpt macro using the ''div id="AnchorID"'' selector |
|
ConfiDoc Show-For (IF) Macro confidoc-show-for |
Macro shows This macro displays included content only for given users and/ |
user or groups | Content is visible only to | restrictions |
|---|
|
Comma| A comma-separated list of |
|
usergroup usernames |
ConfiDoc Globals confidoc-globals |
Convenient This macro provides a convenient way to store and |
show display global variables in Confluence | Variable name | vars | Variable name |
|---|
|
CSS Rules for ConfiDoc Fields confidoc-field-css |
Helper This is a helper macro to |
use use when you want to show differently, based on their values | Field value or expression |
|---|
|
to matchYou can use | Use values or expressions |
|
, similar to filters, Filters | in order to match returned data much as you would for filters; ConfiDoc filters are very similar in functionality to ConfiForms Filters ( |
|
the other plugin | also developed by Vertuna LLC) | | Field name | fieldName |
|---|
|
Name | Define the name of the field to which this rule should be applied |
|
on, if left empty then | (if blank, then the rule is applied |
|
on | to the row) | | CSS to be applied | css | CSS to apply when the above condition is met |
|---|
|
css | CSS to apply when condition is met
Using filters
ConfiDoc filters employ syntax similar to the queries in Apache Lucene for expressions, which supports grouping using brackets (currently, ConfiDoc filters support only outer or single bracket sets, not inner or sub-brackets). Filters support matching for expressions that start with a wild-card, and filtering per field as well as for free text search (seeking a match against any field value).
The operators AND and OR are case-sensitive!
Filters support negative results with "not notation" to filter records that do not match the given filter with the '!'. For example: !f1:[empty] will search for records where the f1 field value is not empty (has some value).
Filters can perform simple arithmetic operations on dates (for example, to add or substract days from today's date). Here are some examples:
To match records where f1 contains 'success' and f2 is after yesterday or where f3 equals 'accepted':
(f1:*success AND f2:>[yesterday]) OR (f3:accepted)
To match records where f1 contains 'success' and where f2 is after yesterday or where f3 is not empty:
(f1:*success AND f2:>[today]-1) OR (!f3:[empty]) -
This filter would be invalid because ConfiDoc does not yet support inner brackets in expressions:
(f1:*success AND (f2:>[yesterday] OR (f3:accepted)).
Reserved words to use in expressions:
| [empty] | To match when a particular field in the returned data is empty; for example: field1:[empty] will match records where field1 is empty (does not have a value even though the form defines this field) |
| [now] | To match on the current time and date; often useed with '<' and '>' for comparing with dates stored. For example: someDateField:<[now] will match records where the field 'someDateField' has a value which is in the past compared to now (current time) |
| [today] | To match on the current date, much like [now], but without hours and minutes |
| [tomorrow] | To compare the returned data against tomorrow's date ( [today]+1 could also be used) |
| [yesterday] | To compare the returned data against yesterday's date ( [today]-1 could be also used) |
| [end-of-month], [start-of-month], [now], [today], [yesterday], [tomorrow], [today]+N, [today]-N | Functions added / revised in ConfiDoc version 3.4.6 |
| '<' and '>' | These can be used together with date and datetime fields, as well as to compare values in the returned data with values stored in numeric fields |
| '=<' and '>=' | Added in ConfiDoc 3.4.6 |
| ! | To reverse or negate the filter condition; for example: !field1:[empty] will find records that have data in 'field1' |
Additional examples:
- assuming field1 is of type date (or datetime), this filter will return records where the returned values of field1 are not older than 5 days before now:
field1:[today]-5
- assuming field1 is of type date (or datetime), this filter will return records where the returned values of field1 is not after 10 days from now
field1:[today]+10
Using sorting and limiting the number of records returned
ConfiDocs supports sorting results in ascending (ASC) and descending (DESC) directions. The syntax is similar to that in SQL, and the ordering rules must be coma separated.
Order directions ASC and DESC are case-sensitive!
Some examples: to limit the number of records returned, a LIMIT operator is used; for example,
f1 ASC, f2 DESC
will sort the dataset by the field f1 in ascending order and by f2 in descending order.
f1 ASC, f2 DESC LIMIT 2
will sort the dataset by the field f1 in ascending order and by f2 in descending order, and will limit the number of records returned to 2.
LIMIT 5
will limit the number of records returned to 5.