The ADF Faces calendar can be used whenever you want to add a calendar feature to your application. You will need to have the relevant data in your data store that represents the content provided by the calendar, such as the date, time, title, location, and owner. You can use the familiar patterns of entity objects and view objects to model the data and then use drag and drop from the Data Controls panel to create the calendar.

The carousel component gives the user the ability to view an image from a series of images. The user can see partial views of the images before and after the image being viewed and can scroll through each image in the sequence. The user can do so using a slider or navigation buttons. The carousel is useful for showing objects that require a highly visual presentation. For example, it can be used to display a photographic collection or merchandise in a catalog.

1. Create an entity object based on your data source. The entity object must include the attributes shown in Table 37-1. The attributes do not have to use the names shown in the table; they can be named anything. However, they must be of one of the types noted. You will map these attributes to attributes in the CalendarModel in a later step.

   Table 37-1 Required Attributes for a Calendar

   Attribute	Valid Types	Description
   Start time	java.util.Date, java.sql.Date, oracle.jbo.domain.Date, oracle.jbo.domain.TimeStamp	Start time for the activity
   End time	java.util.Date, java.sql.Date, oracle.jbo.domain.Date, oracle.jbo.domain.TimeStamp	End time for the activity
   ID	String	Unique ID
   Provider ID	String	ID of the provider object that represents the owner of the activity
   Title	String	Short description of the activity

   The entity object can also contain the known (but not required) attributes shown in Table 37-2:

   Table 37-2 Optional Attributes for a Calendar

   Attribute	Type	Description
   Recurring	String or CalendarActivity.Recurring	Status of recurrence for the activity. Valid values are SINGLE (does not recur), RECURRING, or CHANGED (this activity was part of the recurring activity but has been modified to be different from parent activity).
   Reminder	String or CalendarActivity.Reminder	Whether or not the activity has an associated reminder. Valid values are ON or OFF.
   Time Type	String or CalendarActivity.TimeType	Type of time associated with the activity. Valid values are ALLDAY and TIME. Activities that have a value of ALLDAY do not have any time associated with them. They are considered to span the entire day. Activities with a value of TIME have a specific time duration.
   Location	String	Location of an activity.
   Tags	Set of String values or a semicolon-separated list of String values.	Keywords for the activity.

   Your entity objects can also contain other attributes that the CalendarModel has no knowledge of. You will be able to add these to the model as custom properties in a later step.

   For information on creating entity objects, see Creating a Business Domain Layer Using Entity Objects.

2. Create an associated view object. In the Query page of the overview editor, create named bind variables for the following:

   • A string that represents the time zone

   • A date that represents the start time for the current date range shown on the calendar

   • A date that represents the end time for the current date range shown on the calendar

     Tip:

     Dates in an ADF Faces calendar are "half-open," meaning that the calendar returns all activities that start on or after the start time and before (but not on) the end time.

     For more information about creating named bind variables, see Working with Bind Variables.

3. Create an entity object that represents the provider (owner) of activities. The entity object must include the attributes shown in Table 37-3. The attributes do not have to use the names shown in the table; they can be named anything. However, they must be of the type noted. You will map these attributes to attributes in the CalendarProvider class in a later step.

   Table 37-3 Attributes for a CalendarProvider Class

   Attribute	Type	Description
   Id	String	Unique ID.
   Display Name	String	The name of the provider that can be displayed in the calendar.

4. Create a view object for the provider.
5. Ensure that the new view objects are part of the application module, and if needed, refresh the Data Controls panel.
6. Create your JSF page, as documented in Creating a Web Page.
7. From the Data Controls panel, drag the collection that represents the view object for the activity created in Step 2 and drop it as a Calendar.

   Tip:

   The Calendar option will appear in the context menu only if the view object contains the required attributes documented in Table 37-1 and the bind variables described in Step 2.

8. Complete the Calendar Bindings dialog to map the bind variables and attributes to the CalendarModel and the CalendarProvider classes. For additional help, click Help or press F1.
9. By default, the calendar will be read-only and will return only those activities currently in the data store. You will need to configure the calendar and implement additional functionality as described in the Using a Calendar Component chapter of Developing Web User Interfaces with Oracle ADF Faces.

   For example, to allow creation of a new activity, you might create an input form in a dialog (as described in the How to Create a Dialog section of Developing Web User Interfaces with Oracle ADF Faces) using the same data control collection used to create the calendar. For more information about creating input forms, see Creating an Input Form.

When you drop a collection as a calendar, JDeveloper:

• Defines an iterator binding to the collection of activities, and another iterator binding to the collection of providers.

