pixl8 / preside-ext-calendar-view

Automatic calendar views in Preside data manager for your date-based object data
GNU General Public License v2.0
0 stars 6 forks source link

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:

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
 * @calendarAdditionalSortOrder  label
 * @calendarSelectFields         label,type,status
 */
component {
  // ...
}

Public view

/**
 * @calendarStartDateField        start_date
 * @calendarEndDateField          end_date
 * @calendarAdditionalSortOrder   label
 * @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 {
  // ...
}

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:

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:

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