A good starting point is to take a look over this document, as an overview of how XMS 2.0 works. If there are any question please post them in the XMS 2.0 Overview.

Application structure

  1. app
    • name
    • init
    • use
    • parsers
    • filters
      • ob
        • marker
        • eval
        • match
        • matchiterator
      • dom
        • xpath
        • nodelist
        • domiterator
    • client
      • header
        • title
        • metas
          • element
        • keywords
        • style
        • load
        • run
      • content
An application consists of 5 parts:
  1. name
  2. Set the name of the application used for config and language support;
  3. init Since AWS XMS 1.0 RC1
  4. Initialize application;
  5. client
  6. Content of your web application that has two children nodes: header (a.k.a. head) and content (a.k.a. body). You can use IMPORT HTML feature of Designer to import any web page as this software will integrate new document in the application and build the tree structure for you;
  7. filters
  8. DOM and output buffering filters (or text filters);
  9. parsers (application related) Since AWS XMS 1.0 RC1
  10. Defines user filters;


php connects to the layout by using directives and filters:
- a directive is the the element used anywhere inside /app/client/header (a.k.a html head) or /app/client/content (a.k.a html body); Directives will only alter the document in the place where are called;
- a filter is the the element used only in /app/filters/dom or /app/filters/ob ; Filters can be called for all elements or for specific ones, indicated by the xpath (for dom filters) or the marker (for text filters);

Remarks:
- Root element of each application is always app ;

- All other direct childs of root node, different than name, client and filters are skipped from beign processed. I'm using template node to store my templates for things like navigation bars, exec directives or any other things that are to be used more than once. These templates can be easily used later using import directives to place them where it should, not only in current application, but from within other applications;

- XMS uses DOM (both in Php and Javascript) and Xpath / CSS selectors, so you should have basic knowledge about these;

- Below we will often refer to functions and code. Except run and load directives, which load a javascript file or run javascript code, all other directives only execute php code (found in processing instructions: <?target data?>)

See also:

Application processor

Processing order

XMS 4.0 XMS 3.0
  1. //app/remotetemplate
  2. //app/use
  3. //app/init
  4. //app/name
  5. //app/client/header|content
  6. //app/filters/dom/filter/import
  7. //app/filters/dom/filter/advancedimport
  8. loop for //case //import //advancedimport
  9. processing-instruction('php')executed in the order of appearance in dom tree
  10. //app/filters/dom/filter/xpath
  11. //app/filters/dom/filter/nodelist
  12. //app/filters/dom/filter/domiterator
  13. //app/filters/ob/filter/match
  14. //app/filters/ob/filter/matchiterator
  15. //app/filters/ob/filter/marker
  16. //app/filters/ob/filter/eval
  17. //lang/[activeLanguage]/[appName]/sys/*
  18. //lang/[activeLanguage]/[appName]/ui/*
  19. //lang/[activeLanguage]/[appName]/err/*
  20. global parsers (parsers.xml)
  21. //app/parsers
  1. //app/remotetemplate
  2. //app/use
  3. //app/init
  4. //app/name
  5. //app/client/header/title
  6. //app/client/header/keywords
  7. //app/client/header/metas/element
  8. //app/client/header
  9. //app/client/content/*
  10. //case
  11. //import
  12. //app/filters/dom/filter/import
  13. //advancedimport
  14. //app/filters/dom/filter/advancedimport
  15. //exec | processing-instruction('exec')
  16. //lang/[activeLanguage]/[appName]/sys/*
  17. //lang/[activeLanguage]/[appName]/ui/*
  18. //lang/[activeLanguage]/[appName]/err/*
  19. //app/filters/dom/filter/xpath
  20. //app/filters/dom/filter/nodelist
  21. //app/filters/dom/filter/domiterator
  22. //app/filters/ob/filter/match
  23. //app/filters/ob/filter/matchiterator
  24. //app/filters/ob/filter/marker
  25. //app/filters/ob/filter/eval
  26. //replace
  27. //runhere
  28. processing-instruction('php')
  29. global parsers (parsers.xml)
  30. //app/parsers

Directives and Filters syntax

  1. directiveName ($callParam1,$callParam2,...) [attribute],[attribute]
    • childDirective ($callParam1,$callParam2,...)
  2. filterName [attribute],[attribute]
    • childFilter

