11.3 Creating Calendars

App Builder includes support for creating 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.

• About Supported Calendars
  App Builder supports two types of calendars: Calendar and Legacy Calendar.
• Sample Calendar
  You can view a sample calendar by installing the sample application, Sample Calendar.
• Adding a Calendar to a New Page Using a Local Database
  Run the Create Page Wizard to create a new page with a calendar using a local database.
• Adding a Calendar on a New Page Using External Data Sources
  Use the Create Page Wizard to add a new page with a calendar that uses an external data source.
• Creating a Calendar in Page Designer
  Manually create a calendar in Page Designer by providing the SQL query.
• Managing Calendar Attributes
  Once you create a calendar, you can alter the display by editing attributes in the Property Editor.
• About Dynamic Action Support for Calendar
  Use the Dynamic Action Create Wizard to specify an action that is performed when a defined set of conditions occur. You can specify which elements are affected by the action and when and how they are affected.

See Also:

"Managing Legacy Calendars" and "Integrating with Google Calendar"

11.3.1 About Supported Calendars

App Builder supports two types of calendars: Calendar and Legacy Calendar.

Calendar is based on the FullCalendar jQuery library and can only be customized through CSS. Legacy Calendar is template-based and may 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 and Legacy Calendar 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. Drag and drop is only supported for local data sources, that is, database objects in the referenced database schema and not on external data sources such as a Google calendar.

• 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 web service 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.

See Also:

"Managing Legacy Calendars"

11.3.2 Sample Calendar

You can view a sample calendar by installing the sample application, Sample Calendar.

The following is Monthly Calandar: Projects from the Sample Calendar sample applications.

Description of the illustration calendar_example.png

Features of this calendar include:

• 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:

To see more calendar examples, install the Sample Calendar application. See "Installing a Productivity and Sample App"

11.3.3 Adding a Calendar to a New Page Using a Local Database

Run the Create Page Wizard to create a new page with a calendar using a local database.

To create a calendar on a new page using a local database:

1. Run the Create Page Wizard:
   1. Navigate to the Workspace home page.
   2. Click the App Builder icon.
   3. Select an application.
   4. On the Application home page, click Create Page.
      The Create Page Wizard appears.
2. For Create a Page:
   1. User Interface - Select a user interface for the page (optional).
      This attribute only displays for applications using older themes and for which Desktop and Mobile User Interfaces have been defined.
   2. Select a page type - Select Calendar.
3. For Page Attributes:

   Tip:

   To learn more about an attribute, see field-level Help. See "Viewing 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. Page Group - Identify the name of the page group you would like to associate with this page. 
   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.
4. 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.
5. For Data Source, select Local Database.
6. For Source Type, do one of the following:

   • If the source is a 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 a 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.

     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 display.
   5. Click Create.

11.3.4 Adding a Calendar on a New Page Using External Data Sources

Use the Create Page Wizard to add a new page with a calendar that uses an external data source.

The component(s) described in this topic include built-in support for REST Enabled SQL and REST Data Sources which enables read and write access to remote data sources. In order to build a component on a remote data source, you must first create the application and configure the external data source.

Tip:

To learn more about external data sources, see "Managing REST Enabled SQL References" and "Managing REST Data Sources."

To create a calendar on a new page using an external data source:

1. Run the Create Page Wizard:
   1. Navigate to the Workspace home page.
   2. Click the App Builder icon.
   3. Select an application.
   4. On the Application home page, click Create Page.
      The Create Page Wizard appears.
2. On Create a Page:
   1. Page Type - Select Component.
   2. Click Calendar.
3. For Page Attributes:

   Tip:

   To learn more about an attribute, see field-level Help. See "Viewing 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. Normal presents the page as a normal Application Express application page. Modal Dialog presents the page as an overlay window positioned which remains active and focused until the end user dismisses (closes) it. The underlying page is grayed out and the end user is prevented from interacting with the rest of the page until the dialog is closed.
   4. Page Group - Identify the name of the page group you would like to associate with this page. 
   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.
4. 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.
5. Select a data source. Options include:

   • Local Database - Data is sourced from a local database.

   • REST Enabled SQL Service - Data is sourced from a remote database, where the connection is defined using REST Enabled SQL. To create or maintain REST Enabled SQL references, navigate to Shared Components, REST Enabled SQL.

   • REST Data Source - Data is sourced from a RESTful web service defined using REST Data Sources. REST Data Source are created and maintained within Shared Components.

   For Data Source, select either REST Enabled SQL Service or REST Data Source.

6. What displays next changes based on your selection. Follow the on-screen instruction. To learn more about an attribute, see field-level Help.
7. To view the new master detail, click Save and Run Page.
   The rendered page appears.

11.3.5 Creating a Calendar in Page Designer

Manually create a calendar in Page Designer by providing the SQL query.

Tip:

To create a calendar in Page Designer, you must provide a SQL Query. To create a calendar by selecting a table, use the Create Page Wizard. See "Adding a Calendar to a New Page Using a Local Database".

