Wednesday, 16 December 2009

JQuery Datepicker

Recent suggestions indicate that JQuery will be included as one of many new features in Apex 4.0, so why not start having a play with it now?

Take the example of the JQuery datepicker. The original date picker that comes with Apex reminds me of web applications from yesteryear, and it's welcoming to see a feature that feels integrated with the web page.

The documentation for these features are thorough and at first glance can seem a little overwhelming, so why not illustrate an example specifically for Apex? There are a few sets of instructions out there in the Apex blogging world, but this is what I found useful when I wanted to experiment with the features, plus a few thoughts of my own.

1) Download the bundle of components from
Here you can select the theme your interested in - perhaps match it up with the theme you're using for your Apex application. You can also select what components are going to be included. If you want to keep your application light, deselect those you do not need, or you can prepare multiple copies and attached the relevant ones to the relevant pages in your application - you have a few options for this I'll mention shortly.

The download will also include an index.html to the development-bundle folder, allowing you to demonstrate with a local copy of the scripts.

2) Make the files visible to your workspace.
The following files are a must for the components to work
jquery-1.3.2.min.js -- this represents the functionality core to jquery, all components will need this script
jquery-ui-1.7.2.custom.min.js -- this will include any components you've checked in the build stage on the JQuery website
jquery-ui-1.7.2.custom.css -- this of course represents the theme you selected. Without it things will look a little strange.

If you're working with the embedded PL/SQL gateway, you will need to upload the files as Static Files or Images in Shared Components. By the looks of the CSS, JQuery doesn't seem to be built to easily adapt to this Apex setup, so you may have difficulties incorporating the images. If you wish to use JQuery, I'd suggest using Apache.

If you're working with Apache, they will need to reside somewhere in your /i/ folder. Note the images will need to be in a folder called ./images, relative to the location of the CSS file.
ie -

3) Include the scripts as part of your page
When referring to file locations, Apache will refer to #IMAGE_PREFIX#, and the embedded gateway to #WORKSPACE_IMAGES#
Further to this, it would be better practice to store your file location in a computed application that will return the relevant file location depending on your environment, for instance:
<script src="&F_FILE_LOCATION.jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="&F_FILE_LOCATION.jquery-ui-1.7.2.custom.min.js" type="text/javascript"></script>
<link type="text/css" rel="stylesheet" href="&F_FILE_LOCATION.jquery-ui-1.7.2.custom.css" />
Some people choose to place this within the template, others like to include it in page zero where it may be conditionally included in various pages. This condition could be to include the JQuery scripts only on pages that utilise it. If you want to be really specific, you can include different scripts representing different components. You don't need to use the custom script you generated, you could refer to the specific .js files as required - check out the documentation for further tips.

4) Invoke the JQuery code
Within the page that will utilise the JQuery feature, you need to invoke the relevant function during page load. Again there are a few options here:
a) Include the following script in the source of the page
<script type="text/javascript">
    showOn: "both",
    buttonImage: "#IMAGE_PREFIX#asfdcldr.gif",
    buttonImageOnly: true,
    showOn: 'button',
    dateFormat: 'dd-m-yy'

Edit - modified dateFormat to match documentation.

And apply to the item's HTML Form Element Attributes property:

b) Include the same code, but in the highlighted line 10, add referenced to your selected items:

c) Or apply the date picker to all items in the application
<script type="text/javascript">
  // Convert all Datepickers to a jQuery DatePicker
  // Remove the native Oracle Apex DatePicker and add JQuery one
    { dateFormat : 'dd-mon-yyyy'
    , showOn : 'button'
    , buttonImage: "#IMAGE_PREFIX#asfdcldr.gif"
    , buttonImageOnly : true

And voila! You'll have applied a JQuery component to your application. Why not start playing with other widgets?

Stay tuned for the implementation process come Apex 4.0

No comments: