Using JSCalendar in FF

Setting up jscalendar-1.0 in Facile Forms

Introduction

It is a well known problem that the standard Mambo/Joomla calendar produces some erratic behaviour in multi-page forms, causing form elements on other pages to become visible when you select a date from the calendar popup.

The resolution to this problem, as recommended by Ash in the Facile Forms support forum here and with additional configuration ideas from Wene in the Joomla Forums here, is to use the alternative calendar jscalendar-1.0, which can be found in the following directory of your Mambo/Joomla default installation:

"/joomla/includes/js/jscalendar-1.0/calendar_stripped.js"

But jscalendar-1.0 has more advantages than being just a bugfix alternative for multi-page forms.

It is a javascript calendar which can be configured, with the addition of some simple javascript property code, to customise the behaviour of many different features of the popup calendar - which you may also wish to include in your single page forms too!

Jscalendar-1.0 does this by calling a second file named "calendar-setup_stripped.js" when the "Before Form" script runs, and although I will not have time to explain every possible feature which you can customise here, twenty minutes spent reading the jscalendar-1.0 online reference guide will introduce you to the flexibility of this wee gem.

I have uploaded a sample XML file with this tutorial, which is a custom calendar I made for a hotel booking form, and I will use this as a template to guide you through the steps we need to take to customise JSCalendar. You can grab it from the Support Files section at the bottom of this page.

But before we begin, it is very important that you understand something about using form field ID's in Facile Forms, because you will need to edit those fields in our "After Form" script every time you copy the elements of this sample form to another form where Facile Forms assigns it a new "Script ID" number.

Facile Forms elements are identified in javascript code by their "Script ID" number with the prefix ff_elem* Here is an example, where "007" is your Script ID number:

"ff_elem007"

You will get a better understanding of how this works by the practical example I will show you in Step 2 when we open the installed form package for the first time.

OK then, make sure your sample package Sample_JSCalendar_for_FacileForms_v1.0.xml is nearby and let's get this show on the road....

Step 1. Install our sample calendar form

Most of you will already know how to install a new package, but for those of you who are brand new Facile Forms users I'll step you through it, just in case.

We start by clicking on "Configuration" in the top menu, which brings us to this window:

Now, click on "Package Installer", which brings us to this next window where we will browse for the package file "JSCalendar_for_FacileForms_v1.0.xml" that I made to guide you through this tutorial.

Click on "Install Package", which will direct you to the next window...

This is just an information window that provides information about the form, who made it, what it does and a list of everything that will be imported during it's installation.

Note the ID name of the package "JSCalendar", in case we have to navigate to find it later.

Click continue.

Now you will be directed to a new window to search for the package we just installed. Note in the drop down menu titled "Package" that we are already looking at "JSCalendar", which is the one we want.

Click on the item "JSCalendar 1.0 Sample Form" and let's begin....

Step 2. Open and view our sample form

Oh no!!! It pops up an error message!

Did I do something wrong when I installed it?

Don't panic! This is exactly what it should do, because Facile Forms has imported the package and assigned the elements new "Script ID" numbers.

It's annoying, I know, but we'll have this error fixed in a jiffy - and it will be a valuable learning curve for you too!

Before we proceed to the next step, please note the numbers I have circled in the right column, because they may be different in your form. These are the four elements which are used in our javascript code for the calendar setup, so it would be a good idea if you write these "Script ID" numbers down somewhere where you can access them for the next step.

Step 3. Edit our Script ID codes

Copy the code from "Form Pieces" > custom "After Form" over to your notepad editor, where we can see everything more easily as we edit it.

See below how I have circled the code that we need to edit with our new "Script ID" values?

Did you remember what I said in the introduction about the syntax Facile Forms uses for these being "ff_elem*"?

I hope so! Because this is where we need to be applying that knowledge.

See in the screenshot below how I have edited the javascript code, replacing the initial values from this sample form code with the new values which were assigned by Facile Forms when we installed the package, as I highlighted in Step 2?

Before you proceed any further, please double-check that you transfered the new values correctly, corresponding to their form elements.

Now let's copy this code from notepad and paste it back into the "Form Pieces" > custom "After Form" section, overwriting the code that was already there.

While we are in "Form Pieces" section, please copy the custom "Before Code" and leave this code open in notepad for now, because we may need to return to it later.

Don't forget to save your changes before you exit the "Edit Form" window.

Step 4. Modifying the jscalendar-1.0 setup file

Let's just take a quick peek at our custom "Before Form" code, and note the line I have highlighted, because this calendar-setup-stripped.js is the file which our custom Calendar.setup script will be calling on to work it's modification magic.

Here are some basic examples of the kinds of properties we can modify by calling this file:

• ifFormat: The format string that will be used to enter the date in the input field.
• daFormat: Format of the date displayed in the displayArea (if specified).
• singleClick: Whether the calendar popup closes on select by a "single-click" or "double-click".
• firstDay: Specifies which day is to be displayed as the first day of week.
• weekNumbers: Specifies if the calendar will display week numbers.
• align: Alignment of the calendar, relative to another element in your form.
• range: Sets the minimum and maximum years that the calendar will allow.
• flat: Can be used if you want a flat calendar.
• date: The initial date where the calendar will be positioned to.
• showsTime: Configures the calendar to also allow time selection.
• timeFormat: Specifies if the calendar will display time 12hr or 24hr time.
• electric: Specifies if the calendar will update the field while open, or only when closed.
• position: Specifies the [x, y] position where the calendar will be displayed.

If you need to see some more advanced examples you should refer to the jscalendar-1.0 online reference guide, but I don't want to overload you with too much information in this beginners tutorial.

Before we proceed to editing our Calendar.setup script, let's take note of how our calendar looked before we modified it.

