Development

dgDojoPlugin/DojoHelpers

You must first sign up to be able to contribute.

Version 14 (modified by Dean.Glazeski, 9 years ago)
--

The Dojo Javascript Helpers

All of these helpers rely on the TagHelper and the sfLoader class to load the Tag helpers. Be aware if deploying in a modular environment. Also note that these functions are very similar to the Javascript helpers from the Prototype library. In fact, they are based off of those functions with slight modifications to make them use Dojo and yet still have similar functionality.

Creates a link that calls a Javascript function.

Arguments

  1. Text for the link
  2. Javascript function to be run
  3. Any desired HTML options

Link Text

This can be anything you want it to be assuming it has a toString method.

Javascript Function

A semicolon and 'return false;' is appended to whatever you send to this argument. It is then attached to the onClick attribute of the link.

HTML Options

Any HTML option is allowed here. Below some specific items are described.

Properties:

  • href - If this is not supplied, it is assumed to be '#'
  • onclick - Always overridden by the function passed in the second parameter
  • confirm - Set this if you want a confirmation box. The text in this option will be displayed in the box.

Return

Returns a string with everything ready for a javascript link.

Examples

<?php echo dojo_link_to_function('Click Me!', 'alert("You clicked me!")', array('class' => 'jLink')) ?>
// <a href="#" class="jLink" onclick="alert('You clicked me!'); return false;">Click Me!</a>

Creates a link that sends of an XMLHttpRequest to a server.

Arguments

  1. Text for the link
  2. Options for the remote function
  3. HTML options for the resulting tag

Link Text

This can be anything you want it to be assuming it has a toString method.

Remote Function Options

See Dojo Remote Function for information on these options.

HTML Options

See Dojo Link To Function for the important HTML options.

Return

Returns a string with everything ready for an Ajax requesting link.

Examples

<?php echo dojo_link_to_remote('Update Contacts', array('url'           => '@updateContacts',
                                                        'update'        => 'contacts',
                                                        'renderWidgets' => true)) ?>
/* <a href="#" onclick="dojo.xhr("GET", { url: '/contacts/update', 
*                                         handle: function(response, ioArgs) 
*                                         { 
*                                             dojo.byId('contacts').innerHTML = response; 
*                                             dojo.parser.parse(dojo.byId('contacts'));
*                                             return response;  
*                                         }})">Update Contacts</a>
*/
<?php echo dojo_link_to_remote('Send Information', array('form'   => 'infoForm',
                                                         'update' => array('success' => 'infoReceived',
                                                                           'failure' => 'infoError'),
                                                         'url'    => '@submitInfo',
                                                         'method' => 'post')) ?>
/* <a href="#" onclick="dojo.xhr("POST", { url: '/info/submit',
*                                          form: 'infoForm',
*                                          load: function(response, ioArgs) {
*                                                    dojo.byId('infoReceived').innerHTML = response;
*                                                    return response;
*                                                }
*                                          error: function(response, ioArgs) {
*                                                     dojo.byId('infoError').innerHTML = response;
*                                                     return response;
*/                                                }})">Send Information</a>

dojo_button_to_function

Creates a Dojo Button that executes a function and returns a DojoButton object.

Arguments

  1. Text for the button
  2. Function to be executed
  3. HTML options for the button

Button Text

This can be anything you want it to be assuming it has a toString method.

Javascript Function

Handled just like Dojo Link To Function.

HTML Options

Handled just like Dojo Link To Function.

Return

Returns a new DojoButton object that will execute the desired function when clicked. You can feel free to modify the button more on the other end.

Examples

<?php echo dojo_button_to_function('Click Me!', 'alert("You clicked me!")', array('class' => 'jLink')) ?>
// <button class="jLink" dojoType="dijit.form.Button" onclick="alert("You clicked me!"); return false;">Click Me!</button>

dojo_button_to_remote

This functions in pretty much the same as the Dojo Link To Remote function except it returns a Dojo Button instance much like the Dojo Button to Function.

