Full Calendar Macro

Last modified by Admin on 2018/09/17 00:03

calendarDisplays a Calendar in Javascript and allows to get events from XWiki pages.
Developed by

Vincent Massol, Ludovic Dubost, Ecaterina Moraru (Valica), Alexandru Chelariu, Manuel Smeria, Anca Luca, Gabriela Smeria, Victor Rachieru

Active Installs511
9 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager


Integrates the FullCalendar v2.9.0 JQuery plugin into XWiki to display custom Calendars.


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.

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).

{{calendar classname="Blog.BlogPostClass" startfield="publishDate" editable="false"  year="2009" month="5" date="1"  /}}

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')"/}}

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:

{{velocity filter="html"}}
#if($xcontext.action == 'get' && "$!{request.outputSyntax}" == 'plain')

    "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\/"

Example with Google Calendar

FullCalendar can display events from a public Google Calendar
All you need to do is pass a series of calendar IDs separated by commas as the value for the "gCal" parameter.

 {{calendar gCal="[email protected]"/}}

In order to use your Google Calendar with this macro you'll need to do the following steps:

  1. 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 downward arrow.
    • A menu will appear. Click "Calendar settings".
    • Click on the "Share this calendar" tab.
    • Check "Make this calendar public".
    • Make sure "See all event details" is selected.
    • Click "Save".
  2. Get the calendar id
    • Click on the "Calendar Details" tab.
    • In the "Calendar Address" section of the screen, you will see your Calendar ID. It will look something like "[email protected]".
  3. Pass the Google Calendar id as the value of the "gCal" parameter
It is highly recommended that you get your own Google API key and use it for your FullCalendar instance.
The default key has a quota of 1.000.000 requests/day and it would not fulfill the need of every FullCalendar macro user.
 {{calendar gCal="[email protected]" gApiKey="AIzaSyDedBXsLGUPKGT2SKh1aZXXJZKdpEc8bQU"/}}

In order to get your own Google API key do the following steps:

  1. Go to the Google Developer Console and create a new project (it might take a second).
  2. Once in the project, go to APIs & auth > APIs on the sidebar.
  3. Find "Calendar API" in the list and turn it ON.
  4. On the sidebar, click APIs & auth > Credentials.
  5. In the "Public API access" section, click "Create new Key".
  6. Choose "Browser key".
  7. If you know what domains will host your calendar, enter them into the box. Otherwise, leave it blank. You can always change it later.
  8. Your new API key will appear. It might take second or two before it starts working.
  9. Pass the newly created key as the value for the "gApiKey" parameter


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

        "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/"

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:

  • classname: the classname holding the object (from the classname parameter of the macro)
  • startfield: the startdate field where the event start date is stored (from the startfield parameter of the macro)
  • durationfield: the duration field where the event duration is stored as a string (from the durationfield parameter of the macro)
  • isResize: if the event is resized, otherwise the event start date is moved
  • deltaDays: the delta in days of the move or resize
  • deltaMinutes: the delta in minutes of the move or resize
  • allDay: if the event is moved to be an allDay event

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.

gCalIDs of the Google calendars from which to retrieve eventsNoneComma separated list of Google Calendar IDs
gApiKeyGoogle API Key to be used when retrieving Google Calendar informationAIzaSyDedBXsLGUPKGT2SKh1aZXXJZKdpEc8bQUGoogle API Key


Screenshot using Flamingo skin:


Release Notes for previous versions (not available anymore in Extension Manager)



  • 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.


  • Changed the authors/creators of the pages to xwiki:XWiki.Admin, to match the standard xar format.


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


Compared to 1.1.1 this release adds:

  • adding JQuery as an attachment to avoid issues with the length of the code property


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


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


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


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


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

Tested on

This extension has been tested with the following configurations.

Extension VersionXWiki FlavorNotes
1.1.8XWiki Enterprise 6.0.1
1.1.9XWiki Enterprise 5.4.6 (Colibri), 6.3 (Colibri, Flamingo)
2.0.2XWiki Enterprise 7.1.3, 7.2
2.0.3XWiki Enterprise 6.4.8, 8.4.4

In this version, the FULLCAL-31 bug was introduced. Until the next release, please use the 2.0.2 version of the application.

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:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes


  • Closed FULLCAL-32 Display of calendar entries on the calendar fails if there is an entry with null start date
  • Closed FULLCAL-31 Update service is unusable on 2.0.3


  • Closed FULLCAL-30 Upgrade FullCalendar to use fullcalendar.io v-2.9.0
  • Closed FULLCAL-29 Add endfield parameter to Calendar Macro


  • Closed FULLCAL-28 Double encoding of single and double quotes in the event title


  • Closed FULLCAL-24 Translate Calendar Macro (+parameters)


  • Closed FULLCAL-23 Internationalize notification messages when updating event
  • Closed FULLCAL-22 The calendar should default to the current date
  • Closed FULLCAL-21 Mark Translations and WebHome as hidden
  • Closed FULLCAL-20 Avoid warnings from javascript minimizer
  • Closed FULLCAL-18 Omitting the durationfield parameter does not result in "all day" events
  • Closed FULLCAL-17 Callback to update events needs to be updated for new version of fullCalendar
  • Closed FULLCAL-16 Add polish and german translation
  • Closed FULLCAL-14 Update e.x.o documentation for version 2.0
  • Closed FULLCAL-13 Event names are blue when using Colibri
  • Closed FULLCAL-12 The top border is missing in flamingo
  • Closed FULLCAL-11 Upgrade to a newer version of FullCalendar
  • Closed FULLCAL-2 Be able to use a Google calendar as source


  • Closed FULLCAL-10 Capitalize name of today, day, week, month and also reorder them
  • Closed FULLCAL-9 Strange borders on Calendar's table on Flamingo
  • Closed FULLCAL-8 Invalid JSON when there are double quotes in the document name


This version includes the following fixes:

  • Closed FULLCAL-7 Calendar events do not always display the complete minutes information
  • Closed FULLCAL-6 The calendar header does not scale when using more dashboard columns
  • Closed FULLCAL-5 The calendar macro should not generate unnecessary whitespaces
  • Closed FULLCAL-3 Mark internal pages as hidden


This version includes the following fixes:

  • Closed FULLCAL-4 Html encoding issues for the title of events


This version includes the following fixes:

  • Closed FULLCAL-1 Full Calendar macro should be translated in the current language

Created by Vincent Massol on 2012/06/13 15:10

Get Connected