Documentation

Overview
Understanding how the Plugin works and what it does

The APEX Builder Plugin provides the infrastructure and the APIs to enhance the existing web based interface of the Oracle APEX Builder IDE.

General Enhancements

Each time when you open a page in the Oracle APEX Builder, which belongs to application 4000, the Plugin does some general enhancements to the Oracle APEX Builder page like

  • Making all textareas resizable. (Watch the video)
  • Automatically adjusts the width of all textareas.
  • Split the "Display As" select list of a page item.
  • Add quick pick links to the "Display As" select list of a report column.
  • Enable navigation with cursor up/down in tabular forms like "Bulk Page Item Changes" or Ctrl+cursor left/right on pages with a [<] or [>] button.
  • Highlight the "Comment", "Configuration/Build Option", "Conditions" or "Security" anchor if the related properties are set.
  • And so on. For a full feature overview see the main page.
All the above enhancements can be disabled in the "APEX Builder Plugin Settings".

Dynamic customization

The Plugin also tries to download additional configuration files which can contain API calls and Javascript commands to customize the current page even further. The APEX Builder Plugin provides simple to use API's for

  • Defining keyboard shortcuts for buttons, links, fields. (See Keyboard API)
  • Change the background of the page depending if you are on a production or development system. (See screencapture)
  • Define "Set" operations to change multiple fields/properties with just a single click. (Watch the video)
  • Seamless integration of the ApexLib Framework settings. (See related blog posting)
  • Whatever you want to do to manipulate the DOM tree of the current page.

Configuration files used

The Plugin is looking for the following files when one of the pages of the Oracle APEX Builder is loaded.

