Split view factory code out of mobile ViewController

[Chris Mitchell]

Consider refactoring the parse and _instantiate functions in ViewController? out into a new dojox/mobile/app/viewfactory module, so that different mimetypes/fileext/datatypes can be mapped to custom classes that create views from data (similar to javax.activation pattern.

[ykami]

In [27503]:

Refs #12924 !strict Externalized the hard-coded parse() method, and added componentized data handlers, which are fully customizable.

[ykami]

Dojo Mobile Data Handlers

ViewContoller was refactored to modularize the handlers, and the data handlers are structured as follows:

The data handlers consist of the following components:

1. DataHandler
2. FileTypeMap
3. DataSource
4. ContentTypeMap
5. ContentHandler

All of the above components are loaded dynamically at run-time. You do not need to explicitly requre them in your application. If your application does not use the "url" property of _ItemBase, they will never be loaded.

DataHandler

DataHandler provides an interface between content data and content handlers. DataHandler calls DataSource to retrieve data, and calls ContentHandler to parse the data and create a new view. DataHandler is called from ViewController.

FileTypeMap

FileTypeMap provides a map that can be used to determine content type by the URL of the content data.

DataSource

DataSource encapsulates access to the view content data. It is called from DataHandler.

ContentTypeMap

ContentTypeMap provides a map that can be used to determine content handler class by a content type.

ContentHandler

ContentHandler parses the given data, and creates a new view with the data.

---

The Overall Control-Flow

1. ViewController accesses FileTypeMap to get a content type (e.g. "html" or "json") by a file name suffix.
2. ViewController creates a DataSource with the url property.
3. ViewController creates DataHandler with the created DataSource.
4. ViewController calls DataHandler.processData() with the content type.
5. DataHandler accesses ContentTypeMap to get a ContentHandler class name by the given content type.
6. DataHandler calls DataSource.getData().
7. DataSource gets external content.
8. DataHandler creates the ContentHandler class.
9. DataHandler calls ContentHandler.parse() to parse the content.
10. ContentHandler.parse() parses the content.
11. ContentHandler.parse() creates a new view.
12. DataHandler calls a callback that is defined in ViewController.
13. The callback makes a view transition to the new view.

How to replace DataHandler

The default DataHandler class name is "dojox/mobile/dh/DataHandler", which is defined as the dataHandlerClass property in ViewController. It can be overridden by adding the dataHandlerClass property to transitionOptions. Below is an example of specifying your own DataHandler in ListItem.

<li data-dojo-type="dojox.mobile.ListItem" data-dojo-props='url:"data/view1.html",
 transitionOptions:{dataHandlerClass:"com/acme/MyDataHandler"}'>
    External View #1
</li>

How to replace FileTypeMap

The default FileTypeMap class name is "dojox/mobile/dh/SuffixFileTypeMap", which is defined as the fileTypeMapClass property in ViewController. It can be overridden by adding the fileTypeMapClass property to transitionOptions. Below is an example of specifying your own FileTypeMap in ListItem.

<li data-dojo-type="dojox.mobile.ListItem" data-dojo-props='url:"data/view1.html",
 transitionOptions:{fileTypeMapClass:"com/acme/MyFileTypeMap"}'>
    External View #1
</li>

How to replace DataSource

The default DataSource class name is "dojox/mobile/dh/UrlDataSource", which is defined as the dataSourceClass property in ViewController. It can be overridden by adding the dataSourceClass property to transitionOptions. Below is an example of specifying your own DataSource in ListItem.

<li data-dojo-type="dojox.mobile.ListItem" data-dojo-props='url:"data/view1.html",
 transitionOptions:{dataSourceClass:"com/acme/MyDataSource"}'>
    External View #1
</li>

How to replace ContentTypeMap

Usually, ContentTypeMap does not need to be replaced. If you have your own DataHandler, however, you can have your own ContentTypeMap as well, since DataHandler has dependency on ContentTypeMap.

How to override ContentType

Usually, content type is determined by looking up the matching entry in a ContentTypeMap. If you want to skip the look-up, and explicitly specify a particular content type, you can give the contentType property to transitionOptions. Below is an example of specifying a content type in ListItem.

<li data-dojo-type="dojox.mobile.ListItem" data-dojo-props='url:"data/view1.data",
 transitionOptions:{contentType:"data"}'>
    External View #1
</li>

How to register ContentType

Content type is determined by a FileTypeMap. For example, SuffixFileTypeMap uses the file name suffix to determine content type. For SuffixFileTypeMap, you can register "suffix to content type" entries into the map. SuffixFileTypeMap is a singleton module. You can simply get its module return value and use the add() method to register your entries.

require([
    "dojox/mobile/dh/SuffixFileTypeMap",
    "dojox/mobile/parser",
    "dojox/mobile",
    "dojox/mobile/compat"
], function(SuffixFileTypeMap){
    SuffixFileTypeMap.add("acme", "data"); // regard *.acme as "data" type
});

If you use the old dojo.require() API, you can register entries as follows.

dojo.require("dojox/mobile/parser");
dojo.require("dojox/mobile");
dojo.require("dojox/mobile/compat");
dojo.require("dojox/mobile/dh/SuffixFileTypeMap");

dojox.mobile.dh.SuffixFileTypeMap.add("acme", "data");

If a given suffix does not match any of the entries in the map, ViewController uses "html" as the default content type.

How to register ContentHandler

Which ContentHandler to use is managed by ContentTypeMap. In your application, you can register "content type to content handler class" entries into the map. ContentTypeMap is a singleton module. You can simply get its module return value and use the add() method to register your entries.

require([
    "dojox/mobile/dh/ContentTypeMap",
    "dojox/mobile/parser",
    "dojox/mobile",
    "dojox/mobile/compat"
], function(ContentTypeMap){
    ContentTypeMap.add("html", "dojox/mobile/dh/MyHtmlContentHandler");
});

If you use the old dojo.require() API, you can register entries as follows.

dojo.require("dojox/mobile/parser");
dojo.require("dojox/mobile");
dojo.require("dojox/mobile/compat");
dojo.require("dojox/mobile/dh/ContentTypeMap");

dojox.mobile.dh.ContentTypeMap.add("html", "dojox/mobile/dh/MyHtmlContentHandler");

[ykami]

In [27594]: Refs #14461 !strict. Fixes for View and ViewController to use the data handlers. The hard-coded data handlers were removed.

(the ticket number I used was wrong.)

[ykami]

In [27731]:

Refs #12924 !strict Fixed initialization error.