Calendar

Displays a calendar or schedule.

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

Component mode: Weekdays

A calendar with weekdays as columns and no time scale.

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

Number of weeks
The number of weeks to display in the calendar.
Number of years after
The number of years to add to the year dropdown after the current year.
Number of years before
The number of years to add to the year dropdown before the current year.
Week number culture code
The culture code used to determine week numbering.
Weekday pattern
Which weekdays to display in calendar.

SQL

SQL Call: Retrieve resources (mandatory)

SQL for retrieving the resources for the calendar. All resources are displayed as dropdown resources on top of the calendar.

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 calendar days. The extra information is displayed directly below the calendar day 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
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 info. See Colors.

IsHoliday optional bit
If 1 then the calendar day is a holiday. This will color the calendar resource heading 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.
CalendarDate optional datetime
Date for the calendar item.

Exactly one of this and CalendarDateTime must be not null.
CalendarDateTime optional datetime
Date for the calendar item. Will also show the time part next to the item heading.

Exactly one of this and CalendarDate must be not null.
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.
Tooltip optional string
Tooltip of the calendar item. Mutually exclusive with TooltipHtml.
TooltipHtml optional string
Tooltip of the calendar item. Mutually exclusive with Tooltip.

SQL Call: Drag & drop

Called after every drag & drop operation.

May modify database: Yes

Parameters

@<ResourceName> string
<ResourceName> is the name of the first column in the resource resultset.
@DragId string
The id of the calendar item.
@DropDate date
The date 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: Validate parameters

Allows you to validate the parameters supplied by the user before any other SQL is run in the component. This call is only made if the component has visible parameters, 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

Weekdays - Minimal example

CREATE OR ALTER PROCEDURE Example.Entity_Calendar
	@FromDate  date = NULL,
	@ToDate    date = NULL,
	@ExtraInfo bit = NULL,
	@Resources bit = NULL
AS
BEGIN
	IF @Resources = 1
	BEGIN
		RETURN;
	END;

	IF @ExtraInfo = 1
	BEGIN
		RETURN;
	END;

	SELECT
		CalendarDate,
		CalendarItemHeading,
		CalendarItemText
	FROM
		Example.CalendarItems
	WHERE
		CONVERT(date, CalendarDate) BETWEEN @FromDate AND @ToDate;
END;