README.md
1# Airtable Dokuwiki Sync
2
3A Dokuwiki plugin to sync data from airtable
4**Not For Production Use** - this plugin is still in early development and may contain security flaws
5
6## Prerequisites:
7
8* Create an airtable account and get an API key: https://airtable.com/api - also see their documentation on how to
9 create a query
10* Make sure your account is **READ ONLY**
11
12## Installation
13
14* Place the airtable folder inside your Dokuwiki plugin directory:
15 DOKUWIKI_ROOT/lib/plugins
16* Set your **Base ID** and **API Key** using Dokuwiki's [configuration Manager](https://www.dokuwiki.org/plugin:config)
17* set **Max Records** parameter - this will add a limit to the number of rows in a table that a user can generate
18
19## Usage:
20
21Use the following syntax on any dokuwiki page.
22`{{airtable>type: "theType" | record-url: "theRecordURL"}}`
23
24Each parameter: is followed by a space and values enclosed in "". Parameters are separated by ' | ' (note the importance
25of spaces here)
26Multiple fields are separated by `,`
27
28Required Parameters:
29
30* `type: ` - This sets the display mode. Values:
31 * `image`
32 * `record`
33 * `table`
34 * `text`
35* `record-url: ` - The table/record you wish to pull data from.
36 * Within airtable, expand any record (by clicking on a field and pressing space) and copy the URL in the address bar.
37 * For a table URL, simply select the required table and copy the URL from the address bar
38 * E.g. https://airtable.com/tblQeRuyF7dZuuOLr/viwY9EwnBsF9dWsPt?blocks=hide
39
40### Tables:
41
42To display data from airtable in a table, use the following syntax:
43`{{airtable>type: "table" | record-url: "theURL" | fields: "field1", "field2" | where: "FORMULA" | order-by: "field_to_order_by" | order: "ORDER DIRECTION" | max-records: "X"}}`
44You must specify **at least one** field.
45
46Optional Parameters:
47
48* `where` - [an airtable formula](https://support.airtable.com/hc/en-us/articles/203255215-Formula-Field-Reference)
49 used to filter the results
50* `order-by` - specifies how the records will be ordered.
51* `order` - the direction of the order. Values:
52 * `asc` - Default
53 * `desc`
54* `max-records` - the maximum number of records displayed in the table. The default is the number specified in the
55 configuration manager. Any values higher than the maximum set will be ignored, and the admins maximum is used instead
56
57#### Example:
58
59`{{airtable>type: "table" | fields: "Name", "# of bulbs", "Posted By", "Post Text", "Post Image(s)" | where: "AND({Idea #} <= 3450, {Idea #} > 3430)" | max-records: "10" | order-by: "# of bulbs" | order: "asc" | record-url: "https://airtable.com/tblZnH5CY11MZEboF/viwVm4rH7dceE7VV2?blocks=hide"}}`
60Note: any media (images/audio/video) returned by airtable, will also be rendered inside the table.
61
62
63### Records:
64
65Any table query that results in one record will also be rendered as a 'record'.
66Records are rendered as a template where text is displayed on the left and media on the right. Syntax:
67`{{airtable>type: "record" | record-url: "theURL" | fields: "field1", "field2" | alt-tag: "ALT_TAG"}}`
68You must specify **at least one** field.
69
70Optional Parameters:
71
72* `alt-tag` - used if an image is found - Image
73 description. [How to write a good alt tag](https://moz.com/learn/seo/alt-text)
74
75#### Example:
76
77`{{airtable>Type: "record" | Fields: "Photo ID", "Ref #", "Upload Date", "Photo" | record-url: "https://airtable.com/tblwWxohDeMeAAzdW/viwlkwVdJY5sDNEWB/rec8WvGh6arIxPbqs?blocks=hide"}}`
78
79
80### Images:
81
82To embed an image from airtable use the following syntax:
83
84`{{airtable>type: "image" | record-url: "URL" | alt-tag: "ALT_TAG" | image-size: "IMG_SIZE" | position: "POS"}}`
85
86Optional Parameters:
87
88* `alt-tag: ` - Image description. [How to write a good alt tag](https://moz.com/learn/seo/alt-text)
89* `image-size: ` - The size of the image to appear on the page. Values:
90 * `small`
91 * `large` - Default
92 * `full`
93* `position` - Where the image is displayed on the page. Values:
94 * `block` - Default
95 * `left` - Floats left
96 * `centre` - Floats centre
97 * `right` - Floats right
98
99#### Example:
100
101`{{airtable>type: "image" | record-url: "https://airtable.com/tblZnH5CY11MZEboF/recAvmU5363ofWYR6" | image-size: "full" | alt-tag: "Digital Snake to Ethernet" | position: "right"}}`
102
103
104### Text:
105
106To pull data from airtable and display as inline text use the following syntax:
107
108`{{airtable>type: "text" | fields: "field1", "field2" | record-url: "theRecordURL"}}`
109This display type requires the additional parameter: `fields`
110**At least one** field must be specified. Multiple fields will be concatenated to a single string
111**Make sure to write the field exactly as it appears in airtable**
112
113#### Example:
114
115`Text Before: {{airtable>Type: "text" | Fields: "Part Name" | record-url:
116"https://airtable.com/tblK7lKsAP0YqSOwu/viwi6PpnGIhJsNAuf/recsKmhxWmZFckx66"}} :Text After`
117Will produce:
118`Text Before: Bottom Felt :Text After`
119
