Kore Nordmann wrote:
> Hi,
>
> As shortly discussed on IRC, i still have some isses with the document
> component, as this one needs to be taken over by someone and the
> implementation has not grown that far, I summarized my changes in an
> updated design document, which I would like to see discussed here.
>
> Major changes:
>
> - Document classes are not used purely statically any more
>
> This makes the implementation easier and has benefits when you want
> to extend an existing document handler
Some things are strange for me now, see below where the validation
examples from the design documents are.
> - Format conversion are annotated by interfaces and not by static
> methods
>
> Until now a document class had to optionally implement a set of
> methods for each format it could export directly. Using non static
> access to the classes methods we can annotate this using interfaces.
> This is not only cleaner, but also makes the error handling easier.
> You do not need to try calling some method and handle the optional
> exception, but can test for the interface.
I did not really understand this part. Annotate what?
> - Templating moved to conversions
>
> For now there was a special handling of output of documents, which
> optionally could use a template system to create a string from the
> document. This can and will be implemented as a conversion.
How would a template system be used to create a string from a document?
> eZ Component: Document, Design
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> Examples
> ========
>
> Examples for the usage of the ezcDocument API.
>
> Loading a document
> ------------------
>
> ::
> $doc = new ezcDocumentRstDocument();
> $doc->loadFile( '/path/to/my.rst' );
Is it possible to autodetect the file type? Then it would be nicer to
create a generic ezcDocument object with the file passed in the
constructor, for example:
$doc = new ezcDocument( '/path/to/my.rst' );
Or just use the ezcDocumentManager::loadFile() from an example below.
Another question: what happens if the user uploads a file and the
application needs to decide what type of document it is in order to open
it? One way to do it would be to rely on a mime-type detection. Another
way would be to go through all supported document types and see if the
loadFile() method returns any errors.
Which method would be used by the Document component? Maybe there are
other methods which I don't know about.
For the Feed component there is a method canParse() in each feed type
handler (basically similar to ezcDocument*Document classes) which can
check if the handler can parse the feed, without actually parsing it
completely (check XML root name, version tag, etc). Maybe something like
that can be used for Document?
> 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";
> }
So you first need to create an empty Xhtml document, and use it to
validate xhtml files? Isn't this a bit strange? Why not use static
methods for it? Like:
$result_1 = ezcDocumentXhtmlDocument::validate( '/path/to/first.html' );
> 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();
The converter class could be called ezcDocumentRstToHtmlConverter, but
that is just my opinion.
Also, the ezcDocumentRstDocument class could be called ezcDocumentRst or
ezcDocumentRstHandler or something else, in order not to repeat the same
word in a class name.
> 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;
Do you need to set those format tables at every request? Can lazy
initialization be used for this purpose?
--
Alexandru Stanoi
eZ Components System Developer
eZ Systems | http://ez.no
--
Components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/components
