Hi Alex, Thanks for the answer :)
On Fri, 2008-02-01 at 13:39 +0100, Alexandru Stanoi wrote:
> > - 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?
Annotate, eg, define, which direct conversion exist, like:
ezcDocumentRstDocument extends ezcDocument implments
ezcDocumentHtmlConversion
>
> > - 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?
This is not specified in the original document, but ezp does something
like this now. As the original design document mentions this as a way to
"output" documents, I wanted to mention it here. Not sure about the
possible implementation details yet.
Perhaps this could be just done by specifying callbacks for all XML
elements, and returning a new one, constructed out of the attributes and
the element content. I think normally a XSLT should be used for all
XML->XML conversions...
> > 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.
Yeah, I thought about something like this, too. Won't be that easy,
though. For example, if you receive an errnous HTML document (which
could be quite usual), the XHtml document and the Html document handler
will throw errors, so what to use here?
I think normally the application developer knows which type of file he
wants to handle, and can present an error to the user, if is is wrong
file. It still would be a nice feature. With the manager in place I
think this would be easy to add later, based on validation, mime-type
and similar.
> > 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' );
You just instantiate an object, which you may want to configure in some
special way, to modify the validation rules (like forcing XHtml 1.1
strict, or similar). But I don't really care if this is a static method
or not :).
> > 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.
Works for me, too.
> 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.
Thought about this, too - and in the end it does not really matter for
me. Whatever matches the guidelines better. :)
> > 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?
No, just wanted to include an example for configuring the conmversion,
because it was included in the old versions examples, too.
In this case I included this, because I assume, literal blocks are
normally converted to <pre>, and maybe someone wants them to be
converted to <code> instead...
--
Mit freundlichen Grüßen / Med vennlig hilsen
Kore Nordmann (GPG: 0xDDC70BBB)
eZ Components Developer
eZ systems Headquarters
tel +49 (0) 231-9742-7750 | fax +49 (0) 231-9742-7751
[EMAIL PROTECTED] | eZ systems | ez.no
signature.asc
Description: This is a digitally signed message part
-- Components mailing list [email protected] http://lists.ez.no/mailman/listinfo/components