To create a calendar in Page Designer:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. If necessary, click the Layout tab in the central pane.
3. In the Gallery, click the Regions tab.
4. Right-click Calendar, click Add To, and select the appropriate location.

   Tip:

   You also select Calendar with the mouse and drag it to the appropriate location in the Layout tab.

5. Page Designer indicates what to do next. If there is an error, the Show Messages icon displays in the Page Developer toolbar.
   1. Click the Show Messages icon on the Page Designer toolbar.
      The Messages dialog displays errors that must be addressed.
   2. Select an error to highlight the associated attribute in the Property Editor.
6. In the Property Editor, edit the appropriate Region attributes:

   • Identification, Title - Enter a region title.

   • Source, Location - Select the location of the database which contains column which holds the CSS Class to style the events displayed on this calendar. Options include:

     • Local Database - Data is sourced from a local database.

     • REST Enabled SQL - Data is sourced from a remote database where the connection is defined using a REST Enabled SQL service.

     • REST Data Source - Data is sourced from a RESTful web service defined using REST Data Sources. REST Data Source are created and maintained within Shared Components.

     What displays next depends upon Source, Location you select.

     Tip:

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

7. Edit the calendar Attributes.

   • In the Rendering tab, locate the Calendar region and click Attributes.

     The Property Editor displays the calendar Attributes.

   • Edit the calendar Attributes:

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

     • Settings, Start Date - Select the column which holds the start date for events displayed on this calendar.

8. Click Save.

11.3.6 Managing Calendar Attributes

Once you create a calendar, you can alter the display by editing attributes in the Property Editor.

Each calendar has two sets of editable attributes: Region attributes and calendar Attributes.

• Editing Calendar Attributes in the Property Editor
  Access calendar attributes in the Property Editor.
• Editing an Existing Calendar to Include Add and Edit Functionality
  Edit and existing calendar to include add and edit functionality.
• Adding Calendar Initialization JavaScript Code
  Add a JavaScript function to override the standard jQuery FullCalendar initialization attributes by editing the Initialization JavaScript Code attribute.
• Enabling the Dragging and Dropping of Data in an Existing Calendar
  The Calendar Region supports moving or changing calendar events with drag and drop.

11.3.6.1 Editing Calendar Attributes in the Property Editor

Access calendar attributes in the Property Editor.

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.

To edit calendar Attributes:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In the Rendering tab, locate and select the calendar.
   The Property Editor displays two tabs: Region and Attributes.
3. In the Property Editor, select the appropriate tab:
   • Region - Region attributes define the area of the page which functions as a container for the calendar.
   • Attributes - Calendar Attributes specify the template, date columns, and general calendar formatting.
4. Edit the calendar attributes.

   To view help for an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

5. To save your changes click Save. To save and run the page, click Save and Run Page.

11.3.6.2 Editing an Existing Calendar to Include Add and Edit Functionality

Edit and existing calendar to include add and edit functionality.

Tip:

When defining calendar create and edit links for Desktop applications, Oracle recommends defining two separate pages. To create an Edit Link, select one of the table or SQL query columns as the Primary Key Column in the Calendar attributes.

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

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In the Rendering tab, locate and select the calendar.
3. In the Property Editor, click the Attributes tab.
   The Property Editor displays the calendar Attributes.
4. Edit Settings, Create Link to specify a target page to call when the user clicks an empty cell or an existing calendar entry.

   1. Settings, Create Link - Click No Link Defined.

      The Link Builder - Create Link dialog appears.

   2. Type - Select the type of link target.

   3. Application - If you select Page in a different application, enter the application ID.

   4. Page - Specify the target page number.

   5. Set Items - Configure the values to be passed from the calendar to the target page. The Create Link is called after a date or date range has been selected in the calendar. Therefore, the selected start and end dates must be passed to the Create Page.

      • To pass the selected date or the start date of a selected date range:

        • Name - Specify the name of the target page item containing the start date of the event. If a form, this should be a date picker element.

        • Value - &APEX$NEW_START_DATE.

      • When a date range has been selected, pass the end date as follows:

        • Name - Specify the name of the target page item containing the end date of the event. For a form, this should be a date picker element.

        • Value - &APEX$NEW_END_DATE.

          You can pass additional values in the same way as any other link to an application page.

        • Click OK.

   Tip:

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

5. Edit Settings, Edit Link to define a target page to be called when the user clicks an existing entry.

   Tip:

   To create an Edit Link, you must pass a primary key value to the target page in order for the form to look up the table row.

   1. Settings, Edit Link - Click No Link Defined.

      The Link Builder - Create Link dialog appears.

   2. Type - Select the type of link target.

   3. Application - If you select Page in a different application, enter the application ID.

   4. Page - Specify the target page number.

   5. Set Items - Configure the values to be passed from the calendar to the target page. The Create Link is called after a date or date range has been selected in the calendar. Therefore, the selected start and end dates must be passed to the Create Page.

      • Name - Specify the name of the target page item containing the primary key value; typically a hidden item, for example:

        PX_ID.

      • Value - Specify the table or SQL query column containing the primary key value, for example:

        &ID.

      • Click OK.

6. Click Save.

11.3.6.3 Adding Calendar Initialization JavaScript Code

