Ape: Automagical PmWiki Embed

Summary: Easy embedding of videos, maps and more in wiki pages
Version: 20170521
Prerequisites: Recent browser with JavaScript
Status: Stable
Maintainer: Petko
License: GPLv2 (Ape), BSD-2-clause (Leaflet)
Users: +4 (view / edit)
Discussion: Ape-Talk

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.
  • Umap.openstreetmap.fr: Embedding user-defined maps.
  • TED, Archive.org, YouTube, Daily Motion, Vimeo, Facebook, VBox7: Embedding videos.
  • You can embed local *.pdf files using the Google Docs service.
  • Google: Embedding public calendars, documents and forms.
  • 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. Incidently, 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.
  • Add to config.php this snippet:
 if($action=="browse" || $_REQUEST['preview']) {
   $HTMLFooterFmt['ape'] = '<script type="text/javascript" 
     src="$FarmPubDirUrl/ape/ape.js"></script>';
 }

In a wikifarm containing fields on different domains, place the "ape" folder in each "field/pub" directory and in the snippet above use $PubDirUrl instead of $FarmPubDirUrl.

Configuration

Usage

Video sharing sites

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

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% http://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).

The recipe is a descendant of Embed OpenStreetMap and AutoPlay so the wikistyles %map% and %player% can be used like %embed%.

OpenStreetMap.org

To embed a map in your wiki page, first go to http://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% [[http://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.

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 http://u.osmfr.org/m/48989/
  • place this address as a link in your wiki page, wrapped with the wikistyle %embed% or %map%:

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

Google Calendar

Only public calendars can be embedded.

  • In the left-hand menu, under "My Calendars", select click on the arrow next to the calendar you want to embed and select "Share this calendar".
  • Select the two checkboxes "Share this calendar with others" and "Make this calendar public".
  • Above these, click on "Calendar details".
  • Scroll down until you find "Calendar Address:". On that line right-click or long-tap on the "HTML" button and select "Copy link address" or something like this (depending on your browser model and language).
  • Place this address as a link in your wiki page, wrapped with the wikistyle %embed%:

%embed% https://www.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.

Note: if the calendar is not made "public":
  • 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 a PDF file

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

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

Google Document

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%:

%embed% [[https://docs.google.com/v/o/123456 | My shared document ]] %%

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.

Notes

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.

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

Sometimes embedded videos from different providers are not compatible with one another and may not appear. If that's the case, place the videos on different pages.

In a WikiFarm setting, if your field is not on the same domain name as $FarmPubDirUrl, the OpenStreetMap embedding will fail to load -- this is a browser limitation to prevent cross-site scripting vulnerabilities. In this case, either install the recipe in the 'pub' directory of each field, or create a symbolic link from the field to the farm 'pub' directory, and set the $FarmPubDirUrl variable accordingly.

Some embedded objects are only accessible to visitors in selected regions, eg. some VBox videos are only visible from European IP addresses. Visitors outside the regions will probably be unable to see the videos (this is controlled by the provider, not by Ape).

When installed together with Cookbook:Svg or Cookbook:Flash, the width and height wikistyles are hijacked by these recipes and cannot be used by Ape to set the sizes of objects.

Change log / Release notes

  • 20170521 Add providers Google Docs and Google Forms.
  • 20160708 Fix bug introduced yesterday. Add 30px internal padding at the top when many pins, otherwise the most Northern pins are mostly out of the frame.
  • 20160707 Allow viewport-related width and height frame CSS units "vh" and "vw". Move the inline styles from the #map element in a <style> block in the header.
  • 20160531 Fix fullscreen permissions on video frames (reported by RandyB). Recognize channel links from Vimeo.
  • 20160309 Enable automatic height (16/9 frame).
  • 20160228 For Youtube videos, pass any additional parameters like rel= or start= to the embedded video. For OpenStreetMaps, the map can be included in multiple pages.
  • 20151009a Compute block frame margins from the internal text alignment of the element, eg. %embed center% or %embed right%.
  • 20151001 Enable center and zoom definitions.
  • 20150927 Fix "definition list" map with a single point defined.
  • 20150907 Add OpenStreetMap "Short Links", change license to GPLv2.
  • 20150903 Add Bulgarian video sharing website Vbox7.
  • 20150901 Youtube frames will use privacy enhanced mode.
  • 20150825 added Google Calendar.
  • 20150813 added new format for Facebook video links.
  • 20150809 added "License" blocks into the Leaflet JS and CSS files (reported by RandyB).
  • 20150806 added providers TED, Archive.org, TeacherTube, DailyMotion, enabled short links for Umap.
  • 20150804 first release on PmWiki.org, updated to Leaflet 0.7.3 stable.

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

Cookbook /
EmbedOpenStreetMap  Easy, lightweight and unobtrusive embedding of simple maps in wiki pages (Superseded by Ape)
GMap  Easy Google Maps integration (Uncertain)
GoogleCalendar  Embeds a Google Calendar in a PmWiki page (Stable)
OpenLayersAPI  Adds OpenLayers API to PmWiki pages (for embedding OpenStreetMaps) (alpha)
Cookbook /
Audio5  HTML5 Audio Support for PmWiki (Stable)
AutoPlay  Unobtrusive embedding of video players from simple links (Superseded by Ape)
Dailymotion  Markup for embedding DailyMotion videos (Stable)
Flash  Embedding Flash movies; plus recipes for embedding Flash from specific sites like YouTube, Vimeo, GoogleVideo, Flickr, Archive.org, and more...
FlashMediaPlayer  Embed flash media players in your pages (Beta)
Flowplayer  Flowplayer recipe (Beta)
FLVPlayer  Embedding of Flash video (.flv) files into wiki pages the easy way. (initial release)
HTML5Audio  Play HTML5 Audio (working)
Html5AVCtrl  Enable youtube-like keyboard and mouse control of HTML5 video and audio.
HTML5Video  Show HTML5 Video (working)
QuickTime  Embed QuickTime content on wiki sites. (Stable)
Video5  HTML5 Video Support for PmWiki (Stable)
VideoAttach  Handles Attach: videos, provides a video directive and optional support for popular Video Upload sites. (Beta)
WMPlayer  Embedding a Windows Media Player (stable)

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

User notes +4: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.