====== Import Facebook Events Plugin ======
---- plugin ----
description: This plugin allows you to display your Facebook events in DokuWiki.
author : Grégoire Surrel, Jannes Drost-Tenfelde
email :
type : syntax
lastupdate : 2018-03-09
compatible : 2017-02-19, 2016-06-26, 2015-08-10, 2014-09-29, 2014-05-05
depends :
conflicts :
similar : facebookevents, facebookwall, facebookalbum
tags : facebook, events, calendar
downloadurl: https://github.com/gsurrel/dokuwiki/raw/master/facebookevents/importfacebookevents.zip
bugtracker :
sourcerepo : https://github.com/gsurrel/dokuwiki/tree/master/facebookevents
donationurl:
----
This plugin allows you to connect to your Facebook page and display the page's events in DokuWiki.
The latest Version has been updated to use Facebook's Graph API, rather than the Facebook PHP SDK.
===== Installation =====
* You must create a [[https://developers.facebook.com/apps/|Facebook App]], which allows you to connect to Facebook using
* App ID, which identifies your Facebook App (you can have multiple Apps)
* App Secret, which secures your Facebook App
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
===== Examples/Usage =====
* ''%%{{facebookevents>fanpageid=123456}}%%'' ((Displays events as Facebook fetches them))
* ''%%{{facebookevents>fanpageid=123456&numberOfEntries=3&sort=ASC&from=today}}%%'' ((Displays the 3 events from today))
===== Syntax =====
{{facebookevents>key=value&..&key=value}}
^ key | the parameter key to set | optional |
^ value | the parameter value to set | optional |
Multiple key=value parameters can be set using the & as a separator.
Available parameters:
^ Key ^ Type ^ Comments ^ Requirement ^ Version ^
| appid | string | This is the mandatory App ID of your [[https://developers.facebook.com/apps/|Facebook App]] \\ **Moved to Plugin Settings starting from version 2.x** | **mandatory** | all |
| secret | string | This is the mandatory App Secret of your [[https://developers.facebook.com/apps/|Facebook App]] \\ **Moved to Plugin Settings starting from version 2.x** | **mandatory** | all |
| fanpageid | string | This is the ID of your Facebook page. You can find this ID by going to your Facebook page. Typically, the link of your page looks like %%https://www.facebook.com/#!/pages//%%. Copy the page ID from the URL and use it in the syntax. | **mandatory** | all |
| showAs | string | Default: **default**. Allows you to use alternate display of the events using configuration parameters. You can add more templates by editing the default.php and metadata.php files in the conf/ directory. | optional | all |
| showPostsAs | string | Default: **wallposts_default**. Allows you to use alternate display of the wall posts using configuration parameters. You can add more templates by editing the default.php and metadata.php files in the conf/ directory. | optional | Version 2.0 or newer |
| quoteprefix | string | Default: "**> **". When displaying posts on the event's wall, the plugin prefixes each line with this string parameter. The default creates the Quotation syntax | optional | Version 2.0 or newer |
| from | date | This indicates the date from which the wall posts should be displayed. Older wall posts are disregarded. Format is tolerant since version 2.0, see [[https://secure.php.net/manual/en/function.strtotime.php|the strtotime documentation for details]]. | optional | all |
| to | date | This indicates the date to which the wall posts should be displayed. Newer wall posts are disregarded. Format is tolerant since version 2.0, see [[https://secure.php.net/manual/en/function.strtotime.php|the strtotime documentation for details]]. | optional | all |
| numberOfEntries | number | Indicates the maximum number of entries to display. | optional | all |
| sort | string | Default: **DESC**. Allows you to sort by the date of the event. Valid values are 'ASC' and 'DESC'. | optional | all |
| showEndTimes | onoff | Default: **on**. Allows you to display end times of the event. | optional | all |
| limit | number | Default: **0**. Allows you to limit the maximum number of characters displayed for the event. | optional | Version 1.1 or newer |
===== Configuration and Settings =====
^ Key ^ Type ^ Comments ^ Requirement ^ Version ^
| appid | string | This is the mandatory App ID of your [[https://developers.facebook.com/apps/|Facebook App]] | required | all |
| appsecret | string | This is the mandatory App Secret of your [[https://developers.facebook.com/apps/|Facebook App]] | required | all |
| dformat | date | Formatting of the event date (See [[phpfn>strftime|Format]]) | required | all |
| tformat | date | Formatting of the event time (See [[phpfn>strftime|Format]]) | required | all |
| default | string | Default template for displaying events. | required | all |
| table| string | Template for displaying events. | optional | all |
| short| string | Template for displaying events. | optional | all |
| wallposts_default | string | Default template for displaying event's comments. | required | all |
| wallposts_alternate | string | Template for displaying event's comments. | optional| all |
===== Display templates =====
You may add your own configuration parameters in order to display the events in different formats. The appropriate configuration parameter for the template can be set via the syntax parameters **showAs** and **showPostsAs**.
In order to make a new template, for example one that displays all wall posts as an short list, the plugin configuration files must be changed as follows:
Example:
** showAs: plugin»facebookevents»short **
You can use it in the plugin syntax:
''%%{{facebookevents>fanpageid=123456&showAs=short}}%%''
It works the same for the event's comments with the ** showPostsAs: plugin»facebookevents»wp_* ** configuration.
===== Template tags =====
The templates, which can be configured via the administraton panel, is parsed using the following tags:
^ Event tag ^ Comments ^ Version ^
| ''{date}'' | The date of the wall post. The date format can be configured in the settings. | all |
| ''{time}'' | The time of the wall post. The time format can be configured in the settings. | all |
| ''{datetime}'' | The date and time of the wall post. This functions as ''{date} {time}''. | all |
| ''{title}'' | The title of the event. | all |
| ''{description}'' | The event description. | all |
| ''{location}'' | The location's name of the event. **Before v2.1, displaying also the address** | all |
| "{location_address}" | The location of the event built with ''##{place}, {zip} {city}, {country}##''. | 2.1 |
| ''{place}'' | The place of the event. | all |
| ''{city}'' | The city of the event. | all |
| ''{zip}'' | The city zip code of the event. | all |
| ''{country}'' | The city of the event. | all |
| ''{image}'' | The original picture of the event. | all |
| ''{image_large}'' | A large version of the picture of the event. | all |
| ''{image_small}'' | A small version of the picture of the event. | all |
| ''{image_square}'' | A squared version of the picture of the event. | all |
| ''{url}'' | The unformated URL of the event. You can use this in your template to make your own links to the event. | all |
| ''{more}'' | This is a formatted link to the event, using the language files to output a ''[[{url}|Read more...]]'' link. | all |
| ''{startdatetime}'' | The date and time of the start of the event. | Version 1.1 or newer |
| ''{startdate}'' | The date of the start of the event. | Version 1.1 or newer |
| ''{starttime}'' | The time of the start of the event. | Version 1.1 or newer |
| ''{enddatetime}'' | The date and time of the end of the event. | Version 1.1 or newer |
| ''{enddate}'' | The date of the end of the event. | Version 1.1 or newer |
| ''{endtime}'' | The time of the start of the event. | Version 1.1 or newer |
| ''{timestamp}'' | The ISO 8601 date time of the event. | Version 1.1 or newer |
| ''{starttimestamp}'' | The ISO 8601 date time of the start of the event. | Version 2.0 or newer |
| ''{endtimestamp}'' | The ISO 8601 date time of the end of the event. | Version 2.0 or newer |
| ''{wallposts}'' | The placeholder for inserting event comments. | Version 2.0 or newer |
| ''{microdata}'' | Generate microdata about the event for search engines | Version 2.1 or newer |
^ Wall posts tag ^ Comments ^ Version |
| ''{wp_datetime}'' | The date and time of the wall post. This functions as ''{date} {time}''. | Version 2.0 or newer |
| ''{wp_userImage}'' | The thumbnail picture of the commenter. | Version 2.0 or newer |
| ''{wp_userName}'' | The name of the commenter. | Version 2.0 or newer |
| ''{wp_permalink}'' | The unformated URL of the comment. | Version 2.0 or newer |
| ''{wp_content}'' | The comment itself. | Version 2.0 or newer |
| ''{wp_mediaSource}'' | The URL of attached media if exists. | Version 2.0 or newer |
| ''{wp_mediaImage}'' | The thumbnail URL of attached media if exists. | Version 2.0 or newer |
===== Development =====
=== Change Log ===
* **2018-03-07** Version 3.2 released.
* Fixed microdata breakage
* Better handling of recurrent events
* **2018-03-07** Version 3.0 released.
* Take into account recurrent events
* Better serialize microdata for indexing by Google
* **2017-03-29** Version 2.0 released.
* Code cleanup
* Removed wrong translations
* Made time &from= and &to= handle relative times (i.e. "-2 weeks")
* Implemented sorting of events
* Implemented missing placeholders (square picture, small picture, start/end time/date)
* Handles now posts to the event's wall
* ⚠️ Secured the app id and secret from appearing from source (by moving it to configuration panel) ⚠️
* **2016-09-29** Version 1.2 released.
* Updated to use Facebook Graph API 2.7 instead of the Facebook PHP SDK.
* **2012-03-26** Version 1.1 released.
* Fixed timezone problem, where the times would sometimes not be displayed properly.
* Added 'limit' parameter that allows you to set the maximum number of characters displayed for {description}.
* Added template tags {startdatetime}, {startdate, {starttime}, {enddatetime}, {enddate}, {endtime} and {timestamp}.
* **2012-02-14** Version 1.0 released.
* Initial release
=== Known Bugs and Issues ===
=== ToDo/Wish List ===
===== FAQ =====
===== Discussion =====
Thank you for your contributions!