version

Calendar

Displays a calendar or schedule.

Component modes: Weekdays | Weekdays with time scale | Resources with time scale

Component mode: Resources with time scale

This calendar type has time-intervals and custom resource values as column headings.

Checkboxes (selecteditems)

You can use the calendar setting Show checkboxes to enable checkboxes on a menu item.

The calendar menu item can pass the ids of its selected calendar items, for historical reasons commonly referred to as selecteditems via links from the calendar to other menu items. These menu items then access these ids as a comma-separated string.

Calendar item Ids

Checkboxes use the values from the first calendar item column as calendar item ids. Calendar item ids must be unique unless they are NULL. Any calendar item with NULL in the first column will not show a checkbox.

Warning

The calendar item ids that you access through selecteditems are ID values of calendar items that were valid when the user loaded the calendar. No validation is performed to ensure that the ID values are still valid, that their calendar items would still be visible if the user reloads the calendar.

For example, you have a calendar of meetings and a top-link "Postpone all checked meetings by one month". The user checks a few calendar items and then clicks the top link. Now, the checked meetings are postponed , and their calendar items will no longer appear in the calendar, but the calendar still remembers the IDs of the checked calendar items. If the user checks a few more calendar items and clicks the top link again then the Postpone-menuitem will receive both the IDs of the meetings already postponed and the new IDs. You can avoid this by using the execute component's special column admin_unselectall to clear all checkboxes.

Component settings

Time scale end

The end time of each calendar day.

Time scale resolution

The number of minutes between ticks in the time scale.

Time scale start

The start time of each calendar day.

SQL

SQL Call: Retrieve resources (mandatory)

SQL for retrieving the resources for the calendar. The resources of the first result set are displayed as calendar resources, i.e. as columns in the calendar and the resource label is used as title for the resource filter. Resources of subsequent result sets are displayed as dropdown resources in the calendar sidebar.

May modify database: No

Parameters

@FromDate date

The date of the first day visible in the calendar.

@Resources bit

Is 1 when the component asks for resources.

@ToDate date

The date of the last day visible in the calendar.

Resultset: Resource info (optional)

Each 'Resources' result set can optionally be preceded by a 'Resource info' result set.

Table count: repeated zero or one time

Row count: exactly one row

Columns

DefaultValue optional any

Sets the default (initial) value of the resource.

Since NULL can be a valid resource value, setting this column to NULL is not the same as omitting the column.

Default: The first value will be used if no default value is provided.

ResourceLabel mandatory string

Overrides the label from the 'Retrieve resources' result set.

Resultset: Resources (optional)

Table count: repeated zero or more times

Row count: one or more rows

Columns

<column with ordinal 1> mandatory string

Id value for resource.
The currently selected value will be passed to the procedure in a parameter with the same name as the column in subsequent calls.

<column with ordinal 2> mandatory string

Text to display in heading / dropdown for resource.
The column name will be used as a label for the dropdown.

SQL Call: Extra information (mandatory)

SQL for retrieving extra information for the calendar resources. The extra information is displayed directly below the calendar resource headings. It is also possible to specify if a day is a holiday.

May modify database: No

Parameters

@ExtraInfo bit

Is 1 when the component asks for extra information.

@FromDate date

The date of the first day visible in the calendar.

@ToDate date

The date of the last day visible in the calendar.

Resultset: Extra information (optional)

Table count: repeated zero or one time

Row count: zero or more rows

Columns

ExtraInfoResourceID mandatory string

The Id value of the calendar resource for which the extra information should be displayed.

ExtraInfoCalendarDate mandatory datetime

Date for which the extra information should be displayed.

ExtraInfo optional string

Extra information to be displayed.

ExtraInfoBackgroundColor optional string

Background color for the extra information. See Colors.

IsHoliday optional bit

If 1 then the calendar day is a holiday. This will color the day of month number red.

CanDrop optional bit

Whether calendar items can be dropped on this day.

Default: Defaults to true.

SQL Call: Calendar items (mandatory)

Sql for retrieving the calendar items to display in the calendar.

May modify database: No

Parameters

@<resource-name> string

<resource-name> is the name of the first column in the resource' resultset.

@FromDate date

The date of the first day visible in the calendar.

@ToDate date

The date of the last day visible in the calendar.

Resultset: Calendar items

Table count: repeated exactly once

Row count: zero or more rows

Columns

<column with ordinal 1> mandatory string

The calendar item id. Used in {selecteditems} and by drag & drop.

CalendarItemTimeFrom mandatory datetime

Startdate and starttime for the calendar item.

CalendarItemTimeTo mandatory datetime

Enddate and endtime for the calendar item.

CalendarItemResourceID mandatory string

The Id value of the calendar resource for which the calendar item should be displayed.

CalendarItemHeading optional string

Heading of the calendar item. Mutually exclusive with CalendarItemHeadingHtml.

CalendarItemHeadingHtml optional string

Heading of the calendar item. Mutually exclusive with CalendarItemHeading.

CalendarItemHtml optional string

HTML to display in the calendar item. Mutually exclusive with CalendarItemText.

CalendarItemText optional string

Text to display in the calendar item. Mutually exclusive with CalendarItemHtml.

CalendarItemBackgroundColor optional string

Background color for the calendar item. See Colors.

CalendarItemShowCheckbox optional bit

Can be used to override the component setting when ShowCheckboxes = 1.

CanDrag optional bit

Whether this calendar item can be dragged.

