README.md
1# Dokuwiki External Embed
2
3A Dokuwiki plugin to embed external content from the web
4This plugin includes domain privacy features allow you to embed content without needing a cookie / privacy policy for
5the embedded content This plugin will ask the user to accept embedded content from a domain before loading it (
6preventing it from loading trackers and cookies to the user's browser without consent) - see DOMAIN_WHITELIST
7
8## The road map:
9
10* Currently, only YouTube has been tested with this plugin. I would like to make it more robust so that content from
11 other domains can also be easily embedded (it is currently possible in this version however)
12
13_____
14
15## Prerequisites:
16
17To embed YouTube content:
18
19* Go to https://console.cloud.google.com/ and create a Google developer account
20* Once registered add a YouTube Data API v3 API to your account.
21* When setting up, restrict the key to only use the YouTube data API. You also may want to set an application
22 restriction for a production server.
23
24## Installation
25
26* Place the airtable folder inside your Dokuwiki plugin directory:
27 DOKUWIKI_ROOT/lib/plugins
28* Set your **API_KEY** using Dokuwiki's [configuration Manager](https://www.dokuwiki.org/plugin:config)
29* Set **PLAYLIST_CACHE_TIME** parameter - this is the time in hours before the playlist cache expires. I recommend 24
30 here.
31* Set **THUMBNAIL_CACHE_TIME** Parameter - this is the time in hours before the thumbnail cache expires. I recommend 100
32 here
33* Set **MINIMUM_EMBED_WIDTH** Parameter - the minimum size for an embed (200 default)
34* Set **MINIMUM_EMBED_HEIGHT** Parameter - the minimum height for an embed (200 default)
35* Set **DEFAULT_PRIVACY_DISCLAIMER** Parameter - The default disclaimer for an embed if you have not set a specific
36 disclaimer in the whitelist section below:
37* Set **DOMAIN_WHITELIST** Parameter - `<DOMAIN, DISCLAIMER (optional)>`
38 Enter the domain you want to whitelist. If you wish to set a custom disclaimer for this domain use a comma (see
39 example below:)
40 * `youtube.com, A YouTube video has been embedded here. You must accept the <a href="https://www.youtube.com/static?template=terms" target="_blank" rel="noopener">terms and conditions</a> in order to view the video`
41 * Note how you can use standard HTML here to embed Terms Of Service links.
42 * Separate each whitelist item with a new line
43
44## Usage:
45
46Use the following syntax on any dokuwiki page.
47`{{external_embed>url: "theURL"}}`
48
49Each parameter: is followed by a space and values enclosed in "". Parameters are separated by ' | ' (note the importance
50of spaces here)
51
52Required Parameters:
53
54* `url: ` - The URL associated with the embed
55
56Optional Parameters:
57
58* `embed-position:` - Displays the embedded content to the right, left or centre of the page. Values:
59 * `left`
60 * `centre`
61 * `right`
62* `width: ` - The width of the embedded content. Enter a number with no units e.g. `width: "300"`
63* `height: ` - the height of the embedded content. Enter a number with no units e.g. `height: "600"`
64
65### YouTube Video:
66
67To display a video from YouTube use the following syntax:
68`{{external_embed>url: "https://www.youtube.com/watch?v=UKvqC3t-M1g&ab_channel=Wintergatan" | autoplay: "true" | width: "720" | height: "480" | mute: "true" | controls: "false"}}`
69
70Optional Parameters:
71
72* `height` - Sets the maximum height of the iframe. Values:
73 * `360`
74 * `480`
75 * `720` - Default
76 * `1080`
77* `autoplay` - Specifies if the video will autoplay when the page is loaded. Values:
78 * `true`
79 * `false` - Default
80* `mute` - Specifies if the video will muted if autoplay is enabled. Values:
81 * `true`
82 * `false` - Default
83* `controls` - Specifies if the iframe will have video controls.
84 * `true` - Default
85 * `false`
86
87#### Example:
88
89`{{external_embed>url: https://www.youtube.com/watch?v=UKvqC3t-M1g&ab_channel=Wintergatan" | autoplay: "true" | width: "720" | height: "480" | mute: "true" | controls: "false"}}`
90
91### YouTube Playlist - The Latest Video:
92
93The following syntax is used to get the latest video from a YouTube playlist.
94
95Note that the rendered dokuwiki page is cached, you may want to find a way to auto purge your cache so that your videos
96stay up to date: https://www.dokuwiki.org/devel:caching
97
98The video ID's are stored and cached in a json cache file - these cache files last for the number of hours set in the
99config file.
100This is to prevent and reduce the number of calls needed to the YouTube API (maximum is 10,000 per day)
101`{{external_embed>url: "PLAYLIST_URL"}}`
102
103Optional Parameters:
104
105The same optional parameters used for the video type can also be used when using the playlist type
106
107#### Example:
108
109`{{external_embed>url: "https://www.youtube.com/playlist?list=PLLLYkE3G1HED6rW-bkliHbMroHYFf4ukv" | autoplay: "true" | height: "480" | mute: "true"}}`
110
111### Fusion:
112
113The following syntax is used to embed a fusion file using the fusion web player:
114`{{external_embed>url: FUSION_URL | height: "480 | allowFullScreen: "false"`
115
116Optional Parameters:
117
118* `width` - the width of the iframe. Default is 1280
119* `height` - the height of the iframe. Default is 720
120* `allowFullScreen` - allow users to make the embed fullscreen. Values:
121 * `true` - default
122 * `false`
123
124#### Example:
125
126`{{external_embed>url: "https://inventopia.autodesk360.com/g/shares/SH56a43QTfd62c1cd968f6d420f217923c26" | width: "720" | height: "480" | allowFullScreen: "false"}}`
127
128