gnu-social/vendor/zetacomponents/document/design/design_2.txt
2021-07-16 19:44:40 +01:00

197 lines
5.5 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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