UIZE JavaScript Framework

MODULES Uize.Comm

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Comm class provides functionality and interface that is shared by subclasses that implement support for specific communication protocols.

DEVELOPERS: Chris van Rensburg, Jan Borgersen, original code contributed by Zazzle Inc.

The Uize.Comm class serves as the base class for subclasses that implement support for specific communication protocols (such as Uize.Comm.Ajax, Uize.Comm.Iframe, and Uize.Comm.Script). The Uize.Comm base class provides support for queuing subsequent calls to allow sequenced server requests.

1.1. Examples

There are no dedicated showcase example pages for the Uize.Comm module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Comm module...

SEARCH

1.2. Implementation Info

The Uize.Comm module defines the Uize.Comm class, which is a subclass of Uize.Class.

INHERITANCE CHAIN

Uize.Class −> Uize.Comm

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

flush | flushCache | performRequest | queueRequest | request | useQueue

STATIC METHODS

Uize.Comm.processArrayAsync

1.2.2. Features Overridden in This Module

The features listed in this section have been overridden in this module.

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

valueOf

STATIC PROPERTIES

Uize.Comm.moduleName | Uize.Comm.nonInheritableStatics

1.2.3. Features Inherited From Other Modules

The features listed in this section have been inherited from other modules.

The module that an inherited feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

fire | get | is | isMet | kill | met | onChange | once | set | toggle | unmet | unwire | whenever | wire

STATIC METHODS

Uize.Comm.alphastructor | Uize.Comm.declare | Uize.Comm.doMy | Uize.Comm.dualContextMethods | Uize.Comm.dualContextProperties | Uize.Comm.fire | Uize.Comm.get | Uize.Comm.instanceMethods | Uize.Comm.instanceProperties | Uize.Comm.mixins | Uize.Comm.omegastructor | Uize.Comm.set | Uize.Comm.singleton | Uize.Comm.stateProperties | Uize.Comm.staticMethods | Uize.Comm.staticProperties | Uize.Comm.subclass | Uize.Comm.toggle | Uize.Comm.unwire | Uize.Comm.wire

STATIC PROPERTIES

Uize.Comm.pathToResources

1.2.4. Modules Directly Under This Namespace

Uize.Comm.Ajax | Uize.Comm.Iframe | Uize.Comm.Script

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Comm module.

2. Instance Events

2.1. Perform Request

The Perform Request instance event fires each time before a request is performed - for both single requests as well as batch requests. The event object contains a "request" property, which is a reference to the request object for the request about to be performed.

2.2. Request Queue Updated

The Request Queue Updated event is fired each time the requestQueue instance property is updated.

3. Instance Properties

3.1. requestQueue

An array, containing all pending requests that have been queued up and are waiting to be performed.

NOTES

see also the flush, queueRequest, and useQueue instance methods

4. Instance Methods

4.1. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.2. flush

A method that lets you flush the request queue.

SYNTAX

myInstance.flush ();

NOTES

this method takes no parameters
after flushing the request queue, the Request Queue Updated instance event will be fired
see also the queueRequest and useQueue instance methods
see also the requestQueue instance property

IMPLEMENTATION INFO

this feature was introduced in this module

4.3. flushCache

Lets you flush the cached response for a specific request, or lets you flush the entire response cache for the instance.

SYNTAX

myInstance.flushCache (requestOBJ);

VARIATION 1

myInstance.flushCache (requestUrlSTR);

As an alternative to specifying a request by request object, a request can be specified by its URL (i.e. the value of the url property of the request object).

VARIATION 2

myInstance.flushCache ();

When no parameter is specified, then the flushCache method will flush the entire response cache for the instance.

NOTES

don't confuse this method with the flush instance method that flushes the request queue

IMPLEMENTATION INFO

this feature was introduced in this module

4.4. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.5. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.6. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.7. kill

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.8. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.9. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.10. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.11. performRequest

A method that should be overrided in subclasses that implement support for specific communication protocols.

SYNTAX

myInstance.performRequest (requestOBJ,callbackFUNC)