FilenamePurpose
apex_builder_plugin.js System wide configuration like defining general keyboard shortcuts or setting the background.
apex_builder_plugin_[apex-builder-page#].js Configuration which is specific for that page. For example "Set" operations or page specific keyboard shortcuts.
apex_builder_plugin_[current-appl#]_
[apex-builder-page#]
.js
Configuration which is specific for the current application you are working on. For example "Set" operations which are only valid for that application.
apex_builder_plugin_[apex-builder-page#]_
apexlib.js
Configuration for the integration of the ApexLib Framework.
Note: This is a separate download from the ApexLib Homepage.
The files can exist, but do not have to exist. If you don't need a specific file type, just disable loading the file in the "APEX Builder Plugin Settings". This will improve performance, because it prevents unnecessary calls to your web server.

In the configuration files you can use normal Javascript commands, but you also have access to the powerful jQuery framework and to the APIs the Plugin provides.

Example Configuration

The example configuration which comes with the Plugin, should give you a good start on adapting the Oracle APEX Builder to meet your own needs.

System wide Examples

The system wide config\apex_builder_plugin.js file contains code to

  • Set a background image to indicate that you are on a production system. (Note: You have to remove the comment to enable this feature.)
  • Assign keyboard shortcuts to common functions like
    • F8 to run the page
    • F10 for "Apply Changes". (Note: You have to change the value for other languages!)
    • Ctrl+cursor-left to go to the previous page/page item/column
    • Ctrl+cursor-right to go to the next page/page item/column
    • Alt+1, Alt+2 and Alt+3 to be used on the report pages to activate the different tabs

For an explanation on how you can use the Keyboard APIs, see the Assigning Keyboard Shortcuts section.

Page specific Examples

The page specific configuration files contain examples for the "Set" feature. Like for

  • Date Pickers, to sets all the necessary properties with one click.
  • Label adjustments.
  • Repadding of sequence numbers.
  • And so on. Just explore the different pages of the APEX Builder to see what is available.

For an explanation on how you can use these APIs, see the detailed "Set" feature API documentation.

Assigning Keyboard Shortcuts

Keyboard shortcuts can be assigned to buttons, links or fields. The following API is used to do that.


ApexBuilderPlugin.assignKey
  ( pObject         // DOM object identifying the button, link, ... or
                    // a Javascript function which should be executed
  , pKeyCode        // key code like 121 for F10
  , pCtrlKey        // true or false to indicate if Ctrl has to be pressed
  , pShiftKey       // true or false to indicate if Shift has to be pressed
  , pAltKey         // true or false to indicate if Alt has to be pressed
  , pMetaKey        // true or false to indicate if the Windows/Mac key has to be pressed
  , pDescription    // A description for the key shortcut.
                    // Used in Key shortcut dialog.
  , pDefaultKeyText // A textual representation of the default keys (eg. Alt+F10).
                    // Used in Key shortcut dialog.
  , pStorageKey     // Unique identifier to store the key value if a user
                    // changes the default in the Key shortcut dialog.
  );
                          

pObject is a DOM object which should be triggered when the keyboard shortcut is pressed. It can also be a Javascript function if you want to write more complex code which is triggered when the key is pressed. Use ApexBuilderPlugin.activateElement in your code to fire the "click" event for a DOM element.

If your button, link or field has an ID value, it's quite easy to reference it. You can use jQuery("#id-of-element")[0] to get a reference. If not, you may want to have a look at the powerful jQuery selector feature to still get a handler on the element.

To test the jQuery expressions use the Firebug Console and paste the code of jQuery (can be found in the apex_builder_plugin.user.js, search for "New Wave Javascript") into the run area and execute it. Afterwards you can play around with jQuery("your selector")[0] to identify your button, link, ...

For the key code (pKeyCode), just press the keyboard button in the following field to get the corresponding number.

Example

Register F10 if a button exists which has the label "Apply Changes".

ApexBuilderPlugin.assignKey
  ( jQuery("input[type=button][value=Apply Changes]")[0]
  , 121   // F10
  , false // pCtrlKey
  , false // pShiftKey
  , false // pAltKey
  , false // pMetaKey
  , 'Apply Changes' // pDescription
  , 'apply_changes' // pStorageKey
  );

Register Alt+F10 to "Apply Changes" and stay on page by setting the "Return to Page" checkbox.

ApexBuilderPlugin.assignKey
  ( function()
    {
      var vStayCheckbox =
            jQuery("input[type=checkbox][id$='STAY_0'],
                    input[type=checkbox][id$='RETURN_TO_PAGE_0']")[0];
      var vApplyButton  = jQuery("input[type=button][value=Apply Changes]")[0];
      if (vStayCheckbox)
      {
        ApexBuilderPlugin.setValue(vStayCheckbox, true);
      }
      if (vApplyButton)
      {
        ApexBuilderPlugin.activateElement(vApplyButton);
      }
    }
  , 121   // F10
  , false // pCtrlKey
  , false // pShiftKey
  , true // pAltKey
  , false // pMetaKey
  , 'Apply Changes + Stay on page' // pDescription
  , 'apply_changes_stay'           // pStorageKey
  );
Defining "Set" Operations

The "Set" operations feature is used to quickly change the field values/properties on the page. An example would be to set all properties for a date field like Display As, Format Mask, Alignment, ...

Add a separator

If you look into one of the supplied example files, eg. apex_builder_plugin_4311.js you will see that the first call is

ApexBuilderPlugin.addSetOperation
  ( "General"
  );
                          

This call will generate a disabled separator entry in the "Set" select list. You can add your own separator entries, just place them between your ApexBuilderPlugin.addSetOperation calls.

Simple Set operation

The next example is a real set operation call.

ApexBuilderPlugin.addSetOperation
  ( "Date Picker - date only"
  , { "F4000_P4311_DISPLAY_AS": "PICK_DATE_DD_MON_YYYY"
    , "F4000_P4311_CSIZE": "10"
    , "F4000_P4311_CMAXLENGTH": "11"
    }
  );
                          
  • The first parameter is the description for the set operation and is displayed in the "Set" select list.
  • The second parameter is an array of field id's and the value which should be set when the "Set" operation is selected by the user.

To get the IDs and the possible values of the fields on your Oracle APEX Builder page, I would recommend to use the "Inspect" feature of the "Firebug add-on. (Watch the video).

More complex Set operation

The addSetOperation also supports more complicated value assignments, not just fixed values. You can also write a function which returns a value, instead of just specifying a fixed value. For example

ApexBuilderPlugin.addSetOperation
  ( "Money - right aligned"
  , { "F4000_P4311_DISPLAY_AS": "TEXT"
    , "F4000_P4311_CSIZE": "14"
    , "F4000_P4311_CMAXLENGTH": "15"
    , "F4000_P4311_TAG_ATTRIBUTES": function(pField)
        {
          return ApexBuilderPlugin.addText(pField.value, 'style="text-align:right;"');
        }
    , "P4311_FORMAT_MASK": "FML999G999G990D00"
    }
  );
                          

In this example pField will contain the DOM element of F4000_P4311_TAG_ATTRIBUTES when the function is called. You can use the ApexBuilderPlugin.addText function to make sure that the text you want to set isn't already contained in the field.

Set operations for Tabular Form Bulk updates

The Plugin also supports Tabular Forms in an Oracle APEX Builder page. The syntax is the same, but for Tabular Forms you have to specify the name of the field. eg. f03 or f05. Don't specify f03_0001!

ApexBuilderPlugin.addSetOperation
  ( "Center all Headings"
  , { "f06": "CENTER"
    }
  );
                          

If you use a function instead of a fixed value, then the function will have an additional parameter which contains the current row which is processed. That gives you the possibility to read values from another field of the current row. The following example will add a colon at the end of a label if there isn't one.

ApexBuilderPlugin.addSetOperation
  ( "Label add colon"
  , { "f02": function(pField, pRow)
             {
               if (pField.value.search(/\:$/) == -1) return pField.value+":";
               return pField.value;
             }
    }
  );
                          

Example for a checkbox

If the field which you want to set is a checkbox, then you have to set true or false as value.

ApexBuilderPlugin.addSetOperation
  ( "Uncheck sort"
  , { "f09": false
    }
  );
                          
ApexBuilderPlugin.addSetOperation calls are only useful in the
  • apex_builder_plugin_[apex-builder-page#].js and
  • apex_builder_plugin_[current-appl#]_[apex-builder-page#].js
configuration files.

That's it! Easy, isn't it? ;-)

Have fun and be more productive with the "Set" feature!