FullCalendar Event Object: Non-standard Fields (GCal)

Question

FullCalendar (FC) documentation states

Non-standard Fields In addition to the fields above, you may also include your own non-standard fields in each Event Object. FullCalendar will not modify or delete these fields. For example, developers often include a description field for use in callbacks such as eventRender. [Source: Event Object]

and for Google Calendar event sources

Advanced: Extended Properties Google Calendar’s API allows you to specify Extended Properties for your events. The extended properties will be available as the extendedProperties hash that is attached to each Event Object. [Source: events from Google Calendar]

However what isn't so clear is which GCal eventSource properties are classified as standard and which are non-standard.

‍‍‍‍‍‍ ‍‍

Assuming that the properties listed on the first Event Object Doc are also applicable as standard properties for GCal eventSources means anything else is likely to be a Non-standard Field, right?

If I want to query creator fields for given FC events e.g. creator.displayName or creator.email as per Google API ref doc for events#extendedProperties which appears at the bottom of the event popup i.e. "Created by: ... " (in Google calendar that is, not FC), but I am not sure how to accomplish this. ‍‍‍‍‍‍ ‍‍

I cannot find a complete list of Standard & Non-Standard Fields for FullCalendar (v3) GCal eventSources anywhere, never mind Docs/examples on how to access these properties.

‍‍‍‍‍‍ ‍‍

Anyhow attempted the following:

console.log(event.extendedProperties.creator.displayName);
console.log(event.extendedProperties.creator.email);

just produced

jquery-3.3.1.min.js:2 jQuery.Deferred exception: Cannot read property 'displayName' of undefined TypeError: Cannot read property 'displayName' of undefined

‍‍‍‍‍‍ ‍‍

And sure enough event.extendedProperties.creator did produce undefined. However next I tried:

console.log(event.extendedProperties);
console.dir(event.extendedProperties);

Which did not produce an error, but instead what appears to be an empty object

Screen shot of console.dir(event.extendedProperties)

So if it came back with nothing (i.e. empty object) it's fair to assume that there are no extendedProperties for the given events I'm querying and it also reasonable to assume that perhaps the creator fields: creator.displayName and creator.email aren't Non-standard Fields after all or at least not of the Extended Properties type.

Wait a minute, does this imply that there could be two types on Non-Standard Field lists we are dealing with or have I been staring at this screen for way too long? ????

‍‍‍‍‍‍ ‍‍

Finally I attempted to double check to make sure they are not part of the event object already.

console.log(event.creator.displayName);
console.log(event.creator.email);

but again this resulted in

Uncaught TypeError: Cannot read property 'displayName' of undefined

‍‍‍‍‍‍ ‍‍

I am at a complete loss. How am I supposed to obtain fields that aren't mentioned anywhere on the FullCalendar website nor appear to be an Extended Properties?

Have I overlooked anything or is there perhaps a list in existence of Standard/Non-standard Fields that I've somehow managed to miss?

Any ideas on how to obtain these creator fields would be much appreciated.

‍‍‍‍‍‍ ‍‍

I don't see how any sort of code sample would be helpful here, but as I was told recently "Code is pretty much always required on Stack Overflow" so for compliance sake here's me code sample ...

<div id='calendar'></div>
<script>
$(function() {
  $('#calendar').fullCalendar({
    googleCalendarApiKey: '%googleCalendarApiKey%',
    events: {
      googleCalendarId: '[email protected]' //imdb UK
    },
    defaultView: 'month',
    eventRender: function(event, element) {
      element.popover({
        animation:true,
        delay: 300,
        title: event.title,
        content: event.description, // + req << creator.displayName/email >>  e.g."Created by: [email protected]"
        placement: 'auto',
        trigger: 'hover'
      });
    }
  });
});
</script>

PS Didn't create CodePen as advised not to share GoogleAPIKey

