Getting Started

Requirements

  • jQuery 1.7.0 or above.
  • jQuery UI Core 1.8.6 or above.
    jQuery UI Core consists of the following components: Core, Widget, Mouse and Position. No other jQuery UI components are required.
  • Oracle Application Express 4 or above.
    APEX 4 uses jQuery 1.7.1 and jQuery UI Core 1.8.22 and therefore meets the required minimum version for both these libraries.

Browser Support

Instead of targeting an ever increasing plethora of specific browsers we simply craft thoroughly designed, meticulously developed products using the latest standards, best practices and progressive enhancements. Our products work best with modern browsers, but will accommodate older browsers to the most practical extent possible.

Installation

ProDatePicker Plugin consists of a plugin script and supporting files. For performance reasons the supporting files are not embedded in the plugin and must be hosted, typically in your APEX "images" folder. If you are not using your APEX "images" folder adapt the following instructions to your own environment.

Supporting files

The supporting files must be hosted on a web server. DO NOT upload the plugin script! Distributing the plugin script from a public web server, even accidentally, will be considered an infringement of copyright.

  1. Locate your APEX "images" folder and create a new folder silvercore if it does not already exist.
  2. Extract the folder from the zip file and copy it to the silvercore folder in your APEX "images" folder.

Plugin script

Plugin scripts are provided for APEX versions 4 and 5. Ensure you use the correct version for the version of APEX you are running.

  1. In APEX Application Builder choose the application into which you want to install the plugin.
  2. Go to Shared Components.
  3. Select Plugins under User Interface.
  4. Click Import.
  5. Click Choose file and select the plugin script.
  6. Confirm File Type is Plug-in and File Character Set is Unicode UTF-8.
  7. Click Next, and Next again.
  8. Confirm Install Into Application displays the correct application and click Install Plug-in.

File Prefix

The path to the supporting files is preconfigured in the plugin. Each time you update a plugin the File Prefix is overwritten with the value the plugin was exported with, therefore we recommend that you only change the preconfigured File Prefix if absolutely necessary. If you do, you will need to reinstate your File Prefix after every plugin update. The preconfigured File Prefix we have chosen includes a substitution string that must be set to create a valid path.

  1. In APEX Application Builder choose the application into which you installed the plugin.
  2. Click Edit Application Properties and locate the Substitutions section.
  3. Create a new substitution string SILVERCORE with a value of #IMAGE_PREFIX#silvercore/.

ProDatePicker Plugin is now ready to use.

Usage

Creating a ProDatePicker Plugin instance is the same as any other APEX item plugin.

  1. In APEX Application Builder choose the page on which you want to use the plugin.
  2. Create a new item and choose an Item Type of Plug-in.
  3. Select ProDatePicker from the list and click Next.
  4. Set Display Position and Name and click Next.
  5. Set Item Attributes and click Next.
  6. Set plugin Settings and click Next.
  7. Set the Source and click Create Item.

To set plugin options on an existing plugin instance, select the item and locate the Settings section.

ProDatePicker Plugin is an APEX wrapper for the ProDatePicker widget. For a full JavaScript API reference please refer to the ProDatePicker documentation.

Settings

Type

Default: Popup

This setting sets the type option of the ProDatePicker widget which defines the display mode of the widget.

  • Inline - the widget is inserted into the page immediately after the page item.
  • Modal - the widget is initially hidden and opens with a background overlay when the display input element receives focus.
  • Popup - the widget is initially hidden and opens as a drop down when the display input element receives focus.

Source Model

Type: String Default: "ISO_DATETIME"

This setting sets the sourceModel option of the ProDatePicker widget which is used when parsing and outputting string values of the page item.

The value can be a string literal or a substitution string and must use the Oracle Datetime Format. If a value is set it must exactly match the format mask of the page item value. If the value is omitted the following sources will be used to obtain a value:

  1. The Format Mask attribute of the page item.
  2. For page items with a source of Database Column:
    • APP_NLS_DATE_FORMAT when datatype is DATE.
    • APP_NLS_TIMESTAMP_TZ_FORMAT when datatype is TIMESTAMP WITH TIME ZONE.
    • APP_NLS_TIMESTAMP_FORMAT when datatype is TIMESTAMP or TIMESTAMP WITH LOCAL TIME ZONE.

For performance reasons it is recommended that at least the item format mask is set.

The widget is preconfigured to use the Oracle Datetime Format and supports the following format elements:

Case insensitive
DD, MM, YYYY, DDD, HH, HH12, HH24, MI, SS, FF, FF1, FF2, FF3, TZH, TZM, IYYY, IW, D, FM, FX, X, Q
Case sensitive
DAY, DY, MONTH, MON, AM, PM, A.M., P.M.

Display Model

Type: String Default:null

