• View
• Edit
• History
• Attach
• Print
• Backlinks

Ape: Automagical PmWiki Embed

Description

Easy, lightweight and unobtrusive embedding of maps, videos and more in wiki pages.

The recipe scans the wiki page for "shared" links to different providers and inserts the shared content in an inline frame at the place of every link found.

Providers include:

• OpenStreetMap: Embedding open source maps.
• NZTopoMap: Embedding detailed maps from New Zealand
• Umap.openstreetmap.fr: Embedding user-defined maps.
• TED, Archive.org, YouTube, Daily Motion, Vimeo, Facebook, VBox7: Embedding videos.
• Instagram: Embedding posts.
• Pastebin: embedding program code snippets.
• You can embed *.pdf files using the Google Docs service.
• Google: Embedding public calendars, documents, sheets, and forms.
• 3D Warehouse: Embedding 3D SketchUp models.
• You can embed HTML5 audio and video media files.
• The list can be extended while being very lightweight: adding a provider only needs a single new line in the code.

The recipe is easy to use: no new markup to learn, just normal wiki links.

It is lightweight: the full JavaScript Map/Video libraries are not loaded unless there are objects to be embedded. For embedded maps, the recipe uses the light Leaflet.js framework which is smaller than the full OpenLayersAPI.

The recipe is unobtrusive: visitors with JavaScript disabled can see the links and open the resource at the provider's website if they want.

And finally, if the recipe is disabled some day, the links will continue to work without any need to edit the pages and remove unparsed markup.

OpenStreetMap is a free software and free content resource for editing, updating and sharing maps. The JavaScript libraries used to embed the maps are also free software.

The recipe was created as a replacement for the deprecated GMap module, and for the limited EmbedOpenStreetMap module. Incidentally, as the code was very similar to AutoPlay, it was very easy to add embedding of videos and pdfs, so here it is.

Installation

• Get ape.zipΔ (alt. download: ape.zip).
• Place the "ape" folder into your "pmwiki/pub" directory and "ape.php" in your "pmwiki/cookbook" directory.
• Add to config.php this snippet:

 if($action=="browse" || !empty(@$_REQUEST['preview'])) {
   include_once("$FarmD/cookbook/ape.php");
 }

In a wikifarm containing fields on different domains, place the "ape" folder in each "field/pub" directory and see the Configuration section for additional settings.

Usage

Video sharing sites

1. Get the "Share" link or the "URL address" of the video page (note: only "public" videos can be embedded):

• TED: get the address of the lecture page like https://www.ted.com/talks/barry_schwartz_on_the_paradox_of_choice
• Archive.org (video or audio): get the address of the page https://archive.org/details/Europeanposte-StanLaurelOliverHardyFlatTire921
• YouTube:
  • get the "Share" URL address below the video like https://youtu.be/fgTyiaDmytw
  • or the URL address of the page of the video, like https://www.youtube.com/watch?v=fgTyiaDmytw
  • or the URL address of the playlist, like https://www.youtube.com/playlist?list=PLoQdn1RPNURS5VDLo6RlN0HJFZ-3eJNZU
• Vimeo: get the URL address of the page of the video, like https://vimeo.com/8806470
• DailyMotion: get the "Share link" below the video, like https://dai.ly/x30kg1y, or the URL address of the page of the video, like https://www.dailymotion.com/video/x4vsa0d
• Facebook: Get the URL address of the video page, like https://www.facebook.com/photo.php?v=10200625226809972
• Vbox7: Get the URL address of the video page, like https://www.vbox7.com/play:1e7e81ff
• ClipTube.org and PeerTube.tv: Get the URL address of the video page, like https://cliptube.org/w/fb4QGVSVJMbpqG7N3WXCnS

2. Place that link in your page, and wrap it with the %embed%...%% or %player%...%% wikistyle:

