<?xml version="1.0" encoding="UTF-8"?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>calendar</keyword>
    </keywordset>
  </sectioninfo>

  <table>
    <title>Component identification parameters</title>

    <tgroup cols="2">
      <thead>
        <row>
          <entry>Name</entry>

          <entry>Value</entry>
        </row>
      </thead>

      <tbody>
        <row>
          <entry>component-type</entry>

          <entry>org.richfaces.Calendar</entry>
        </row>

        <row>
          <entry>component-class</entry>

          <entry>org.richfaces.component.html.HtmlCalendar</entry>
        </row>

        <row>
          <entry>component-family</entry>

          <entry>org.richfaces.Calendar</entry>
        </row>

        <row>
          <entry>renderer-type</entry>

          <entry>org.richfaces.CalendarRenderer</entry>
        </row>

        <row>
          <entry>tag-class</entry>

          <entry>org.richfaces.taglib.CalendarTag</entry>
        </row>
      </tbody>
    </tgroup>
  </table>

  <section>
    <title>Creating the Component with a Page Tag</title>

    <para>To create the simplest variant on a page use the following syntax:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:calendar popup="false"/>
...]]></programlisting>
  </section>

  <section>
    <title>Creating the Component Dynamically Using Java</title>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlCalendar; 	
...
HtmlCalendar myCalendar = new HtmlCalendar();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>
    <para>The <emphasis>
        <property>&quot;popup&quot;</property>
      </emphasis> attribute defines calendar representation mode on a page. If it&apos;s
      &quot;true&quot; the calendar is represented on a page as an input field and a button.
      Clicking on the button calls the calendar popup as it&apos;s shown on the picture below. </para>
    <figure>
      <title>Using the <emphasis>
          <property>&quot;popup&quot;</property>
        </emphasis> attribute</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/calendar.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>Usage <emphasis>
      <property>&quot;currentDate&quot;</property>
    </emphasis> attribute isn&apos;t available in the popup
      mode.</para>
    <para>The <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> component ables to render pages of days in two modes. Switching mode
      could be defined with the <emphasis>
        <property>&quot;mode&quot;</property>
      </emphasis> attribute with two possible parameters: Ajax and Client. Default value is set to
      &quot;Client&quot;.</para>
    <itemizedlist>
      <listitem>
        <para>Ajax</para>
      </listitem>
    </itemizedlist>

    <para>Calendar requests portions of data from Data Model for a page rendering. If
      <emphasis>
        <property>&quot;dataModel&quot;</property>
      </emphasis> attribute has <property>&quot;null&quot;</property> value, data requests are
      not sent. In this case the &quot;Ajax&quot; mode is equal to the
      &quot;Client&quot; mode. </para>

    <itemizedlist>
      <listitem>
        <para>Client</para>
      </listitem>
    </itemizedlist>

    <para>Calendar loads an initial portion of data in a specified range and use this data to
      render months. Additional data requests are not sent.</para>

    <para>There are three button-related attributes:</para>
    <itemizedlist>
      <listitem>
        <para><emphasis>
            <property>&quot;buttonLabel&quot;</property>
          </emphasis> defines a label for the button. If the attribute is set "buttonIcon" and
          "buttonIconDisabled" are ignored </para>
      </listitem>
    </itemizedlist>
    <itemizedlist>
      <listitem>
        <para><emphasis>
            <property>&quot;buttonIcon&quot;</property>
          </emphasis> defines an icon for the button</para>
      </listitem>
    </itemizedlist>
    <itemizedlist>
      <listitem>
        <para><emphasis>
            <property>&quot;buttonIconDisabled&quot;</property>
          </emphasis> defines an icon for the disabled state of the button</para>
      </listitem>
    </itemizedlist>
    <para>The <emphasis>
        <property>&quot;direction&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;jointPoint&quot;</property>
      </emphasis> attributes are used for defining aspects of calendar appearance.</para>
    <para>The possible values for the <emphasis>
        <property>&quot;direction&quot;</property>
      </emphasis> are: </para>
    <itemizedlist>
      <listitem>top-left - a calendar drops to the top and left</listitem>
      <listitem>top-right - a calendar drops to the top and right</listitem>
      <listitem>bottom-left - a calendar drops to the bottom and left</listitem>
      <listitem>bottom-right - a calendar drops to the bottom and right</listitem>
      <listitem>auto - smart positioning activation</listitem>
    </itemizedlist>
    <para> By default, the <emphasis>
        <property>&quot;direction&quot;</property>
      </emphasis> attribute is set to &quot;bottom-right&quot;.</para>
    <para>The possible values for the <emphasis>
        <property>&quot;jointPoint&quot;</property>
      </emphasis> are: </para>
    <itemizedlist>
      <listitem>top-left - a calendar docked to the top-left point of the button element</listitem>
      <listitem>top-right - a calendar docked to the top-right point of the button element</listitem>
      <listitem>bottom-left - a calendar docked to the bottom-left point of the button element</listitem>
      <listitem>bottom-right - a calendar docked to the bottom-right point of the button element</listitem>
      <listitem>auto - smart positioning activation</listitem>
    </itemizedlist>
    <para> By default, the <emphasis>
        <property>&quot;jointPoint&quot;</property>
      </emphasis> attribute is set to &quot;bottom-left&quot;.</para>
    <para>The <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> component provides to use <emphasis>
        <property>&quot;header&quot;</property>
      </emphasis> facet. For example, you can add following scrolling elements to the facet:
      {currentMonthControl}, {nextMonthControl}, {nextYearControl}, {previousYearControl},
      {previousMonthControl}.</para>
    <para>Simple example is placed below.</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <f:facet name="header">
            <f:verbatim>
                  {previousMonthControl} | {nextMonthControl}					
            </f:verbatim>
      </f:facet>
