CalendarScript - Calendar Documentation: Administration

This section details each screen in the Administration Application.

Login Screens

Login

The Login screen is displayed when entering the Calendar Admin application. All user ID's are case-sensitive. When logging out of the Admin Application, there is also a 'View Calendar' link to the calendar that you were just editing.

Your user ID must have permissions to perform at least one operation on at least one calendar to login to the Calendar Admin application.

Select Calendar

The Select Calendar screen is displayed after a user logs in successfully. This selects the 'context' that the Calendar Admin application operate under. All calendar-specific operations will affect this calendar. You can change which calendar is being modifed at any time by choosing the 'Change Calendar' link from the menu.

The list of calendars will only include those that your user ID has permission to operate on.

Main Menu

The Main screen includes links to all the functions of the Calendar Admin application. Only actions which your user ID has permission to perform are included in the list.

Events

Add Event

To add an event, enter values for all fields in the Add Event screen. These fields and their input types are configured via the Customize Event Fields screen. Click 'Save And Continue' to save the event and continue to the 'Schedule Event' screen.

Schedule Event

The Schedule Event screen handles scheduling an event's time, date, and recurring schedule. It is the screen with the most number of options and can therefore be confusing at first glance. However, using it is common sense.

There are two modes of the Schedule Event screen - Static Schedule and Recurring Schedule. The Static screen allows you to schedule an event on any number of individual days, or on every day in a date range (between two dates). The Recurring screen allows you to schedule an event that repeats on a regular basis. To switch between these two modes, click the 'Recurring Schedule' button on the Static screen, or the 'Standard Schedule Options' button on the Recurring screen.

Event Time (common to both screens)
Events are either sceduled as 'All Day', meaning they have no start and end times during the day (used for Holidays, for example), or given a start time and optionally an end time.

To schedule an All Day event, click the All Day checkbox. This will clear any values that might have existed in the time entry fields. This event will be displayed in the calendar without any time next to it.

To set the time for an event, enter the values into the input fields. The time input fields can be configured as either 12-hour format, using AM/PM, or 24-hour format. This is a setting in the Calendar Admin application. If a start time is entered and no end time is entered, the end time is automatically set to be the same time as the start time. This is an indication to the calendar program that this event has no specified end time. In the calendar display, this will be shown as the event occurring at the specified time but without a time range.

The end time must always be after the start time. Also, the two times must occur on the same day. That is, you cannot schedule an event to start at 11:00pm and end at 2:00am the next day. This type of schedule is currently not supported.

Static Date Entry
There are two options for schedule a date on the static screen. You may either select individual dates when this event will occur, or a date range during which the event will occur every day. By default, Individual Dates is selected.

Dates may be entered into the text box by hand, or the popup calendar may be used to select dates. If entering dates manually, separate them by commas and use the format specified above the input boxes. This date format is a setting in the configuration of the calendar and may be changed in the Calendar Admin application. To use the popup calendar utility, click on the '>' button. This will open a small new window containing a calendar. Click on the dates on which this event will occur. After clicking a date, the calendar will re-draw with the selected date having a yellow background. You can click on the date again to un-select that date. You can easily select today's date by clicking the 'Today' link at the bottom. To close the window, either cloes the browser window manually, or click anywhere on the main Schedule Event screen to close it automatically.

To enter a date range for the event, enter begin and end dates in the format specified above. You may use the popup calendar utility to select either of these dates also. The dates selected are inclusive, meaning the event will occur on the starting and ending dates as well as all dates between.

Recurring Schedule Entry
A recurring event can either repeat forever or repeat only during a given date range. If the 'Repeat only between these dates' option is checked, you must supply a Start and End date. The event will only repeat on matching dates between these two dates (including on the dates themselves). Without this option checked, the event will appear with the repeating schedule forever, on any calendar year/month viewed.

It is always recommended to supply a Start and End date for events, for performance reasons. A number of recurring events which have no Start and End dates may cause the calendar to slow down, because the schedules of these events need to be re-calculated with every request. It is always recommended that you put in a date range for recurring events, and this option is selected by default.

There are a number of options available for a recurring event schedule.

Weekly : Select one or more days of the week
Monthly :
- Select any individual date of the month. If a date selected is higher than the total days in any given month, the event will not occur on those months.
- Select a relative day of the month by selecting either First, Second, Third, Fourth, or Last and then either 'Day' or a specific day of the week.
Yearly :
- Select a specific month and date that this event occurs on every year
- Select a relative schedule in the same way as the Monthly option, but also select which month it applies to every year.

Changing any option will automatically select the corresponding Weekly/Monthly/Yearly option and sub-option, if it applies.

Edit/Delete Events

