Full Calendar Macro
 | Displays a Calendar in Javascript and allows to get events from XWiki pages. |
| Type | XAR |
| Category | Macro |
| Developed by | Vincent Massol, Ludovic Dubost, Ecaterina Moraru (Valica), Alexandru Chelariu, Manuel Smeria, Anca Luca, Gabriela Smeria, Victor Rachieru |
| Active Installs | 179 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
Integrates the FullCalendar v3.10.2 JQuery plugin into XWiki to display custom Calendars.
Usage
This application provides a calendar macro. There are multiple ways to use this macro, either by referring to an XWiki class or by writing your custom JSON script to read the data. The editable feature is not available when using an iCal
Example with an XWiki class
This example will display the blog articles on the calendar based on the publishDate field. Additionally the calendar is displayed by default on June 2009 (year=2009 and month=5).
Example with custom JSON
For example put the following in a page named MyCalendar in the Main space (i.e. Main.MyCalendar):
{{calendar json="$xwiki.getURL('Main.MyCalendarJSON', 'get', 'outputSyntax=plain')"/}}
{{/velocity}}
Now since we've specified to use the Main.MyCalendarJSON page to get the calendar events you also need to create a MyCalendarJSON page in the Main space and put the following in it:
#if($xcontext.action == 'get' && "$!{request.outputSyntax}" == 'plain')
$response.setContentType('application/json')
#end
[
{
"id" : 111,
"title" : "Event1",
"start" : "2012-06-10",
"url" : "http:\/\/yahoo.com\/"
},
{
"id" : 222,
"title" :"Event2",
"start" : "2012-06-20",
"end" : "2012-06-22",
"url" : "http:\/\/yahoo.com\/"
}
]
{{/velocity}}
Example with Google Calendar
FullCalendar can display events from a Google Calendar.
Public calendar
In order to get your own Google API key do the following steps:
- Go to the Google Developer Console and create a new project (it might take a second).
- Once in the project, go to APIs & Services > ENABLE APIS AND SERVICES in the top bar.
- Find "Calendar API" in the list and turn it ON.
- Go back and choose on the sidebar Credentials.
- On the top bar select Create credentials > Create new Key > Restrict key.
- On API restrictions select Restrict key and choose Google Calendar API, then Save.
- Your new API key will appear. It might take a second or two before it starts working.
- Pass the newly created key as the value for the "gApiKey" parameter
All you need to do is pass a series of calendar IDs separated by commas as the value for the "gCal" parameter.
In order to use your Google Calendar with this macro you'll need to do the following steps:
- Make your calendar public
- In the Google Calendar interface, locate the "My calendars" area on the left.
- Hover over the calendar you need and click the options button.
- A menu will appear. Click "Settings and sharing".
- Under Access permissions check "Make available to public"
- Make sure "See all event details" is selected.
- Get the calendar id
- Click on "Integrate calendar".
- You will see your Calendar ID. It will look something like "[email protected]".
- Pass the Google Calendar id as the value of the "gCal" parameter.
Private calendar (Since 2.1)
All you need to do is pass the iCal secret address as the value for the "iCal" parameter.
In order to get your iCal secret address from Google Calendar you'll need to do the following steps (https://support.google.com/calendar/answer/37648?hl=en):
- On your computer, open Google Calendar.
- In the top right, click Settings.
- Click the name of the calendar you want to use.
- Go to "Integrate calendar" section.
- Copy the ICAL link that appears under "Public anddress in iCal format".
- Pass the link as the value of the "iCal" parameter.
Reference
Here is the reference of all parameters
| Parameter | Detail | Default | Possible values |
|---|---|---|---|
| classname | Name of the class to retrieve data for | None | Any xwiki class name. This setting is not used if a "json" url is provided |
| startfield | Field of the class to use as the date | None | any date field in the class chosen. This setting is not used if a "json" url is provided |
| durationfield | Field of the class to use as the duration of the event. When not set the events will be "day" events | None | any number field in the class chosen. This setting is not used if a "json" url is provided |
| editable | Used to activate the edit feature allowing to move events. Supported by internal events | true | true or false |
| defaultView | default agenda to show on load of the agenda | month | month, agendaWeek, agendaDay, basicWeek, basicDay |
| year | Year of the date to show when loading the calendar. Leave empty for today | Will set the day as today | Any year |
| month | Month (from 0 to 11) of the date to show when loading the calendar. Leave empty for today | Will set the day as today | 0-11 for January-December |
| date | Day (from 1 to 31) of the date to show when loading the calendar. Leave empty for today | Will set the day as today | 1-31 |
| firstDay | First day (from 0 being Sunday to 6 being Saturday) of the week to show in the calendar. | Will be Monday by default | 0-6 for Sunday-Saturday |
| firstHour | First hour to show in the calendar | 0-24 | |
| minTime | First time to show in the calendar. Users won't see hours before this time | 8.00 | 0.00 to 23.00 |
| maxTime | Last time to show in the calendar. Users won't see hours after this time | 23.00 | 0.00 to 23.00 |
| json | URL of the JSON page to retrieve the data from | None | URL to a page generating JSON. Example format: [ This is only needed if the JSON generated by the Calendar.JSONService does not fit your needs. The Calendar.JSONService can query events from any class with a date and a duration field (string) Example value in velocity: An XWiki url: $xwiki.getURL('Main.MyCalendarJSON', 'get', 'outputSyntax=plain') |
| updateurl | URL of the page to call for updates | None | URL page to update events when they are moved or resized in the Calendar. The following parameters are passed:
The default update service handles updating a document holding a specific classname with a start date and a duration field as specified in the macro parameters. The editable parameter needs to be set to true for this field to be used. |
| gCal | IDs of the Google calendars from which to retrieve events. Editing feature is not supported, as they are considered external events. | None | Comma separated list of Google Calendar IDs |
| iCal | The secret address of the Google calendar from which to retrieve events. Editing feature is not supported, as they are considered external events. | None | |
| gApiKey | Google API Key to be used when retrieving Google Calendar information | AIzaSyDedBXsLGUPKGT2SKh1aZXXJZKdpEc8bQU | Google API Key |
| extraFields | Extra fields to be added in the calendar event | None | The current implementation accept exactly a list of 3: description, location and status, in this particular order. The reason is that the used class will not have all the time these properties named like that. {{calendar classname="Blog.BlogPostClass" extraFields="description,location,status" /}} |
Screenshot
Screenshot using Flamingo skin:
Release Notes for previous versions (not available anymore in Extension Manager)
v1.1.5
- Fixed the formatting of the date of the JSONService to not rely on the wiki default anymore, otherwise it can break if the wiki default is not supported or does not contain time information, and the items will not be displayed properly on the calendar.
v1.1.4
- Changed the authors/creators of the pages to xwiki:XWiki.Admin, to match the standard xar format.
v1.1.3
Compared to 1.1.2 this release adds:
- Updated query string to fix the JSON example query
- Added titles and set parents for some pages that didn't have them
v1.1.2
Compared to 1.1.1 this release adds:
- adding JQuery as an attachment to avoid issues with the length of the code property
v1.1.1
Compared to 1.1 this releases adds:
- minor CSS improvements in order to assure compatibility with Colibri skin: removed the bottom scroll and added right border
v1.1
Compared to 1.0.2 this releases adds:
- many parameters to configure the calendar (default view, firstDay, firstHour, minTime, maxTime, etc..)
- a new default JSONService to lookup for document with a specific classname with a date field and an optional duration field (the class and fields names are provided as parameter to the macro). For instance you can query Blog posts with this default JSON Service
- a new update service which allows to update the date and duration field when moving the event on the calendar
- a fix to allow to display multiple calendars on the same page
v1.0.2
Compared to version 1.0.1 this release fixes the CSS issue with table borders showing in the Calendar header when on the Colibri skin.
This is an early integration and lots of things remain to be done. Just to cite a few:
- Test edition and drag and drop of Events
- Improve the Calendar Macro to support other sources
- Fix CSS style bugs when used with the Colibri skin
v1.0.1
This is a very first integration and lots of things remain to be done. Just to cite a few:
- Test edition and drag and drop of Events
- Improve the Calendar Macro to support other sources
- Fix CSS style bugs when used with the Colibri skin
v1.0
This is a very first integration and lots of things remain to be done. Just to cite a few:
- Test edition and drag and drop of Events
- Improve the Calendar Macro to support other sources
- Fix CSS style bugs when used with the Colibri skin
- Some issue between JQuery and XWiki (try clicking on a Tab at the bottom of pages). Strangely this doesn't happen with the JQuery Helper extension
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
v2.4.1
The following translations have been updated with this release:
v2.4.0
v2.3.2
The following translations have been updated with this release:
v2.3.1
v2.3.0
v2.2.12
The following translations have been updated with this release:
v2.2.11
v2.2.10
v2.2.9
The following translations have been updated:
v2.2.8
v2.2.7
v2.2.6
v2.2.5
The following translations have been updated:
v2.2.4
The following translations have been updated:
v2.2.3
v2.2.2
v2.2.1
v2.2
v2.1.9
v2.1.8
v2.1.7
v2.1.6
v2.1.5
v2.1.4
v2.1.3
v2.1.2
v2.1.1
v2.1
v2.0.4
v2.0.3
v2.0.2
v2.0.1
v2.0
v1.1.9
v1.1.8
This version includes the following fixes:
v1.1.7
This version includes the following fixes:
v1.1.6
This version includes the following fixes:
Dependencies
Dependencies for this extension (org.xwiki.contrib:macro-fullcalendar-ui 2.4.1):
- org.xwiki.contrib:macro-fullcalendar-api 2.4.1
- org.xwiki.contrib:macro-fullcalendar-webjar 2.4.1
