Pretius APEX Date range

Oracle APEX item plugin

The plugin is Oracle APEX item plugin providing new date picker supporting range of dates. The plugin is dedicated to work with Oracle APEX Universal Theme. Behaviour and appeareance of the plugin can be changed with various settings.

The plugin is implemented on top of the Dan Grossman's javascript plugin "Date Range Picker". Not all functionalities of the original plugin were implemented in Pretius APEX Date Range plugin.

License

This plugin is currently available for use in all personal or commercial projects under MIT license. License has been included with this software.

Legal Disclaimer

The program(s) and/or file(s) are supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author takes no responsibility, assumes no liability for damages, direct or consequential, which may result from the use of these program(s) and/or file(s).

Documentation

Detailed documentation, usage guide, roadmap ang version changelog is available at Pretius GitHub repository.

Live demo

The demo presents functionalities of the plugin in action. Inspect all described examples to understand how the plugin works.

Modes

The plugin works in three modes:
  • One field
  • Two fields
  • Two fields - alternative
Each mode has same extra settings which can be previewed in sections Predefined quick picks and settings of this demo.

One field

Basic plugin mode, where the plugin is defined as one field which means both dates (start and end) are returned to APEX item separated with - string.

Two fields

In Two fields mode the plugin requires reference to another APEX item (text field). After selecting range of dates, ending date is returned to specified text field APEX item.

When items don't have values, clicking date to results in showing date picker for item representing a starting date. When items have values set, clicking date to results in showing date picker for item representing ending date - clicking on a date in calendars starts a new range of dates.

Two fields - alternative

The Two fields - alternative mode is similar to Two fields except that clicking on Date to item results in selecting only ending date of the range. Click on Date from item, select range of dates and then click Date to item. Clicking on date after starting date results in selecting new ending date.

Predefined quick picks

Quick pick(s) are defined as JSON object (Quick pick(s) attribute). JSON object keys represent available quick pick labels. Each key is defined as Array with two elements - start and end of a predefined range. Start and end date are instances of Moment.js JavaScript library. To learn more about Moment.js visit its home page.

Only quick picks

Selecting Settings > Quick pick(s) and Appearance > Quick pick(s) without calendar results in showing only defined quick picks. User can't select different range than defined by the developer.

Quick picks with custom selection

Similar to Only quick picks example but with Custom range declared to be shown. The custom label allows a user to define his own date range.

Quick picks with calendars visible

Selecting only Settings > Quick pick(s) results in displaying calendars and quick picks.

Example of quick pick(s) JSON

{ 
  'Today': [
    moment(), 
    moment()
  ],
  'Yesterday': [
    moment().subtract(1, 'days'), 
    moment().subtract(1, 'days')
  ],
  'Last 7 Days': [
    moment().subtract(6, 'days'), 
    moment()
  ],
  'Last 30 Days': [
    moment().subtract(29, 'days'), 
    moment()
  ],
  'This Month': [
    moment().startOf('month'), 
    moment().endOf('month')
  ],
  'Last Month': [
     moment().subtract(1, 'month').startOf('month'), 
     moment().subtract(1, 'month').endOf('month')
  ]
}

Settings

Examples are implemented using One field mode. Item settings can be mixed together and used in every mode (One field, Two fields, Two fields - alternative).

Default settings

Default settings of the plugin. None option is selected.

Auto apply

When this option selected, buttons Apply and Cancel are not visible. Selecting range of dates automatically set item(s) value.

Show days of other months

When this option selected, plugin renders starting/ending days of next/previous month.

Single calendar

When this option selected, plugin renders only one month.

Link calendars

When this options selected, plugin renders months one after the other. Using navigation arrows results in presenting consecutive months.

Show calendar inputs

When this option selected, plugin renders inputs for date and timpepicker*.

*Timepicker is rendered when proper date mask is applied. Different time masks renders diffrent elements.

Show month as dropdown

When this option selected, plugin renders month and year names as select lists. Selecting month or year results in jumping to the selected month / year.

