Component Parser Requirements =================================== :Author: Dylan Schiemann :Version: 0.1 :Copyright: Dojo Foundation, 2005 :Date: $Date:$ .. contents:: Purpose ------- This document outlines the rationale and usage scenarios for parsing component and application information from multivarious sources. Requirements ------------ The client-side parser component of Dojo MUST: - provide a single, uniform data structure from all of the various supported markup encodings - instantiate and provide properties (data and configuration directives) to components and widgets - a second pass of the parser MUST provide deeper linking structures such as property sets shared among items, and event handling linkage Use Cases ------------ .. image:: ../images/applicationParsingRendering.png Author apps using a third-party application declaration language **************************************************************** An app author wants to use a pre-existing third party application declaration language such as JSF, Struts, Tapestry, etc. Reasons for this include using dojo components in another environment to extend the capabilites of an existing framework, or to comply with a set of standards for building distributed web applications. In this case, the parser will usually receive dojoml or inline constructors from the server framework. Author apps using dojoml ************************ A mechanism for an author to describe components, their properties, events, and data sources, through a sane xml declaration language. In most of today's browser environments, this would either be transformed to HTML and/or SVG documents with inline dojo constructors and a reference to the dojoml document, or to HTML and/or SVG documents with the dojo environment and a reference to the dojoml document(s) for the application which would then be parsed on the client side. The parser would thus need to be able to handle both inline constructors and dojoml documents. Property sets and data sources may also reside in external resources. Author apps using inline html and/or svg constructors ***************************************************** The author is simply interested in a single namespace environment such as HTML or SVG, and wants to add some dojo components and logic to their application. Author apps using JavaScript objects ************************************ The author is a more sophisticated JavaScript developer and does not want to use markup to describe their applications. In this case, the parser would skip the first pass and start directly with JS objects representing components and application logic and properties. Author apps using more than one of the above methods ******************************************************** Because an author might want to use more than one of the techniques listed above, the parsing system needs to accommodate the mixing of these options. The most common example would seem to be using inline constructors and JacaScript objects together. Parsing Environments ----------------------- Arbitrary xml server-side languages *********************************** (not sure if we would ever need to parse these... but we would need to offer a translation step between the language and what dojo components support/expect Dojoml *********************************** It should be possible for the parser to read dojoml files and parse them into components, data models, and property sets, and to retrieve external resources for each of these. Inline constructors *********************************** The parser needs to be able to parse incline component constructors in HTML and SVG namespaces into the same result set as it would were it reading a dojoml document. It should also be able to retrieve external resources, and be able to map translated property names that may be used in non-namespace aware environments. For example, dojo:componentName in dojoml may be the same as div dojoType="componentName" in an inline HTML constructor. JavaScript objects *********************************** JavaScript objects are essentially already parsed, so the only issue is mixing them with other component declaration styles,a nd external resources. Abstraction of namespaces *********************************** In a namespace aware environment, dojoml and inline constructors use namespaced attributes. In other environments, custom attributes and tags are prefixed according to a rule set stored in ???????. Parsing Steps ------------- Generic XML to generic JavaScript ********************************* The first step of parsing instantiates an instance of dojo.xml.ParseDocumentFragment, which offers the ability to parse a fragment into a generic JavaScript object structure. Basically each level of nested elements is translated into an array of objects, which may contain an array of objects representing attributes and nested elements. Because properties may be described as elements and attributes, and because there is no requirement for uniqueness, every nested level has the somewhat confusing obfuscation of everything being an array. For example, the following dojoml fragment:: would be translated to:: fragmentObject = { dojo:button[0]:{ dataProvider[0]:"#buttonDataProvider", dojo:image[0]: { xlink:href[0]:"test.png" } } } The primary reason for doing this step is that it seems to be more performant to parse all of the xml to JavaScript once, rather than making multiple passes on XML data structures. Generic JavaScript to component and data objects ************************************************ This step converts a generic JavaScript object structure to one that populates structures that describe components, their properties, and data models. There should be a way to define the set of rules and properties from a component. For example, what should be done with unrecognized property attributes? Should they be added to the data structure in an unknown attribute collection, or should they be ignored, but still available by going back and looking at the source XML structure. There also needs to be a mechanism for round-tripping so that the application end user may modify data or properties, which would then be provided back to the server and stored locally in the xml structure. Does this make sense? So how do we define a generic component interface, and then properties and subcomponents or child components specific to a particular component type? Do we use a hash map or lookup map style system? Do we use a factory pattern for components? I guess that I am currently working under the assumption that there will be a base component class, and types of components will have the properties that they accept defined in a dictionary or list, as well as a listing of subcomponents that they accept or expect. How this will be done is still somewhat of an ill-formulated thought in my mind, though I am sure that Alex has a better concept worked out in his mind. Also, at this stage of parsing, we need to be able to mixin external data models and property sets, as well as deal with conflicting properties, e.g. the same property being defined in multiple ways. The conclusion we have come to for property cascading or inheritance is to simply choose the last specified instance of a property, and by last, this also means most specific. So this would imply that the parser would work from the top down in determining property values.