calendariffic

== Calendariffic.
May 2007 by Paul N. Danese. email bugs &c. to: [e-mail]

=== WHAT THIS PLUGIN DOES: Allows the user to create a DHTML pop-up calendar and an associated text-box that displays the selected date using 1 Rails function from within a .rhtml file.

=== INSPIRATION: Like all the other good calendar plugins, Calendariffic relies on the heavy-lifting performed by the Dynarch DHTML calendar (http://www.Dynarch.com/projects/calendar/).

=== LICENSE: As Calendariffic is simply a rails extension of the Dynarch calendar, it is released under the same license as that of the Dynarch calendar (i.e. the GNU General Lesser Public License, http://www.gnu.org/licenses/lgpl.html).

=== BACKGROUND: The Rails community needs another Ajax Calendar plugin like I need another hole in my head.
Fortunately for all of us, my Colt .45 single-action Peacemaker just arrived from Ebay, complete with bullets. Okay okay, there were a handful of questionable reasons for building this plugin.

1. To see if I could do it.
2. I tried the Datetime Toolbocks plugin, which is beautiful and slick and does everything but perform surgery and it worked like a champ--unless I wanted to modify its look and feel, in which case I needed a PhD in Ajaxology, which I don't have.
3. I tried another Calendar plugin which (in theory) possessed a configurable look and feel, but the documentation was so lacking that I (again) had to plumb the depths of someone else's ruby, rails and javascript and, well, I'm just a little too ADHD for that.

=== PLEDGE: So Here's my Plugin Pledge.

• Calendariffic won't do as much as Datetime Toolbocks (e.g. you can't type in 'tomorrow' and have it guess the correct date), however it will do the basics just fine (i.e. pick a date from a calendar) and it'll still be easier to alter w/ respect to look and feel.
• The documentation won't [completely] suck.

=== HOW TO INSTALL THE PLUGIN:

1. YOU MUST HAVE A FUNCTIONAL COPY OF RAILS INSTALLED ON YOUR SYSTEM
2. YOU MUST HAVE A FUNCTIONAL RAILS PROJECT INSTALLED ON YOUR SYSTEM (let's say the project is called myrailsapplication and is located in the linux directory /myrailsapplication/.
3. Navigate to the /myrailsapplication/ directory and type script/plugin install http://opensvn.csie.org/calendariffic/calendariffic/
4. Press the enter key and wait for all files to be downloaded into your rails application (files will be located in /myrailsapplication/vendor/plugins/calendariffic/)
5. You're done.

=== HOW TO USE THE PLUGIN:

1. Identify the .rhtml file that will display the Calendariffic calendar. Let's say this file is called myrailsview.rhtml.

2. You then need to include links to 3 Dynarch calendar javascript files which the plugin has installed in your PUBLIC/javascripts/calendariffic directory. These 3 files are called 'calendar.js', 'calendar-setup.js', and 'calendar-en.js'. The easiest way to do this is to use the rails function javascript_include_tag. e.g. your myrailsview.rhtml file might have this in the section:
   <%= javascript_include_tag 'calendariffic/calendar.js', 'calendariffic/calendar-setup.js', 'calendariffic/lang/calendar-en.js' %>

   Some things to note:
   The Calendariffic file, calendar-setup.js, is a slightly modified version of Dynarch's calendar-setup.js file.
   Specifically, it has 1 more function (called set_cal()) that is used to facilitate calendar creation.
   So don't try replacing Calendariffic's calendar-setup.js file with the equivalently-named Dynarch file.

   The calendar-en.js file is located in a subdirectory named 'lang'. The calendar-en.js file sets the language associated with the calendar to ENGLISH.
   There are MANY different language-specific javascript files located in the lang directory, so you can choose whichever is suitable for you.

   You MUST include the relative path to each of the 3 javascript files in your javascript_include_tag function (i.e. don't just write javascript_include_tag 'calendar.js' instead, write javascript_include_tag 'calendariffic/calendar.js'

3. To specify the look-and-feel of your calendar pop-up, you now need to include a link to your favorite Dynarch calendar css file.

   There are 10 different looks-and-feels to the standard Dynarch pop-up calendar and they are located within the rails directory public/stylesheets/calendariffic

   The standard method to reference 1 of these .css files in your .rhtml file is to add something like this to your tag: <%= stylesheet_link_tag 'calendariffic/calendar-win2k-cold-1.css' %>

4. Here's where you add the DHTML calendar. Add this (or something similar) to the portion of your .rhtml file at the point where you want your pop-up calendar to appear: for example <%= calendariffic_input(false, 'start_date', 'calendariffic/date.png', 'start_cal', '%m/%d/%y', nil, {:class => 'myfavoriteclass', :readonly => 'true'}, {:class => 'borderless'}) %> will yield the following HTML <input type="text" name="start_date" id="start_date", value="" readonly="true" class="myfavoriteclass" /> Details of the syntax for the calendariffic_input function are given in the rdoc. Note that you MUST supply a value for text_name and a different value for image_name for the pop-up calendar to work

5. Once you've added your calendariffic_input function to your .rhtml file, you're done.
   You now have a calendar icon that can be clicked on to pop-up a calendar widget.
   Once you select a date from the calendar widget, it will be displayed in your custom build text-box.