Notice that the first day of the week is "Monday", the calendar range is from "2005-2020", and we are using the British long date format "full weekday name/day of the month/full month name/year including the century". And you cannot tell from this screenshot, but the calendar popup will also close on a single-click when the date is selected.

Now we are going to change the way those four things behave, using the jscalendar formatting guide.

We want the date display format to be USA long date, we want the popup to close on a double-click, we want Sunday as our first day of the week, and we want to extend our selectable date range from 1950-2050.

Can you see which fields I have modified in the code below?

Now let's copy that code from notepad and paste it back into our custom "After Form" field.

Next, we save the script and return to the work window to see how our form looks.

Step 5. Modifying the PHP date format code

Oh drat, it doesn't seem to have changed at all! Well, nothing we can see at this point anyway.

That's because we need to make a couple more modifications, but to our PHP code this time.

For those of you who are new to scripting, PHP and javascript use different kinds of code to define their date formats.

Below is the PHP equivalent for the javascript date format "%A, %B %d, %Y":

You will find an online reference guide for formatting PHP date code here and a page with date formats used in the Calendar.setup code here, if you need them.

So let's go edit our StartDate and EndDate text elements so they match our javascript format.

First we need to open the edit window of our StartDate element, as pictured below.

I have circled the code we need to modify in the screenshot below.

This will be our new code:

<?php return date('l, F d, Y'); ?>

Modify the same code in the EndDate text element too, and then save your changes.

Next we need to go to "Edit Form" > "Submit Pieces" > "Begin Script" and modify the date formats for the StartDate and EndDate in there also.

Click save and return to your form to see how it looks now.

Step 6. Checking our calendar layout

Yay! Now our date display is reading by the same format as we defined in our javascript!

Now let's go see what our customised calendar popup looks like.

Notice all the things that have changed from before we modified the Calendar.setup javascript? We now have Sunday as our first day of the week and our date range has extended too.

There's a lot more we could have changed here by adding some extra properties in our javascript, but I wanted to keep it simple for now and I know you will go and read the jscalendar-1.0 reference guide to learn the rest.

As I have learned, there's a lot to be said for "Reading The @#%$ Manual" ;-)

Step 7. Testing our calendar functions

OK, now let's test our calendar script by selecting the arrival and departure dates to make sure they update the text field correctly.

Also take note of whether the popup calendar closes on a double-click now instead of a single-click, as we modified it to do.

So far, so good.

Now lets submit our form to see if there are any validation errors.

Great! No validation errors reported there.

Next we need to go and see how it outputted.

For those of you who are new to Facile Forms, you may not know that there is a very excellent feature called "Manage Records" which can verify if all your input form fields have submitted their data correctly.

You will see a link to it on the top menu of your working window, so let's go there now.

Right away you can see that a new item is listed in "Manage Records" and it was recorded just a few moments ago when we submitted our form.

This is good news, because we know that at least something worked!

Now click on the record to see exactly what happened.

Yay! We can see that the date values are exactly as we entered them for the appropriate start and end dates.

So it worked perfectly as we required!

Now all we have to do is return to our form and publish it and our calendar form is essentially finished.

Well, maybe not quite finished, because there is just one more thing that some artistically fussy people might like to do to pretty-up their calendar some more, which is to change the stylesheet that governs the colour scheme and text alignment of the popup calendar...

Step 8. Changing the calendar stylesheet

Many people prefer the style of the default Mambo/Joomla calendar, so I'll use that for my demonstration and modify the existing stylesheet path to reflect that.

If you would like to experiment with some alternative CSS stylesheets for jscalendar-1.0, I have uploaded a pack with ten CSS files that I extracted from the full version on their web site. You can grab it from the Support Files section at the bottom of this page and extract them into the "/includes/js/jscalendar-1.0/" folder of your Mambo/Joomla installation.

OK, let's go change our stylesheet:

See the line that I have highlighted in the screenshot above?

We need to modify that highlighted line in the javascript code to this:

<link rel="stylesheet" type="text/css" media="all" href="{mossite}/includes/js/calendar/calendar-mos.css">

Next, copy the code from notepad and overwrite the "Form Pieces" > "Before Form" with the modified code for our preferred stylesheet path.

Now let's see how our re-styled popup calendar looks.

Wowee! It looks really sexy and it works great too!

So that about does it folks!

A Final Check List

• Don't forget to change the "Script ID" code in your "Form Pieces" > "After Form" javascript if you copy the elements of the sample page to a new form.

• If you change the names of your elements, then do not forget to reflect those changes in the "Submit Pieces" > "Begin Script".

• If you change your date formats then do not forget to reflect those changes in the custom "Begin Submit" code and the PHP text of your StartDate and EndDate elements in "Edit Element Text".

Support Files

Sample package file for this tutorial: Sample_JSCalendar_for_FacileForms_v1.0.xml

Printable PDF version of this tutorial: Setting up jscalendar-1.0 in Facile Forms.pdf

Copy of this tutorial in Open Document format: Setting up jscalendar-1.0 in Facile Forms.odt

Printable PDF copy of the JSCalendar-1.0 Reference Guide from their web site

Ten extra CSS stylesheets for JSCalender: Extra_CSS_Stylesheets_for_JSCalendar.zip

A final note from the author

It took me three days of mental torment before I was able to figure out how to implement this calendar modification, so documenting what I learned (the hard way) was somewhat therapeutic for me. Knowing others might benefit from my crazy learning curve makes it all worthwhile it at the end of the day.

So I hope you all found this tutorial useful and easy to follow, especially all my fellow Facile Forms newbies!

Good learning and good luck!!!

~zANavAShi~

Last edited by: zANavAShi 01:23, 10 October 2006 (EDT)