The Edit/Delete Events screen displays events and their schedules so you can Edit, Delete, or Reschedule them. By default, the screen displays all events for the current month. You can view events occurring in other months by using the drop-down menus for month and year and then clicking 'Go', or by using the << and >> links to go back or forward one month. You can also do a simple search for events by entering a word into the text field and clicking 'Search'. This search matches the text in any field of the event and cannot be restricted to only certain fields.

When events for the month are being displayed, every start date and time during the month is displayed, as well as the title. An asterisk is displayed to signify that the event has a recurring schedule.

When search results are displayed, the ID of the event (as stored in the database), the date of the next occurrence, and the event title are shown.

Clicking the 'Delete' button for any event will delete it from the database, after accepting the confirmation dialog box.

Clicking 'Edit' takes you to the Edit Event screen, where you can change the details of the event. From this screen you can also navigation to the Schedule Event screen to modify its schedule, or uncheck the 'Modify event schedule now' checkbox to return to the Edit/Delete Events screen without rescheduling the event. Click 'Schedule' to change the schedule of the event.

When deleting, editing, or rescheduling recurring events, all occurrences of the event will be changed. Changing only one instance of a recurring event is currently not supported.

Customize Event Fields

The 'Customize Event Fields' screen lets you modifying the data fields that define an event. There are a number of fields pre-defined, some of which are not editable, and others which can cannot be deleted and only partially edited.

To add a new field, click the 'Add New Field' button at the top of the screen. To edit or delete an existing field, click the Edit or Delete button next to the field. Adding or Editing a field takes you to the Add/Edit Field screen.

At the bottom of the screen you can change the display order of the fields. This affects the order that they are displayed in for the event details screen as well as the Add Event screen. To move an option up or down, highlight it and click the 'Up' or 'Down' button. To save the changes, click the 'Save Order' button.

Add/Edit Field

This screen defines a field for either the event database or the user database definitions.

Display Name: The text that will be displayed next to the value or form input for the field.
Unique Field ID: This is the column name that the field is stored under in the database. It is automatically populated with a suggested value based on the value entered for Display Name. This value is only used internally and never displayed. Each field must have a unique value.
Description: The full description of the field.
Required: Whether or not a value is required for this field in the Add form.
Display in Add Form: Whether or not to display this field in the Add form.
Display in details: Whether or not the value of this field should be displayed in the Event Details.
Searchable: Whether or not the field will appear in the criteria in the Search screen.
Form Input Properties: These options control how the field will appear in the Add form, and what type of input field it will be. Not all options apply to all types of inputs.
- Input Type: The type of HTML form input to represent the field.
- Default Value: For text or textarea types, the value that should be filled into the input by default.
- Size: For text or password types, the size of the input box.
- Maxlength: For text or password types, the maximum number of characters allowed in the input box.
- Rows: For textarea types, the number of rows of the input area.
- Cols: For textarea types, the number of columns of the input area.
- Value if checked: For checkbox types, the value to store in the database (and the value which will be displayed in the details) if the checkbox is checked.
- Checked as default: For checkbox types, whether or not the checkbox should be checked by default.
Select Box: For selectbox types, this set of controls defines the options that will appear in the option list. Each option has two values - the display text and the value of option. The display text is what will actually appear in the drop-down list as a choice. The option value is what will be stored in the database and will be displayed in the details for the event. These are often the same.
- Adding an option: Enter a value for the 'Display Text' and 'Option Value' and then click the 'Add' button. This will add it to the list of options under 'Current Options'.
- Removing an option: Select an option and click 'Remove'. It will be removed from the 'Current Options' list and its text and value will be put into the boxes on the left.
- Editing an option: To edit an option, remove it, modify the values, and add it again.
- Ordering options: The items will appear in the drop-down list in the order that they appear on the screen here. To move an option up or down, select it and click the 'Move Up' or 'Move Down' button to the right.
- Selecting a default value: By default, the first option in the list will be selected. If you would like a different option to be selected by default, select it and click 'Make Default'.

When you are finished defining the field, click 'Save' to update the database and instantly activate the field.

Approve Pending Events

If a user (such as the anonymous user) has privileges to add an event, but not automatically approve their own events, then any events they add will be added to a 'pending' list. A user with the 'Approve Pending Events' privilege can then login to approve the events and make them active.

Each event is shown with its Title, Description, Author, ID, and Schedule. To the left is the options of 'No Action', 'Approve' or 'Reject'. Select the action for each event in the list and click 'Save' to save all of them. Anything approved or rejected will be removed from the list, and the others will remain in the pending list.

To edit an event before approving it, click the Edit button. This will take you to the Edit Event screen and also allow you to proceed to the Schedule Event screen. Once finished editing and saving the event, you will automatically be returned to the Approve Pending Events screen.

Import Events

The Import Events screen allows you to load a number of events, their details, and their schedules all in one step. It is useful for upgrading from a previous version of the program, or for loading events from another application.

The format of events to import must be in a delimited text file. That is, each part of the event's details and schedule are separate by a character such as | or comma. To import the contents of this file, you need to provide the following 4 things:

The format row. This is a row that defines which fields appear in which order in your file. This is required so that the fields can be imported and mapped to the correct fields in the CalendarScript application. It may or may have a # as the first character, and should contain fields names separated by the delimiter.
The text of the file. This just consists of a number of lines, one for each event. The lines should be separated by the delimiter and have the value for each field in the same order as the header row.
The delimiter used to separate fields, both in the header row and the text
Field Mappings. This is a list of all the event fields which you have defined in your calendar, as well as schedule fields. When you change the format row at the top, this will populate the drop-down boxes next to your event fields. Then pick which field from the import file should be mapped to which field in the CalendarScript database. The date field is required, but the times are optional. Iif time fields are not mapped, then each imported event will become an 'all day' event.

Once this is complete, click 'Import' and all the events will be loaded into the database.

User Admin

Change Your Password

Every user except the anonymous user has the ability to change their password. simply type in the old password and the new password twice and save.

Add User

Add user enables you to create additional users for the calendar application, and then assign privileges to that ID.

The fields available to fill in by default are Username, Password, and Name, which are all required. You may add additional fields and customize these fields through the Customize User Database screen.

If the 'Edit permissions for this user' box is checked, you will be taken to the permissions screen for this user once it is added to the database.

Edit/Delete Users

This screen lists all current users in the system, and allows you to edit and delete users. The 'Administrator' and 'anonymous' users may not be deleted.

Clicking on the 'Edit' button will take you to the Edit User screen, which is identical to the Add User screen. The Username field may not be changed, but all others may. If you wish to change the Username of a user, you must delete their user and add a new one.

Modify User Permissions

There are a number of specific permissions that may be granted to users of the system to enable them to perform these actions of the Calendar Admin application. This screens allows you to grant those permissions to users.

When the screen first comes up, it has a list of calendars and users on the system. Select a calendar, then select a user whose permissions you wish to edit. Click 'View Permissions' to load all the current permissions for that user.

Permissions may not be change for 'Administrator' because this account always has full permissions on all calendars in the system. The 'Anonymous User' account is used for anyone viewing the calendar without logging in. So, in order for the 'Add Event' link to appear on the calendar for the general public, for example, you will need to grant the 'Add Event' permission to 'Anonymous User'.

The list of permissions is divided into two categories - Global Permissions and Specific Permissions. The Global Permission section grants permission to access screens and functions of the Calendar Admin application which are common among all calendars. These options are as follows:

Add User
Edit Delete Users
Modify Global Permissions: This allows the user to edit this group of permissions itself, which would allow them to grant the 'Add User' permission to other users, for example.
Customize User Database: Customize the fields that define the user databasse.
Manage Calendars: Add/Edit/Delete calendars from the system.
Feedback/Support: Access the Feedback and Support screen.

The second set of permissions are the 'Specific Permissions'. These allow you to grant permissions to a specific user for a specific calendar, or for all users for a specific calendar, or for any calendar for a specific user. These separate categories are divided into three columns, and each individual permission exists in each column.

A user has permissions to perform a given action if a check appears in any of the three columns. For example, the 'Add event' permission might be checked in the second column, meaning all users for this calendar are able to perform this action. No matter which user you view permissions for, this will always be checked, meaning the user will be able to perform this action.

These three different levels of granting permissions allow the Administrator to easily give everyone access to some functions, yet restrict other actions to only specific users. It also allows a user to have the 'Add Event' permission on every calendar in the system, but only be able to change settings on one of the calendars, for example. The different permissions are as follows:

View Calendar: This option only applies if you have the 'Require Login' option turned on in the Calendar Settings screen. If enabled, only users who have the 'View Calendar' permission will be able to login and view the calendar.
Add Event: Add an event into the system and schedule it, pending approval.
Edit/Delete Events: The ability to edit and delete any event in the calendar, no matter who entered it.
Edit/Delete Own Events: The ability to edit and delete only the events that this user added himself.
Approve Pending Events: The ability to approve any pending events entered by people with the 'Add Event' permission.
Automatically approve own events: When adding an event, it will not be marked as pending, but will instead be immediately added to the calendar.
Customize Event Fields: Change the fields that define an event in the database for this calendar.
Calendar Permissions: Modify these permissions for other users. When this option is enabled but 'Modify Global Permissions' is not, then this user will not be able to assign permissions for third column. These options will not be available.
Calendar Settings: Modify the settings and configuration of the calendar.

