https://github.com/colak/txp-media-shortcode
A shortcode for Textpattern CMS which allows the easy embedding of local or external media in articles.
https://github.com/colak/txp-media-shortcode
textpattern textpattern-shortcode
Last synced: 4 months ago
JSON representation
A shortcode for Textpattern CMS which allows the easy embedding of local or external media in articles.
- Host: GitHub
- URL: https://github.com/colak/txp-media-shortcode
- Owner: colak
- License: unlicense
- Created: 2020-07-09T08:23:01.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-01T17:34:51.000Z (about 1 year ago)
- Last Synced: 2024-11-01T18:27:17.397Z (about 1 year ago)
- Topics: textpattern, textpattern-shortcode
- Language: Smarty
- Homepage:
- Size: 449 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# txp-media-shortcode
## Introduction
This textpattern shortcode draws inspiration from [Nicolas Morand's](https://github.com/NicolasGraph) oui_player plugin and tries to produce similar results using textapattern's native tags but also make the players [GDPR](https://gdpr-info.eu/) compliant. In the case of locally hosted media no cookie consent is required. This work was [encouraged](https://forum.textpattern.com/viewtopic.php?pid=324309#p324309) by [Stef Dawson](https://github.com/Bloke), who first developed the smd_macro textpattern plugin. This later became part of txp's core code thanks to [Oleg's](https://github.com/bloatware) reworking of the native `` tag. Finally, many thanks are also due to [Michael K. Pate](https://github.com/michaelkpate) for the exhaustive testing and help for the detection of numerous bugs.
## Disclaimer (further to the one in the Licence)
Obviously, the author does not agree with one, or any of the policies or content of the providers the shortcode supports.
## Dependencies
* [Textpattern 4.7+](https://textpattern.com/)
* [oui_cookie](https://forum.textpattern.com/viewtopic.php?id=47048)
* [etc_query](https://forum.textpattern.com/viewtopic.php?id=37932)
* The media hosts' url schemas and embed codes.
* Georestrictions and privacy settings of individual media.
* The availability of the content. Millions of videos and sound-files are taken off the web daily. This is because they are removed by the original uploader or blocked by the hosts (usually because of DMCA notices).
## Advantages and disadvantages of shortcodes
Shortcodes are easy to edit by those without any knowledge of php but with sufficient knowledge of html and txp tags.
If you often embed media in your website, it is much easier to update the shortcode when providers change their embed scripts rather than find and change all instances of the embedded content in your articles.
The shortcode's GDPR warnings are parsed automatically, which save on typing, remembering cookie names, and privacy policy links.
When visitors accept a particular host's cookies, they do so for all embeds from that host site-wide.
Shortcodes are normally slightly slower in execution than raw php, or txp plugins.
## Installing
1. Copy the latest txp snippet from the [GitHub project page](https://github.com/colak/txp-media-shortcode/blob/master/media.tpl),
2. Create a new miscellaneous form in your Textpattern administration interface and name it `media`,
3. Paste the code into the form you created, and save.
4. Copy the media providers you are using for your website and paste those codes in new miscellaneous forms, using the same names as the ones provided without the tpl extension. For example `media_yt.tpl`should be `media_yt`.
5. Copy and paste the provided [css](https://github.com/colak/txp-media-shortcode/blob/master/css.css) in your style sheet and edit it to your liking.
## Cookies
According to GDPR, webmasters should never serve any tracking cookies without their visitors' explicit consent. The GDPR gives the right to any EU citizen to legally institute legal proceedings against any website owner, regardless of the website's or owner's location. The cookies served by the oui_cookie plugin do not track, but most media hosting providers do include tracking in their embeddable content. The acceptance cookies last for a duration of one year.
The above is but only one of the steps needed for full adherence to the EU law which also requests for a privacy policy and a description of the first and third party cookies served. Examples of such pages can be found in the neme.org site on:
* http://www.neme.org/about/privacy-policy
* http://www.neme.org/about/cookies
## Usage
1. To embed the media, simply use
`====`
2. Using the shortcode above, insert the id of the media file in the `media` attribute. The id can normally be found in the url of the video. For example:
* For a Vimeo address such as https://vimeo.com/336049258, the video id is `336049258`
* For a YouTube address such as https://www.youtube.com/watch?v=zlZTghhCuxg, the video id is `zlZTghhCuxg`
3. Use the `title` attribute should you wish to have a textile enabled descriptive text in the GDPR container. This text is replaced by the `embed` container once the cookie for the particular provider is accepted.
4. The `url` attribute is used in different ways, explained in the examples.
## Errors and warnings
You may see some errors and warnings after posting your shortcodes. These can appear before or after the cookies are accepted and they are only visible to logged-in users. They were added as prompts to promote the proper usage of the attributes.
## Attributes
1. from (required)
2. media (required)
3. title (recommended)
4. url (Required or recommended by some hosts)
5. img (optional id of an image from the database)
6. others. (See examples.)
### Details
Media hosts
from
url
title
img
others
Examples
Video or audio
Local
local
url="v"
ISO 639-1
✓
mp4, ogg, mpeg-4, flac, webm, m4v, mpg
(5)
url="a"
NA
NA
m4a, mp3, ogg, mp4, sac, webm, flac
(3)
Internet Archive
ia
url="v"
✓
✓
NA
(7)
url="a"
NA
Video
YouTube
yt
✓
✓
0
(6)
url="pl"
url="user"
Vimeo
v
✓
✓
NA
(1)
url="a"
url="vr"
DailyMotion
dm
NA
✓
✓
0
Utreon
u
NA
✓
✓
0
Utreon
twitch
NA
✓
✓
0
PeerTube
peer
NA
✓
✓
0
Rumble
rum
NA
✓
NA
NA
TED
ted
NA
✓
✓
NA
Vidyard
vy
NA
✓
✓
0
Vlare
vl
NA
✓
✓
NA
Freespeechtube
fst
NA
✓
✓
NA
BitChute
bc
NA
✓
✓
NA
Playtube
pt
NA
✓
✓
0
YouTube-nocookie 1
ytnc
NA
✓
✓
0
MetaCafe
mc
NA
✓
✓
0
Rebranded as Videoshub
Coub
cb
NA
✓
✓
NA
Video and GIF
Giphy
gp
url="g"
✓
✓
NA
(4)
url="v"
Audio
AudioBoom
ab
NA
✓
NA
NA
IndieSound
is
NA
✓
NA
NA
SoundCloud
sc
url in SoundCloud
✓
NA
NA
(2)
Spotify
sf
NA
✓
✓
NA
BandCamp (albums)
bac
Artist’s name as it appears in the subdomain
NA
✓
NA
(8)
MixCloud
mix
Artist’s name as it appears in the url
✓
NA
NA
(9)
Others
Google Maps 2
gm
NA
✓
✓
NA
Datawrapper
dw
NA
✓
✓
NA
## Examples
### 1. Embed from Vimeo
The shortcode allows for **individual video** embeds and Vimeo albums.
To embed an individual video use
``
Resulting code before cookie is accepted
Resulting code after cookie is accepted
The `title` attribute is textile enabled. As such you can have
``
Resulting code before cookie is accepted
For Vimeo **albums** use the `url="a"` attribute
``
Resulting code after cookie is accepted
``
### 2. Embed from SoundCloud
``
Resulting code before cookie is accepted
Resulting code after cookie is accepted
Embed from SoundCloud **using the url** attribute
``
Resulting code before cookie is accepted
News from Nowhere
Hosted by SoundCloud on https://soundcloud.com/furtherfield/news-from-where-we-are-1.
The resulting code after the cookie is accepted is the same as the one in the second example.
### 3. Embed local audio
The html5 audio tag, allows for the embedding of multiple formats to enhance compatibility with the various browsers and computer setups. To embed music residing in your installation's files directory, first upload the audio files using the same name followed by the extension. In your articles call the file name and state the extensions you have encoded those files to. (Currently the tag supports m4a, mp3, mp4, aac, webm, flac and ogg). You may want to check the [formats supported by different web browsers](https://en.wikipedia.org/wiki/HTML5_audio#Supported_audio_coding_formats).
``
The resulting code will be
Your browser does not support the audio element.
### 4. Embed from Giphy
Giphy offers two types of urls based on the media type, gif and video.
* giphy.com/gifs/name
* giphy.com/videos/name
To embed a **gif from Giphy** use
``
Resulting code before cookie is accepted
Resulting code after cookie is accepted
To embed a **video from Giphy** use
``
Resulting code before cookie is accepted
Resulting code after cookie is accepted
### 5. Embed a local video
The html5 video tag, allows for the embedding of multiple formats to enhance compatibility with the various browsers and computer setups. To embed your videos residing in your installation's files directory, first upload the video files using the same name followed by the extension. In your articles call the file name and state the extensions you have encoded those files to. (Currently the tag supports mp4, ogg, mpeg-4, flac, webm). You may want to check the [status of video format support in each web browser](https://en.wikipedia.org/wiki/HTML5_video#Browser_support).
``
The resulting code will be
Your browser does not support the video element.
If you wish to include a poster-frame for the video use
``
Where the `32` is the id number of your selected image from the database.
The resulting code will be
Your browser does not support the video element.
HTML5 allows the addition of subitiles in the videos and suport for one **srt** subtitle track is provided. The track should have the same name as the video file with the addition of `_language`, so for an english subtitled track the name of the file could be `my_video_en.srt`. The language string should use the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard.
So for:
``
The resulting code will be
Your browser does not support the video element.
### 6. Embed from YouTube
YouTube's url structures allow for the presentation of the video thumbnail before their cookies are served. As such the code below also embeds the thumbnail before the cookie is accepted.
The shorcode allows for embeding individual videos, YouTube playlists, or a feed from a YouTube user.
Embed an **individual video**
``
Resulting code before cookie is accepted
Resulting code after cookie is accepted
The default, pre cookie acceptance behaviour, calls the images from YouTube and some may find this unacceptable so I provided an option to include an image from the database. For that you can use:
``
Resulting code before cookie is accepted
If an image is not desired before the cookie acceptance use
``
Resulting code before cookie is accepted
To embed a **YouTube user's feed** use the `media` attribute for the user handle and the `url` attribute to prompt the shortcode that it will will be embedding the feed.
``
Resulting code after cookie is accepted
To embed a **playlist from YouTube** use the `url` attribute to prompt the shortcode that it will be loading a playlist and the `media` attribute for the playlist ID. Note that YouTube playlist IDs always start with `PL`.
``
Resulting code after cookie is accepted
### 7. Embed from the Internet archive
The Internet archive allows the embedding of both video and audio files.
To embed a **video** from the the Archive simply, use
``
The resultig code before cookie is accepted
Luis Bunuel: Un Chien Andalou, 1929
Hosted by Vimeo on archive.org/details/PiesAndaluzyjski.
Internet Archive’s private policy.
Resulting code after cookie is accepted
You may have noticed that the parsed code of the embed-container, after the cookie is accepted, does not include ARIA. This is because the Object types (video or audio) need to be specified. You can do that by typing: `url="v"` or `url="a"`, where `v` is for video and `a` is for audio.
### 8. Embed from Bandcamp
Bandcamp offers subdomains for their artists and normalised urls do not appear to be supported. The id of the tracks can be found in their embed code but found no way to link to their pages by using those ids. Having this in mind, to embed from Bandcamp use
``
Resulting code after cookie is accepted:
" itemscope itemtype="http://schema.org/AudioObject">
Resultig code before cookie is accepted
If the url attribute is not used, a warning, only visible to logged in users will be provided
Icarus
Hosted by BandCamp.
Warning: url is a recommended attribute. Use url="artistname" and replace artistname with the name appearing in the subdomain.
### 9. Embed from Mixcloud
Mixcloud offers subdirectories for their artists and normalised urls do not appear to be supported. The id of the tracks can be found in their embed code but found no way to link to their pages by using those ids. Also the artist's name is a required field and should be used under the `url` attribute. Having this in mind, to embed from Mixcloud use
``
Resulting code after cookie is accepted:
" itemscope itemtype="http://schema.org/AudioObject">
Resultig code before cookie is accepted
If the required `url` attribute is not used, an error will be presented
Resultig code before cookie is accepted
Midnight silhouettes
Error: url is a required attribute.
Resultig code after cookie is accepted
## Licence
This shortcode is released as free and unencumbered software. Read about it on https://github.com/colak/txp-media-shortcode/blob/master/LICENCE.md.
## Support
Please post any questions requests, or bugs on https://forum.textpattern.com/viewtopic.php?id=50879
## Not what you are looking for?
If you are not using textpattern or if you are looking for a general php which can *embed from anywhere*, you may want to have a look at Oscar Otero's [Embed](https://github.com/oscarotero/Embed).
## Notes
1 I have detected that embedded videos from youtube-nocookies do serve 3 cookies, 2 of which are from youtube. I have nevertheless included it in the list as, unlike Youtube, the embedded videos do not show related content when a video is paused or finished.
2 Created in and shared from the My Maps API.
://site.tld/images/33.jpg)
://site.tld/images/34.jpg)