Show week numbers

When this option selected, plugin renders week numbers as first column in each calendar.

Maximum and minimum date

When this option selected, plugin uses Minimum date and Maximum date attributes to narrow available range of dates. In this example Minimum date and Maximum date are defined as +1m and -1m. It means user can't pick date older then current day - 1 month and younger then current day+1 month. The attributes can be specified as static date in format YYYY-MM-DD.

To learn more read inline APEX help for those attributes

Date limit

When this option selected, plugin uses Date limit attribute to narrow range of dates to given number of dates. Narrowing range starts after picking first date.

In this example you can't pick period longer then 7 days.

Dynamic actions integration

In this example, you can test plugin integration with basic dynamic actions.

One field mode

Two fields mode

Date from is the plugin instance and it has reference to Date to APEX item (text field) via Date to item plugin attribute. In result Date to's dynamic action integration is overriden by the plugin. Disabling, enabling the item results in same effect as it is in plugin instance.

In Two fields mode plugin support dynamic dates for Set vale true action. It means you can set static date with proper format (eg. 2016-12-11) or date depending on current date (eg. +1w+2d = trunc(SYSDATE)+7+2).

Positions

The plugin supports 6 positions for calendars in relation to the APEX item: Top left, Top center, Top right, Bottom left, Bottom center and Bottom right

Position declared in Display options attribute is prefered. It means that if there is no space (above / below or left / right to the APEX item) for calendar, the plugin will try to fit calendars to the current position and available space. If the plugin can't find position allowing all elements to be in-line, the plugin displays elements in one column one by one.

Component settings

Component settings can be changed in Sharec components > Plugins > Pretius APEX date range > Component Settings.

First day

Default value is 1.

Use this attribute to determine which day of week should be rendered as first day of the week. While default day names are defined as Mo,Tu,We,Th,Fr,Sa,Su, default value 1 refers Mo. Value 7 refers Su.

Button classes

Default value is t-Button t-Button--small

Use this attribute to determine what classes will be applied to date picker buttons.

Apply class

Default value is t-Button--hot

Use this attribute to determine what classes will be applied to Apply button.

Cancel class

Default value is t-Cancel

Use this attribute to determine what classes will be applied to Cancel button.

Translations

Adding new translation

To add new translation (ie. polish names of days) follow steps:
  1. Select application
  2. Go to Shared Componentes> Globalization > Text Messages
  3. Click button Create Text Message
  4. Set new message as:
    • Name = PRETIUS_DATERANGEPICKER_DAYS
    • Language = Polish (pl)
    • Text = Nd,Pn,Wt,Śr,Czw,Pt,So
    • Click button Create Text Message
  5. Repeat steps 3 and 4 to add more tranlated text

Translatable plugin elements

Translatable plugin texts are presented on image below.

List of translatable plugin elements

PRETIUS_DATERANGEPICKER_DAYS

Names of days separated witm coma. Default value is set to Su,Mo,Tu,We,Th,Fr,Sa

PRETIUS_DATERANGEPICKER_MONTHS

Names of months separated witm coma. Default value is set to January,February,March,April,May,June,July,August,September, October,November,December

PRETIUS_DATERANGEPICKER_APPLYLABEL

Label of button confirming selected date range. Default value is set to Apply.

PRETIUS_DATERANGEPICKER_CANCELLABEL

Label of button closing date range picker. Default value is set to Cancel.

PRETIUS_DATERANGEPICKER_CUSTOM_RANGE

Label of quick pick used to select custom date range. Default value is set to Custom.

PRETIUS_DATERANGEPICKER_WEEK_LABEL

Header for column presenting week numbers. Default value is set to W.

Download

Please click on the button below

 

About the author

Bartosz Ostrowski
Bartosz Ostrowski

Oracle Application Express, PL/SQL and Frontend developer. IT consultant experienced in developing database and web applications using Oracle Application Express.
Oracle APEX enthusiast, plugin developer and active community member.

release 1.0 Set Screen Reader Mode On