This setting sets the displayModel option of the ProDatePicker widget which defines the date and time format displayed to the end user and is used to automatically configure the widget as a date picker, time picker or date and time picker.

The value can be a string literal or a substitution string and must use the Oracle Datetime Format. If the value is omitted the value of Source Model is used.

The widget is preconfigured to use the Oracle Datetime Format and supports the following format elements:

Case insensitive
DD, MM, YYYY, DDD, HH, HH12, HH24, MI, SS, FF, FF1, FF2, FF3, TZH, TZM, IYYY, IW, D, FM, FX, X, Q
Case sensitive
DAY, DY, MONTH, MON, AM, PM, A.M., P.M.

Source Zone

Type: String | Number Default: ""

This setting sets the sourceZone option of the ProDatePicker widget which defines the time zone used to parse and output dates.

In its default configuration ProDatePicker manipulates dates and times in the end user's local time, therefore this option is invaluable when dates from multiple end user time zones need to be normalised (typically to UTC) before being stored in the database.

When the widget is initialised with a source value the string is parsed and its values are interpreted using the time zone offset set by this option instead of being interpreted in local time. This is useful if the source date time zone offset is known but not present in the source value, e.g. source dates that have been normalised but have been stored without time zone offsets. Time zone offset information contained within the source value itself will always override this option.

When the selected date is output to the page item the time zone offset set by this option is applied. This results in the output date being normalised to the set time zone offset.

Values must be one of the following:

String
A time zone offset in one of the following formats: ±HH24:MI, ±HH24MI, ±HH24 or ""Z" (UTC), e.g. "+01:00", "-0730", "-05"
Number
A time zone offset in minutes from UTC, e.g. 300 (i.e. "+05:00"), -60 (i.e. "-01:00")

If the time zone offset is part of the sourceModel and sourceZone is set to "Z" (UTC) the output string time zone offset will also be "Z". If a time zone offset of "+00:00" is required sourceZone can be set to either "+00:00" or 0 instead. This results in the exact same date and time but with a different time zone offset representation.

Default Date

Type: Array | String | Date | ProDate Default: null

This setting sets the defaultDate option of the ProDatePicker widget which defines the date and time on which the calendar is focused when the widget is initialised without a selected date. Setting null sets the default date to the date and time the widget was initialised, i.e. "now". If an APEX item name is set the value of the item will be used.

Minimum Date

Type: Array | String | Date | ProDate Default: null

This setting sets the minDate option of the ProDatePicker widget which defines the earliest selectable date and time. If null then there is no limit to the earliest selectable date and time. If an APEX item name is set the value of the item will be used.

By setting minDate to be another ProDatePicker using a jQuery selector the earliest selectable date and time is the selected date of the target widget. If no date is selected in the target widget then there is no limit to the earliest selectable date. ProDatePicker ensures that this link is created regardless of the initialisation order of widgets and dynamically updates the minimum date whenever the selected date of the target widget is changed. This feature enables easy pairing of ProDatePicker widgets to create dynamic date range pickers.

Maximum Date

Type: Array | String | Date | ProDate Default: null

This setting sets the maxDate option of the ProDatePicker widget which defines the latest selectable date and time. If null then there is no limit to the latest selectable date and time. If an APEX item name is set the value of the item will be used.

By setting maxDate to be another ProDatePicker using a jQuery selector the latest selectable date and time is the selected date of the target widget. If no date is selected in the target widget then there is no limit to the latest selectable date. ProDatePicker ensures that this link is created regardless of the initialisation order of widgets and dynamically updates the maximum date whenever the selected date of the target widget is changed. This feature enables easy pairing of ProDatePicker widgets to create dynamic date range pickers.

Time Step

Type: Number Default: 1

This setting sets the timeStep option of the ProDatePicker widget which defines the precision to which time is kept. The focused and selected dates are rounded down to the nearest number of minutes defined by timeStep. Additionally, the values displayed in the minute select element are limited to multiples of timeStep.

The value must be a number between 1 and 60 inclusive.

Year Range

Type: String Default: "focus-10:focus+10"

This setting sets the yearRange option of the ProDatePicker widget which defines the range of years displayed in the year select list. This option has no bearing on minimum and maximum selectable dates and only limits the number of year options available for performance and usability reasons.

The value must use a specific syntax in order to be parsed correctly. The format consists of a start year and an end year separated by a colon. Start and end years can be defined as either absolute or relative values:

Absolute years
Any 4 digit year
Relative years
An optional number of years, from -999 to 999 inclusive, to offset from one of the following base years:
  • "default" - the default year defined by the defaultDate option.
  • "today" - today's year.
  • "focus" - the focused date's year.

If the focused year falls outside the defined year range the year range will be extended to create a contiguous range of years that starts or ends with the focused year, so that the widget UI is always able to accurately display the focused date.

Number of Months

Type: Number | Array Default: 1

This attribute sets the numberOfMonths option of the ProDatePicker widget which defines the number of calendar months displayed and their layout.

The value must be either a number between 1 and 12 inclusive or an array of two numbers (rows, columns) with a product between 1 and 12 inclusive.

Examples

  • 5 - 5 consecutive months displayed horizontally.
  • [2,4] - 8 consecutive months displayed as 2 rows of 4 columns.

Pad Calendar

Default: No

This setting sets the padCalendar option of the ProDatePicker widget which forces each calendar to render 6 rows regardless of the number of weeks in the month, thereby normalising the height of the calendar and preventing the height of the widget from changing as the calendar is updated.

Show Week

Default: No

This setting sets the showWeek option of the ProDatePicker widget which displays ISO week numbers in the calendar.

Locale

Type: String Default: "en"

This setting sets the locale option of the ProDatePicker widget which defines the language used for the widget UI, month and day names in dates and other country-specific date and time preferences. The value must be a language code that uses the same syntax used by the HTTP Accept-Language header: ISO 639-1 language code optionally followed by a hyphen separated ISO 3166-1 alpha-2 country code, e.g. en-gb English (United Kingdom), es-ar Spanish (Argentina), fi Finnish etc.

If a comma separated list of values is set the first value that matches an available locale is used. This means the value obtained from the HTTP Accept-Language header can be used to set this option. If a value contains a country code in addition to a language code an exact match is sought first and if no match is found the language code is tried without the country code. If a value is set that does not correspond to any available locales then the generic English locale is used.

Theme

Type: String Default: "silvercore"

This setting sets the theme option of the ProDatePicker widget which defines the theme class applied to the widget, display <input> and modal overlay. The theme class is the string "prodatepicker-theme-value". For this option to have any effect, related CSS styles that make use of the theme class must be present. Setting the widget theme using this option enables multiple themes to be loaded at once and applied to individual ProDatePicker instances independently of each other, or even for themes to be switched after initialisation.

Other Options

Type: Object Default: null
In APEX 5 you must Show All plugin settings to edit this setting.

This setting allows ProDatePicker widget options to be set directly. Since the ProDatePicker widget has more options than there are custom attributes for item plugins in APEX, only a limited number of options can be exposed through plugin settings. Other options can be set using JavaScript object key/value pairs (the JavaScript object curly brackets should not be used as they are generated by the plugin). View all ProDatePicker options.

Options set in Other Options will override options set by plugin settings. More advanced configurations can be achieved by setting widget options directly instead of using plugin settings.

Events

JQuery UI Widget Factory, on which ProDatePicker is built, provides inbuilt functionality to trigger widget events and when used this way generates event names automatically. However, these generated event names are different for different verions of jQuery UI and are slated to change again in the future:

widgetEventPrefix: The prefix prepended to the name of events fired from this widget. For example the widgetEventPrefix of the draggable widget is "drag", therefore when a draggable is created, the name of the event fired is "dragcreate". By default the widgetEventPrefix of a widget is its name. Note: This property is deprecated and will be removed in a later release. Event names will be changed to widgetName:eventName (e.g. "draggable:create").Widget Factory | jQuery UI API Documentation

In order to create a more stable widget, regardless of the version of jQuery UI Widget Factory running, ProDatePicker always triggers events with names using the format widgetname:eventname (lowercase). Therefore, you should always use the event names as documented, not the event name you might expect to use based on the version of jQuery UI running.

An event can be handled by binding a function to the widget element using an event handler or by passing a function to the callback option on or after initialisation. Both methods can be used together on the same widget. When an event is triggered the bound event handlers are invoked before any callbacks are executed. Either method can be used to cancel a cancellable event, either by calling e.preventDefault() or returning false. If a handler and a callback are bound to the same event and the handler cancels the event, the callback is still executed.

Created

Type: "prodatepicker:created" Cancellable: No

Triggered after the widget has been created.

Due to the order in which APEX 4 initialises dynamic actions and executes plugins this event cannot be used by dynamic actions targeting ProDatePicker Plugin instances. However, it can be used by dynamic actions targeting manually invoked ProDatePicker widgets provided care is taken to invoke such widgets after dynamic actions have been initialised.

Data

Event data is available to dynamic actions through the this object.

this.data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
this.data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.

Focused

Type: "prodatepicker:focused" Cancellable: No

Triggered after a date is focused.

Data

Event data is available to dynamic actions through the this object.

this.data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
this.data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.

Selected

Type: "prodatepicker:selected" Cancellable: No

Triggered after a date is selected.

Data

Event data is available to dynamic actions through the this object.

this.data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
this.data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.