A5 JQCalendar Installation, Use and Trouble Shooting
Last updated May 30, 2013
The most current information is located at http://www.a5customsolutions.com/jqcalendar_docs.html
There are instructional videos located at http://www.a5customsolutions.com/JQCalendar_Videos.html
Initial Installation
Install using the supplied installer. This will install a new A5 workspace/database. Open the workspace and the autoexec script will prompt you to allow it to copy the necessary files to the live preview folder on your machine. If using A5 version 11 or greater it will also install the User Defined Component files as well.
Create the Calendar Table
You can add any extra columns you might need in your application, the calendar will ignore them.
Make sure the default field values match the examples
To use DBF see the example jqcalendar.dbf file located in the control panel.
NOTE: The calendar will return an ID of zero for new events. That means you will need to ensure your table's auto increment is set to start at 1. (DBF will start at zero by default.)
You will probably want to have indexes, at a minimum, on the start and end dates and the groupid.
MySQL Table format:
CREATE TABLE `jqcalendar` (
`Id` int(11) NOT NULL AUTO_INCREMENT,
`Subject` varchar(200) NOT NULL ,
`Location` varchar(200) DEFAULT NULL,
`Description` longtext,
`StartTime` datetime NOT NULL,
`EndTime` datetime NOT NULL,
`IsAllDayEvent` smallint(2) NOT NULL DEFAULT '0',
`Color` varchar(200) DEFAULT '0',
`RecurringRule` varchar(200) DEFAULT NULL,
`Multi_Day` smallint(1) DEFAULT '0',
`Editable` smallint(1) DEFAULT '1',
`Attendees` varchar(200) DEFAULT NULL,
`Recurring` smallint(1) DEFAULT '0',
`GroupId` int(11) DEFAULT NULL,
`GroupName` varchar(200) DEFAULT NULL,
PRIMARY KEY (`Id`)
) ENGINE=InnoDB AUTO_INCREMENT= 1
SQL Server Table format: >>>Set the groupid, and Multi_Day to default to zero. Set Editable to default of 1.
CREATE TABLE [dbo].[jqcalendar](
[Id] [int] IDENTITY(1,1) NOT NULL,
[Subject] [varchar](200) NOT NULL,
[Location] [varchar](200) NULL,
[Description] [varchar](255) NULL,
[StartTime] [datetime] NULL,
[EndTime] [datetime] NULL,
[IsAllDayEvent] [smallint] NULL,
[Color] [varchar](50) NULL,
[RecurringRule] [varchar](255) NULL,
[Multi_Day] [smallint] NULL,
[Editable] [smallint] NULL,
[Attendees] [varchar](200) NULL,
[Recurring] [smallint] NULL,
[GroupId] [int] NULL,
[GroupName][varchar](200) NULL,
CONSTRAINT [PK_jqcalendar] PRIMARY KEY CLUSTERED
( [id] ASC)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF,
ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY]
GO
SET ANSI_PADDING OFF
GO
ALTER TABLE [dbo].[jqcalendar] ADD CONSTRAINT [DF_jqcalendar_Multi_Day] DEFAULT ((0)) FOR [Multi_Day]
GO
ALTER TABLE [dbo].[jqcalendar] ADD CONSTRAINT [DF_jqcalendar_Editable] DEFAULT ((1)) FOR [Editable]
GO
ALTER TABLE [dbo].[jqcalendar] ADD CONSTRAINT [DF_jqcalendar_GroupId] DEFAULT ((0)) FOR [GroupId]
GO
Calendar Table Custom Field Mapping
The first column must be an auto-increment column and be mapped to the ID column in the table mapping properties.
Your table must have a column for each of the mapped columns.
Your table can have additional columns, in any order, as long as the first is defined as explained above.
You can have separate date and time columns or use date-time columns. Set the mapping accordingly.
Create your connection string (SQL tables)
Create an AlphaDAO named connection string for the calendar table/view you just created.
Dynamic connection strings are supported.
Explicit connections strings are supported starting with version 4.53.
A5 Version 11 Users Only - Uses A5's new Dialog2 component for detailed edits/inserts
Edit the "jqcal_recurring" dialog component by selecting "Data Binding" and then choose "Bind the controls on your Dialog to fields in one or more....." From the pop up dialog choose "Specify Tables". On the next pop up select your calendar table that you created earlier. Click "OK" and then choose "Bind Dialog Controls to Table Fields" from the pop up dialog. Bind your calendar table fields to the dialogs fields using the same mapping as the calendar. The fields at the bottom that are set to unbound and not updateable are used for the recurring events and should remain as is. If you've added any additional fields to the calendar table and dialog you can map them accordingly. Note that any added fields are not added to recurring events. Next, click "OK", "OK" and then save the dialog component. If your local date format is not MM/dd/YYYY then you need to edit the default date format in the properties pane to your date format. This controls how the dates are submitted to the database. A wrong setting here will send data to the table in a date you did not expect. NOTE: The example dialog has code in the onDialogInitialize server-side event the allows for automatic detection of the date and time formats.
Publish the "jqcal_recurring.a5w" page to the live preview folder. Do this by double clicking the page in the "Web Projects Control Panel" and then use the lightning bolt icon on the toolbar to execute the page. We need to do this because the calendar uses this a5w page to show the dialog component for adding/editing detailed events. Alpha does not know the calendar will need this page so we have to make sure it is available.
A5 Version 10 Users Only - Uses an HTML form or A5 Grid component for detailed edits/inserts.
Open the "jqcal_V10_template" custom component and select the "Arguments" smart field icon from the properties section. Enter your named connection, or DBF if using a DBF calendar table, in the "sqlconnection", "Argument Binding" "Default value" field. Enter your calendar table name in the "Default value" field of of the "sqltable" section. Leave the rest of the arguments as is until your sure you have everything working. Save the component. At this point you should be able to run it in the live preview tab. Again, DON'T choose working preview or you'll most likely crash Alpha. It is recommended that you only use the live preview tab to initially open the component. Do all your testing by launching the component in your browser by clicking on the browser icon at the bottom of the live preview window.
You can use a grid placed on an a5w page for the detailed inserts and edits as well. See the video for more information on how to set it up.
Note that V10 does not support the option of running in an Iframe.
If at this point you don't have a working calendar, refer to the Troubleshooting section of this document.
Installing as a User Defined Custom Component - A5 Version 11 Users Only
The installer will attempt to install the UDC files for you. To manually copy the necessary files, if needed, follow the instructions below.
To install as a "User Defined Custom Component" you will need to unzip the "JqCalendar_User_Defined_Component.zip" file into your A5 directory where these are stored. The UDC zip file was installed into the web projects folder during the installation routine.
To locate the UDC directory, from the "Web Projects Control Panel" choose the "Edit" menu, "Advanced", "Open folder where User Defined Components are Registered."
Once the folder is copied, restart Alpha, you will then see a new component type "JQCalendar" in the list of available components when you define a new web component.
Please note that in your own applications you will still need to have the "jqcal_datafeed.a5w" page, the a5w page you are using for the calendar detail add/edits, the "jqcalendar.aex" and the "jqcalcss" and "jqcalsrc" folders in the "Web Projects Control Panel" of each application you use it in. You will also have to remember to add "jqcalendar.aex" to the "Project Properties", "Aex files", "File list" to ensure the aex gets loaded into memory. As of version 4.53 this is all done automatically in the onsave event of the JQCalendar's builder.
The component builder's property sheet has help section at the bottom for each of the options.
Using the custom components in your own web project.
If you're using V11+ you'll need to either create a new dialog component, using the provided template as an example of the support code needed, and put it on a page for the detail edit/inserts or use the samples and edit them to match your projects needs. See the example page for important files that need to load with the page and are defined in the "<head>" section of the page. Don't forget to set up data binding.
The User Defined Component (V11+ users) will automatically install the necessary support files in the web project folder for you when you save a component. If for some reason it does not succeed, follow the instructions below. This should only need to be done if you have a non standard installation. For V10 users follow the instructions below.
V10.5 users: To install and use in your own web project you will need to copy files over to your web project folder. In A5 V11 you can easily do this by clicking the folder icon located on the web projects control panel toolbar at the far right side of the window. This will open up a windows explorer window where you can select the files to copy.
The files needed are: The jqcalcss, and jqcalsrc folders, the jqcalendar.aex file, the jqcal_datafeed.a5w page and the custom component of your choice. You'll also need the jqcal_edit.a5w page or your own page that will handle the detailed edits and inserts.
Updating JQCalendar
Calendar Options - Most of the properties are defined as arguments. Argument definitions for those defined as such in the component properties pane can be set to "cookies" or "page variables" or "session variables" in addition to the default of "set value at runtime". A5 V11 users using the "User Defined Component" option should set these values in the component's property sheet. They are still available in the arguments section if you need to set them to a variable instead of the default. All of the options for User Defined Components are not listed here. There is a help section at the bottom of the property sheet in the component builder that describes each option in the User Defined Component.
SqlConnection - Required - your named connection without the ::NAME:: prefix as in "connection1"(no quotes). IF using DBF enter "DBF" (no quotes).
SqlTable - Required - name of your calendar table.
DefaultView - Optional - Choice of day, week, workweek, or month. Will default to week if nothing provided
StartDayofWeek - Required - number value of day to start calendar on, 0 for Sunday, 1 for Monday etc.
ReadOnly - Required - false to allow edits, true to prevent edits. If you use this, then also set the CanDrag option to false as well.
CanDrag - Required - true to allow drag and drop, false to prevent. Can still edit with pop up window unless you also set the ReadOnly option to true as well.
CalFilter1 through CalFilter3 - Optional - filtering criteria Example: You have a field in your calendar table called group. Setting CalFilter1 to group = "Employees" will add that clause to the where clause when the calendar loads and refreshes.
StartDate - Optional - Starting day for the calendar to load. Must be in MM/dd/yyyy format as this gets loaded into a javascript date object. If blank or not a valid javascript date it will try to default to the current date. Weird dates may give weird results.
EditWindowHeight - Required - sets the height (in pixels) of the model window div that opens to add or edit calendar details
EditWindowWidth - Required - see above
EditWindowPage - Required -URL of the page that contains the form or dialog component to add/edit calendar details.
EditWindowContainer - A5 Message Box, DIV - Default = A5 Message Box - The container used for displaying the Edit window page. NOTE: If using a DIV, sizing is limited to px, pt, in, cm, and mm only.
CalWindowHeight - Optional - Number in pixels of container window for calendar, if false or not a valid number, uses size of parent window. Useful for sizing window for use in Iframes.
GroupID - Required - Numeric value. This is the data that will get written to the groupid field of the calendar table.
GroupList - Required - comma delimited list of numeric groupids to show, or all for all groupids. This controls whose events are displayed. To show only Joe's events and Joe has a GroupID of 1 then use 1 here. To show Joe and Mary, where Mary has a GroupID of 2 use 1,2 etc.
CalendarTitle - Optional - Default = A5 JQCalendar - Text to display in the calendar's title bar.
SlotHeight - Required - Default = 42 - Size of the hour slots in the day and week view in pixels. A minimum of 24 is accepted. Multiples of 42 work best for all time slots. If you see unusual results when dragging or single clicking on the calendar, use a multiple of 42.
StartHour - Required - Default = 0 - Start hour for day and week views in 24 hour time format. Must be less than EndHour.
EndHour - Required - Default = 24 - End hour for day and week views in 24 hour time format. Must be greater than StartHour
PopUpBubble - Required - true or false - Default = true - Show pop up bubble for existing events when clicked.
PopUpEditBubble - Required - true or false -Default = true - Show pop up bubble for new events when using a mouse drag/click to create them.
TimeSlotMinutes - Required - Default 15 - Day and Week calendar time divisions in minutes. Allowed values: 5, 10, 15, 30 Note: Smaller values require higher SlotHeight values to ensure there are enough divisions (pixels) to get the desired results.
OneClickFactor - Required - Default 1 - Sets the default time of a "One Click" event on day/week/workweek views. 1 = one hour. Any number can be used here but the results will vary depending on the value that is set in the TimeSlotMinutes argument. With a default TimeSlotMinutes of 15, .5 will yield 1/2 hour, .25 yields 1/4 hour, 1.25 yields 1 1/4 hours and so on. With TimeSlotMinutes set to 10, .166 will yield 10 minutes, .332 will yield 20 minutes, .5 will yield 1/2 hour and so on.
ShowAddNewButton - Optional - true or false - Default = true - Show or hide the "NewEvent" button on the calendar.
ShowWorkWeekButton - Optional - true or false - Default = true - Show or hide the "WorkWeek" button on the calendar.
ShowWeekButton - Optional - true or false - Default = true - Show or hide the "Week" button on the calendar.
ShowDayButton - Optional - true or false - Default = true - Show or hide the "Day" button on the calendar.
ShowMonthButton - Optional - true or false - Default = true - Show or hide the "Month" button on the calendar.
ShowSheduleButton - true or false - Show the "Schedule View" button on the calendar. Schedule view will only show events that have a value in the Resource/Groupname column that match one of the list of Resources/Groupnames defined in the Groups/Resources List property below.
ResourceNameTitle ( Schedule Button text and title) - Sets the "Schedule View" button's text and title that is displayed on the calendar.
Resources (Groups/Resources List) - A comma separated, "double quoted", list of Groups or Resources. The items in this list are what are shown on the "schedule view" of the calendar and will be inserted/updated to the calendar table for any events created/edited while in the "schedule view". ONLY events that have a matching entry in the calendar table's Resource/Groupname column will be shown in the "schedule view".
ShowCustomButton (Show Next xx Days (Custom View) Button) - true or false - Show the "Custom View" button on the calendar. The custom view shows the next xx days. xx is defined below in the "Days to Show in Custom View" property.
DaysToShow (Days to Show in Custom View) - Numeric number of days to display for the "Next xx Days" view.
Sequence - Optional - Used for postgreSQL sequence if needed.
Language - Required - Default = US - Sets the language file to use. Included options are US (English with mm/dd/yyyy date format), FR (French), IT (Italian), HK (Chinese), CA (Canada - English with dd/mm/yyyy date format) - See examples to add your own files. You can also alter the existing language files to suit your needs.
TimeFormat - Required - 12 or 24 - Default = 12 - Sets the time format to 12 or 24 hours.
pop upWindowPage - User Defined,jQuery Dialog,A5 Message Box,NONE -Set to NONE to disable the pop up. Determines what is displayed when the "Subject" hyperlink is clicked in the popup bubble, or when read only events are clicked. Styling for the jQuery UI dialog is controlled either by the jQuery UI style selected in the Web Project Properties, Run-time Properties, CSS Libraries, jQuery CSS property. Or by specifying a css file in the components css linked files property. "Cupertino" blends well with the default calendar CSS and is set in CSS properties as a default. The A5 Message Box will be styled to the calendar's component style.
UserDefinedPopUp - Specify an .a5w or .html page for the user defined option. The user defined page is called with the Calendar event's ID, Start, End, Title, and GroupID parameters in the GET query string..
UserDefinedPopUpContainer - A5 Message Box or DIV - Default = A5 Message Box - The container used for displaying the Pop UP data. NOTE: If using DIV, sizing is limited to px, pt, in, cm, and mm only.
poupWindowPageHeight - Default = 350px - Height size in css units (px,in,cm, etc.) of "User Defined" PopUpWindow for read only events and popup bubble "Subject" hyperlink.
popupWindowPageWidth - Default = 500px - Width size in css units (px,in,cm, etc.) of "User Defined" PopUpWindow for read only events and popup bubble "Subject" hyperlink.
ReadOnlyCalendars - Optional - Comma delimited list of groupids to load as read only. Any groupids added here will cause events with that groupid to load as a read only event.
DragRecurringEvents - true or false - True to allow drag and drop edits of recurring events, false to prevent. Can still edit with popup window unless you also set the ReadOnly option to true as well.
ScrollDescription - true or false - Add Scrolling (auto Y scroll bar) to the calendar table's description contents in the Day/Week/WorkWeek's events. CAUTION: Set the can drag option to false when using this option.
Recurring Events - Only supported with UserDefineComponets (V11+) based on SQL back ends. Sorry, there are no plans for V10 or DBF support.
Calendar Color Key
The calendar has 22 colors available for the color of the events. The default, if the color field in the calendar table is null is grey. Thanks goes to Scott Moore for creating the number to color key shown below.
0 = Grey
1 = Light Red
2 = Pink
3 = Light Purple
4 = Purple
5 = Light Blue
6 = Pale Blue
7 = Aqua Green
8 = Light Green
9 = Bright Green
10 = Lime Green
11 = Yellow Green
12 = Brown Yellow
13 = Orange Yellow
14 = Light Orange
15 = Light Grey/Pink
16 = Purple/Grey
17 = Cool Grey
18 = Cool Blue
19 = Cool Green
20 = Tan
21 = Light Brown
Trouble Shooting
When I open the component I get a "Fatal error: oninitialRender render event not found." message - This error means that Alpha is not finding one of the jqcalendar functions. They are all in the jqcalendar.aex file. Ensure the "jqcalendar.aex" file is in the live preview folder, the Web Projects Control Panel, and also listed in the Project Properties aex files list. This file must be published to your server during publishing.
I'm getting a bunch of javascript error messages when I try to run the calendar in live preview - This happens when the files in the jqcalsrc or jqcalcss are not available. Ensure these folders are in the live preview folder and in the Web Projects Control Panel.
I get a "Sorry, could not load your data" error. -Open the component in Firefox with Firebug enabled. Look at the console and open the "Post" and check the response tab for clues. Most likely your connection string or table is incorrect in the argument properties of the component. As of version 4.0 most error messages are now shown in a jQuery dialog on the calendar.
I get an error message when I open in live preview, but if I click yes to continue to run scripts the calendar loads fine. -Launch in your browser and you won't see these. They don't happen when published.
When I open an event to edit it with a dialog2 page I get an error "Error executing onDialogExecute event: Error 1287........." -You don't have your data binding correctly set up for the dialog component. Check the connection string area.
When I save an event in live preview using the dialog component I get an error "'JQCAL_EDIT_DlgObj' is undefined" -Another live preview issue. Doesn't happen when published and doesn't happen if you run the component in your browser. Answer yes and the data will save fine.
I created events but now I can't move or edit them. - You don't have the "editable" field in your calendar table set to default to 1, or you've changed the dialog component to insert a default of 0. Check you calendar table to see what is getting written to the database.
I'm trying to use a calendar in a tabbed_ui, it is running in an Iframe but the edit window is not selectable when opened. - You need to have the jqcalcss/dailog.css (note the spelling) link defined in the tabbed_ui properties.
I'm trying to use the calendar (set to run in an Iframe) from a button on a grid but when I open it and attempt to do a detail edit the dialog that opens in not in focus and not selectable. - You need to have the jqcalcss/dailog.css (note the spelling) link defined in the grid's properties.
My first entry in the calendar is not displaying the correct date when I view it with the dialog2 component. - See the note above about creating tables and how the autoinc ID field must start at greater than zero.
I'm getting and error when trying to set the calendar to run in an IFrame under Alpha Five V10. - This is a known issue. Iframes are not supported in V10. To use the calendar in a Tabbed_UI or other component put the calendar component on an a5w page and put the page in the Tabbed_UI.
I'm trying to use the Calfilter options but I'm getting an error. - Make sure you use either single quotes, or escape your double quotes in your expression.
I'd like to have a title on the web page other than "Custom Component". How do I do that? - In the calendar component's client side OnItializeComplete event add the following javascipt: window.parent.document.title = "Your Calendar page Title"
When tyring to use the iCal export feature in a browser without cookies enabled I get an error message. - Cookies are required for the calendar's iCal export to function due to the way that A5 tracks sessions and security.
