Changeset View
Changeset View
Standalone View
Standalone View
externals/JAXL/docs/users/xml_objects.rst
- This file was added.
.. _xml-objects: | |||||
Xml Objects | |||||
=========== | |||||
Jaxl library works with custom XML implementation which is similar to | |||||
inbuild PHP XML functions but is lightweight and easy to work with. | |||||
JAXLXml | |||||
------- | |||||
``JAXLXml`` is the base XML object. Open up :ref:`Jaxl interactive shell <jaxl-instance>` and try some xml object creation/manipulation: | |||||
>>> ./jaxlctl shell | |||||
jaxl 1> | |||||
jaxl 1> $xml = new JAXLXml( | |||||
....... 'dummy', | |||||
....... 'dummy:packet', | |||||
....... array('attr1'=>'friend@gmail.com', 'attr2'=>''), | |||||
....... 'Hello World!' | |||||
....... ); | |||||
jaxl 2> echo $xml->to_string(); | |||||
<dummy xmlns="dummy:packet" attr1="friend@gmail.com" attr2="">Hello World!</dummy> | |||||
jaxl 3> | |||||
``JAXLXml`` constructor instance accepts following parameters: | |||||
* ``JAXLXml($name, $ns, $attrs, $text)`` | |||||
* ``JAXLXml($name, $ns, $attrs)`` | |||||
* ``JAXLXml($name, $ns, $text)`` | |||||
* ``JAXLXml($name, $attrs, $text)`` | |||||
* ``JAXLXml($name, $attrs)`` | |||||
* ``JAXLXml($name, $ns)`` | |||||
* ``JAXLXml($name)`` | |||||
``JAXLXml`` draws inspiration from StropheJS XML Builder class. Below are available methods | |||||
for modifying and manipulating an ``JAXLXml`` object: | |||||
* ``t($text, $append=FALSE)`` | |||||
update text of current rover | |||||
* ``c($name, $ns=null, $attrs=array(), $text=null)`` | |||||
append a child node at current rover | |||||
* ``cnode($node)`` | |||||
append a JAXLXml child node at current rover | |||||
* ``up()`` | |||||
move rover to one step up the xml tree | |||||
* ``top()`` | |||||
move rover back to top element in the xml tree | |||||
* ``exists($name, $ns=null, $attrs=array())`` | |||||
checks if a child with $name exists, return child ``JAXLXml`` if found otherwise false. This function returns at first matching child. | |||||
* ``update($name, $ns=null, $attrs=array(), $text=null)`` | |||||
update specified child element | |||||
* ``attrs($attrs)`` | |||||
merge new attrs with attributes of current rover | |||||
* ``match_attrs($attrs)`` | |||||
pass a kv pair of ``$attrs``, return bool if all passed keys matches their respective values in the xml packet | |||||
* ``to_string()`` | |||||
get string representation of the object | |||||
``JAXLXml`` maintains a rover which points to the current level down the XML tree where | |||||
manipulation is performed. | |||||
XMPPStanza | |||||
---------- | |||||
In the world of XMPP where everything incoming and outgoing payload is an ``JAXLXml`` instance code can become nasty, | |||||
developers can get lost in dirty XML manipulations spreaded all over the application code base and what not. | |||||
XML structures are not only unreadable for humans but even for machine. | |||||
While an instance of ``JAXLXml`` provide direct access to XML ``name``, ``ns`` and ``text``, it can become painful and | |||||
time consuming when trying to retrieve or modify a particular ``attrs`` or ``childrens``. I was fed up of doing | |||||
``getAttributeByName``, ``setAttributeByName``, ``getChild`` etc everytime i had to access common XMPP Stanza attributes. | |||||
``XMPPStanza`` is a wrapper on top of ``JAXLXml`` objects. Preserving all the functionalities of base ``JAXLXml`` | |||||
instance it also provide direct access to most common XMPP Stanza attributes like ``to``, ``from``, ``id``, ``type`` etc. | |||||
It also provides a framework for adding custom access patterns. | |||||
``XMPPMsg``, ``XMPPPres`` and ``XMPPIq`` extends ``XMPPStanza`` and also add a few custom access patterns like | |||||
``body``, ``thread``, ``subject``, ``status``, ``show`` etc. | |||||
Here is a list of default access patterns: | |||||
#. ``name`` | |||||
#. ``ns`` | |||||
#. ``text`` | |||||
#. ``attrs`` | |||||
#. ``childrens`` | |||||
#. ``to`` | |||||
#. ``from`` | |||||
#. ``id`` | |||||
#. ``type`` | |||||
#. ``to_node`` | |||||
#. ``to_domain`` | |||||
#. ``to_resource`` | |||||
#. ``from_node`` | |||||
#. ``from_domain`` | |||||
#. ``from_resource`` | |||||
#. ``status`` | |||||
#. ``show`` | |||||
#. ``priority`` | |||||
#. ``body`` | |||||
#. ``thread`` | |||||
#. ``subject`` | |||||