Dynamics 365 portals: Implement FullCalendar with Liquid

Using the techniques discussed in Using liquid to return JSON or XML we can easily build a services that work with various with JavaScript libraries. FullCalendar is one of the most popular libraries for displaying events in various views on the web and can easily be used in the portal and creating a JSON return template for the event data. With FullCalendar you can fully customize a calendar output in the portal to really get that user experience you might be looking for. In this post is a simple implementation of FullCalendar with a custom entity JSON return template that will help outline how you can use this library in your portal projects.

First we can start with creating the web template that will be the return JSON data. Within this template a fetchxml query that takes at least the parameters of start and end so that it will filter for the date range being displayed on the calendar by adding the necessary conditions in the fetch.

{% fetchxml feed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false" count="100" returntotalrecordcount="true" {% if request.params['page'] %} page="{{request.params['page']}}" {% else %}
page="1"
{% endif %}>
  <entity name="dpx_courseschedule">
    <attribute name="dpx_number" />
    <attribute name="createdon" />
    <attribute name="dpx_starttime" />
    <attribute name="dpx_endtime" />
    <attribute name="dpx_courselocationid" />
    <attribute name="dpx_courseid" />
    <attribute name="dpx_coursescheduleid" />
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0" />
      {% if request.params['location'] %}
        <condition attribute="dpx_courselocationid" operator="eq" value="{{ request.params['location'] | xml_escape }}" />
      {% endif %}
      {% if request.params['start'] %}
        <condition attribute="dpx_starttime" operator="ge" value="{{ request.params['start'] | xml_escape }}" />
      {% endif %}
      {% if request.params['end'] %}
        <condition attribute="dpx_endtime" operator="le" value="{{ request.params['end'] | xml_escape }}" />
      {% endif %}
    </filter>
    <link-entity name="dpx_instructor" from="dpx_instructorid" to="dpx_instructorid" visible="false" link-type="outer" alias="instructorlink">
      <attribute name="dpx_contactid" />
      <attribute name="dpx_number" />
    </link-entity>
    <link-entity name="dpx_course" from="dpx_courseid" to="dpx_courseid" alias="courselink">
      <attribute name="dpx_coursecategoryid" />
      {% if request.params['category'] %}
        <filter type="and">
          <condition attribute="dpx_coursecategoryid" operator="eq" uiname="Category 1" uitype="dpx_coursecategory" value="{{ request.params['category'] | xml_escape }}" />
        </filter>
      {% endif %}
    </link-entity>
  </entity>
</fetch>
{% endfetchxml %}[
  {% for item in feed.results.entities %}
    {
      "title": "{{ item.dpx_courseid.name }} - {{ item['instructorlink.dpx_contactid'].name }}",
      "start": "{{ item.dpx_starttime | date_to_iso8601 }}",
      "end": "{{ item.dpx_endtime | date_to_iso8601 }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor -%}
]

The JSON is formatted to follow the FullCalendar Event Object and return an Event Source Object. Providing the return format directly in the service allows us to now easily hook up this service to the FullCalendar event configuration. The sample above only includes a number of simple properties but you can add any number of properties from the Event Object and map them to data in the query results.

Ensure that you now give the return JSON template a URL using the instructions in Use liquid to return JSON or XML and the Mime Type is set to application/json.

Now create a new web template that is going to implement the FullCalendar library and consuming the event return JSON template.

The first thing that needs to be added is references to both the CSS as well as JavaScript for FullCalendar as well as a reference to Moment.js. FullCalendar utilizes Moment.js for all date functions and therefore the Moment.js library needs to be referenced prior to the FullCalendar JavaScript library. Below is a simple template that uses the CDN’s for FullCalendar as well as Moment.js.

<link href="//cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.3.1/fullcalendar.min.css" rel="stylesheet" />

<div id='calendar'></div>

<script src="//cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.3.1/fullcalendar.min.js"></script>

<script>
  $(document).ready(function() {
      $('#calendar').fullCalendar({
          // FullCalendar configuration properties
      });
  });
</script>

The JavaScript in the code above initializes FullCalendar on the HTML element with the id of calendar and takes a series of parameters. You can review all the parameters available for configuration on the FullCalendar documentation. There are configuration properties for just about every function and include event callbacks that can be configured for certain events which could be utilized to make further calls to return JSON based templates.

To display event data on the calendar there are a couple of parameters that can be used to inject event data. For the following configuration we will be using the previously created web template that returns the FullCalendar Event Object based on our custom entity, but you can retrieve the data in various ways with the options that FullCalendar provides including multiple event sources.

<script>
  $(document).ready(function() {  
      $('#calendar').fullCalendar({
        events: {
          url: '/fullcalendar-json/',
          type: 'GET',
          error: function() {
            alert('there was an error while fetching events!');
          },
          color: 'yellow',
          textColor: 'black'
        }
      });
  });
</script>

Here we have replaced the blank configuration properties with the Events property which uses a url to retrieve event data. The URL is configured to our previous templates URL and the GET HTTP method is configured as the type. The event properties color and textColor are also configured for the default display of events on the calendar. After hooking up this new web template to a page template and web page you can view it in the portal and should have a result similar to the following:

Now we can take this further and enhance the display of events as well as add event filtering options. For my custom entities, I extended the Instructor with 2 additional fields, color and text color which I put in HEX color code values into for each record. I extended the fetchxml query to include these fields as well as the JSON output to add these fields as Event Object properties, below is the new JSON output including as well a URL that will link to the event details using a site marker.

{% fetchxml feed %}
<!-- fetchxml statement removed for length -->
{% endfetchxml %}[
  {% assign urlMarker = sitemarker['Event Details'] %}
  {% for item in feed.results.entities %}
    {
      "title": "{{ item.dpx_courseid.name }} - {{ item['instructorlink.dpx_contactid'].name }}",
      "start": "{{ item.dpx_starttime | date_to_iso8601 }}",
      "end": "{{ item.dpx_endtime | date_to_iso8601 }}",
      "color": "{{ item['instructorlink.dpx_colorcode'] }}",
      "textColor": "{{ item['instructorlink.dpx_textcolor'] }}",
      "url": "/{{ urlMarker.Url }}?id={{ item.id }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor -%}
]

In my FullCalendar liquid template I have add a fetchxml query so I can get a list of locations which are displayed in a drop down so users can then filter events in the calendar by this property.

{% fetchxml locationfeed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
  <entity name="dpx_courselocation">
    <attribute name="dpx_name" />
  </entity>
</fetch>
{% endfetchxml %}

<p>
  <div class="input-group">
    <select id="course-location" class="form-control">
        <option value="" selected disabled>Select a location...</option>
      {% for item in locationfeed.results.entities %}
        <option value="{{ item.id }}">{{ item.dpx_name }}</option>
      {% endfor %}
    </select>
    <span class="input-group-btn">
      <button id="refresh-events" class="btn btn-primary">Refresh Events</button>
    </span>
    <span class="input-group-btn">
      <button id="clear-events" class="btn btn-danger">Reset/Clear</button>
    </span>
  </div>
</p>

Then the JavaScript I have added 2 events for the new refresh and clear buttons, as well I have added a data property to the events call that will inject the location value if it is selected.

$('#calendar').fullCalendar({
  events: {
    url: '/fullcalendar-json/',
    type: 'GET',
    data: function() {
      var locationId = $('#course-location option:selected').val();            
      if (locationId) {
        return {
          location: locationId
        };
      }            
      return null;
    },
    error: function() {
      alert('there was an error while fetching events!');
    },
    color: 'yellow',   // a non-ajax option
    textColor: 'black' // a non-ajax option
  }
});

$('#refresh-events').on('click', function(){
  $('#calendar').fullCalendar('refetchEvents');
});

$('#clear-events').on('click', function(){
  $('#course-location').prop('selectedIndex',0);
  $('#calendar').fullCalendar('refetchEvents');
});

The display and function of the calendar should now be enhanced with colors for each instructor and the ability to filter the course schedules by location!

Hopefully this has helped show an example of the power you can get out of liquid templates by creating your own JSON based service and utilizing a JavaScript library like FullCalendar.

If your interested in learning more about liquid techniques I will be giving a webinar with xRMVirtual on April 26th at 12pm EST – Advanced Liquid Templates for Dynamics 365 portals.

Leave a Reply

Your email address will not be published. Required fields are marked *