Add a JavaScript function to override the standard jQuery FullCalendar initialization attributes by editing the Initialization JavaScript Code attribute.

Note that the function must return a JavaScript Object containing the calendar initialization attributes as parameters.

To add initialization JavaScript code:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In the Rendering tab, locate and select the calendar.
   The Property Editor displays Region attributes.
3. In the Property Editor, click the Attributes tab.
   The Property Editor displays the calendar Attributes.
4. Find Advanced.

   Tip:

   To search for a group or an attribute, enter a keyword in the Filter Properties field. The groups and attributes containing the term appear.

5. In Advanced, Initialization JavaScript Code, enter a JavaScript function to override the standard jQuery FullCalendar initialization attributes.

   For example:

   function ( pOptions) {
       pOptions.titleFormat      = "[Conference Schedule]";                  // custom title
       pOptions.minTime          = "07:00:00";                               // hide slots before minTime
       pOptions.maxTime          = "18:00:00";                               // hide slots after maxTime
       pOptions.columnFormat     = {month: '', week: 'dddd', day: 'dddd'};   // week view column headings
       pOptions.slotDuration     = "00:15:00";                               // custom slot duration
       pOptions.weekNumbers      = true;                                     // show week numbers
       pOptions.weekNumberTitle  = "CW";                                    
       return pOptions;
   }

6. Click Save.

Note:

To view examples of this functionality, run the Sample Calendar sample application. From the Navigation menu, select Custom Calendar Initialization. See "Installing a Productivity and Sample App."

11.3.6.4 Enabling the Dragging and Dropping of Data in an Existing Calendar

The Calendar Region supports moving or changing calendar events with drag and drop.

To enable support for drag and drop for a calendar region:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In the Property Editor, click the Attributes tab.
   The Property Editor displays the calendar Attributes.
3. Find Settings and edit the following attributes:

   1. Settings, Primary Key Column - Select a table or SQL Query column.

      The Drag and Drop field appears in the Property Editor, below Additional Calendar Views.

   2. Settings, Drag and Drop - Select On.

      Drag and Drop PL/SQL Code appears.

   3. Settings, Drag and Drop PL/SQL Code - Enter the PL/SQL code to execute when the end user finishes a drag and drop for an event.

       Within the PL/SQL code, you can reference the ID of the dragged event, the new start, and end end dates as:

      :APEX$PK_VALUE, :APEX$NEW_START_DATE amd :APEX$_NEW_END_DATE

      For example, the following code changes the event row in the PROJECTS table after the end user has dragged the event to a new date.

      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;

      To learn more, click the Help tab in the central pane.

4. Click Save.

11.3.7 About Dynamic Action Support for Calendar

Use the Dynamic Action Create Wizard to specify an action that is performed when a defined set of conditions occur. You can specify which elements are affected by the action and when and how they are affected.

Dynamic actions provide a way to define complex client-side behavior declaratively without the need for JavaScript. When working with dynamic actions, you should be mindful of the fact that the more dynamic actions you add to a page, the greater your overall page size. This is because the dynamic action framework emits additional code to the client for each dynamic action defined, which then also must be downloaded and executed by the framework in the client.

Dynamic actions contain a condition that can be specified to control the action. Oracle Application Express components such as reports or charts can react to specific calendar events. For example, if you view a calendar and click a button to view a subsequent month, you can create a dynamic action to automatically refresh an associated report.

To use this feature the developer creates a new dynamic action on the Calendar page in Page Designer. Select the new dynamic action in the Dynamic Action tab in the left pane of Page Designer. Once created, the new dynamic action displays in red with the label New. Then, the developer edits the dynamic action attributes in the Property Editor. In Property Editor, locate and expand When attribute. Under the When attribute, for Event, select one of the following events:

• Date Selected [Calendar]

  This event fires when the user selects an empty date or date range either with the mouse or with the keyboard. If the developer provides a "create link" in the calendar attributes, no event fires.

  Information about the current view is being passed as the "data" object:

  { "newStartDate"::: "newEndDate"::: }
  
  { "newStartDate":{first day of selection} (YYYYMMDDHH24MISS),
   "newEndDate": {last day of selection} YYYYMMDDHH24MISS }

• Event Selected [Calendar]

  This event fires when the user clicks an existing event with the mouse or selects it with the keyboard. When the developer provided an "edit link" in the Calendar attributes, no event is being fired. The "data" object contains the jQuery FullCalendar JSON representation of the event.

  See Also:

  Full Calendar documentation Event Data, "Event Object"

• View Changed [Calendar]

  This event fires when either the view type changes (day, week, month, list) or when the view changes to its previous or next view page. The "data" object contains the following information:

  { "viewType": {view type, day, week, month or list},
   "startDate": {first day of view} (YYYYMMDDHH24MISS),
   "endDate": {last day of view} (YYYYMMDDHH24MISS) }

Note:

To view examples of this functionality, run the Sample Calendar sample application. From the navigation menu, select the Calender and Dynamic Actions and select the calender event. See to "Installing a Productivity and Sample App."

See Also:

"Managing Dynamic Actions" and "Debugging Dynamic Actions" for information on how to debug problems