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.

Download Component

2020-05-08

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>&ctdot;</b>', // the HTML to place at the end of a item that is continuing out of view
                before: '<b>&ctdot;</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
        }
    }
}