Arguments

  1. Text for the button
  2. Options for the remote function
  3. HTML options for the resulting tag

Button Text

This can be anything you want it to be assuming it has a toString method.

Remote Function Options

See Dojo Remote Function for information on these options.

HTML Options

See Dojo Link To Function for the important HTML options.

Return

Returns a string with everything ready for an Ajax requesting button.

Examples

<?php echo dojo_button_to_remote('Update Contacts', array('url'           => '@updateContacts',
                                                          'update'        => 'contacts',
                                                          'renderWidgets' => true)) ?>
/* <button dojoType="dijit.form.button" onclick="dojo.xhr("GET", { url: '/contacts/update', 
*                                                                  handle: function(response, ioArgs) { 
*                                                                             dojo.byId('contacts').innerHTML = response; 
*                                                                             dojo.parser.parse(dojo.byId('contacts'));
*                                                                             return response;  
*                                                                          }})">Update Contacts</button>
*/
<?php echo dojo_button_to_remote('Send Information', array('form'   => 'infoForm',
                                                           'update' => array('success' => 'infoReceived',
                                                                           'failure' => 'infoError'),
                                                           'url'    => '@submitInfo',
                                                           'method' => 'post')) ?>
/* <button dojoType="dijit.form.button" onclick="dojo.xhr("POST", { url: '/info/submit',
*                                                                   form: 'infoForm',
*                                                                   load: function(response, ioArgs) {
*                                                                             dojo.byId('infoReceived').innerHTML = response;
*                                                                             return response;
*                                                                         }
*                                                                   error: function(response, ioArgs) {
*                                                                              dojo.byId('infoError').innerHTML = response;
*                                                                              return response;
*/                                                                         }})">Send Information</button>

dojo_periodically_call_function

Dojo does not explicitly have a periodically call object like Protoype. This function creates Javascript for periodically calling a function in lew of this fact.

Arguments

  1. The function to be run
  2. Options for the execution of the periodic call

Javascript Function

The function is tucked into an anonymous Javascript function that is called every so many seconds.

Options

There is really only one major option.

  1. frequency - How many seconds between each call of the Javascript function, default is 10 seconds

Return

Returns a Javascript tag with the needed Javascript to do the calls.

Examples

<?php echo dojo_periodically_call_function('alert("Hello, there!")', array('frequency' => 5)) ?>
//<script type="text/javascript">
//<![CDATA[
//setInterval(dojo.hitch(this, function() {alert("Hello, there!");}), 5000);
//]]>
//</script>

dojo_periodically_call_remote

Builds the remote function and uses Dojo Periodically Call function to create the resulting periodic caller.

Arguments

  1. Options for the remote call

Remote Function Options

See Dojo Remote Function for information on these options.

Return

Returns a Javascript tag with the needed Javascript to do the calls.

Examples

<?php echo dojo_periodically_call_remote(array('url'           => '@homepage',
                                               'timeout'       => 2000,
                                               'hasBody'       => true, 
                                               'update'        => array('success' => 'stuff', 'failure' => 'locale'),
                                               'success'       => array('after' => 'alert("Update Complete");'),
                                               'always'        => array('after' => 'alert("Always comes here");'),
                                               'renderWidgets' => true,
                                               'position'      => 'bottom',
                                               'frequency'     => 20,
                                               )) ?>
//<script type="text/javascript">
//<![CDATA[
//  setInterval(dojo.hitch(this, function() {
//                                   dojo.xhr('GET', { error: function(response, ioArgs) { 
//                                                                var theDiv = document.createElement('div');
//                                                                dojo.place(theDiv, 'locale', 'last');
//                                                                dojo.byId(theDiv).innerHTML = response;
//                                                                dojo.parser.parse(theDiv); 
//                                                                return response; 
//                                                            }, 
//                                                     handle: function(response, ioArgs) { 
//                                                                 alert("Always comes here"); 
//                                                                 return response; }, 
//                                                     load: function(response, ioArgs) { 
//                                                               var theDiv = document.createElement('div');
//                                                               dojo.place(theDiv, 'stuff', 'last');
//                                                               dojo.byId(theDiv).innerHTML = response;
//                                                               dojo.parser.parse(theDiv);
//                                                               alert("Update Complete"); 
//                                                               return response; 
//                                                           }, 
//                                                     timeout: 2000, 
//                                                     url:"/admin_dev.php/" }, 
//                                            true);;
//                                   }), 20000);
//]]>

dojo_form_remote_tag

Creates a form that submits to a remote site using XMLHttpRequests.

Arguments

  1. Options for the remote function
  2. HTML tag options for the form tag

Remote Function Options

See Dojo Remote Function for information on these options. Some options are modified, though.

  1. before - 'var formElement = this' added to the end of the call to setup for the xhr request 'form' option
  2. formElement - Overridden to be 'formElement'

HTML Options

Some options have some specific things done to them.

  1. action - Action for the tag, will become the URL of the remote function if not provided
  2. method - Defaults to a 'post' request if not set (this overrides the method of the remote function)
  3. onsubmit - Replaced by the remote function call

Return

Returns the form tag with the proper Javascript in the form's onsubmit property.

Examples

<?php echo dojo_form_remote_tag(array('url' => '@homepage', 
                                     'timeout' => 2000,
                                     'hasBody' => true, 
                                     'update' => array('success' => 'stuff', 'failure' => 'locale'),
                                     'renderWidgets' => true,
                                     'position' => 'bottom',
                                     ), array('id' => 'mainForm',
                                              'method' => 'get')) ?>
<input type="text" id="name" name="name" value="None" />
<input type="submit" id="submit" value="Submit" />
</form>

dojo_submit_to_remote

Creates a button that submits a form or other data to a server. If you don't specify what form ID or form element node to submit, it will attempt to guess it as 'this.parentNode'. You can still specify 'with' parameters, though.

Arguments

  1. The name of the input created
  2. Value of the input button
  3. Options for the Remote Function
  4. HTML options for the created button

Name of the Input

Any name that you would like for the input device.

Value

What text you want to have appear on the button.

Remote Function Options

See Dojo Remote Function for information on these options. Some options are modified, though.

  1. method - Defaults to post if not set

If you do not specify what form or what form element to be submitted, the following changes will happen:

  1. before - 'var formElement = this.parentNode' added to the end of the call to setup for the xhr request 'form' option
  2. formElement - Overridden to be 'formElement'

HTML Options

Some options have some specific things done to them.

  1. onclick - Replaced by the remote function call
  2. type - Forced to be a 'button'
  3. name - Set to the name passed in
  4. value - Set to the value passed in

Returns

Returns a string that creates an HTML input button that submits the data supplied to the remote function.

Examples

<?php echo dojo_submit_to_remote('submit', 'Remote', array('url'           => '@homepage', 
                                                           'timeout'       => 2000,
                                                           'hasBody'       => true, 
                                                           'update'        => array('success' => 'stuff', 'failure' => 'locale'),
                                                           'renderWidgets' => true,
                                                           'form'          => 'mainForm',
                                                           )) ?>

dojo_submit_image_to_remote

This creates an image input that will submit a form or other items using Ajax.

Arguments

  1. Name of the input
  2. Source of the image
  3. Options for the remote function
  4. HTML options for the created input

Name of the Input

Any name that you would like for the input device.

Image Source

Anything that resolves to an image when image_path is used.

Remote Function Options

See Dojo Remote Function for information on these options. Some options are modified, though.

  1. method - Defaults to post if not set

If you do not specify what form or what form element to be submitted, the following changes will happen:

  1. before - 'var formElement = this.parentNode' added to the end of the call to setup for the xhr request 'form' option
  2. formElement - Overridden to be 'formElement'

HTML Options

Some options have some specific things done to them.

  1. onclick - Replaced by the remote function call
  2. type - Forced to be a 'image'
  3. name - Set to the name passed in
  4. src - Overridden by the result of image_path on the source passed in
  5. alt - If not set, some alt text will be guessed at

