List Calendar Layout
Description
The List Calendar Layout renders list records (events) in a monthly, weekly, or daily calendar layout.
This feature is still under development and requires a Feature Key in order to enable it. This feature is being made available early in the development cycle so we can get feedback from the community. To request a feature key, go to Help and send an email to [email protected] with "List Calendar Feature Key" in the subject.
Settings
Settings are defined as a JSON object that specifies how to render the calendar. Sample settings can be inserted using the Sample settings link. Sample layouts are designed to be used with the "Calendar data" sample data (available when the list's data source is set to "Static Data").
Sample layouts include:
- Month
Displays events with a calendar picker on the left and the selected month on the right.
- Week
Displays events with a calendar picker on the left and the selected week on the right.
- Day
Displays events with a calendar picker on the left and the selected day on the right.
- Timeline
Displays events with a calendar picker on the left and a two-week view on the right.
- Custom
Deletes all settings in the settings dialog, letting you define your own custom settings.
See Appendix A for a listing of the available settings. This same information can be accessed in the Calendar Settings dialog via the Settings object documentation link.
Events
onClick
Fires when the calendar is clicked. Several variables are available in this event:
- target
The part of the calender that was clicked (such as "item", "nav", and "date")
- date
The date/time that was clicked.
- item
The item that was clicked if target was "item".
onDblClick
Fires when the calendar is double-clicked. Several variables are available in this event:
- target
The part of the calender that was clicked (such as "item", "nav", and "date")
- date
The date/time that was clicked.
- item
The item that was clicked if target was "item".
onRightClick
Fires when the calendar is right-clicked. Several variables are available in this event:
- target
The part of the calender that was clicked (such as "item", "nav", and "date")
- date
The date/time that was clicked.
- item
The item that was clicked if target was "item".
onDragStart
Fires when the user starts dragging an existing calendar event.
onDrag
Fires while an existing event is being dragged.
onDragEnd
Fires when the user stops dragging an existing calendar event. The following variables are available in this event:
- d
An object with the drag properties.
The example below updates the data in the List when the user stops dragging the event -- i.e. when an event is dragged to a new date or its duration is changed. This allows users to change an event's duration or date by dragging it to a new time or date.
var data = this.getData(d.index); var start = d.start.toFormat('MM/dd/yyyy h:mm am') var dur = ''+d.start.diff('hours',d.end).hours; if(d.type == 'move' || d.type == 'start' || d.type == 'end'){ data.start = start; data.duration = dur; } else if(d.type == 'drop'){ if(d.target.indexOf('group:') == 0){ data.group = d.target.substr(6); } } else if(d.type == 'custom'){ this.appendRows({id: ''+Date.now(), start: start, duration: dur,group: 'A', title: 'New Item', disc: 'New item description...'}); } this.calendarRefresh();
Videos
Overview of the List Calendar Layout
In this video, we show how to add a calendar layout to a List Control.
How to Dynamically set the Color for an Event
In this video, we show how set the color for a calendar event using data from the list row.
Appendix A: Settings Object
General Settings:
Most className and style attributes support the ability to use a function to generate the class name or style - this can be used to do things like style specific dates (holidays, weekends, etc.)
{ flow: 'ltr', // the flow of the calendar - can be "ltr", "rtl", or "ttb" in the case of "timeline" resolution: 'time', // the resolution of items in the calendar - can be "time" or "date" input: { start: 'startDate:MM/dd/yyyy h:mm am', // start date-time column name and format - required - can also be an object that uses the Date.fromObject method (see documentation.alphasoftware.com) where the properties passed in are the names of columns instead of values end: 'endDate:MM/dd/yyyy h:mm am', // end date-time column name and format - optional - can also be an object that uses the Date.fromObject method (see documentation.alphasoftware.com) where the properties passed in are the names of columns instead of values duration: { // alternate duration instead of end settings days: 'days', // days duration field - optional hours: 'hours', // hours duration field - optional minutes: 'minutes', // minutes duration field - optional seconds: 'seconds', // seconds duration field - optional milliseconds: 'milliseconds', // seconds duration field - optional }, group: { // see documentation for A5.u.array.group (on documentation.alphasoftware.com) by: 'column' // the column to group by } }, layout: { // define content around calendar above: { // content above (top) show: true, // whether or not to show the content section className: '', // the class name for the content section style: 'border-bottom: 1px solid #bbb;', // the style for the content section html: '<previous /><today/><next/> <range/>' // the HTML to place in the content section - generated controls can be placed by using the custom tags: "<previous />", "<today />", "<next/>", "<navigator />" and "<range />" - see layout.controls }, before: { // content before (left) show: true, // whether or not to show the content section className: '', // the class name for the content section style: 'border-right: 1px solid #bbb; margin-right: -1px;', // the style for the content section html: '<navigator />' // the HTML to place in the content section - generated controls can be placed by using the custom tags: "<previous />", "<today />", "<next/>", "<navigator />" and "<range />" - see layout.controls }, after: { // content after (right) show: false, // whether or not to show the content section className: '', // the class name for the content section style: 'border-left: 1px solid #bbb;', // the style for the content section html: '' // the HTML to place in the content section - generated controls can be placed by using the custom tags: "<previous />", "<today />", "<next/>", "<navigator />" and "<range />" - see layout.controls }, below: { // content below (bottom) show: false, // whether or not to show the content section className: '', // the class name for the content section style: 'border-top: 1px solid #bbb;', // the style for the content section html: '' // the HTML to place in the content section - generated controls can be placed by using the custom tags: "<previous />", "<today />", "<next/>", "<navigator />" and "<range />" - see layout.controls }, controls: { // settings for generated controls navigator: { // the navigator control type: 'month', // the type of navigator - can be "month" or "date" - "month" will show standard calendar view and "date" will show a run of dates range: '', // the range of the navigator - value can be a number (e.g. the number of months/dates to show), or one of several strings: "year", "month", "week". multiples of these units can be specified as well with "N-years", "N-months", or "N-weeks" where "N" is the number of years/months/weeks flow: 'ttb', // the flow of the navigator - values can be "ttb", "ltr", "rtl" pr "ttb-rtl" className: '',// the class name for the navigator style: 'height: 100%;', // the style for the navigator navigation: { // the navigation secton of the navigator control location: 'inline', // the location of navigation - values can be "before", "after", "inline" className: '', // the class name for the navigation "header" style: 'border: 1px solid #ccc; margin: -1px; padding: 1px; z-index: 1', // the style for the navigation "header" previous: {theme: this.theme, icon: 'default'}, // the settings for the previous button (see A5.Button for all settings) - the icon can be automatically chosen based on the flow by using the value "default" next: {theme: this.theme, icon: 'default'}, // the settings for the next button (see A5.Button for all settings) - the icon can be automatically chosen based on the flow by using the value "default" range: {theme: this.theme, html: 'default'} // the settings for the range button (see A5.Button for all settings) - the HTML can be automatically chosen based on the range by using the value "default", or can be a date formate (see Date.toFormat) or a function that will be passed the start and end dates }, month: { // settings for month navigator className: '', // the class name for a calendar month style: 'margin: 0px -1px; border-left: 1px solid #ddd; border-right: 1px solid #ddd; background: #fff;', // the style for a calendar month header: { // the settings for a calendar month heading className: '', // the class name for a calendar month heading style: 'padding: 4px; font-size: 75%; font-weight: bold; text-align: center;', // the style for a calendar month heading html: '{month.full.toCase(\'proper\')} {year.value}' // the HTML to put in a calendar month heading - can be a template for function }, week: { // the settings for a calendar month week className: '', // the class name for a calendar month week style: '' // the style for a calendar month week } }, date: { // settings for a date in the navigator className: 'listItem', // the class name for a date selectedClassName: 'listItemSelected', // the selected class name for a date style: 'padding: 6px; text-align: center;', // the style for a date html: 'default' // the HTML for a date - a value of "default" will use a reasonable default, or a template or function can be used }, items: { // settings for items in the navigator type: 'dots', // the item type - values can be "none", "dots", "single-dot", "condensed-dots" (e.g. one-per-color), or "timeline" className: '', // the class name for the items container style: '', // the style for the items container max: 8, // the max number of items to show (per date or week) item: { className: '', // the class name for an item style: 'border: 1px solid;', // the style for an item color: 'inherit', // the color for an item - see items.item.color size: 4, // the size (in pixels) of an item offset: 2 // the offset (in pixels) between items } } }, range: {theme: this.theme+':subtle', html: 'default'}, // the settings for the range button (see A5.Button for all settings) - the HTML can be automatically chosen based on the range by using the value "default", or can be a date formate (see Date.toFormat) or a function that will be passed the start and end dates previous: {theme: this.theme+':icon', layout: 'icon'}, // the settings for the previous button (see A5.Button for all settings). next: {theme: this.theme+':icon', layout: 'icon'}, // the settings for the next button (see A5.Button for all settings). today: {theme: this.theme, layout: 'text', html: 'Today'} // the settings for the today button (see A5.Button for all settings). } }, items: { allowCustom: true, // allow drag on the background of the calendar allowEdit: true, // allow drag edit of existing items on the calendar item: { // settings for an item html: '<b>{data.title}</b><div style="position: absolute; left: 4px; right: 4px; top: 40px; bottom: 4px; overflow: hidden; text-overflow: ellipsis;">{data.disc}</div>', // the HTML to place in an item - can be a template or function - row data can be found in the data sub-property className: '', // the class name for an item selectedClassName: 'A5CalItemSelected', // the class name for a selected item style: 'border: 1px solid; border-radius: 2px; color: {color.text}; background: {color.fill}; border-color: {color.line};', // the style for an item overflow: { // item overflow settings after: '<b>⋯</b>', // the HTML to place at the end of a item that is continuing out of view before: '<b>⋯</b>' // the HTML to place at the start of a item that is continuing out of view }, handles: { // item handle settings start: { // item start handle settings adjust: 'start', // what the start handle adjusts - values can be "start", "move" to move the item or "none" to not show a handle className: '', // the class name for the start handle style: 'display: inline-block; width: 12px; height: 12px; background: {color.line}; border: 1px solid rgba(0,0,0,.5); border-radius: 7px;' // the style for the start handle }, end: { // item end handle settings adjust: 'end', // what the end handle adjusts - values can be "end", "move" to move the item or "none" to not show a handle className: '', // the class name for the end handle style: 'display: inline-block; width: 12px; height: 12px; background: {color.line}; border: 1px solid rgba(0,0,0,.5); border-radius: 7px;' // the style for the end handle } }, color: [{line: '#0A7EE5', fill: '#3F96E4', text: '#000'},{line: '#D41712', fill: '#F05B57', text: '#000'},{line: '#67A228', fill: '#A0CE6D', text: '#000'},{line: '#D9A300', fill: '#FDCC39', text: '#000'},{line: '#00899D', fill: '#01DFFE', text: '#000'},{line: '#D58000', fill: '#FCAC35', text: '#000'},{line: '#9607AF', fill: '#A641B8', text: '#000'}] /* the colors for an item - can be a single CSS color, and array of colors (each group will use a color from the array), or a function. a color can be a CSS color, or an object with "line", "fill", and "text" values as CSS colors. other representation of items can use the selected color of an item by using "inherit", or use a custom color object (with "line", "fill", and "text"). */ }, range: { // the settings for the drag range both "edit" and "custom" step: '15m', // the snapping step - "m" and "hr" can be used to specify minute or hour units color: 'inherit', // the color for the drag range - see items.item.color start: { // range start settings format: 'default' // the format to use for the range start text (see Date.toFormat) - a value of "default" will use the most logical format based on calendar type and settings }, end: { // range end settings format: 'default' // the format to use for the range end text (see Date.toFormat) - a value of "default" will use the most logical format based on calendar type and settings } }, dragDrop: { // the settings to use when the user has dragged an item out of the calendar to drop it on some other part (such as a navigator date) html: '<b>{data.title}</b>', // the HTML to display while drag-dropping can be a template or function className: '', // the class name for a drag-drop item style: 'border: 1px solid; border-radius: 2px; color: {color.text}; background: {color.fill}; border-color: {color.line}; box-shadow: 2px 2px 10px 0px rgba(0,0,0,.5);', // the style for a drag-drop item offset: 10 // the offset for a drag-drop item } }, date: { // the settings for a date in the calendar header: { // the settings for the date header in the calendar className: '', // the class name for the date header style: '', // the style for the date header labels: { className: '', // the class name for a date header label style: ''// the style for a date header label } }, content: { // the settings for a date content region in the calendar className: '', // the class name for a date style: '' // the style for a date } }, time: { // the settings for time in the calendar scale: '1hr', // the time scale (in "m" or "hr" - decimals allowed) - a major and minor unit can be specified by using a "/" - for example "1hr/15m" for one hour major steps divided into 15 minute minor steps header: { // the settings for the time header className: '', // the class name for the time header style: '',// the style for the time header major: { // the settings for the time header major units className: '', // the class name for the time header major units style: '', // the style for the time header major units labels: { // the label settings for the time header major units html: 'h:mm am', // the label html - can be a format (see Date.toFormat) or a function className: '', // the label class name style: '' // the label style } }, minor: { // the settings for the time header minor units className: '', // the class name for the time header minor units style: '', // the style for the time header minor units labels: { // the label settings for the time header minor units html: 'mm', // the label html - can be a format (see Date.toFormat) or a function className: '', // the label class name style: '' // the label style } } }, content: { // the settings for the time content (inside the date content) - used to draw lines show: true, // show the time content className: '', // the class name for the time content style: '', // the style for the time content major: { // the settings for the major time content className: '', // the class name for the major time content style: '' // the style for the major time content }, minor: { // the settings for the minor time content className: '', // the class name for the minor time content style: '' // the style for the minor time content } }, now: { // the current date/time marker show: true, // whether to show the current date/time marker className: '', // the current date/time marker class name style: 'border: 1px dotted #ff351c;', // the current date/time marker style (every border except the logical best will be set to a type of none automatically) label: { // the current date/time marker label location: 'after-end', // the current date/time marker label location - values can be "none", "before-start", "before-end", "after-start", "after-end", "on-start", or "on-end" html: 'h:mm am', // the current date/time marker label format (see Date.toFormat) className: '', // the current date/time marker label class name style: 'background: #ff351c; color: #fff; border-radius: 2px; padding: 2px 4px; font-size: 60%; margin: -1px;' // the current date/time marker label style } } }, groups: { // the settings for item groups (if used) header: { // the settings for the item groups header className: '', // the class name for the item groups header style: '', // the style for the item groups header labels: { // the settings for a group header label className: '',// the class name for a group header label style: ''// the style for a group header label } }, content: { // the settings for a item group content className: '', // the class name for a item group content style: '' // the style for a item group content } }, stack: { // the settings for item stacks (if used) content: { // the settings for item stack content className: '', // the class name for a item stack content style: '' // the style for a item stack content } }, onClick: function(target,date,item){}, // event for when the user clicks on the calendar - target is the part of the calendar the user clicked on (such as "item", "nav" and "date"), date is the date/time clicked on, and item is the item clicked on it the target was a item. onDblClick: function(target,date,item){}, // event for when the user double clicks on the calendar - see click for more onRightClick: function(target,date,item){}, // event for when the user right clicks on the calendar - see click for more onDragStart: function(drag){}, // event for when the user starts a drag onDrag: function(drag){}, // events during a drag onDragEnd: function(drag){}, // event for when the user ends a drag /* the drag events argument is an object with data about the drag: { type: 'item', // the drag type - "item" or "custom" original: { start: Date(), // the original start date-time end: Date(), // the original end date-time }, start: Date(), // the current start date-time end: Date(), // the current end date-time index: 1, // the item index target: '', // the target when the action is drag drop } */ }
Timeline layout specific settings:
{ range: '2-weeks', // the range of the timeline layout - number of days, "week", "N-weeks", "work-week" and "month" allowed date: { size: 250, // the size of a date in the timeline (in "ltr" and "rtl" it is "width", in "ttb" it is "height") header: { size: 50 // the size of the date header } } }
Month layout specific settings:
{ date: { header: { size: 20, // the size of the date header } }, daysOfWeek: { // the days of week settings names: 'short', // names to use - values can be "short", "minimal", "full", an array of names, or a function that returns an array start: 0, // the start day of the week (0 = Sunday) end: -1, // the end day of the week (0 = Sunday, -1 is the last day of the week) className: '', // the class name for the days of week section style: '', // the style for the days of week section header: { // the settings for the days of week header className: '', // the class name for the days of week header style: 'border-bottom: 1px solid #ccc;', // the style for the days of week header labels: { // the settings for the days of week header labels className: '', // the class name for the days of week header labels style: 'text-align: center; font-size: 75%; font-weight: bold; padding: 4px;' // the style for the days of week header labels } } }, items: { collapse: { // collapse settings count: 4, // the collapse count size: 20, // the size of collapse section className: '', // the class name of collapse section style: 'background: rgba(0,0,0,.2); opacity: .2; font-size: 10px; font-weight: bold; padding: 4px 2px;', // the style of collapse section show: { // the settings for the show more collapse section html: '<span style="font-family: monospace;">+</span>{count} events...', // the HTML for the show more collapse section className: '', // the class name for the show more collapse section style: '' // the style for the show more collapse section }, hide: { // the settings for the hide more collapse section html: '<span style="font-family: monospace;">-</span>{count} events...', // the HTML for the hide more collapse section className: '', // the class name for the hide more collapse section style: '' // the style for the hide more collapse section } }, item: { size: 20 // the size of the and item } } }
Day(s) layout specific settings:
{ range: 1, // the range of the day layout - number of days, "week", "N-weeks", "work-week" and "month" allowed time: { size: 120, // the size of the major time block range: { // custom time range settings start: '6:00', // the start time of a day end: '22:00' // the end time of a day }, header: { size: 60 // the size of the time header } } }