197 lines
5.5 KiB
Plaintext
197 lines
5.5 KiB
Plaintext
eZ Component: Document, Design
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
:Author: $Author$
|
||
:Revision: $Revision$
|
||
:Date: $Date$
|
||
|
||
Design description
|
||
==================
|
||
|
||
ezcDocument class (abstract)
|
||
----------------------------
|
||
|
||
This class is the base class for each implemented markup format. The extending
|
||
classes are named like 'ezcDocumentHtmlDocument'.
|
||
|
||
The extending classes implement the required actions to load a file or string
|
||
in the respective markup and return an arbitrary structure describing the
|
||
document and containing all available markup information. For each document
|
||
there will be at least a conversion to the DocBook__ format.
|
||
|
||
The document classes may implement additional interfaces for direct access to
|
||
some converted format, if there are shortcut implementations available, like
|
||
the following example shows::
|
||
|
||
<?php
|
||
class ezcDocumentRstDocument extends ezcDocument implements
|
||
ezcDocumentHtmlConversion
|
||
{
|
||
// Required by ezcDocumentHtmlConversion interface
|
||
public function getAsHtml()
|
||
{
|
||
// Use direct conversion using `rst2html.py`
|
||
}
|
||
}
|
||
?>
|
||
|
||
Beside loading a document all document classes need to implement save()
|
||
method, which returns the document serialized as a string.
|
||
|
||
ezcDocumentWikiBase class
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
There may be extensions, like a basic wiki syntax parser, from the document
|
||
class, which implement a set of parse helper functions for some set of markup
|
||
languages.
|
||
|
||
ezcDocumentConversion interface
|
||
-------------------------------
|
||
|
||
Interface that defines an abstract conversion class. Real conversion classes
|
||
will implement conversion of the given document from one format to another.
|
||
The names of that classes follow the pattern:
|
||
'ezcDocumentRstToHtmlConversion'.
|
||
|
||
The main method of this abstract class, convert(), takes a document of the
|
||
first format and returns a document in the other format. Both objects extend
|
||
the ezcDocument class::
|
||
|
||
<?php
|
||
abstract class ezcDocumentConversion
|
||
{
|
||
/**
|
||
* @return ezcDocument
|
||
*/
|
||
abstract public function convert( ezcDocument $source );
|
||
}
|
||
?>
|
||
|
||
ezcDocumentXsltConversion
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
There are a lot of conversions which may just work on the base of an XSLT. For
|
||
all those conversions an abstract ezcDocumentXsltConversion class is provided,
|
||
which just takes a set of XSLT files to apply to the XML of the source
|
||
document and handles the selection of a proper XSLT engine.
|
||
|
||
ezcDocumentManager
|
||
------------------
|
||
|
||
The document manager knows about the document parsers to use for each format
|
||
and offers a set of static convenient methods to change the used parser for a
|
||
document type, or directly create a document from a string or file. The Syntax
|
||
for accessing the document manager could look like::
|
||
|
||
<?php
|
||
ezcDocumentManager::setFormat( 'rst', 'myCustomRstDocument' );
|
||
$doc = ezcDocumentManager::loadFile( 'rst', '/path/to/my.rst' );
|
||
?>
|
||
|
||
The document manager initiall knows about all internal formats and has them
|
||
registered.
|
||
|
||
ezcDocumentConversionManager
|
||
----------------------------
|
||
|
||
This won't be implemented in the first release.
|
||
|
||
While you may call the conversion directly, the conversion manager has a set
|
||
of registered conversion routes and offers you direct access to the document
|
||
conversions, like::
|
||
|
||
<?php
|
||
$result = ezcDocumentConversionManager::convert(
|
||
'rst', 'xhtml', '/path/to/my.rst'
|
||
);
|
||
?>
|
||
|
||
There will be an interface to overwrite default conversion routes and add or
|
||
change the classes used for some conversion.
|
||
|
||
Multiple conversions
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
There may be multiple conversion implementations for a set of formats. A
|
||
conversion from ezp4xml to HTML may not only be done by using an XSLT, but also
|
||
using a simple templating enging, based on string replacements, or a
|
||
ezcDocumentTemplateTieIn which uses ezcTemplate to convert between the
|
||
documents.
|
||
|
||
ezcDocumentValidation interface
|
||
-------------------------------
|
||
|
||
The document classes may implement the ezcDocumentValidation, which provides
|
||
the method validate( $file ), which can be used to validate an input file
|
||
before trying to load it.
|
||
|
||
The XML based formats will usually implement this by checking against a
|
||
RelaxNG based document definition.
|
||
|
||
Algorithms
|
||
==========
|
||
|
||
Transforming XML
|
||
----------------
|
||
|
||
XML documents are transformed using XSLT stylesheets and XSL extension for
|
||
PHP. Transformations are done with ezcDocXSLTTransformer class. Optionally
|
||
the transformations may be done by the xsltrans CLI utility.
|
||
|
||
Examples
|
||
========
|
||
|
||
Examples for the usage of the ezcDocument API.
|
||
|
||
Loading a document
|
||
------------------
|
||
|
||
::
|
||
$doc = new ezcDocumentRstDocument();
|
||
$doc->loadFile( '/path/to/my.rst' );
|
||
|
||
Validating a set of documents
|
||
-----------------------------
|
||
|
||
::
|
||
$doc = new ezcDocumentXhtmlDocument();
|
||
$result_1 = $doc->validate( '/path/to/first.htm' );
|
||
$result_2 = $doc->validate( '/path/to/second.htm' );
|
||
|
||
foreach ( $result_1 as $error )
|
||
{
|
||
echo "- {$error->msg} in {$error->line} in {$error->file}.\n";
|
||
}
|
||
|
||
Convert between documents
|
||
-------------------------
|
||
|
||
::
|
||
$doc = new ezcDocumentRstDocument();
|
||
$doc->loadFile( '/path/to/my.rst' );
|
||
|
||
$converter = new ezcDocumentRstToHtmlConversion();
|
||
$converter->option->literalTag = 'code';
|
||
$html = $converter->convert( $doc );
|
||
|
||
// __toString() will of course be implemented, too.
|
||
echo $doc->save();
|
||
|
||
Using the document manager
|
||
--------------------------
|
||
|
||
::
|
||
ezcDocumentManager::setFormat( 'rst', 'myCustomRstHandler' );
|
||
$doc = ezcDocumentManager::loadFile( 'rst', '/path/to/my.rst' );
|
||
|
||
// All errors in the RST syntax should now be magically fixed.
|
||
echo $doc;
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: rst
|
||
fill-column: 79
|
||
End:
|
||
vim: et syn=rst tw=79
|