...]]></programlisting>
    <para>It&apos;s possible to define <emphasis>
        <property>&quot;footer&quot;</property>
      </emphasis> facet and replace in it (in the same way how it was described for <emphasis>
        <property>&quot;header&quot;</property>
      </emphasis> facet), for example, following today bar elements: {todayControl},
      {selectedDateControl}, {helpControl}.</para>
    <para>Also you can use <emphasis>
        <property>&quot;optionalHeader&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;optionalFooter&quot;</property>
      </emphasis> facets. These facets define the top and the bottom elements of the calendar. They
      are not attached to the control parts of the calendar. You can replace in them any content.</para>
    <para>The <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> component provides the possibility to use <emphasis>
        <property>&quot;weekNumber&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;weekDay&quot;</property>
      </emphasis> facets. For example, using these facets you can change text style for the elements
      of the calendar as it&apos;s shown in the example below:</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <f:facet name="weekNumber">
            <h:outputText style="font-weight: bold;" value="{weekNumber}" />
      </f:facet>
...]]></programlisting>

    <para>The example of using JavaScript API is placed below:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
         <a4j:form id="form">
                <h:panelGroup id="test" columns="2" style="width: 300px">
                        <h:selectBooleanCheckbox value="#{bean.check}">
                                <a4j:support event="onchange" reRender="test" />
                                <f:selectItem itemValue="true" itemLabel="Show" />
                                <f:selectItem itemValue="false" itemLabel="Hide" />
                        </h:selectBooleanCheckbox>
                        <rich:calendar popup="true"
                                        rendered="#{!bean.check}" value="#{bean.date}" id="c"/>
                                <a onclick="$('form:c').component.doExpand()" href="#">Show</a>	
                </h:panelGroup>
        </a4j:form>