Default: Defaults to false.

CanResize optional bit

Whether this calendar item can be resized.

Tooltip optional string

Tooltip of the calendar item. Mutually exclusive with TooltipHtml.

TooltipHtml optional string

Tooltip of the calendar item. Mutually exclusive with Tooltip.

Resultset: Background definitions

Table count: repeated exactly once

Row count: zero or more rows

Columns

CalendarBackgroundId mandatory any

Id that is used to reference this background in the usage call.

CalendarBackgroundColor mandatory string

Color of the background. See Colors.

CalendarBackgroundLabel optional string

Label displayed as a heading in the tooltip for the background.

CalendarBackgroundTooltip optional string

Tooltip body for the background.

Resultset: Background usage

Table count: repeated exactly once

Row count: zero or more rows

Columns

CalendarBackgroundId mandatory string

Reference to a definition in the background definitions table.

CalendarBackgroundDatetimeFrom mandatory datetime

Start date and start time for the calendar background.

CalendarBackgroundDatetimeTo mandatory datetime

End date an end time for the calendar background.

CalendarBackgroundResourceId mandatory string

The Id value of the calendar resource for which the background should be displayed.

SQL Call: Drag & drop

Called after every drag & drop operation.

May modify database: Yes

Parameters

@<ResourceName> string

<ResourceName> is the name of the selected resources.

@DragId string

The id of the calendar item.

@Drop<resource-name> string

Id of the resource the calendar item was moved to.

<resource-name> is the name of the first column in the resource's result set.

@DropDateTime datetime

The date and time the calendar item was moved to.

Resultset: Messages (optional)

Table count: repeated zero or one time

Row count: exactly one row

Columns

ADMIN_Force optional string

Confirmation message to show.

ADMIN_Message optional string

Message to show (preventing the move).

SQL Call: Resize

Called after every resize operation.

May modify database: No

Parameters

@<ResourceName> string

<ResourceName> is the name of the selected resources.

@EndDateTime datetime

The new end time of the calendar item or if the start was changed this contains the old end time.

@ResizeId string

The id of the calendar item.

@StartDateTime datetime

The new start time of the calendar item or if the end was changed this contains the old start time.

Resultset: Messages (optional)

Table count: repeated zero or one time

Row count: zero or one row

Columns

ADMIN_Force optional string

Confirmation message to show.

ADMIN_Message optional string

Message to show (preventing the move).

SQL Call: Validate parameters

Allows you to validate the SQL parameters before any other SQL is run in the component. This call is only made if the SQL is a stored procedure and Validate parameters is checked.

May modify database: No

Parameters

@Force bit

Set to 1 if the last call to validate parameters used admin_force and the user clicked OK in the OK/Cancel dialog.

@ValidateParams bit

Set to 1 when this call is made.

Resultset: Messages (optional)

Table count: repeated zero or one time

Row count: zero or one row

Columns

ADMIN_Force optional string

Message asking the end user to confirm their parameters.

ADMIN_Message optional string

Message explaining why the parameters are rejected.

InfoSQL

See the InfoSQL documentation for details.

Custom access control and logging

SQL Call: Custom access control and logging

Use this call to restrict which entries a user is allowed to view and edit, and to log which entries a user views.

Access to a menu item is normally controlled through functions and roles alone but some entities need more fine grained control. For example, a user may have access to the View Member menu item for normal members but not for members with a protected identity.

The menu items a user visits are always logged (in ADMINLogMenuItem) but for sensitive data you may need to log exactly what entries are viewed. Do the logging in this call as the common ways of viewing data (grid and InfoSQL) are not allowed to modify the database.

If you bind a scalar function instead of a stored procedure to this call then its name must end with '_GrantAccess'.

May modify database: Yes

Resultset: Access permissions

Return whether the user is allowed to visit the menu item with the current parameters.

Table count: repeated exactly once

Row count: exactly one row

Columns

GrantAccess mandatory bit

1 if the user is allowed to view the menu item, 0 if the user should not be allowed to view the menu item.

If 0 then an error will be logged as the user should not have been able to reach the menu item with the given parameters in the first place.

Querystring parameters

menuitemheading optional

String that replaces the menu item name when the menu item is loaded. It does not replace the name before that (like for example in the navigator). It is ignored if the menu item is displayed as a part in a multipart in which case the name can be set from the multipart procedure.

startdate optional

Date to display in calendar. Format must be: YYYY-MM-DD.

If omitted the calendar will start at todays' date.

Examples

Resources with time scale - Minimal example

CREATE OR ALTER PROCEDURE Example.Entity_ResourceCalendar
	@FromDate  date = NULL,
	@ToDate    date = NULL,
	@ExtraInfo bit = NULL,
	@Resources bit = NULL
AS
BEGIN
	IF @Resources = 1
	BEGIN
		SELECT
			RoomId,
			RoomName
		FROM
			Example.Room;

		SELECT
			'Room' AS ResourceLabel;

		RETURN;
	END;

	IF @ExtraInfo = 1
	BEGIN
		RETURN;
	END;

	SELECT
		RoomId AS CalendarItemResourceId,
		CalendarItemTimeFrom,
		CalendarItemTimeTo,
		CalendarItemHeading,
		CalendarItemText
	FROM
		Example.CalendarItems
	WHERE
		(CONVERT(date, CalendarItemTimeFrom) <= @ToDate) AND
		(CONVERT(date, CalendarItemTimeTo) >= @FromDate);
END;