Go to primary content
Oracle® Application Express Application Builder User's Guide
Release 5.0
E39147-04
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

12.1 Creating Calendars

This section describes how to create a calendar in Application Builder. Application Builder includes a built-in wizard for generating a calendar with monthly, weekly, daily, and list views. Once you specify the table on which the calendar is based, you can create drill-down links to information stored in specific columns and enable drag and drop capability.

12.1.1 About Supported Calendars

Application Builder supports two types of calendars:

  • Calendar - Calendar is based on the FullCalendar jQuery library and can only be customized through CSS.

  • Legacy Calendar - Legacy Calendar is template-based and will be deprecated in the future release.


Tip:

In previous releases Legacy Calendar was referred to as Calendar (Template), Classic calendar, Easy calendar, and SQL calendar).

Both calendar options enable you to create a calendar based on a table or SQL query you provide. During the creation process, you are prompted to select a date column and display column. Because it offers a better user interface and numerous additional features, Oracle recommends converting all legacy calendars to the latest calendar.

Calendar

The Calendar option supports:

  • Rendering calendar events on multiple views (Month, Week, Day, or List).

  • Rendering of duration and non-duration based events.

  • Ability to modify the start and end dates by dragging and dropping events on different dates.

  • Ability to change the duration by resizing the length of the events, by changing the end date.

  • Ability to Edit or Adding new events on calendar using forms by cllicking either on events or empty calendar cell.

  • Rendering events from external sources using webservice calls or Google Calendar feeds.

  • Ability to render events titles on single or multiple lines.

  • Using different CSS classes, developer can choose different styles for different type of events.

  • Ability to download events in PDF printable format

  • Support of multiple formats for sharing events (iCal, CSV, XML).

  • Ability to add tooltip on Month/Week/Day views to make it easier for users to have a quick look at details of each event.

Legacy Calendar

Legacy Calendars option supports:

  • Creation of one legacy calendar per page.

  • Rendering of start date only.

  • Look and feel defined by templates.

  • Modification of start date by dragging and dropping events.

  • Calendars that include daily, weekly, and monthly views.

  • The date column determines the days on the calendar which contains entries.

  • The display column defines a specific row which displays the calendar.

12.1.2 Sample Calendar

The following is a sample calendar from Sample Database Application.

Description of calendar_example.png follows
Description of the illustration calendar_example.png

This calendar includes the following buttons:

  • Previous - Navigates to the previous month.

  • Next - Navigates to the next month.

  • Month - Displays a monthly view of all orders.

  • List - Displays a list of all orders.


Tip:

Expand the SQL Source region at the bottom of the page to view the underlying SQL.

12.1.3 Adding a Calendar to a New Page

This section describes how to add a new calendar from the Application home page.

12.1.3.1 Adding a Calendar to a New Page

To create a Calendar from the Application home page:

  1. Run the Create Page Wizard:

    1. Navigate to the Workspace home page.

    2. Click the Application Builder icon.

    3. Select an application.

    4. Click Create Page.

      The Create Page Wizard appears.

  2. For Create a Page:

    1. User Interface - Select a user interface for the page.

    2. Select a page type - Select Calendar.

    3. Click Next.

  3. Select Calendar and click Next.

  4. For Page and Region Attributes:


    Tip:

    To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help".

    1. Page Number -If you identify a new page number, the wizard creates a new page. If you identify an existing page number, the wizard adds the component to that page.

    2. Page Name - Enter a title for the page to be created.

    3. Page Mode - Select a page mode.

    4. Region Name - Enter a name for the region to contain the calendar.

    5. Breadcrumb - Select whether to use a breadcrumb navigation control on your page, and which breadcrumb navigation control you want to use.

    6. Click Next.

  5. For Navigation Menu, specify the type of navigation to include on this page and click Next. The navigation options that display depend upon the current application theme.

  6. For Source, select if the calendar source is a table or SQL query.

    If the Calendar source is table:

    1. Source Type - Select Table.

    2. Table/View Owner - Select the owner of the table on which you are building a calendar.

    3. Table/View Name - Select the table or view on which the calendar is based.

    4. Select Columns - Select one or more columns to be included in the calendar.

    5. Click Next.

    If the Calendar source is SQL Query:

    1. Source Type - Select SQL Query.

    2. Enter Region Source - Enter the SQL SELECT statement to be used for the calendar. The SQL SELECT statement must include at least two columns, of which one must be a DATE column.

      For examples, see field-level Help.

    3. Click Next.

  7. For Settings:

    1. Display Column - Select the column which holds the text displayed for events on this calendar.

    2. Start Date Column - Select the column which holds the start date for events displayed on this calendar.

    3. End Date Column - Select the column which holds the end date for events displayed on this calendar. If this attribute is specified, then the calendar displays duration-based events.

    4. Show Time - Select whether the time portion of the date should be displayed.

    5. Add Create Page - Identify whether a new form page is created. This form will be used to add events on calendar.

    6. Add Edit Page - Identify whether a new form page is created. This form will be used to edit events on calendar.

    7. Generate Drag&Drop Code - Specify if the calendar includes code for drag and drop. This code add support for updating the events records when an end user drags and drops events from one date to another.

    8. Click Next.

  8. If you elected to include a Create/Edit Page, configure the attributes and follow the on-screen instructions.

  9. Click Create.