...
]]></programlisting>

    <para>Also the discussion about this problem can be found on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4078301#4078301"
        >RichFaces Users Forum</ulink>.</para>

    <para>The <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> component provides the possibility to use a special Data Model to define data for
      element rendering. Data Model includes two major interfaces: </para>

    <itemizedlist>
      <listitem>CalendarDataModel</listitem>
      <listitem>CalendarDataModelItem</listitem>
    </itemizedlist>

    <para><property>CalendarDataModel</property> provides the following function:</para>
    <itemizedlist>
      <listitem>CalendarDataModelItem[] getData(Date[]);</listitem>
    </itemizedlist>

    <para>This method is called when it&apos;s necessary to represent the next block of
      CalendarDataItems. It happens during navigation to the next (previous) month or in any other
      case when calendar renders. This method is called in <emphasis>
        <property>&quot;Ajax&quot;</property>
      </emphasis> mode when the calendar renders a new page. </para>

    <para><property>CalendarDataModelItem</property> provides the following function:</para>
    <itemizedlist>
      <listitem>Date getDate() - returns date from the item. Default implementation returns date.</listitem>
      <listitem>Boolean isEnabled() - returns <emphasis>
          <property>&quot;true&quot;</property>
        </emphasis> if date is <emphasis>
          <property>&quot;selectable&quot;</property>
        </emphasis> on the calendar. Default implementation returns &quot;true&quot;.</listitem>
      <listitem>String getStyleClass() - returns string appended to the style class for the date
        span. For example it could be &quot;relevant holyday&quot;. It means that the class
        could be defined like the &quot;rich-cal-day-relevant-holyday&quot; one. Default
        implementation returns empty string.</listitem>
      <listitem>Object getData() - returns any additional payload that must be JSON-serializable
        object. It could be used in the custom date representation on the calendar (inside the
        custom facet).</listitem>
    </itemizedlist>

  </section>

  <section>
    <title>JavaScript API</title>
    <table>
      <title>JavaScript API</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Function</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>

          <row>
            <entry>selectDate(date)</entry>

            <entry>Select the date specified. If the date isn&apos;t in current month - performs
              request to select</entry>
          </row>

          <row>
            <entry>isDateEnabled(date)</entry>

            <entry>Check if given date is selectable</entry>
          </row>

          <row>
            <entry>enableDate(date)</entry>

            <entry>Enables date cell control on the calendar</entry>
          </row>

          <row>
            <entry>disableDate(date)</entry>

            <entry>Disables date cell control on the calendar</entry>
          </row>

          <row>
            <entry>enableDates(date[])</entry>

            <entry>Enables dates cell controls set on the calendar</entry>
          </row>

          <row>
            <entry>disableDates(date[])</entry>

            <entry>Disables dates cell controls set on the calendar</entry>
          </row>

          <row>
            <entry>nextMonth()</entry>

            <entry>Navigate to next month</entry>
          </row>

          <row>
            <entry>nextYear()</entry>

            <entry>Navigate to next year</entry>
          </row>

          <row>
            <entry>prevMonth()</entry>

            <entry>Navigate to previous month </entry>
          </row>

          <row>
            <entry>prevYear()</entry>

            <entry>Navigate to previous year</entry>
          </row>

          <row>
            <entry>today()</entry>

            <entry>Select today date</entry>
          </row>

          <row>
            <entry>getSelectedDate()</entry>

            <entry>Return currently selected date</entry>
          </row>

          <row>
            <entry>Object getData()</entry>

            <entry>Return additional data for the date</entry>
          </row>

          <row>
            <entry>enable()</entry>

            <entry>enables calendar</entry>
          </row>

          <row>
            <entry>disable()</entry>

            <entry>disables calendar</entry>
          </row>

          <row>
            <entry>getCurrentMonth()</entry>

            <entry>Returns number of the month currently being viewed</entry>
          </row>

          <row>
            <entry>getCurrentYear()</entry>

            <entry>Returns number of the year currently being viewed</entry>
          </row>

          <row>
            <entry>doCollapse()</entry>

            <entry>Collapse calendar element</entry>
          </row>

          <row>
            <entry>doExpand()</entry>

            <entry>Expand calendar element</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

  </section>


  <section>
    <title>Look-and-Feel Customization</title>

    <para>For skinnability implementation, the components use a <emphasis>
        <property>style class redefinition method.</property>
      </emphasis> Default style classes are mapped on <emphasis>
        <property>skin parameters.</property>
      </emphasis></para>

    <para>There are two ways to redefine the appearance of all <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> components at once:</para>

    <itemizedlist>
      <listitem>
        <para>Redefine the corresponding skin parameters</para>
      </listitem>

      <listitem>
        <para>Add to your style sheets <emphasis>
            <property>style classes</property>
          </emphasis> used by a <emphasis role="bold">
            <property>&lt;rich:calendar&gt;</property>
          </emphasis> component</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Skin Parameters Redefinition</title>

    <table>
      <title>Skin parameters redefinition for a popup element</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for headers (header, optional header)</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-bottom-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>generalSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for footers (footer, optional footer) and names of working
        days</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-top-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>

            <entry>border-right-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>background</entry>
          </row>

          <row>
            <entry>generalSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for weeks numbers</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-bottom-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>

            <entry>border-right-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>background</entry>
          </row>

          <row>
            <entry>calendarWeekBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>generalSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a toolbar and names of months</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>headerBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>headerSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>headerFamilyFont</entry>

            <entry>font-family</entry>
          </row>

          <row>
            <entry>headerWeightFont</entry>

            <entry>font-weight</entry>
          </row>

          <row>
            <entry>headerTextColor</entry>

            <entry>color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for cells with days</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-bottom-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>

            <entry>border-right-color</entry>
          </row>

          <row>
            <entry>generalBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>generalSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for holiday</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>calendarHolidaysBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>calendarHolidaysTextColor</entry>

            <entry>color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for cell with a current date</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>calendarCurrentBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>calendarCurrentTextColor</entry>

            <entry>color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a selected day</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>headerBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>headerTextColor</entry>

            <entry>color</entry>
          </row>

          <row>
            <entry>headerWeightFont</entry>

            <entry>font-weight</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

  </section>

  <section>
    <title>Definition of Custom Style Classes</title>

    <para>On the screenshot there are classes names that define styles for component elements.</para>

    <figure>
      <title>Style classes</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/calendar1.png" scalefit="1"/>
        </imageobject>
      </mediaobject>
    </figure>

    <table>
      <title>Classes names that define an input field and a button appearance</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>rich-calendar-input </entry>

            <entry>Defines styles for an input field</entry>
          </row>

          <row>
            <entry>rich-calendar-button</entry>

            <entry>Defines styles for a popup button</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Classes names that define a days appearance</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>

          <row>
            <entry>rich-calendar-days</entry>

            <entry>Defines styles for names of working days in a header</entry>
          </row>

          <row>
            <entry>rich-calendar-weekends</entry>

            <entry>Defines styles for names of weekend in a header</entry>
          </row>

          <row>
            <entry>rich-calendar-week</entry>

            <entry>Defines styles for weeks numbers</entry>
          </row>

          <row>
            <entry>rich-calendar-today</entry>

            <entry>Defines styles for cell with a current date</entry>
          </row>

          <row>
            <entry>rich-calendar-cell</entry>

            <entry>Defines styles for cells with days</entry>
          </row>

          <row>
            <entry>rich-calendar-holly</entry>

            <entry>Defines styles for holiday</entry>
          </row>

          <row>
            <entry>rich-calendar-select</entry>

            <entry>Defines styles for a selected day</entry>
          </row>

          <row>
            <entry>rich-calendar-hover</entry>

            <entry>Defines styles for a hovered day</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Classes names that define a popup element</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>

          <row>
            <entry>rich-calendar-exterior</entry>

            <entry>Defines styles for a popup element</entry>
          </row>

          <row>
            <entry>rich-calendar-tool</entry>

            <entry>Defines styles for toolbars</entry>
          </row>

          <row>
            <entry>rich-calendar-month</entry>

            <entry>Defines styles for names of months</entry>
          </row>

          <row>
            <entry>rich-calendar-header-optional</entry>

            <entry>Defines styles for an optional header</entry>
          </row>

          <row>
            <entry>rich-calendar-footer-optional</entry>

            <entry>Defines styles for an optional footer</entry>
          </row>

          <row>
            <entry>rich-calendar-header</entry>

            <entry>Defines styles for a header</entry>
          </row>

          <row>
            <entry>rich-calendar-footer</entry>

            <entry>Defines styles for a footer</entry>
          </row>

          <row>
            <entry>rich-calendar-boundary-dates</entry>

            <entry>Defines styles for an active boundary button</entry>
          </row>

          <row>
            <entry>rich-calendar-btn</entry>

            <entry>Defines styles for an inactive boundary date</entry>
          </row>

          <row>
            <entry>rich-calendar-current</entry>

            <entry>Defines styles for a today control date</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <para>In order to redefine the style for all <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
      same names and define the necessary properties in them.</para>

    <para>To change the style of particular <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> components define your own style classes in the corresponding <emphasis
        role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis>attributes.</para>
  </section>

  <section>
    <title>Relevant Resources Links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/calendar.jsf?c=calendar"
        >Here</ulink> you can see the example of <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> usage and sources for the given example. </para>
    <para>How to use JavaScript API see on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4078301#4078301"
        >RichFaces Users Forum</ulink>.</para>
  </section>

</section>