%embed% [[https://youtu.be/fgTyiaDmytw | Just For Laughs clip]]%%

Initial dimensions of the embedded frame are height 315px, width 560px. You can specify custom dimensions in the wikistyle markup:

%embed width=100pct height=400px% https://youtu.be/IDENTIFIER %%

If you specify height=auto then the height will be automatically set so that the dimensions of the frame are in the 16/9 ratio (useful with width=100pct when the width is not known).

HTML5 audio and video

You can embed HTML5 video or audio elements into your page, simply wrap the link with %embed%...%% :

* %embed% [[Attach:song.ogg | My song (vorbis) ]]%%
* %embed% [[Attach:song.mp3 | My song (mp3) ]]%%
* %embed% Attach:video.mp4 Attach:video.ogv Attach:video.webm %%
* %embed% Attach:video.webm [[Attach:subtitle.vtt"en"|English subtitles]] %%

* %embed% https://URL/video.mp4 %%  -OR-
* %embed% [[https://URL/video.mp4 | link text ]] %%

For both tags, you can link to multiple formats, from which the browser could select the first one it can perform (Audio: ogg, flac, mp3, wav, oga, opus; Video: mp4, ogv, webm). Do not mix audio with video formats in the same %embed%...%% tag.

You can add subtitle track(s) to the video in the *.vtt format. The link text will be displayed as a track "label" (if you have multiple tracks, the first one will be displayed as default, and the visitor can select a different one). The link "tooltip title" can be set as a language identifier, eg "en", "fr" or "bg" for English, French or Bulgarian (optional).

To add a video poster image attribute, embed the image in the first video link like:

• %embed% [[Attach:video.mp4 | Attach:Poster.jpg ]] %% (both the video and the poster attached to the wiki)
• %embed% [[https://URL.mp4 | https://URL.jpg ]] %% (both the video and the poster external)

To add start and end timestamps, add them the video URL like #t=start,end:

• %embed% https://wiki/full/url/of/video.mp4#07:00,07:53 %% in the format (HH:)MM:SS
• %embed% https://wiki/full/url/of/video.mp4#30,60 %% in the format start-second,end-second
• similarly for external URLs.

See MDN reference.

To configure a "preload" attribute to the audio or video element, add a class name to the embed WikiStyle:

• %embed preload-none% ... %% Preload nothing until the user clicks to play. This is enabled when there is a poster.
• %embed preload-metadata% ... %% Preload some video information like length and maybe the first frame.
• %embed preload-auto% ... %% The browser may choose how much to preload, the frame, the length, the first few seconds, or the whole video. This is the default unless there is a poster.

Links to timestamps

Timestamps like 0:19 or 1:01:34 written in plain text close to the video or audio can be converted to links starting the playback at these points. There are 2 ways to do this, either within the "embed" block or within a "mediajump" wrapping block. In all cases, the wrapping block should only have one video or one audio element:

>>embed<<
Attach:video.mp4
The first song starts at 0:19, the end credits at 52:58.
>><<

>>mediajump<<
%embed width=800 height=450% Attach:recording.mp3 %%
* 0:00 start/intro
* 0:19 first song
* 6:55 second song
* 9:57 third song
* ...
* 52:58 end credits
>><<

All timestamps in the "mediajump" block control the first audio or video element in the block. If you have more than one, wrap them in separate "mediajump" blocks.

OpenStreetMap.org

To embed a map in your wiki page, first go to https://www.openstreetmap.org/ to retrieve the "shared" link:

• find the location you want to embed, optionally select the layers
• pull the right sidebar and select "Share"
• enable the checkbox "Include marker" (if you want a marker) then re-position the map so that the marker is where you want it
• copy the address from the text field under the "Link" tab
• alternatively, you can copy the "Short Link" address.

This link can now be pasted into your wiki page like any other regular link, just wrap it in the WikiStyle %embed% or %map%:

%embed% [[https://www.openstreetmap.org/?mlat=48.85359&mlon=2.34805#map=3/48.85359/2.34805 | Paris, France, Parvis de Notre-Dame]] %%

To create a map with multiple markers, use a definition list:

: %list map% 51.5728226,-0.3171152  :  [[NPH/ | Northwick Park]]
: 51.3771046,-0.5286385  :  [[SPH/ | St Peters]]
: 51.5041414,-0.0867275  :  [[STH/ | Tommies]]
: 51.4263919,-0.1754239  :  [[SGH/ | St Georges]]
: center=51,0 zoom=8     :  (optional)

As definition terms, place the geographic coordinates Latitude,Longitude of the pins. As definition data, place any text that will be displayed in a popup when a user clicks on the pin:

  : Latitude,Longitude : Some text and/or links 

Before the first list term, include a WikiStyle %list map% to mark the list for embedding, see above. In the WikiStyle you can set width and height of the map.

To set the center and zoom level of the map, your definition list should have such an entry:

 : center=Latitude,Longitude zoom=14 : ... 

If such line is absent, the map will automatically set the center and the closest zoom level where all pins are visible.

Demo with multiple pins on a markup and popups with wikitext and images.

You can get the geographic coordinates of the center of the map at the right bottom of the frame. If the page contains an input field (text, textarea or hidden) with the id "ape_latlon", maps on the page will have a circle marker at the center and when the map is moved and zoomed, the current coordinates will appear in the ape_latlon field. If the visitor pastes or types geographic coordinates in the field, the map will move to place its center at the typed coordinates.

You can see a map with multiple markers and a coordinate field at PmWikiUsers-Map and add your wiki there!

Unlike for videos, the default frame for a map is 100% wide.

Including a common map into multiple pages

This feature allows to use a map with multiple markers for browsing from one page to another.

You create your map like the above example, placing the coordinates and links to individual pages. They will become pins with popups containing the links to the different pages.

In every destination page, you include the map, for example:

  (:include Main.Map#mapstart#mapend:)

Then in every page,

• the pin to the current page will be blue and centered in the map,
• the other pins will be gray,
• you can browse to another page by clicking on the pins.

Map pulling coordinates from different pages

Let's say we have a number of pages about a trip. Each page has page text variable with the coordinates in the form (:Coord: 48.85638,2.34588:) and they all link to the category [[!Europe2024Trip]].

To show a map with pins on the coordinates, and links to these pages, you can have a pagelist with a custom template which will find the pages from the category, and make a list formatted for a map. The pins from the pages will be placed on their coordinates, and will open a balloon with the page title and a link to the remote page.

Add a PageList template, either in the same page, or in the page Site.LocalTemplates, which then can be used in other maps:

[[#tripmap]]
(:template first:)
: %list map% : Map will be here
(:template each:)
: {=$:Coord} : [[{=$FullName} | + ]]
(:template none:)
No pages found linking to {$$link}.
[[#tripmapend]]

Add a PageList to the page where you want the map:

(:pagelist link=Category.Europe2024Trip fmt=#tripmap:)

Instead of link=Category.Europe2024Trip you can use other PageList attributes such as group=Trip2024, or name=TripEurope* or trail=IndexPage, see the PageList documentation.

Displaying KML or GPX traces

To embed GPX or KML traces, just attach them to the page with [[Attach:sample.gpx]] or otherwise link to them, then wrap them in the wikistyle "map":

%map% Attach:traceroute.kml %%

%map% Attach:sample.gpx %%

Demo

Compressed KMZ files are not currently supported.

Ape can do some popular trace formats, and should work in many cases, but not every possible feature has been implemented. If you have specific files that you need to use and that do not display well, please send them to me at 5ko [snail] 5ko [period] fr.

Also note that the trace files need to be on the same website (domain name) where the file pub/ape/ape-osmap.html is located.

To allow the uploading of KML and GPX files, add to config.php these lines:

$UploadExts['kml'] = 'application/vnd.google-earth.kml+xml';
$UploadExts['gpx'] = 'application/gpx+xml';

uMap.openstreetmap.fr

This open source service allows you to create a map with different pins, options, layers, to draw figures.

To create a map, go to https://umap.openstreetmap.fr/ and use the intuitive interface to configure a map.

After you're done:

• near the left border click on a button "More"
• click on the icon "Embed and share this map"
• on the right side copy the address under title "Short URL" like https://u.osmfr.org/m/48989/
• place this address as a link in your wiki page, wrapped with the wikistyle %embed% or %map%:

%embed% https://u.osmfr.org/m/48989/ %%

NZTopoMap

To embed a map frame from NZTopoMap, find your location in the website, click on "Share Map", in the sidebar near the top click on the button after "Copy link to share map".

Place this link in your page, and wrap it with %embed%...%% or %map%...%% wikistyle:

%map height=400px% [[ https://www.topomap.co.nz/NZTopoMap?v=2&ll=-41.315866,174.811448&z=15 | my map]] %%

If the link URL contains "&pin=1" but not "&lbl=", then link text will become the label of the pin.

Note that this service produces a map frame, but does not allow to zoom and pan, clicking on the map opens the provider's website in a new browser tab.

To manually type coordinates and other settings, it may be useful to define a custom InterMap prefix like:

   NZTopo: https://www.topomap.co.nz/NZTopoMap?v=2&new=1&$1 

...then in the page type something like %map%[[NZTopo:ll=-41.26,174.864&z=12&pin=1|My location]]%%.

To embed GPX or KML traces, just attach them to the page with [[Attach:sample.gpx]] or otherwise link to them, then wrap them in the wikistyles "map nztopo":

%map nztopo% Attach:traceroute.kml %%

Google Custom Maps

Ape can now embed a custom map created on Google Maps and saved into your Google account. It is possible to select a "Satellite view" (click on "Base map") which is not yet available on OpenStreetMap.

When on Google Maps, go to My Maps (or select Menu - Your places - Maps) then create a new map or select an existing map. When you're done editing the map, select the "Share" link and if needed type a name and description. In the dialogue box, in the section "Who has access" make sure it says "Public on the web - Anyone on the Internet can find and view", otherwise click on "Change..." to select it. Then copy the "link to share" and place it in your wiki page:

%map height=400px% [[https://drive.google.com/open?id=16KTA&usp=share | my map]] %%

If you subsequently edit the map on Google, it will automatically update on your wiki as well.

Google Calendar

Only public calendars can be embedded.

• In the left-hand menu, under "My Calendars", select click on the "⋮" next to the calendar you want to embed and select "Settings and sharing".
• Under "Access permissions" select the checkbox "Make this calendar public".
• Below, under "Integrate calendar" from "Public URL to this calendar"", select and copy the URL.
• Place this address as a link in your wiki page, wrapped with the wikistyle %embed%:

%embed% https://calendar.google.com/calendar/embed?src=vhbc%40group.calendar.google.com&ctz=Europe/London %%

If you wish to resize the calendar frame, use for example %embed width=100pct height=400px% for a frame 100% wide and 400 pixels high.

• most users will see an empty frame, and will have no way to know that the frame requires login into google
• people logged into google but not permitted to see the calendar will see an empty frame
• people both logged into google and permitted to see the calendar will see it.

Embed PDF or RTF files

This uses the Google Docs service. The method is the same as above: wrap your Attach: link with the %embed%...%% wikistyle:

%embed% Attach:your-file.pdf %%

Office documents - text, spreadsheet, presentations

This uses the Microsoft Live Office service. The method is the same as above: wrap your Attach: link with the %embed%...%% wikistyle:

%embed width=100pct height=600px% Attach:your-file.doc %%

The following file formats are supported (read only): doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp with limited compatibility. You may be limited by file size.

Engineering drawings

This uses a free service from ShareCAD. The method is the same as above: wrap your Attach: link with the %embed%...%% wikistyle:

%embed width=100pct height=600px% Attach:plan.dwg %%

The following file formats are supported (read only): dwg, dxf, plt, spl, stp, igs, sat, cgm with limited compatibility.

Google Documents - docs, sheets, slides

Only published public documents can be embedded.

• Near the top left corner, press the "File" menu then select "Publish to web".
  • If you prefer embedding the whole editing interface, use the "Share" button instead.
• In the dialogue box, copy the link from the text field.
• Place this address as a link in your wiki page, wrapped with the wikistyle %embed%:
• document: %embed% [[https://docs.google.com/v/o/123456 | My shared document ]] %%
• spreadsheet: %embed% [[https://docs.google.com/spreadsheets/d/e/99999GUID99999/pubhtml?gid=0&single=true]] %%
• presentation: %embed% [[https://docs.google.com/presentation/d/e/88888GUID88888/pub?start=false&loop=false&delayms=3000]] %%
• drawing: https://docs.google.com/drawings/d/e/77777GUID77777/pub?w=960&h=720&format=.png
  • or : %embed% [[https://docs.google.com/drawings/d/e/77777GUID77777/pub?w=960&h=720]] %%

If you wish to resize the document frame, use for example %embed width=100pct height=400px% for a frame 100% wide and 400 pixels high.

Google Forms

Only published, public forms can be embedded.

• Near the top right corner, press the "Send" button. In the dialogue box, on the "Send via" line, press the second "Link" icon then copy the link from the text field. Do not check the "Shorten URL" checkbox.
• Place this address as a link in your wiki page, wrapped with the wikistyle %embed%:

%embed% [[https://docs.google.com/forms/123456/viewform | Please fill our survey ]] %%

If you wish to resize the form frame, use for example %embed width=100pct height=400px% for a frame 100% wide and 400 pixels high.

SVG pictures and SWF animations (experimental)

To make Ape embed SVG pictures instead of PmWiki, add to config.php such a line:

  $ImgExtPattern="\\.(?:gif|jpg|jpeg|png|GIF|JPG|JPEG|PNG)";

To embed a media file, same format as for the others:

%embed width=200px height=150px% Attach:picture.svg %%

%embed width=200px height=150px% Attach:animation.swf %%

It is not possible to pass parameters to the SWF animation.

Embed program code snippets

Ape can now embed code snippets ("pastes") from Pastebin.

Place the URL address of the snippet in your page, wrap it in an %embed%...%% tag.

%embed width=100pct% https://pastebin.com/Ms8bFtfZ %%

Only public "pastes" can be embedded. If the snippet has a programming language set, it will have syntax highlighting.

Embed 3D Warehouse models

To embed a SketchUp 3D model, find it or upload it to the 3D Warehouse and place the URL in the page, wrap it in an %embed%...%% tag:

%embed width=100pct height=auto% https://3dwarehouse.sketchup.com/model/0005bb31-b04c-41b4-ab50-0c11faccd4f9 %%

Only public models can be embedded, and they are read-only (cannot be edited).

Instagram posts

Just link the post, and wrap it in the %embed% ... %% wikistyle:

  %embed width=300px height=460px% https://www.instagram.com/p/CBur8M-px2m/ %%

Configuration

The following variables can be set in a local configuration, before the include_once() line:

• $Ape['dir'] = "$FarmD/pub/ape"; # The directory (filesystem path) to the ape directory. Note the double quotes.
• $Ape['dirurl'] = '$FarmPubDirUrl/ape'; # The URL-accessible directory where ape.js, leaflet.js and the other files can be downloaded by browsers. Note the single quotes.
• $Ape['snippet'] = '<script...'; # The snippet inserted in the HTML page footer to load ape.js. The following variables will be replaced: {dirurl} with $Ape['dirurl'], {fname} with the file name, eg "ape.js", and {mtime} with the last modification timestamp for that file (useful for aggressive caching).
• $Ape['scripts'] = array('ape-local.js', 'ape.js'); # a list of JS files to load; only those that actually exist in the pub/ape directory will be linked.

OpenStreetMap in a WikiFarm with different domains

If your wikifarm contains different wikis all on the same domain, this doesn't apply to you.

Browsers do not allow frames from one domain to read the content of pages on other domains, and the OpenStreetMap ape frame needs to read the current page to get the link(s).

If on a same wikifarm you have different wikis on different domains like example1.com, example2.com, other.example2.com, then Ape needs to be made accessible on each different domain.

The easiest way to achieve this is to copy the "ape" directory inside a "pub" directory on every field (where your index.php is). Then, set the following variables before the include_once() call:

  $Ape['dir'] = "pub/ape"; 
  $Ape['dirurl'] = '$PubDirUrl/ape'; # Note the single quotes.

If you have any difficulty setting this please contact us.

Custom rules

You can configure custom rules that replace the URL address of a resource link with the address of the inline frame of some embedding service. 20230213 By default, a file named "ape-local.js" will be included if it exists in the pub/ape directory. Create this file, or rename ape-local-sample.js to ape-local.js and modify it for your needs.

The ape-local.js file should define an array with the replacement rules, for example:

var uAPErx = uAPErx || [ ];

uAPErx.push([/^https?:\/\/youtu\.be\/(.+)$/i, 'https://www.youtube-nocookie.com/embed/$1']);

uAPErx.push([/^(.*\.(doc|xls|ppt)x?)$/i, "https://view.officeapps.live.com/op/view.aspx?src=$1"]);

uAPErx.push([/^search patterns (match)$/i, "replacement strings $1"]);

In the example, the first rule will take a short "youtu.be" link to a video and transform it into the "embed" address of the inline frame for the same video. The second rule will embed various Office documents with the Microsoft embedding service. See other examples defined as the "rx" array in the ape.js script.

See also: a custom rule to enable any iframe from any website.

Custom rules override default ones: a link matching a custom pattern will use the custom rule for the replacement rather than a matching default one.

Writing rules with regular expressions may be tricky: if you have any difficulty do not hesitate to contact us.

Notes

The recipe needs to have the line <!--HTMLFooter--> in the skin template. Some skins don't have it, if yours doesn't have it, insert this line right before the closing </body> tag.

If the user's browser does not have JavaScript enabled, only the regular link will appear. The user will be able to follow it in order to see the content (although, most of the external providers require JavaScript to be enabled).

If your wiki is on the more secure HTTPS protocol, you cannot load frames from less secure HTTP sites (the other way around is possible). Most providers are already on HTTPS.

The providers' inline frames and scripts are only loaded if there is a link to their content.

Sometimes embedded frames from different providers are not compatible with one another and may not appear. If that's the case, place the frames on different and separate wiki pages (not included or otherwise presented to the browser at the same time).

Some embedded objects are only accessible to visitors in selected regions. Visitors outside the regions will probably be unable to see the resource (this is controlled by the provider, not by Ape) and may see a blank frame.

The recipe is not compatible with Cookbook:Svg or Cookbook:Flash, you cannot use Ape with either of those (Ape provides simple SVG and SWF embedding).

It is not yet possible to embed a video or another remote document inside an Ape-embedded map. It may be possible to embed a locally attached video in an Ape map if you use some HTML5 <video> markup from a recipe other than Ape.

It is possible for a provider to change the interface, and the above instructions "how to get a share link" may become obsolete. In that case use your best judgment to get the "share link" and feel free to edit this page and update the instructions, or contact us and we'll do it.

Change log / Release notes

The recipe was written in April 2014 and used daily on a large wikifarm. I just never had the time to correctly document it and add it to the Cookbook.

See also

Contributors

• Recipe written and maintained by Petko (5ko [snail] 5ko [period] fr).
• If this recipe helps you or saves you time, you can help support its continued development by ♥ .

Comments

See discussion at Ape-Talk