Location: PHPKode > scripts > PAX > pax/doc/tutorial.txt

1. What is it?
	PAX, first of all, is an acronym for (P)HP (A)ctive (X)ml. It is based on PHP
and XML functionality to accomplish various tasks. In fact, due to the status of
XML which is open and the simplicity of PHP, you can add new functionalities for
PHP in no time with a minimum of XML and PHP understanding.

2. How it works?
	In order to extend PHP with your functionality, you must understand the XML
format and for this you can visit http://www.w3schools.com/xml/default.asp for
	The main ideea behind the PAX, like many other good ideas, is that the simple
facts are always the best. The PAX input is a XML file that contains one root
element and nodes. Each of this node from the file is considered later as a PHP
class that has to provide some basic functionality. What this class does it up
to you, use your imagination. 
	Further more, this XML file has to meet some requirements. These requirements
refers to which tags are allowed, what are each tag's allowed attributes and what
are the value for these attributes and what is the valid tag content. All these
pieces together form the model concept. In this model that is a directory, there
must be, if wanted, the following informations:
- model definition
	- allowed tag and valid tag attributes
- model libraries - needed for your work
- model implementation - classes for each node used
- extra functions, also needed for your work

2.1. Tag definitions
	In a XML file configured in the setup is the list of all the tags that are valid
for the model. This list if grouped under a root tag, also configurable, like the 
following example:

	<example />
	<say />

	Above I mentioned to the model that are two tags that are allowed, the "example"
and "say" tag. If a node found in the source XML is not also present in the 
definition, it will be ignored from parsing.

2.2. Tag attributes
	This file is more complex than previous, but as important as it. It mentions
not only what are the valid attributes for each node, but also it signature. This
signature will allow later when filtering is done, to keep only the valid data
for parsing. Lets take the following example:

<attributes xmlns:a="http://pax.org/a">	
		<compileInstructions type="string"/>
		<message mandatory="yes" defaultValue="Hello!" type="string" minLength="1" maxLength="250" trim="yes"/>
		<from mandatory="yes" defaultValue="pax" type="string" minLength="1" maxLength="250" trim="no" />

	Like the tags' xml file, I mentioned to the model that I have two nodes, 
"example" and "say" and for these nodes, I want to specifiy their valid attributes
"compileInstructions" for "example" and "message" and "from" for "say". The other 
attributes found have the following meaning:
- "mandatory" (configurable) means if the tag is mandatory or not. If an attribute 
is mandatory but not found in the source file, it will be added by default with the 
value specified in the "defaultValue" (configurable).
- any other attribute found will be passed to the node's class for filtering, there
is no limit of what these attributes are and what they do - is up to you to provide
(if wanted) the semantics for them and the functionality.

2.3. Model libraries 
	Specify the libraries needed for your functionality here. Use the "_addLiraries.php"
(configurable) to load them.

2.4. Extra
	Specifiy any other functionalities needed (like functions, etc) for your actions here. 
Use the "_addExtra.php" (configurable) to load them.

2.5. Model implementations
	This is the part if (A) in the PAX, or the active part. For each node found in 
the source, there must be a PHP class for each of it. Additionaly, it provides extra
functionality as in the following example:

final class Say extends Node
	public function __construct()
	public static function validateAttributeValue_FROM($attributeValue, $attributeDefinition)
		return $attributeValue; 

	public static function validateContent($content)
		return $content;

	public function onOpen()
	    echo sprintf("Saying %s from %s: ", $this->attributes['message'], $this->attributes['from']);

	public function onClose()
	    echo $this->content . "<br/>";
		echo 'Please enjoy the program' . '<br/>';

	Like said before, the class is the one that interprets the XML and also validate the 
content. This validation is done for the attribute values and also for the tag node, where
is found. 
	To validate node attribute's value, you must define a method for each node and the 
method name is "validateAttributeValue_[ATTRIBUTE]" configurable. This function takes
as parameter the attribute value and the definition as found in the "attributes.xml" file.
	Further more, the content of the node can be validated using the method 
"validateContent" that takes as parameter the current content of the node. 
	In order to define an action for a node, at least two more functions must be defined. The
previous validations methods are optional, but the next two are mandatory. These are "onOpen"
and "onClose". Optionally, a third function can be defined, "onComplete" and this function
will be called when the tag is in short form (like "<tag />"). The "onOpen" and "onClose"
functions will be called when the tag starts ("<tag>") and completes ("</tag>").
	The current node has access by reference to a custom user object. Using this custom object,
you can add extra functionality to the program. For this functionality please see the method

3. Putting all together: The input source
	The PAX "fuel" consists in XML files. The first condition that these files must meet is
that they need to be valid. If not, PAX will throw exceptions and parsing will stop. For 
example, lets consider the following source file:

<?xml version="1.0" ?>
<example paxns:e="example">	
    <say>Hello world from PAX v_PAX_VERSION_! The date is !# return date("r"); #!</say>   

	The first line is a standard XML declaration. Next is a tag called "example" with an
inner tag "say". The "example" tag also has a namespace definition, "e". This is a first
difference from the previous version, since from now you can define implementations that
are valid for various model, but for not repeating them every time, only once they are
made, and use as many times as needed. To do this, set an alias for the namespace, like
"e" in the example above and set the directory where the implementations resides. This
directory must be a subdirectory in the global namespaces directory. When a tag name
is composed using a namespace alias, like "<e:say>", PAX knows that needs to load the 
"say" implemenation from the namespace alias "e" and not from the current model. The 
following variables are already made available:

_NODE_NAME_ : the name of the node (like "say")
_NODE_TYPE_: the type of the node ("open", "close", "complete")
_NODE_LEVEL_: the level of the node
_NODE_VALUE_: the content of the node
_NODE_IS_ROOT_: 1 or 0 if the node is the root or not
_NODE_HAS_ATTRIBUTES_: 1 or 0 if the node has or not attributes
_NODE_ATTRIBUTES_COUNT_: the count of the attributes
_NODE_ATTRIBUTE_X_ : the value of attribute X

	Next, there are another updates from the previous versions. First comes the custom
variables, that will be replaced with their value before parsing the file. Such 
custom variable is _PAX_VERSION_ and will be replaced with the value "6" before calling
the "say" implementation. The same actions applies to PHP instructions, delimited by
a start ("!#") and end delimiter ("#!") both configurable in config. Inside these 
delimiters almost any PHP instruction can be written and evaluated before the parsing
of file begins. 
	The above source file with the implementation specified will produce the following

Starting PAX
Saying Hello! from pax: Hello world from PAX v6! The date is Tue, 06 Jan 2009 17:28:36 +0200
Please enjoy the program
Stopping PAX ... 
(C) Marius Zadara, 2008

	Notice how the variable and instruction have been replaced. There is no limitation to
the number of variables or instructionns present in a tag or attribute, but the 
instructions must be correct.

4. Where can be used
	Is up to you. Because at the heart of PAX is XML technology, PAX can be used in 
interpreting XML files more than only display them as a XSL processor. These files, along
with their implementations can be used various transactions, like B2B processes, etc.

5. License to use
	PAX comes with a "free for non-comercial" license. This means that as long as is not
used in commercial applications, it is free. For further informations, please read the 
"license.txt" file and fell free to contact me using the e-mail address hide@address.com
Any comments will be appreciated. Thanks and enjoy!


Return current item: PAX