Full Calendar Macro

Version 123.13 by Alex Cotiugă on 2021/06/11 15:36

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

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

Active Installs513
Rating
10 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

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.

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

{{velocity}}
 {{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:

{{velocity filter="html"}}
#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

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.

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 & Services > ENABLE APIS AND SERVICES in the top bar.
  3. Find "Calendar API" in the list and turn it ON.
  4. Go back and choose on the sidebar Credentials.
  5. On the top bar select Create credentials > Create new Key > Restrict key.
  6. On API restrictions select Restrict key and choose Google Calendar API, then Save.
  7. Your new API key will appear. It might take a second or two before it starts working.
  8. 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.

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

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 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.
  2. Get the calendar id
    • Click on "Integrate calendar".
    • 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.

Private calendar (Since 2.1)

No API key is needed for accessing the private calendar.

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

  1.  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". 
  2. Pass the link as the value of the "iCal" parameter.
  {{calendar iCal="https://calendar.google.com/calendar/ical/john.doe%40gmail.com/private-c64b704cb242b53ddc0ce6d5f57f9709/basic.ics" /}}

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  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
iCalThe secret address of the Google calendar from which to retrieve eventsNoneiCal address
gApiKeyGoogle API Key to be used when retrieving Google Calendar informationAIzaSyDedBXsLGUPKGT2SKh1aZXXJZKdpEc8bQUGoogle API Key
extraFields Since 2.2.4Extra fields to be added in the calendar eventNoneThe 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:

calendar.png

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:

  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

For XWiki version < 7.0:
Since version 2.1, when the support for iCalendar (.ics) was introduced, the installation process demands some manual jar upgrades (replace the existing versions from webapps/xwiki/WEB-INF/lib/ with the newer ones - these jars can be taken from newer XWiki verions) for earlier versions, as it follows:

  • groovy-all-2.1.7.jar -> groovy-all-2.3.2.jar or higher (until XWiki 6.1)
  • commons-lang3-3.1.jar -> commons-lang3-3.3.2.jar or higher (until XWiki 6.1)
  • commons-codec-1.8.jar -> commons-codec-1.9.jar or higher (until XWiki 6.0)
  • slf4j-api-1.7.5.jar -> slf4j-api-1.7.10.jar or higher (until XWiki 7.0)

Release Notes

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

  • org.xwiki.contrib:macro-fullcalendar-api 2.2.8
  • org.xwiki.contrib:macro-fullcalendar-webjar 2.2.8
Tags:
    

Get Connected