• Defines an action binding to the executeWithParams operation on the activities collection. It is this operation that will be invoked to execute the query to return the activities to display. Because the operation requires parameters to determine the date range and time zone, NamedData elements are also created for each of the parameters (created as named bind variables on the view object). For more information about NamedData elements, see Method Parameters.

  Note:

  A runtime error will occur if you specify java.sql.Date as the NDType in the calendar page definition file. Use one of the following supported data types instead:

  • oracle.jbo.domain.Timestamp

  • oracle.jbo.domain.Date

  • java.sql.Timestamp

  • java.util.Date

• Defines a calendar binding. This binding contains a node element that represents a row in the collection and maps the data control attributes to the calendar activity's attributes, as defined when using the wizard.The value is the data control attribute and the type is the calendar attribute. For any custom defined attributes, the type will be custom and value will be the data control attribute. Each row (node) is represented by a rowKey, which is the activity ID.

  There is also a providerDefinition element that determines the source and mapping of available providers. This mapping allows the calendar model to filter activities based on the state of the provider (either enabled or disabled).

  Tip:

  To access a custom attribute, use the CalendarActivity.getCustomAttributes() method, passing in the name of the attribute as defined by the value element.

  The following example shows the page definition code for a calendar.

<executables>
    <iterator Binds="ActivityView1" RangeSize="-1"
              DataControl="AppModuleDataControl" id="ActivityView1Iterator"/>
    <iterator Binds="EmployeesView1" RangeSize="25"
              DataControl="AppModuleDataControl" id="EmployeesView1Iterator"/>
  </executables>
  <bindings>
    <action IterBinding="ActivityView1Iterator" id="ExecuteWithParams"
            RequiresUpdateModel="true" Action="executeWithParams">
      <NamedData NDName="startTime"
                 NDValue="#{bindings.ActivityView1.startDate}"
                 NDType="oracle.jbo.domain.Date"/>
      <NamedData NDName="endTime" NDValue="#{bindings.ActivityView1.endDate}"
                 NDType="oracle.jbo.domain.Date"/>
      <NamedData NDName="timeZone"
                 NDValue="#{bindings.ActivityView1.timeZoneId}"
                 NDType="java.lang.String"/>
    </action>
    <calendar IterBinding="ActivityView1Iterator" id="ActivityView1"
              xmlns="http://xmlns.oracle.com/adf/faces/binding"
              ActionBindingName="ExecuteWithParams">
      <nodeDefinition DefName="model.ActivityView">
        <AttrNames>
          <Item Type="id" Value="Id"/>
          <Item Type="providerId" Value="ProviderId"/>
          <Item Type="title" Value="Title"/>
          <Item Type="startTime" Value="StartTime"/>
          <Item Type="endTime" Value="EndTime"/>
        </AttrNames>
      </nodeDefinition>
      <providerDefinition IterBindingName="EmployeesView1Iterator">
        <AttrNames>
          <Item Type="id" Value="EmployeeId"/>
          <Item Type="displayName" Value="FirstName"/>
        </AttrNames>
      </providerDefinition>
    </calendar>
  </bindings>

JDeveloper inserts code onto the JSF page that binds the calendar value to the CalendarModel class, as shown in the following example.

<af:form>
  <af:calendar value="#{bindings.ActivityView1.calendarModel}"/>
</af:form>

The CalendarModel class uses CalendarActivityDefinition class to access the calendar binding.

When the calendar is accessed, the executeWithParams operation is invoked, with the value of the startDate and endDate parameters determined by the value of the calendar component's view and activeDay attributes. For example, if the view attribute is set to month and the activeDay is set to the current date (say, May 5, 2013), then the value for the startDate would be May 1, 2013 and the endDate value would be May 31, 2013. By default, the time zone value is taken from the time-zone setting in the trinidad-config.xml file (for more information, see the Configuration in trinidad-config.xml section of Developing Web User Interfaces with Oracle ADF Faces). Therefore, the query would be restricted to return only activities that fall within that date range.

When the query returns data, because the calendar component is bound to the CalendarModel, the CalendarModel uses the CalendarActivityDefinition class to access the calendar binding class and map the values from the data source to the calendar, using the mappings provided by the binding.

1. From the Data Controls panel, drag the collection for the view object on to the page and choose Carousel from the context menu.
2. In the Properties window, in the Behavior section, bind the CarouselSpinListener to a handler method that you created in the prerequisites.
3. In the Structure window, expand the carousel component and the nodeStamp facet, and select the carouselItem component.
4. Bind the CarouselItem component's text attribute to the associated property on the view object using variable value set on the carousel's var attribute, which by default is set to item. So for example, to use the Name attribute on the view object, the value of the carouselItem's text attribute might be #{item.Name}.

   You can also bind other properties to the text attribute if you want to display more information. For example, the inventory carousel binds both the Name and the AmountInStock properties to the text attribute.