The only things which fullCalendar considers as "standard" fields are the ones explicitly listed in the Event Object documentation. That's regardless of what the source of the events is — ADyson
What you perhaps haven't considered here is that almost none of the field names in the data that Google's API returns will match the ones that fullCalendar recognises (as per the Event Object documentation). So the little gcal.js plugin which makes this integration work has to process that Google data, translate the necessary field names and output a new event object for fullCalendar to use. Whether or not it also copies other fields from google at the same time, you can perhaps check by looking at the final event objects being held in fullCalendar — ADyson
E.g. you could use the "clientEvents" method in fullCalendar as a test to output all the events which were copied from the Google API data and see what, if any, custom fields were included. If it doesn't include data you need then you'd have to either alter the gcal.js script or write your own integration code instead in order to make it include that data from Google in the object it passes to fullCalendar. — ADyson
But as to it being documented about which exact fields are carried across, you're right, I don't think it's documented to that level, hence why you'll have to test it yourself and/or read the source code — ADyson
e.g. perhaps return { id: item.id, title: item.summary, start: item.start.dateTime || item.start.date, end: item.end.dateTime || item.end.date, url: url, location: item.location, description: item.description, extendedProperties: extendedProperties, creator: item.creator }; would do the job. (Note that creator may not always have a displayName, e.g. if the event was created by a Service Account or something. Maybe you might want to include the organizer as well - I don't know, depends on your setup.) — ADyson

ADyson ADyson · Accepted Answer · 2019-03-19T09:58:53

When the fullCalendar docs say

Google Calendar’s API allows you to specify Extended Properties for your events. The extended properties will be available as the extendedProperties hash that is attached to each Event Object.

they are referring to extra custom fields you may have defined in your Google Calendar events - fields which are not otherwise supported or provided by the Calendar API as standard. These are the fields which fullCalendar will copy as "extra". It is not referring to "any fields which fullCalendar normally doesn't regard as standard".

Now, because almost none of the event data structure returned by the Calendar API would map directly onto the data structure which fullCalendar requires you to provide in order to construct a valid event object (see the list of fullCalendar's "standard" fields in the Event Object docs), we cannot simply provide the JSON output of the Calendar API direct to fullCalendar and expect it to work and automatically map the fields.

That's why fullCalendar has provided the gcal.js file as a convenience utility to connect to the API, retrieve the event data and transform it into the format that fullCalendar expects and will understand. Clearly the developers made a choice about which fields they were going to carry over from one to the other. Since a new object is being constructed to pass to fullCalendar, there's no automatic mapping of any kind - it all relies on what's written in the code. Normally if you provide JSON to fullCalendar direct it also copies across any other fields it finds in the object, in addition to the ones it actually recognises as "standard" (i.e. the standard ones are the ones it uses for specific purposes as explained in the documentation). But again since the code creates new objects for fullCalendar, this does not occur either.

Apart from the note on "extendedProperties", there's no explicit documentation of which fields the code copies from the API output into the fullCalendar-compatible event objects. A quick experiement using console.log($("#calendar").fullCalendar("clientEvents")); in your page will reveal what properties the final events have, but you can also look in the source code. At the time of writing, the latest version of fullCalendar v3 was 3.10, and the gcal.js source code for that version (viewable here).

The code contains the following snippet to transform the API data into a fullCalendar object:

    return {
        id: item.id,
        title: item.summary,
        start: item.start.dateTime || item.start.date,
        end: item.end.dateTime || item.end.date,
        url: url,
        location: item.location,
        description: item.description,
        extendedProperties: extendedProperties
    };

In your question and comments, you've mentioned that you'd be interested in the creatorand description fields which the Calendar API provides. These are standard fields in GCal (as per the resource representation docs) and therefore would not be in the "extendedProperties" collection. You can also see that description is already copied across by gcal.js, even though it's not a field that fullCalendar ordinarily makes use of - nevertheless it's there if you want to make some use of it in your calendar.

Therefore all you need to do to make the creator field (or any other field from the GCal properties) available in your fullCalendar events is include it in the data which gcal.js copies. e.g.:

    return {
        id: item.id,
        title: item.summary,
        start: item.start.dateTime || item.start.date,
        end: item.end.dateTime || item.end.date,
        url: url,
        location: item.location,
        description: item.description,
        extendedProperties: extendedProperties,
        creator: item.creator
    };

Of course if you are including gcal.js / gcal.min.js via a CDN you'll need to change your code to host your own modified version instead.

As an aside, if you feel the fullCalendar project would benefit as a whole from having more fields from GCal included by default, then since fullCalendar is an open-source, community project, you'd be free to make a feature request to get changes made to the gcal utility (which is really just a convenience add-on as a layer between fullCalendar's standard functionality and the Google Calendar API), or even make a code contribution containing the suggested change, for consideration by the maintainers for inclusion in the main release. Failing that, you can continue to maintain your modified version of gcal.js, or even replace it entirely with your own utility for interacting with the Calendar API.

FullCalendar Event Object: Non-standard Fields (GCal)

1 Answers