Further in the documentation we will often reffer to directives and filters as executing functions: these functions are all lambda type php functions, created on the fly so you do not have to write the whole function, only the code in it
- WRONG WAY: function my_function() {CODE}
- GOOD WAY: CODE

- CODE is to be declared in the first child of type processing instruction (in Designer is #pi of nodeName)
- CODE is the $code parameter of php's create_function, therefore it does not contain the whole declaration of the function

All the variables declared in these functions are local and will be lost once the function is executed. To access or declare new global variables, from within the lambda functions you have to use this syntax: $GLOBALS["MYVAR"]

In order to understand easily how each directive or filter works, download and open (either in Designer or a text editor) the examples provided for each of them.

List of filters

DOM tools

  1. xpath
  2. Executes the function for each DOM element of the xpath query;The DOM element is $el argument of the function;

    Context: //app/filters/dom/filter/xpath

    Remarks:
    - filter node first processing instruction holds the function code;
    - xpath node text content holds the xpath;
    more...
  3. nodelist
  4. Executes the function, specified in the first processing instruction, with $GLOBALS["HTMLPARSER"]->q(xpath) as $el argument of the function;

    Context: //app/filters/dom/filter/nodelist

    Remarks:
    - filter node first processing instruction holds the function code;
    - nodelist node text content holds the xpath;
    - $GLOBALS["HTMLPARSER"] is an instance of awsXML class; For further details see class documentation;
    more...
  5. domiterator Since AWS XMS 1.0 beta 10
    • eachreference ($el,$label,$value,$recordset) Since AWS XMS 1.0 beta 10
    • eachnamedreference ($el,$label,$value,$recordset) Since AWS XMS 1.0 rc2
    • norecords Since AWS XMS 1.0 RC1
  6. Replaces with a given value, corresponding descendants of unit node indicated by the labels of the array;

    Context: //app/filters/dom/filter/domiterator

    Remarks:
    - This directive uses DOM to make replacements
    - unit is a descendant of the each xpath node and will be multiplied (as clone) as many times as the assoc array levels are; unit node will be removed from DOM;unit node will be identified by the document processor as the one child having the unit attribute;
    - corresponding descendants of unit will be identified by document processor by the value of "reference" attribute; the value needs to be one of the labels of the array (see a model below);
    -filter node first processing instruction holds the function code; this has to return an array of associatice arrays like
    array(0=> array("label1"=>"Value", "label2"=>"Value", ....), 1=> array("label1"=>"Value", "label2"=>"Value", ....),...)
    -domiterator node text content holds xpath;
    more...
  7. import [source],[xpath],[importashtml],[cache],[cachestorage],[clearcache]
    • check ($doc,$el)
    • eachnode ($el)
    • filter ($doc,$el)
    • runfirst ($doc,$el)
  8. import filter was introduced as a filter in AWS XMS 1.4. The reason is mainly to be able to access AWS XMS code (HTML source as well) when using remotetemplate directive. By using this new "import" filter you are able to alter the client side.

    Context: //app/filters/dom/filter/import

    Remarks:
    - "import" filter has the same syntax as import directive;
    - text content of "filter" will hold the xpath; all the DOM elements found will be sent as parameters for "import/eachnode";
    more... import directive documentation
  9. advancedimport [source],[xpath],[importashtml],[cache],[cachestorage],[clearcache]
    • check ($doc,$el)
    • eachnode ($el)
    • filter ($doc,$el)
    • runfirst ($doc,$el)
  10. advancedimport filter was introduced as a filter in AWS XMS 1.4. The reason is mainly to be able to access AWS XMS code (HTML source as well) when using remotetemplate directive. By using this new "advancedimport" filter you are able to alter the client side.

    Context: //app/filters/dom/filter/advancedimport

    Remarks:
    - "advancedimport" filter has the same syntax as advancedimport directive;
    - text content of "filter" will hold the xpath; all the DOM elements found will be sent as parameters for "advancedimport/eachnode";
    more... advancedimport directive documentation

Text processing tools

  1. marker
  2. Replaces the marker with the given string within the whole document

    Context: //app/filters/ob/filter/marker

    Remarks:
    - filter node text content holds the replacement text;
    - marker node text content holds the text to be replaced (marker);
    more...
  3. eval
  4. Replaces the marker with the return value of the function within the whole document

    Context: //app/filters/ob/filter/eval

    Remarks:
    - filter node text content holds the replacement text;
    - eval node's first processing instruction holds the function code;
    more...

Mixed processors

  1. match
  2. Replaces the returned array labels with corresponding values of each DOM element's source returned by the xpath query

    Context: //app/filters/ob/filter/match

    Remarks:
    - array labels will be enclosed first between AWS_ITERATOR_MATCH_PREFIX and AWS_ITERATOR_MATCH_SUFFIX, then the replacement is made
    - AWS_ITERATOR_MATCH_PREFIX and AWS_ITERATOR_MATCH_SUFFIX are defined in defaults.php;
    - filter node's first processing instruction holds the function code;
    - match node text content holds xpath;
    more...
  3. matchiterator
    • norecords Since AWS XMS 1.0 RC1
  4. Replaces with a given value ,indicated by the labels of the array, corresponding markers in unit's source;

    Context: //app/filters/ob/filter/matchiterator

    Remarks:
    -unit is a children node of the each xpath node, that will be used as source and multiplied; unit node will be removed from DOM when the multiplication finishes;unit node will be identified by the document processor as the one child having the unit attribute;
    - array labels will be enclosed first between AWS_ITERATOR_MATCH_PREFIX and AWS_ITERATOR_MATCH_SUFFIX, then the replacement is made
    - AWS_ITERATOR_MATCH_PREFIX and AWS_ITERATOR_MATCH_SUFFIX are defined in defaults.php;
    -filter node's first processing instruction holds the function code; this has to return an array of associatice arrays like
    array(0=> array("label1"=>"Value", "label2"=>"Value", ....), 1=> array("label1"=>"Value", "label2"=>"Value", ....),...)
    -matchiterator node text content holds xpath;
    more...

List of directives

Server side coding

  1. init Since AWS XMS 1.0 RC1
    • return Since AWS XMS 1.0 RC1
  2. First code to be executed; same as 'exec' directive, only that is executed right after 'use' directive; you can create a 'return' child directive and result is put in GLOBALS["APPINIT"][returnDirectiveText]; (ex. when connecting to a database,...) more...
  3. php processing instruction (php#pi)
  4. Executes the function and returns the result;
    - $el parameter of the function is the parent node of the processing instruction;
    - if the function returns a string or DOM node, when finished the processing instruction is replaced by the return value

    Context: anywhere in //app/client

    Remarks:
    - this is basically the <?php CODE?> that we all know from daily php programming;
    more...
  5. exec ($el) DEPRECATED
    • return
  6. Executes the function and returns the result in the $GLOBAL["return_node_text_content"]

    Context: anywhere in //app/client

    Remarks:
    - exec text content is the code to be executed;
    - directive's $el param is the parentNode;
    - exec directives will be executed in the order found in the DOM tree;
    - exec/return is optional;
    - only one return children is allowed and this will be the key name of $GLOBALS where the result is stored;
    more...
  7. runhere ($el) DEPRECATED
  8. Similar with exec, different timing (see Processing order)
    more...

Source managing tools

To parse remote files "allow_url_fopen" needs to be set to On in php.ini
  1. import [source],[xpath],[importashtml],[cache],[cachestorage],[clearcache]
    • check ($doc,$el)
    • eachnode ($el) Since AWS XMS 1.0 beta 10
    • filter ($doc,$el)
    • runfirst ($doc,$el) Since AWS XMS 1.0 beta 10
  2. Imports a local (or remote) xml (or html) resource and builds an awsXML (or awsHTML) object with it; The nodes specified by the xpath attribute will replace the import directive within the client side of the application;

    Context: anywhere in //app/client

    Remarks:
    - the source document has to be valid (no missing tags);
    - source attribute is optional; in case it does not exists the application's document itself is used;
    - xpath attribute is mandatory
    - import/runfirst is the first function to be executed, and is mainly used to change the attributes of import directive (xpath, source, importashtml,cache,...). If present, the document processor will create a lambda function from first processing instruction child of the runfirst node and execute it with $el parameter as the DOMNode of parent import directive
    - import/eachnode is present, the document processor will create a lambda function from first processing instruction child of the "eachnode" node and execute it with $el parameter as the DOMNode of each new node that is to be imported;
    Return values
    - TRUE the current node is imported
    - FALSE or does not return anything the node is not imported
    - text value this will be used to create a documentFragment to be used instead of the current node
    - if dom node object then will be used instead of the current node

    - import/check is given, the document processor will create a lambda function from first processing instruction child of the check node and import the new element or not, depending on the result of the function (function needs to return a value);
    - if import/filter is given, the document processor will create a lambda function from the first processing instruction child of the filter node and this function will be called with $doc parameter, awsXML (or awsHTML) instance on the local/remote file;
    more...
  3. advancedimport [source],[xpath],[importashtml],[cache],[cachestorage],[clearcache]
    • check ($doc,$el)
    • eachnode ($el) Since AWS XMS 1.0 beta 10
    • filter ($doc,$el)
    • runfirst ($doc,$el) Since AWS XMS 1.0 beta 10
  4. Same like import directive above, additionally has the ability to connect to the data sources using php streams. This means you will be able to make posts, bind connection to certain sockets, even use a proxy.

    Context: anywhere in //app/client

    Remarks:
    - the source html document has to be valid (no missing tags) and comply with w3c rules;
    - source attribute is optional; in case it does not exists the application's document itself is used;
    - xpath attribute is mandatory
    - advancedimport/runfirst is the first function to be executed, and is mainly used to change the attributes of import directive (xpath, source, importashtml,cache,...). If present, the document processor will create a lambda function from first processing instruction child of the runfirst node and execute it with $el parameter as the DOMNode of parent advancedimport directive
    - if advancedimport/eachnode is present, the document processor will create a lambda function from first processing instruction child of the "eachnode" node and execute it with $el parameter as the DOMNode of each new node that is to be imported; if this function returns TRUE, the current node is imported, if returns FALSE or does not return anything the node is not imported; if returns a text value, this will be used to create a documentFragment to be used instead of the current node
    - if advancedimport/check is given, the document processor will create a lambda function from first processing instruction child of the check node and import the new element or not, depending on the result of the function (function needs to return a value);
    - if advancedimport/filter is given, the document processor will create a lambda function from the first processing instruction child of the filter node and this function will be called with $doc parameter, awsXML (or awsHTML) instance on the local/remote file;
    more...
  5. replace ($el)
  6. Replaces itself with the result of the function created from the node's first processing instruction. Result of the function can be both text or XML and will be used to make a document fragment that replaces the directive in the DOM tree

    Context: anywhere in //app/client

    more...
  7. case
  8. Case directive is similar with the switch - case in any programming language. Basically you can define several blocks of xml and select the right one to be displayed;

    Context: anywhere in //app/client

    more...
  9. remotetemplate [source],[cache],[cachestorage],[clearcache] Since AWS XMS 1.1
    • check ($doc,$el) Since AWS XMS 1.1
    • filter ($doc,$el) Since AWS XMS 1.1
    • runfirst ($el) Since AWS XMS 1.1
  10. This directive will load a remote web page, convert it to aws xms format and add the result to your application as client tree (header/content). Using Filters you can modify it to suit your need. Cache (or local storage) can be used as well to improve performance.

    Context: direct children of //app
    more...
  11. use [source],[xpath],[where]
    • check ($doc,$el) Since AWS XMS 1.0 beta 9
  12. Purpose of this directive is to import first level directives (filters, content, name) from source file in current application. In a way provides the same functionality as include does for php

    Context: direct children of //app
    more...

Typical HTML


The easy way to learn how these directives work is to use Designer's IMPORT HTML INTO ACTIVE NODE tool.

Download exampleRun example

  1. load [type],[src]
  2. Loads a client script (javascript) file. Copies all other attributes of the directive to the output "script" tag
  3. links/element
  4. Links a new resource to the output document. It has this structure "links/element" to keep the application organized better so when you want to add a new link you can either use an existing sequence "links/element", or add a new "element" child inside an existing "links".
    XMS copies all the attributes of the "element" node to the output "link" tag.
  5. metas/element
  6. Same like "links/element" above, except that outputs a "meta" tag from each "element"
  7. title
  8. Sets the document title
  9. style [type],[src]
  10. this will load the styles; if the href attribute is given, document processor will create a link element, else will create a style element;
  11. run
  12. this will run the javascript in the text node

User defined filters (parsers) Since AWS XMS 1.0 RC1

A user filter has the following structure:
  • item
    • xpath
    • callback ($el)
    • check
    • alias

There are two types of user defined filters:
  • Global filters, executed for all applications and defined in parsers.xml
  • Application related user filters, defined in any application, under /app/parsers node; these filters are only executed in the application where are defined

Remarks:
- In order to avoid confusing the user filters with predefined filters of XMS, I named the user defined filters as parsers as they are defined under "parser" node either in the applications or parsers.xml

- xpath and callback are mandatory;

- xpath text content is the xpath of the target nodes;

- callback first processing instruction child holds the code of the function to be executed for each DOMElement in the xpath (as $el parameter)

- check and alias are optional;

- check first processing instruction child holds the code of the function to be executed; "check" is the first function to be executed and if returns FALSE the parser will stop, without going further and look for the elements in the xpath

- alias doesn't play any role and is only meant for the programmer to put some note in it, in order to know what this parser stands for;

Global parsers

Download example

Application parsers

Run exampleDownload example

Global Variables

  1. $GLOBALS["HTMLPARSER"]
  2. awsXML instance of the output document; Due to backward compatibility reasons I kept the same name for it but this will change in future realeases. As it is built from the application's "client" node, keeps the same structure (client/header|content) and will be translated later through XSL to the desired document type (for html: client->html, header->head, content->body, for xml could stay the same or change based on custom xslt)
  3. $GLOBALS["TEMPLATE"]
  4. awsXML instance of the application file
  5. $GLOBALS["LANG"]
  6. awsXML instance of the multilanguage support file
  7. $GLOBALS["CONFIG"]
  8. awsXML instance of the configuration file

Designer - application editor

The only tool used to build the applications, edit language and config files, importing offsite pages to use as app templates even design your own rss news page. XML code is represented in a tree like structure
more...

Multi-language support

Multi language support is provided by offering a linkage between the document entities and the language file. When processing, entities in the language file having a xpath connection to the document will replace these. The language processing is made after executing import and exec directives.

Remarks:
- This processor will only work if you set up application's name with name directive, as the language file structure looks like //lang/langName/appName/...
- Default language file is lang.xml and can be found in the root folder;
more...

Builtin classes

  1. awsCommonXML
  2. Abstract class enabling basic XML operations; parent of awsHTML and awsXML classes
    more...
  3. awsHTML
  4. This class is a tool that can be used to parse HTML files in a intuitive manner using chainability. The DOMNodeList can be easily accesed though results property of the awsHTML instance.

    Sample code:
    $app = new awsHTML(file_get_contents("appTemplate.xml"));

    $app->q("//a[@id='id_of_entity']")->
    each("do_something_callbackFunction")->
    removeAttr("SOME_ATTRIBUTE")->
    attr("ANOTHER_ATTR","VALUE")->
    append("HTML_FRAGMENT")->
    prepend("HTML_FRAGMENT")->
    q("something_else_xpath")->
    replace("HTML_FRAGMENT")->
    q("something_else_xpath")->
    removeChilds()->
    append("HTML_FRAGMENT");

    echo $app->content();

    more...
  5. awsXML
  6. Same like awsHTML but only works with XML files
    more...
  7. awsPDO
  8. Based on php pdo driver this class is an interface for handling the following databases: MySQL, PostgreSQL, Ms SQL / DBLIB, SQLite. We are currently working to extend support for Oracle and Firebird.
    Using modified DNS (data source name) you can instantly connect to your database, get all needed info about the tables you are working with, retrieve the query results as arrays

    Sample code:
    $do = new awsPDO("mysql://user:user@host/dbName/tableName");
    $do->userQuery("insert into {table} (ip,date) values ('ip',NOW());");

    more...

Utilities

  1. appConfig($query,$context,$alternateConfigFile)
  2. Utility function to aquire data from the config file. Will return the text content of the node selected with the xpath query;

    Remarks:
    - If no other file is given as parameter, config.xml will be used as default
    - Before use this function set up the application name using the name directive
    - Given query needs to be like /nodeName1/nodeName2/.... as this will be automaticaly prepended by //config/appName
    more...