Tip:

If you add a new region of type Calendar directly in Page Designer than you need to specify the SQL Query for the calendar and manually define additional attributes such as Drag and Drop Pl/SQL Code. You will also need to manually define create and edit pages, or link to existing form pages.

12.1.3.2 Adding a Legacy Calendar to a New Page

In previous releases Legacy Calendar was referred to as Calendar (Template), Classic calendar, Easy calendar, and SQL calendar). A Legacy Calendars are template-based and will be deprecated in the future release.


Tip:

When creating a Legacy Calendar by running the Create Page Wizard, you must manually create an On Demand page process to enable drag and drop functionality. See "Enabling the Dragging and Dropping of Data In an Existing Calendar."

To create a Legacy Calendar by running the Create Page Wizard:


Tip:

To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

  1. Run the Create Page Wizard:

    1. Navigate to the Workspace home page.

    2. Click the Application Builder icon.

    3. Select an application.

    4. Click Create Page.

      The Create Page Wizard appears.

  2. For Create a Page:

    1. User Interface - Select a user interface for the page.

    2. Select a page type - Select Calendar.

    3. Click Next.

  3. Select Calendar (Template) and click Next.

  4. For Page Attributes:

    1. Page Number -If you identify a new page number, the wizard creates a new page. If you identify an existing page number, the wizard adds the component to that page.

    2. Page Name - Enter a title for the page to be created.

    3. Page Mode - Select a page mode.

    4. Region Template - Select a region template for the new calendar region. The template controls the appearance of the region.

    5. Region Name - Enter a name for the region to contain the calendar.

    6. Display Type - Determines the behavior of the calendar. Options include:

      • Standard - Submits the page along with the associated request.

      • Partial Page Refresh - Only refreshes the Calendar region


      Tip:

      Once the calendar is created, the display type cannot be changed. To change the display type, you must delete the calendar and then re-create it.

    7. Breadcrumb - Select whether to use a breadcrumb navigation control on your page, and which breadcrumb navigation control you want to use.

    8. Click Next.

  5. For Navigation Preference, specify the type of navigation to include on this page and click Next. The navigation options (for example, navigation menu or tabs) depends upon the current application theme.

  6. For Source, select if the calendar source is a table or SQL query.

    If the Calendar source is table:

    1. Source - Select Table.

    2. Owner - Select the database schema that owns the table from which you are creating a calendar.

    3. Table/View Name - Specify the table to be used in the calendar.

    4. Click Next.

    If the Calendar source is SQL Query:

    1. Source - Select SQL Query.

    2. SQL Query - Enter the SQL SELECT statement to be used by the calendar. The SQL SELECT statement must include at least two columns, of which one must be a DATE column.

      For examples, see field-level Help.

    3. Click Next.

  7. For Calendar Attributes:

    1. Date Column - Specify which column is used as the date to place an entry on the calendar.

    2. Display Column - Specify the column to be displayed on the calendar.

    3. Date Format - Specify how you want to represent dates on your calendar. Options include:

      • Date Only - Results display in a monthly and list calendar.

      • Date and Time - Results display in a monthly, weekly, daily, and list calendar.

    4. Custom Date Range - Identify whether to include custom start and end dates. Use this option to enable more than one month to be represented on a monthly calendar.

    5. Click Next.

    Next, define Link Details for calendar entries. The Link Target determines where users are redirected to if they select a calendar entry.

  8. For Link Details:

    1. Link Target - Identify whether a calendar entry should have a link target. When a calendar entry is selected, the user is redirected to the link target. The selected Link Target determines what additional attributes display.

      To learn more, see field-level Help.

    2. Click Next.

  9. Click Create.

12.1.4 Managing Calendar Attributes in Page Designer


Tip:

When creating a calendar based on a SQL query, you must manually create an On Demand page process to enable drag and drop functionality. See "Enabling the Dragging and Dropping of Data In an Existing Calendar."

Once you create a calendar, you can alter the display by editing attributes in the Properties Editor. Each calendar has two sets of editable attributes: region attributes and calendar attributes. Region attributes define the area of the page which functions as a container for the calendar. Calendar attributes specify the template, date columns, and general calendar formatting.