Customize User Database

This screen functions the same as the 'Customize Event Fields' screen, except that it modifies the fields that exist for a user in the system.

Calendar Options

Current Calendar Settings

This is where all the configuration otions for a calendar can be customized. The options on this screen only apply to the currently-selected calendar.

Display Template Type: If there are multiple template styles defined in the templates directory of the application, this select box allows you select which templates style will be used to display this calendar.
Require Login: If you want your calendar to be password-protected, enable this option. Then before anyone can load the calendar display, they will be forced to login and must have 'View Calendar' permissions on the calendar they are trying to view.
Weekday Names: Change the names and abbreviations used for weekdays in the calendar, for language translation or any other reason that you wish to use different names. Day name 1 should always be used for the translation of 'Sunday' regardless of which Week Start Day you select.
Week Start Day: Many countries display their calendar grid beginning with a day other than Sunday. Change this option to begin the calendar on a different day. The number matches the day name above.
Month Names: Change the names and abbreviations used for months in the calendar.
Date Format: Choose the date format that will be used to format dates throughout the calendar. This allows you to change to the European format of MM/dd/yyyy, for example, rather than the default American format. You can also use the other format options if you wish to use a custom format.
Time Format: Choose between 12-hour and 24-hour formats.
Allow HTML: If you wish to put HTML into your event descriptions or other fields, this option must be enabled. However, if the HTML entered is incorrect or incomplete, it may cause the application to display incorrectly when the event is shown. For this reason, this option is turned off by default.
If HTML tags are used when this option is turned off, and then the option is turned on, it will not affect events entered previously. They will still not display the HTML. Likewise, if HTML tags are entered when this option is on, and then it is turned off, the HTML will still be displayed. This option only affects the event when it is actually added.
Auto-Link: When events are displayed, any text beginning with http:// can be assumed to be a URL, and the program can automatically hyperlink the text to the URL. This way links can be included in events without turning on the 'Allow HTML' option.
The TARGET attribute is added to links added by the Auto-Link option. The default value is "_blank" which causes all links to open up in a new popup window. If you would like links to open up in the same window and replace the calendar display, set this value to be empty.
Time Zone Offset: If your web server is physically located in a different timezone than your or your users, the calendar display may not be correct. For example, if it is Monday at 10:00pm for you on the west coast, but your web site is hosted by a company on the east coast, thenit will be 1:00am there, and the calendar will display the current day as being Tuesday. You can adjust for this by setting the timezone offset to add or substract a certain number of hours from the web server's clock. The text above the select box displays both the web server's time and your local computer's time so you can correctly configure the difference.

Global Options

Manage Calendars

The calendar program allows you to create multiple calendars all run through the same script, and this is the screen to add, edit, and delete those calendars. The main screen contains the list of calendars, and the Edit/Delete buttons. Whichever calendar is currently selected as the 'Default Calendar' in the Admin Interface screen cannot be deleted.

To add a new calendar to the system, click the 'Add Calendar' button. This brings up the screen to add the details for the calendar.

Key: This is the unique ID of the calendar itself This will be the name of the directory that will hold the files, as well as the name used to load the calendar from the display. For example, if you give a key of "test" then you would load this calendar by loading /cgi-bin/calendar.pl?calendar=test in your browser.
Name: The display name of the calendar.
Description: The calendar's description.
Copy Calendar: You can make an exact copy of another calendar, including its events and configuration, by selecting one from the list. Permissions are not copied. Leave this blank to create a calendar with the default options and no events.
Give Full Permissions To: When creating a new calendar, there is often one user of the system who will be the administrator of this calendar. You can select a user from the select list who should be setup with full permissions on this specific calendar when it is created.

Admin Interface

This screen allows you select several high-level options, and customize the colors of the Calendar Admin screens.

Admin Template Language: If multiple language directories exist for the Admin templates, you can select which language to use.
Default Calendar To Display: When the calendar display is loaded without specifying which calendar to display, this defines which calendar is loaded.
Color options: These options change the display colors for screens in the Admin Interface. Either type in a valid HTML hex code, or you can use the color picker popup window. Click the 'Pick...' link and a popup window will give a grid of the web-safe color palette. Click a color to select it.
If you have a current browser version, color selections will be instantly visible when you change a value. This way you can change values into you find a color combination that you like, and then save it.
Saving color changes takes effect immediately, and when the screen re-draws the new colors will be used.

Feedback/Support

This screen provides a number of options for obtaining support information, providing feedback, and checking for updates.