Return

Returns an input that houses the needed Javascript.

Examples

<?php echo dojo_submit_image_to_remote('submit', 'submit.gif', array('url'           => '@homepage', 
                                                                     'timeout'       => 2000,
                                                                     'hasBody'       => true, 
                                                                     'update'        => array('success' => 'stuff', 'failure' => 'locale'),
                                                                     'renderWidgets' => true,
                                                                     'position'      => 'bottom',
                                                                     'form'          => 'mainForm',
                                                                     )) ?>

dojo_update_element

Updates a certain element based on position. It can also empty nodes or completely remove nodes from the page.

Arguments

  1. The element ID of the node being updated
  2. Options for the function that is built

Element ID

A valid element ID that will not return null from 'dojo.byId()'.

Options

There is a set of options that actually affect what this function returns.

  1. content - What content update the node with. If not supplied, this is assumed to be ''. It is also escaped using javascript_escape.
  2. action - What action to perform. Must be one of 'update', 'empty', or 'remove'. An exception gets thrown if this isn't followed.
  3. position - Where to add the content. If left empty, the whole node is replaced with content. Otherwise, must be one of 'top', 'bottom', 'before', or 'after'.
  4. renderWidgets - Specifies if Dojo should parse the node for widgets to be created after the update.

Return

Returns the Javascript to perform the desired update.

Examples

// empties the 'stuff' div
<?php echo dojo_button_to_function('Clear Updates', dojo_update_element('stuff', array('action' => 'empty'))) ?>
// removes the 'stuff' div
<?php echo dojo_button_to_function('Remove Updates', dojo_update_element('stuff', array('action' => 'remove'))) ?>

dojo_observe_field

Creates Javascript to watch a field for a specific event. It then does an XMLHttpRequest to a server with the current value of the field. This function can connect to any event you need it to, but it defaults to the 'onchange' event.

Arguments

  1. The field ID of the field to watch
  2. Options for the remote function

Field ID

This can be any valid field ID in the current page.

Remote Function Options

See Dojo Remote Function for information on these options. Some options are modified, though.

  1. withj - Adds the value of the field to the request as 'value'

There are some additional options that are not used by the remote function.

  1. frequency - If set and greater than zero, the observer will trigger every 'frequency' seconds instead of on an event
  2. event - What Javascript event to have the observer trigger on, default is 'onchange'

Return

Returns a Javascript tag with all of the Javascript to execute the desired action.

Examples

// observe the name field 'onchange' which is triggered after the input looses focus
<?php echo dojo_observe_field('name', array('url'           => '@homepage', 
                                            'timeout'       => 2000,
                                            'update'        => array('success' => 'stuff', 'failure' => 'locale'),
                                            'renderWidgets' => true,
                                            'position'      => 'bottom',
                                            )) ?>

dojo_observe_form

Creates Javascript that will watch all parts of a form for an event and will submit the form to a specified URL when that happens. Additional items will be specified in the 'target' and 'value' parameters to tell you what item triggered the submit and what its new value is respectively.

Arguments

  1. Form ID to be watched
  2. Options for the remote function or for the periodic caller

Form ID

This can be any valid field ID in the current page.

Remote Function Options

See Dojo Remote Function for information on these options. Some options are modified, though.

  1. withj - Adds the value of the field and what field triggered the event to the request as 'value' and 'target' respectively

There are some additional options that are not used by the remote function.

  1. frequency - If set and greater than zero, the observer will trigger every 'frequency' seconds instead of on an event
  2. event - What Javascript event to have the observer trigger on, default is 'onchange'

Return

Returns the Javascript that will observe all items in a form for some event.

Examples

<?php echo dojo_observe_form('mainForm', array('url'           => '@homepage', 
                                               'timeout'       => 2000,
                                               'update'        => array('success' => 'stuff', 'failure' => 'locale'),
                                               'renderWidgets' => true,
                                               'position'      => 'bottom',
                                               )) ?>