This method is not intended to be called by application code. It is only public so that it can be overrided in subclasses. When implementing this method in a subclass, your method should expect to receive the two parameters requestOBJ and callbackFUNC. The requestOBJ parameter will contain all the information necessary for performing the request.

Once the request has been sucessfully completed, your implementation should place request results into requestOBJ and then call the callback function specified in the callbackFUNC parameter. It is not necessary to pass any parameters when calling the callbackFUNC function, since the request results are placed into requestOBJ.

IMPLEMENTATION INFO

this feature was introduced in this module

4.12. queueRequest

IMPLEMENTATION INFO

this feature was introduced in this module

4.13. request

A method that lets you initiate a request.

SYNTAX

myInstance.request (requestOBJ);

All the information that governs the request is contained inside the requestOBJ parameter. The properties of this object will vary, depending on the communication protocol and are determined by the particular subclass Uize.Comm you are using.

SYNTAX (EXPLODED)

myInstance.request ({
  // ...properties specific to comm protocol...
  // ...properties specific to comm protocol...
  // ...properties specific to comm protocol...
  returnType:returnTypeSTR,
  cache:cacheBOOLorSTR,
  callback:callbackFUNC
});

4.13.1. requestOBJ Properties

The Uize.Comm base class handles the following properties of the requestOBJ parameter...

4.13.1.1. returnType

A string, specifying the data type that should be used when passing the response result to the callback function specified by the callback property.

VALUES

'text' - the value of the responseText property of requestOBJ will be passed as the parameter to the callback function
'json' - the value of the responseJson property of requestOBJ will be passed as the parameter to the callback function
'xml' - the value of the responseJson property of requestOBJ will be passed as the parameter to the callback function
'object' (default) - the requestOBJ object will be passed as the parameter to the callback function

NOTES

the default value for this property is 'object'

4.13.1.2. cache

A string, specifying the caching mode that should be employed when performing the request.

VALUES

'memory' - a JavaScript memory based mechanism will be employed to cache the request's response. Using this caching mode, the browser's caching mechanism is preempted. Because this caching mode is memory based, the caching of responses in this mode is not persisted across page reloads or navigation. This mode is useful for requests that are likely to be hit heavily and repeatedly throughout a page session.
'browser' - caching is left to the browser's built-in mechanism.
'never' (default) - a cache defeat mechanism is employed to ensure that the request is never cached. This mode is useful for requests where the response will vary with repeated use - even with identical request parameters - because the response may be determined by data beyond that contained in the request, such as data contributed through community interaction with a Web application, or data that is updated in the user's session.

NOTES

the default value for this property is 'never'

4.13.1.3. callback

A function reference, specifying the function that should be called once the request has been performed.

The callback function you specify should expect to receive one parameter that will be of the type specified by the returnType property.

4.13.1.4. cutToHead

A boolean, specifying whether or not the request should cut to the head of the request queue.

If the value false is specified for the cutToHead property, or if this property is not specified, then the request is appended to the request queue. This is the default behavior. In some rare cases, such as when recovering from a request that returns a failure / error response, it might be desirable to push requests that are part of recovering from the failed request to the head of the queue. In such cases, such recovery requests can specify the value true for the cutToHead property.

IMPLEMENTATION INFO

this feature was introduced in this module

4.14. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.15. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.16. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.17. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.18. useQueue

IMPLEMENTATION INFO

this feature was introduced in this module

4.19. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

4.20. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.21. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

5. Static Methods

5.1. Uize.Comm.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.2. Uize.Comm.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.3. Uize.Comm.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.4. Uize.Comm.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.5. Uize.Comm.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.6. Uize.Comm.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.7. Uize.Comm.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.8. Uize.Comm.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.9. Uize.Comm.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.10. Uize.Comm.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.11. Uize.Comm.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.12. Uize.Comm.processArrayAsync

A method that facilitates asynchronous iteration through and processing of the elements of an array.

SYNTAX

Uize.Comm.processArrayAsync (elementsARRAY,processElementAsyncFUNC,completionFUNC);

While asynchronous, the array specified by the elementsARRAY parameter is guaranteed to be iterated through sequentially. This method is useful for iterating through the elements of an array and using an asynchronous communication protocol, such as Ajax, in the processing of the elements.

