|
|
ZenEngine
the lightweight CMS framework |
Doc::Overview
# What's in a bird ?
In this document, we will just take an overall look at the way ZenEngine works. You can get more explanations in the next documents, and in the API documentation.
Navigation
To use ZenEngine, the first thing you have to do is to instanciate a ZenEngine object, passing it the path to its configuration file. This object will create directly or indirectly all the needed other objects, according to some configuration options.
The first thing that the ZenEngine object will do is to instanciate the appropriate menuMaker object, ask it for the menu, and then create a ZenMenuManager object with this menu. You can access the menu via ZenEngines's methods, or retrieve a reference to the menuMaker, and display your menu the way you like.
[New in version 0.0.6] : The new ZenEngine->getPrettyMenu() method, used with an appropriate template file,
let you display a nicely formatted menu with just one line of code. Isn't it nice ?
Displaying content
When you click on a link, the appropriate php page is called, with the key corresponding to that link. The ZenEngine object then retrieve from the menuManager the menuItem corresponding to that key, and pass it to its ZenContentManager to get the document.
The ZenContentManager look up for the docMaker class associated with the docType specified in the menuItem object, instanciate
the docMaker, and invoke its getDocument() method. The ZenDocument instance so created is sent back to the ZenEngine
object, and user code can then use the getDocumentHead() and getDocumentBody() to echo them in the page.
A sample php page using ZenEngine
The following exemple is pretty dumb, and it's obvious that the first PHP processing instructions block should go in a distinct script. Now it should give you a first - and pretty incomplete, since it doesn't cover menuMakers, docMakers, and configuration - idea of how ZenEngine works.
<?php
require_once('ZenEngine/Core/ZenEngine.inc');
$zen = new ZenEngine('conf/zenengine.conf');
$key = isset($HTTP_GET_VARS['key']) ? $key : null;
$zen->setCurrentPage($key);
?>
<html>
<head>
<?php echo $zen->getDocumentHead(); ?>
</head>
<body>
<div id='menu'>
<?php echo $zen->getPrettyMenu(); ?>
</div>
<div id='body'>
<?php echo $zen->getDocumentBody(); ?>
</div>
</body>
</html>
[top]
# Extensibility: the framework and the packages
None of this tells you how ZenEngine create the menus or the documents. Well, the fact is that ZenEngine does not create the menus and documents. Remember : ZenEngine is only a framework.
A bit of history
When I first started working on what is now ZenEngine, I wanted something that could automagically create the menu from a file system hierarchy where content would be stored in XML format (yes, that's just what the ZenFS package does, but wait a minute). Now I also wanted to be able to use several different XML format, and even non XML format. And more, I wanted to handle what I call 'composed documents', which means that multiple 'source' files could be 'assembled' into a single 'document' (a document being the true content of the page...).
While implementing first drafts, it soons appeared that I would need some 'plug-in' architecture for the class(es) in charge of translating source files to ZenDocument objects. This led to the ZenContentManager object handling association between a 'docType' (just a free alphanumeric code) and a 'docMaker', the docMaker being any class implementing a pretty simple API (2 methods). It then became possible to create doc from virtually any source, be it an XML or other textual file format, a SQL database server, or whatever can produce data.
By this time, it also became obvious that the file system based menu creation process was a show-stopper. Most of the code just didn't care about how the menu and documents were created, and this MenuMaker class was restricting the use of ZenEngine to a file system based menu... which BTW might not be the best choice. So why not make this class pluggable too ?
Back to the content management : ZenFS in a few words
So here we are : you can now use whatever docMaker and whatever menuMaker implementation you like. The existing implementations now live in the ZenFS and ZenXML packages, which will probably grow in the future. As an exemple, the ZenXML/ZenXMLMenuMaker creates the menu from an XML file.
So as you see, ZenEngine is (well, should be, let's wait for real-life tests) extensible. This site uses the ZenFSMenuMaker to create the menu. ZenFSMenuMaker walks a directory, creating ZenMenuItem objects for files and sub-directory in it. Some of those directories - those with an extension - happens to be 'composed document', the parts of the document being the files in that directory.
About docMakers, this site uses a generic XML/XSLT based docMaker. This was the most generic XML to HTML translation I could think of, and even if a good XSLT doc could help, XSLT turns out to be pretty usable and powerful - the small toc at the beginning of this page is generated by the XSLT processor. But if you fear XSLT or dont have access to it (or whatever your reason), or want to use something else than XML as document format, any PHP programmer should be able to write a specialised docMaker.
[New in version 0.0.6]Note that there's also a plain stupid HTML based docMaker (ZenFS/ZenFSHTMLDocMaker), so you can also forget about all this XML/XSLT stuff and stick to good ole HTML.
The 'News' page makes use of the ZenFSComposedDocMaker. This docMaker doesn't do much by itself, it just walks it's sub-directory, calls back the contentManager and then assemble the resulting documents into a single one. So this docMaker may be used with docMakers other than the XSLT based one.
[top]
# And for a few more features
As a last word, there are a few last feature of ZenEngine that I'd like to mention, and that are not used in this site.
php pages as templates
The first one is the possibility to use different PHP pages for different contents. As you saw in the sample page above, with ZenEngine, the php page act as a layout template. I didn't have a use for it here, but you may want to know this is possible. ZenFSMenuMaker has a builtin (and somewhat dumb) mechanism for this, based on the category name, but other menuMakers may implement whatever solution seems right for this.
Including PHP code
as ZenEngine does not build and display a whole page, but just fills in some parts of an existing php page, nothing can stop you from adding whatever PHP code (or anything else for that matter...) you like in the static part of the page. This could be for simple things like links to external pages in the menu, or for HTML/PHP forms, etc...
[top]