12.1.4.1 Editing Calendar Attributes in the Property Editor

To edit calendar attributes:

  1. Navigate to the appropriate page in Page Designer. See "Viewing a Page in Page Designer."

    Page Designer appears

  2. In the Rendering tree, select the calendar title.

    The Property Editor displays the region attributes.

  3. In the Rendering tree, under the calendar title, select the Attributes node.

    The Property Editor displays the Calendar attributes.

  4. View all attributes in the Property Editor. Select Show All from the Property Editor Menu.

  5. Edit the region attributes:


    Tip:

    To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

  6. Click Save.

12.1.4.2 Editing an Existing Calendar to Include Add and Edit Functionality

When defining calendar create and edit links for Desktop applications, Oracle recommends defining two separate pages. For the page used for creating a new calendar entry the Page Access Protection should to be defined as Unrestricted. However, for the page used for editing existing calendar entries the Page Access Protection should be set to Arguments Must Have Checksum.

To edit an existing calendar to include add and edit functionality:

  1. Navigate to the appropriate page in Page Designer. See "Viewing a Page in Page Designer."

    Page Designer appears

  2. In the Rendering tree, under the calendar title, select the Attributes node.

    The Property Editor displays the Calendar attributes.

  3. View all attributes in the Property Editor. Select Show All from the Property Editor Menu.


    Tip:

    To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

  4. Under Create Link or View / Edit Link:

    1. Open Link In - Specify if the page or URL replaces the current page or opens in a dialog.

    2. Create Target - Click No Link Defined.

  5. In the Link Builder - Event Target dialog:

    1. Type - Select the type of target application: Page in this application or Page in a different application.

    2. Application - If you select Page in a different application, select the application.

    3. Page - Specify the target page number.

    4. Set Items:

      • Name - For Create Link enter start date column. For duration-based events also enter the end date column. For View/Edit Link enter the primary key column.


        Tip:

        The selected date column must have a format mask of RRRRMMDDHH24MISS since the calendar passes the date in that format.

        If you do not want to change the format mask of date item, you must create a hidden item (this hidden item should be selected as Date Item which accepts the date value) in the form page with the above format mask.


      • Value - For Create Link enter the substitution strings &APEX$NEW_START_DATE. and &APEX$NEW_END_DATE.. For View/Edit Link enter the appropriate substitution strings, such as &ROWID. or &ID..


        Tip:

        For Legacy Calendar use the substitution strings #DATE_VALUE# and #PRIMARY_KEY_VALUE#.

    5. Click OK.

  6. Expand Entry. From Primary Key Column, select the value to be passed when editing calendar data. This value is substituted for the #PRIMARY_KEY_VALUE# specified in the previous step.

  7. Click Save.

12.1.5 Managing Calendars in Component View

This section describes how to manage calendars in Component View.


Tip:

When creating a calendar based on a SQL query, you must manually create an On Demand page process to enable drag and drop functionality. See "Enabling the Dragging and Dropping of Data In an Existing Calendar."

12.1.5.1 Creating a Calendar in Component View

To create a Calendar in Component View:

  1. Create a Calendar region:

    1. Navigate to the page. See "Viewing a Page in Component View".

    2. Create a new Calendar region. Under Region, click the Create icon.

      The Create Region Wizard appears.

    3. Select Calendar and click Next.

  2. For Implementation, select Calendar and click Next.

  3. For Display Attributes:

    1. Title - Enter a title for the region. This title displays if the region template you select displays the region title.

    2. Region Template - Choose a template to control the appearance of the region.

    3. Parent Region - Defines the parent region to which the new region belongs.

    4. Display Point - Identify a display point for this region. To learn more, see field-level Help.

    5. Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.

    6. Click Next.

  4. For Source, select if the calendar source is a table or SQL query.

    If the Calendar source is table:

    1. Source Type - Select Table.

    2. Table/View Owner - Select the owner of the table on which you are building a calendar.

    3. Table/View Name - Select the table or view on which the calendar is based.

    4. Select Columns - Select one or more columns to be included in the calendar.

    5. Click Next.

    If the Calendar source is SQL Query:

    1. Source Type - Select SQL Query.

    2. Enter Region Source - Enter the SQL SELECT statement to be used for the calendar. The SQL SELECT statement must include at least two columns, of which one must be a DATE column.

      For examples, see field-level Help.

    3. Click Next.

  5. For Settings, accept the defaults and click Next.

    To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

  6. For Conditional Display:

    1. Condition Type - Select a condition type from the list that must be met in order for this component to be rendered processed.

    2. Authorization Scheme - Optionally select an authorization scheme which must evaluate to TRUE in order for this component to be rendered or otherwise processed.

    3. Click Create Region.

  7. Click Create.

