README.txt in Availability Calendars 7.3

/**
 * README for Availability Calendar Booking Formlet module.
 *
 * @author Erwin Derksen (fietserwin: http://drupal.org/user/750928)
 */

The availability calendar booking formlet module defines a booking formlet
field that cooperates with Availability Calendar fields. It offers a small form
that can receive an arrival and departure date by reacting to click events on
Availability Calendar fields. If both dates are filled in, the submit button is
enabled and the user can continue to the real booking form.

This form is called a formlet as it is a small minimal form that only receives
the arrival and departure dates. The full booking form, where the visitor can
enter his/her name and other details is to defined separately. Think off an "Add
to cart" form where one can enter the quantity and click on "add to cart" which
brings you to the full cart form.


Dependencies
------------
This sub-module depends on the Availability Calendar module.
Also the form will typically be posted to a webform. So installing the webform
module is recommended.


Limitations
-----------
This module will not:
- Change the calendar. When clicking on the departure date the calendar will be
  updated visually, but this change will not be stored on the server. You can
  define a hook for that. See e.g. the webform documentation to find out which
  (submission) hooks best fit your needs.
- Define the webform. This depends to much on your specific situation.
- Offer payment integration.


Installing
----------
As usual.


Configuring
-----------
After enabling the module:
1) Define the date formats you want to use on admin/config/regional/date-time.
   You can localize these formats in admin/config/regional/date-time/locale.
2) Add a webform to post the form to. See the details below.
3) Add an "Availability Calendar Booking formlet" field to the entity type that
   also has an "Availability Calendar" field. Fill the "URL to continue the
   booking" field with the URL of the webform created in step 2.
4) Set the display settings on the "Manage display" page.
5) Style the form as you like. Note that this module only contains some basic
   styling for the formlet.

Basically this is it. Additionally you may want to define some webform
submission processing. This will be explained further on.


Views integration
-----------------
Suppose you have defined a view that searches on availability. The results page
shows the teasers of the entities that are available during the defined period.
Why not present just the "book now" button and allow the visitor to directly
go to the complete reservation form?

This is possible. You can define default values for the begin and date that can
come from some contextual variable. The results page of the search will probably
have a URL that looks like
search-availability?available[arrival][date]=2012-07-01&available[duration]=2
You can tell the formlet to take the begin date from $_GET, more specifically
the entry available[arrival][date] and that the end date should be based on a
duration (in days) given by the available[duration] entry of $_GET.

You can define this in the display settings for a given display mode. So, the
settings can differ for the full view, where visitors will still have to click
on the calendar before they can proceed to the complete reservation form, and
the teaser, where visitors can directly click on "book now".


How it works
------------
There seems to be quite some confusion about the why and how of this module. So,
following is a bit more in-depth explanation of the ideas behind this module.

Normally the page with the calendar is quite stuffed with all sorts of
information. Thus adding the complete booking form is not desirable. Therefore,
just a small form (aka 'formlet') is rendered that only contains the most basic
fields to allow it to interact with the calendar. Once this information is
completed by the visitor, it can be forwarded to the complete booking form.

Step by step:
- A visitor arrives at your site and, hopefully, eventually at the page with the
  Availability Calendar.
- The Availability Calendar module renders the calendar and defines the
  javasript that allows the visitor to click on available dates.
- This module adds the 'formlet' to that page including some javascript to
  handle the date click events and place the selected dates on the formlet.
- When the user clicks on "Book this resource ..." all information is POSTed to
  another page. This page is defined in the field settings and normally points
  to a webform with the real booking form.
- Together with the arrival and departure dates, a lot of hidden fields are
  submitted. These hidden fields contain information about the calendar field
  and the entity the calendar is attached to. (Note that calendar fields may be
  synchronized between translations and thus the calendar at its own, does not
  necessarily uniquely define the entity that was being shown.)
- The visitor fills in the remaining information and submits the complete
  booking form.
- Note: on webform submission, the values that the formlet orignally POSTed will
  not be there anymore. So if you need them during the webform submission phase,
  you need to place them in webform components! (see below)
- The webform module handles the submission by e.g. e-mailing the submission to
  the website or accommodation owner.


Defining the 'complete booking form' webform
--------------------------------------------
This part assumes you are using the webform module.
- Define the webform components that the visitor should complete like name,
  e-mail, address, number of persons, etc.
- Define webform components for the dates that are already filled in:
  - Begin date (default value: %post[from_display]): the begin date.
  - End date (default value: %post[to_display]): the end date.
  or
  - Begin date (default value: %post[from_iso]): the begin date.
  - end date (default value: %post[to_iso]): the end date.
  These will typicaly be disabled textfields, the visitor can not change the
  dates anymore as the availability calendar is not visible on the webform.

  The difference between these 2 sets of dates are:
  - The latter are in the ISO 8601 (date part only) format: yyyy-mm-dd, while
    the former are in the format as presented to the visitor. You can define and
    localize this format via the Drupal admin interface at
    admin/config/regional/date-time(/locale).
    Note that this may lead to different date representations for the same date
    depending on the *visitor*, not the *recepient* of the webform!
  - For overnight calendar fields, the to_iso date is the last full day of the
    rental period, while the to_display date is the departure date.
- As you will typically post to the same webform for all accommodations, you
  need to know from wich accommodation the request was coming. To this end, you
  may want to define additional webform components that receive this information
  needed to process the boooking:
  - cid (default value: %post[cid]): the calendar id.
  - calendar label (default value: %post[calendar_label]): title of the calendar
    (if set).
  - entity type (default value: %post[entity_type]): the entity type.
  - entity id (default value: %post[entity_id]): the ID of the entity.
  - entity label (default value: %post[entity_label]): the title of the entity.
  With the exception of entity label and/or calendar_label, these will typically
  be hidden fields as the visitor does not have to see this information.
  Note that in a multi-lingual site, a calendar may be synchronized over all
  translations of an enity. So there is not necessarily a 1-to-1 relationship
  between the calendar and the entity.
- Fields from the POST that you don't need, don't have to be defined as a
  webform component.
- You may also have fields from the POST that you only need for internal
  processing, but do not want to send in the e-mail. You should declare those
  fields as webform component and, subsequently, you can exclude them from the
  e-mail in the "Edit e-mail settings" page of the webform module.


Hooks for custom processing
---------------------------
Depending on your situation, processing the webform may need some additional
programming from your side. Think of extracting the name of the accommodation
from the entity, or getting the e-mail address to send the reqeust to. The
webform module and the mail system offer hooks for this.

1) The webform to complete the booking is used for multiple accommodations and
you want to change the e-mail addres to which the webform submission is sent

2) On submission, you want to update the calendar and set the requested dates
to "Optionally booked".

ad 1)
See issue http://drupal.org/node/1470490

ad 2)
See issue http://drupal.org/node/1379384