The function you specify in the processElementAsyncFUNC parameter should be of the form...

myAsyncElementProcessor (elementToProcessANYTYPE,processNextElementFUNC,elementNoINT);

The value of the elementToProcessANYTYPE parameter will be the value of each successive element in the array that is being iterated through. In order to inform the Uize.Comm.processArrayAsync method that the asynchronous processing of the current element has been completed so that it can continue on with the iteration, the function specified by the processNextElementFUNC parameter should be called. This function does not need to be called with any parameters. However, if you call it with the value false, then the iteration will be terminated and any function that you specified for the completionFUNC parameter will be called.

Your processor function can optionally declare an elementNoINT parameter, to receive the array index of the current element being processed. This might be useful if you need to index into other corresponding support data structures, or use the number as part of the construction of some string or such. Naturally, your own element processor function can name these three parameters whatever it likes.

If you specified a value for the optional completionFUNC parameter, then your completion function will be called once the iteration is completed, with one parameter, being the length of the array that was processed.

TYPICAL USAGE SKELETON

Uize.Comm.processArrayAsync (
  _elementsToIterateThrough,
  function (_currentElement,_continueIterating) {
    _doSomethingAsynchronous (
      function () { // the callback for _doSomethingAsynchronous
        // further processing of element
        _continueIterating ();
      }
    );
  },
  function () {
    // done iterating, wrap it all up
  }
);

EXAMPLE

var imagesInfoHtml = '';
Uize.Comm.processArrayAsync (
  myPhotoStream.getImageIds (),
  function (_imageId,_addInfoHtmlForNextImage) {
    myAjaxCommObject.request ({
      url:'/svc/getimageinfo?id=' + _imageId,
      returnType:'json',
      requestMethod:'GET',
      callback:function (resonseJson) {
        imagesInfoHtml +=
          'title: ' + resonseJson.title + '
' +
          'description: ' + resonseJson.description + '
' +
          'dimensions: ' + resonseJson.width + 'x' + resonseJson.height + '
' +
          '
'
        ;
        _addInfoHtmlForNextImage ();
      }
    });
  },
  function () {
    Uize.Dom.Basics.setInnerHtml ('imagesInfo',imagesInfoHtml);
  }
);

In this fictitious example, Uize.Comm.processArrayAsync is being used to iterate through an array of image IDs for a photo stream.

On each iteration, the processor function performs an asynchronous request, using an instance of Uize.Comm.Ajax, to the service "/svc/getimageinfo" in order to get info for each image. When the Ajax request returns with the image info, the callback registered for the request uses the image info to build image info HTML for the entire photo stream. After adding to the HTML string, the continuation function is called in order to continue the iteration. Once all the image IDs have been processed, the completion function is called, which spits out the constructed info HTML into the page.

One thing that this example demonstrates is that the parameters that your element processor function receives can be named to be semantically suitable to your application.

VARIATION 1

Uize.Comm.processArrayAsync (
  elementsARRAY,processElementAsyncFUNC,completionFUNC,directionINT
);

The optional directionINT parameter lets you specify the increment (and, therefore, direction) of the asynchronous loop. By default, this method loops forward through the array - from the first element to the last element. Specifying a value of -1 for the directionINT parameter will cause the iteration to start from the last element of the array and loop towards the first element - one element at a time. Specifying a value of -2 will also result in a reverse loop, but will iterate backwards two elements at a time.

VARIATION 2

Uize.Comm.processArrayAsync (elementsARRAY,processElementAsyncFUNC);

When the optional completionFUNC parameter is not specified, then the caller of this method will not be notified when the process has been completed.

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

5.13. Uize.Comm.set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.14. Uize.Comm.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.15. Uize.Comm.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.16. Uize.Comm.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.17. Uize.Comm.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.18. Uize.Comm.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.19. Uize.Comm.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.20. Uize.Comm.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.21. Uize.Comm.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6. Static Properties

6.1. Uize.Comm.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.2. Uize.Comm.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

6.3. Uize.Comm.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses