DOMi, DOM Improved
What Is DOMi?
DOMi is an improved DOM object for PHP that combines and improves upon the
capabilities of three existing PHP objects: DOMDocument, DOMXpath and
XSLTProcessor. These three objects, combined with the XSL language, create a
templating system that can be used to render HTML pages., (*1)
Example
Creating the DOMi object
The first step to using DOMi to create an XSL template is to include the DOMi
class and create an instance of the DOMi object. DOMi's constructor requires a
single parameter to be passed over. This parameter is used to set up the
DOMDocument object that DOMi will use to build the XML tree. Three different
kinds of parameters can be passed to create a DOMi object., (*2)
The first way to create a DOMi object is passing a string to be used as the
node name of the root node of the XML document, as in the example below., (*3)
$DOMi = new DOMi('root');
The second way to create a DOMi object is by passing a string that is the
filename of a local XML document., (*4)
$DOMi = new DOMi();
$DOMi->load('/var/www/xml/document.xml');
The third way to create a DOMi object is by passing a DOMDocument object, and
DOMi will use this DOMDocument as it's primary DOMDocument, (*5)
$DOMDocument = new DOMDocument('1.0', 'UTF-8');
$DOMi = new DOMi($DOMDocument);
In all three events, DOMi is created with a built in DOMDocument, DOMXpath and
XSLTProcessor. Each of these objects is a member property that can be accessed
transparently through DOMi. For instance, if you wanted to use the
DOMXpath::query method, you could access it in one of two ways, (*6)
$DOMi->Xpath->query()
$DOMi->query()
Both of these methods are identical. When an unknown method is requested of
DOMi, it will check to see if that method exists within it's member objects,
and if so, return the result of the member object invoking the requested method.
Through this system, legacy support for old DOMDocument setups is 100%., (*7)
Adding data to DOMi
Once the DOMi object exists, the next step is to begin adding data to the
DOMDocument, and the best way to do this is through the DOMi::AttachToXml
method. This method will accept a PHP data structure and transform it into an
XML tree and attach it to the DOMDocument inside DOMi. Currently,
AttachToXml supports the following PHP data structures, (*8)
- Array
- String
- Int
- Null
- DOMDocument
- DOMElement
- Any PHP object
AttachToXml accepts two required parameters and a third optional parameter. The
first parameter is the data to be converted into an XML tree. The second
parameter is the name to be used for the node. The third parameter is a DOMNode
within DOMi's DOMDocument where the new node will be attached, this will default
to the root node., (*9)
$DOMi->AttachToXml($_SERVER, 'server');
This code will make a new node named <server>, attach that to the root
node of the DOMDocument, and create new nodes for each element within the
$_SERVER superglobal array., (*10)
Adding stylesheets
DOMi can import a stylesheet upon rendering, or a manual call can be made to
add the stylesheet. If you plan to add upon rendering, which is a simpler,
cleaner method, you may skip to the Rendering section., (*11)
As mentioned above, DOMi is capable of transparently accessing any of the
methods of DOMDocument, DOMXpath and XSLTProcessor. This means that stylesheets
are added through the same method as XSLTProcessor - the importStylesheet()
method., (*12)
$DOMi->importStylesheet($DOMStylesheet);
However, DOMi has a method that allows for easier creation of DOMDocument
objects that are to be used as stylesheets. The GenerateXsl() method accepts
either a string or an array of filenames that are to be included. This method
will then dynamically create a DOMDocument that includes each of the provided
stylesheets, which is useful when the list of stylesheets to be included will
vary based on what page the user is looking at. GenerateXsl will, by default,
then import these stylesheets, although a second parameter can be passed to
disable this feature., (*13)
$DOMi->GenerateXsl('/var/www/xsl/skin.xsl');
Rendering
Once DOMi has been created, data has been added, and a stylesheet has been
imported, the only thing left to do is render the page. DOMi::Render() is the
method that DOMi uses to run the XSLTProcessor and return the output.
Render() accepts two optional parameters - the file location for an XSL
stylesheet and a rendering flag. The first parameter can be used to provide
the stylesheet upon rendering, if GenerateXsl() or importStylesheet() is not
called. The second flag can be set to one of the following three values, (*14)
- DOMi::RENDER_HTML - the default setting that will run the XML and XSL
stylesheet through the XSLTProcessor and return the output.
- DOMi::RENDER_XML - display the DOMDocument contents with the content type set
as XML, this is the useful for debugging as it lets you see your XML tree to
help you write your XSL.
- DOMi::RENDER_VIEW - display the result of the XML / XSL / XSLTProcessor
conversion with the content type set as XML, this is primarily used for
writing APIs.
License
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version., (*15)
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details., (*16)
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/., (*17)
Wallogit.com