5. In the ADF Faces page of the Components window, from the General Controls panel, drag an Image and drop it as a child to the carouselItem.

   In the Insert Image dialog, enter the path to the source for the images, being sure to use the variable for the item in the carousel. For example, the path to the image files for the products would normally be:

   /images/products/#{item.Filename}
   

   Bind the shortDesc attribute to the text you want to appear when the mouse hovers over the image. For example:

   #{item.Name}
   

   For information about setting other attributes of the carousel and carouselItem components, see the How to Create a Carousel section of Developing Web User Interfaces with Oracle ADF Faces.

6. If you want to provide additional information about the items in the carousel, you can drag and drop the same view object onto the page, for example, as a table. For the components in the table to redisplay the information for the current item displayed once the carousel is spun, you need to set the partialTrigger attribute of the component containing the form to the carousel component's ID.

   For example, a table displays the information for each item in Figure 37-3. The partialTrigger attribute for the table component is set to c1, which is the carousel component's ID. This means that whenever the carouselItem invokes the CarouselSpinEvent, the table will be refreshed, causing the row that displays information about the item that was just made current in the carousel is also made current in the table.

   Additionally, the partialTrigger attribute for the carousel and carousel item is set to t1, which is the table's ID. This means that whenever a selection event occurs on the table, the carousel is refreshed to make the item that was just made current in the table, the current item in the carousel.

   For more information about partial page rendering and the partialTriggers attribute, see the Rerendering Partial Page Content chapter of Developing Web User Interfaces with Oracle ADF Faces.

   The following example shows the page code for the carousel displayed in Figure 37-3.

   <f:facet name="first">
     <af:carousel currentItemKey="#{bindings.Inventory.treeModel.rootCurrencyRowKey}"
                  value="#{bindings.Inventory.treeModel}" var="item" id="c1"
                  carouselSpinListener="#{InventoryControl.handleCarouselSpin}"
                  partialTriggers="::t1">
       <f:facet name="nodeStamp">
         <af:carouselItem id="ci1" text="#{item.Name} #{item.AmountInStock}"
                          partialTriggers="::t1">
           <af:image source="/images/products/#{item.Filename}"
                     shortDesc="#{item.Name}" id="i1"/>
         </af:carouselItem>
       </f:facet>
     </af:carousel>
   </f:facet>
   <f:facet name="second">
     <af:table value="#{bindings.Inventory.collectionModel}" var="row"
               rows="#{bindings.Inventory.rangeSize}"
               emptyText="#{bindings.Inventory.viewable ? 'No data to display.' :
                           'Access Denied.'}"
               fetchSize="#{bindings.Inventory.rangeSize}" rowBandingInterval="0"
               selectedRowKeys="#{bindings.Inventory.collectionModel.selectedRow}"
               selectionListener="#{bindings.Inventory.collectionModel.makeCurrent}"
               rowSelection="single" id="t1"
               columnStretching="last" partialTriggers="::c1">

When you drop a collection from the Data Controls panel as a carousel, a tree value binding is created. A tree consists of a hierarchy of nodes, where each subnode is a branch off a higher-level node.

The tree binding iterates over the data exposed by the iterator binding. The carousel wraps the result set from the iterator binding in a treeModel object, which is an extension of the collectionModel. The collectionModel allows each item in the collection to be available within the carousel component using the var attribute. For more information about the tree binding, see Iterator and Value Bindings for Tables.

JDeveloper adds both a carousel component and its child carouselItem component onto the page, as shown in the following example.

<af:carousel
        currentItemKey="#{bindings.Products.treeModel.rootCurrencyRowKey}"
        value="#{bindings.Products.treeModel}" var="item"
        id="c1"
        carouselSpinListener="#{InventoryControl.handleCarouselSpin}">
  <f:facet name="nodeStamp">
    <af:carouselItem id="ci1" text="#{item.Name}"/>
  </f:facet>
</af:carousel>

The carousel value is bound to the treeModel for the associated collection, and the currentItemKey attribute of the carousel is bound to the rootCurrencyRowKey of the binding object. In this example, the carousel iterates over the items in the Products iterator binding. The iterator binding binds to a rowKeySet that keeps track of the current product. By default, the currentItemKey attribute of the carousel is bound to the rootCurrencyRowKey of the binding object, which causes the product currently displayed at the front of the carousel to be the root and the current item. The carouselItem component accesses the current data object for the current item presented to the carousel tag using the item variable.