12.1.5.2 Editing Calendar Attributes in Component View

Once you create a calendar, you can alter the display by editing attributes. Each calendar has two sets of editable attributes: region attributes and calendar attributes. Region attributes define the area of the page which functions as a container for the calendar. Calendar attributes specify the template, date columns, and general calendar formatting.


Tip:

To disable a view of a calendar, you must delete the Monthly, Weekly, or Daily buttons on the calendar page.

12.1.5.2.1 Accessing Calendar Attributes

To access Calendar attributes:

  1. Navigate to the appropriate page. See "Viewing a Page in Component View".

  2. Access the Region Definition page. Under Region, select the region name.

    The Region Definition appears. Use these attributes to alter the container that holds the calendar, including the region title.

  3. Click Calendar Attributes.

    The Calendar Attributes page appears.

  4. Edit the appropriate attributes.

    To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

  5. Click Apply Changes.

12.1.5.2.2 Editing an Existing Calendar to Include Add and Edit Functionality

When defining calendar create and edit links for Desktop applications, Oracle recommends defining two separate pages. For the page used for creating a new calendar entry the Page Access Protection should to be defined as Unrestricted. However, for the page used for editing existing calendar entries the Page Access Protection should be set to Arguments Must Have Checksum.

To edit an existing calendar to include add and edit functionality:

  1. Navigate to the appropriate Calendar Attributes page. See "Accessing Calendar Attributes."

  2. Scroll down to Create Link or View / Edit Link. Enter the URL.

    For example, a Create Link for a duration based event navigating to Page 3 would be:

    f?p=&APP_ID.:3:&SESSION.::&DEBUG.:RP,3:P3_START_DATE,P3_END_DATE:#APEX$NEW_START_DATE#,#APEX$NEW_END_DATE#:
    

    For example, a View / Edit Link using ROWID for the primary key column, navigating to Page 4 would be:

    f?p=&APP_ID.:4:&SESSION.::&DEBUG.:RP,4:P4_ROWID:&ROWID.:
    

    Tip:

    The selected date column must have a format mask of RRRRMMDDHH24MISS since the calendar passes the date in that format.

    If you do not want to change the format mask of date item, you must create a hidden item (this hidden item should be selected as Date Item which accepts the date value) in the form page with the above format mask.


  3. Scroll up to Calendar Display.

    From Primary Key Column, select the value to be passed when editing calendar data. This value is substituted for the #PRIMARY_KEY_VALUE# specified in the previous step.

  4. Click Apply Changes.

12.1.6 About the Date Column Format Mask

Because the calendar passes the date in specific format, the selected date column must have a format mask of RRRRMMDDHH24MISS. If you do not want to change the format mask of date item, you must create a hidden item (this hidden item should be selected as Date Item which accepts the date value) in the form page with the above format mask. The default value of the date column should be changed to:

return to_char(to_date(<hidden item created>,'RRRRMMDDHH24MISS'),<Date item format mask>);

Consider the following example:

return to_char(to_date(:P130_HIREDATE_TMP,'RRRRMMDDHH24MISS'),:APP_DATE_TIME_FORMAT);

The source type for default should be PL/SQL Function returning value.

12.1.7 Enabling the Dragging and Dropping of Data In an Existing Calendar

If you choose to enable drag and drop capability when you create a Desktop calendar, the generation process automatically defines PL/SQL code to implement this functionality.

For Legacy Calendars an On Demand process is required to enable the drag and drop functionality. This process is automatically created if you use the Create Page Wizard. In contrast, when you create a Legacy Calendar on a new page by running the Create Page Wizard, the Enable Drag and Drop option does not appear. To enable this functionality, you must create the On Demand process, create a calendar page, and then edit the page to enable drag and drop. As a best practice, Oracle recommends creating this process before creating the calendar.

To enable support for dragging and dropping of Legacy Calendar data:

  1. Edit the attributes for the calendar.

  2. Set Drag and Drop to Yes.

  3. Enter the appropriate PL/SQL Code using the substitution variables APEX$NEW_START_DATE, APEX$NEW_END_DATE and APEX$PK_VALUE.

    For example, for a duration based calendar use:

    begin
        update projects
           set start_date = to_date(:APEX$NEW_START_DATE, 'YYYYMMDDHH24MISS'),
               end_date = to_date(:APEX$NEW_END_DATE, 'YYYYMMDDHH24MISS')
         where id = :APEX$PK_VALUE;
    end;
    

12.1.8 About Supported Calendar Substitution Strings in Legacy Calendars

Application Builder supports many date format substitution strings. You can view a complete list of supported substitution strings on the Calendar Templates page.

To view a list of supported substitution strings for calendars:

  1. Navigate to the appropriate calendar template.

  2. View the Substitution Stings list on the right side of the page.