FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

PresideCMS Extension: Calendar View

v1.1.6.00042 Public

Preside calendar view extension

The Calendar View extension allows developers to present date/time based preside object data in calendar view. The extension builds upon both Full Calendar and Bootstrap year Calendar, both open source JavaScript calendar tools, and provides Preside hooks to make it super convenient.

Install

Requires Preside 10.9.0 or higher. Install with:

box install preside-ext-calendar-view

Rendering a calendar

The extension provides a helper method for your handlers and views, objectCalendarView():

#objectCalendarView( objectName="my_object", args=options )#

Current arguments are:

  • eventAspectRatio: controls the width to height ratio of a day block in the calendar. The default is 2.
  • allowFilter: whether or not to show the favourite filters bar above the calendar (rules engine filter favourites)
  • calendarView: which js calendar to show. Use calendarView=year to show the Bootstrap year Calendar, or ommit/leave blank to use Full Calendar (default)
  • publicView: to render events for public audience, i.e. non-Admin users. This will hide admin favourite filter from being rendered, hence allowFilter is not needed (and will be ignored) when this is set
  • publicFormFilter: path to public form filter. This will render form filter above the calendar

Decorating your object

In order for the calendar view to know how to render your object data, you must decorate your object with some special attributes:

Admin view

/**
 * @calendarStartDateField start_date
 * @calendarEndDateField   end_date
 * @calendarSelectFields   label,type,status
 */
component {
  // ...
}
  • calendarStartDateField: (required) tells the extension what field to use for the
  • calendarEndDateField: (required) tells the extension what field to use for the end date (can be the same as the start date)
  • calendarSelectFields (optional, default is just the label field) tells the extension what fields to select when fetching data. These fields can then be used in custom renders for a calendar event (see below).

Public view

/**
 * @calendarStartDateField start_date
 * @calendarEndDateField   end_date
 * @calendarPublicSelectFields    id,name,event_type.label as event_type,slug,group_concat( distinct region.id ) as region_ids
 * @calendarPublicHandler         admin.appEventViewer
 * @calendarLinkKey               appEventSlug:slug
 */
component {
  // ...
}
  • calendarStartDateField & calendarEndDateField: (required) same usage as per Admin endpoint
  • calendarPublicSelectFields: (required) fields to select when fetching data. Define as how you would for selectFields. These fields can then be used in custom renders for a calendar event
  • calendarPublicHandler: (required) path to custom handler endpoint which contains rendering functions for public view.
  • calendarLinkKey (optional, needed to render public event link) this builds custom URL. The notion in the example will be used in event.buildAdminLink( appEventSlug={recordid} ) with additional {recordid} replacement with record slug field in processRecordsForCalendar()

Customizing

Admin view

The Calendar View extension uses the Data Manager customization system to allow you to make per-object and global customisations of calendar views. Customizations are focused on how to fetch and what data is fetched from the system to populate the calendar. Customizations are:

  • buildAjaxCalendarViewLink Allows you to take over the logic for building the ajax link that will fetch records
  • getAdditionalQueryStringForBuildAjaxCalendarViewLink Similar to buildAjaxCalendarViewLink, but allows you to just add query string params to the URL. Often used in conjunction with preFetchRecordsForCalendarViewListing or preFetchRecordsForGridListing.
  • preFetchRecordsForCalendarViewListing Run before calling selectData. The args struct can be added to/ modified to change selectData() arguments, i.e. add additional filters, etc.
  • processRecordsForCalendar This customization is given args.records result from selectData and should return an array of structs that will be passed back to the calendar
  • addCalendarEventFields This customization is run per record and allows you to modify / add fields to a single record that will be returned to the calendar. This will not be used if you implement processRecordsForCalendar.

In addition, the extension also attempts to hook into core grid listing customizations so that you can use the same filter logic, etc. in your calendar as you do with your grid:

Public view

Customisation of the following functions has to be in the handler as defined in the object's @calendarPublicHandler:

  • getAdditionalFiltersForAjaxCalendarPublicView: required function for filtering records, if custom form filter is defined for publicFormFilter
  • processRecordsForCalendar: same usage as admin view
  • addCalendarEventFields: same usage as admin view

All Full Calendar configuration options can be passed in as dynamic values to the calendar initialisation. e.g. adding the month, agendaWeek and agendaDay views on the left side.

objectCalendarView(
	  objectName = "myPresideObject"
	, args       = {
		config = {
			header = {
				  left   = "month,agendaWeek,agendaDay"
				, center = "title"
				, right  = "today prev,next"
			}
		}
	}
)

Public view - multiple sources

Can be setup via interceptor with the function preRenderCalendarViewlet( ... ) to define additional sources endpoint, and pass it via includeData, i.e.

event.includeData( { additionalUrls = interceptData.additionalUrls } );

Configuration for Bootstrap year Calendar can be passed using yearConfig. Currently only monthCalendarUrl is supported which can be used to provide a base url to link to Full Calendar. For example, to link to a particular day you could use:

objectCalendarView(
	  objectName = "myPresideObject"
	, args       = {
		  calendarView = "year"
		, yearConfig   = {
			monthCalendarUrl = "www.yoursite.com/page-with-full-calendar/?defaultView=basicDay&defaultDate="
		}
	}
)

The selected day will be appended to the url.

Calendar event fields

When returning an array of structs for the calendar, all the fields that are implemented by FullCalendar are supported. See docs for full details: https://fullcalendar.io/docs/event-object.

In addition, the extension also allows you to set a htmlTitle field that allows you more flexibility for rendering the title of a calendar item (the default implementation of title escapes any html).

Calendar event colour codes

You can setup colour codes for different event types using this component. To use this, enable feature calendarManageColour

This comes with a helper function getCalendarItemColoursByLabel() which can be called in processRecordsForCalendar()

Contributing

Contribution in all forms is very welcome. Use Github to create pull requests for tests, logic, features and documentation. Or, get in touch over at Preside's slack team and we'll be happy to help and chat: https://presidecms-slack.herokuapp.com/.

Changelog

1.1.6

  • Remove timezone information from date
  • Reinstate date filter values for filtering
  • Reinstate add operation for colour code

1.1.5

  • changed year view mouseover rendering
  • check calendarManageColour feature is enabled when getting item colour

1.1.4

  • Markup update for public view filter
  • Assign colour code to cache only when there's record

1.1.3

  • multiple input sources
  • calendar code object: to manage colours for different types
  • helper function to map event type with correct colour codes
  • Public view functionality added: renders calendar for public audience
  • Public endpoint ajax filters
  • Public event view
  • Workaround to display days in week within month view

1.1.2

  • Add localisation possibilities
  • Add german localisation

1.1.1

  • Fixes issue when events with start/end dates are not in view are not displayed
  • Fixes issue issue with events not showing in Safari

1.1.0

  • Added a 'year view' mode

1.0.5

  • Added possibility to pass in dynamic calendar config options

1.0.4

  • Add readme and license

1.0.3

  • First working release

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
1.1.6.00042 May 14 2020 12:17 PM May 14 2020 12:17 PM
Version History
1.1.6.00042 May 14 2020 12:17 PM May 14 2020 12:17 PM
1.1.5.00038 May 04 2020 09:01 AM May 04 2020 09:01 AM
1.1.4.00034 Apr 29 2020 06:08 AM Apr 29 2020 06:08 AM
1.1.3.00028 Apr 22 2020 04:24 AM Apr 22 2020 04:24 AM
1.1.2.00022 Apr 21 2020 06:11 AM Apr 21 2020 06:11 AM
1.1.1.00017 Apr 15 2020 11:25 AM Apr 15 2020 11:25 AM
1.1.0.00013 Mar 30 2020 03:31 AM Mar 30 2020 03:31 AM
1.0.5.00010 Mar 25 2019 11:59 AM Mar 25 2019 11:59 AM
1.0.4.00004 Nov 28 2018 03:47 AM Nov 28 2018 03:47 AM
1.0.3.00001 Nov 28 2018 03:34 AM Nov 28 2018 03:34 AM

 

$ box install preside-ext-calendar-view

No collaborators yet.
  • Nov 28 2018 03:34 AM
  • May 14 2020 12:17 PM
  • 481
  • 777
  • 792