An introduction into JDocument
Before we dive into the actual solution we need to talk a bit about JDocument first. JDocument is a completely new framework API that allows developers to render different types of output. JDocument is a very flexible library that handles the loading and rendering of your templates and is made up out of formats and renderers.
A format is the type of document that gets created, for 1.5 the supported formats are html (default), pdf, feed, error and raw.
A renderer is responsible for creating the actual output. It can be triggered by a function call or by a placeholder. For example, the html format has renderers for a module, modules, component, head and message. These renderers are triggered by the
<jdoc:include type="modules" name="footer"> </jdoc:include>
The above piece of code will load the all modules assigned to the footer position and wrap them in an xhtml module style.
The feed format on the other hand has renderers for atom1.0 and rss2.0. These renderers are called by specifying the type of renderer in the url of by passing the type to the JDocument constructor.
For example, the following URL will display the rss feeds for the FAQ’s category :
or with search engine friendly url’s on this becomes :
The JDocument library is very flexible and powerfull. It would take a whole tutorial to explain how to leverage all the power, for now i’ll just stick to explaining how to use it to render only the component and how to render without any html output.
Rendering only the component
Old way Joomla! 1.0 : index2.php and index3.php where used to only output the component without any modules. These two files have been deprecated in Joomla! 1.5. There are only in the package to maintain backwards compatibility and should not be used anymore when developing new extensions.
New way Joomla! 1.5 : index.php?option=com_mycomponent&tmpl=component
How does this work ?
When you render only the component you are loading a special layout file that doesn’t has placeholders for any of the modules. This is exactly what happens here.
The ‘tmpl’ variable, refers to the name of the template file that is being loaded by JDocumentHTML. Instead of loading the ‘index.php’ template (the default layout) JDocumentHTML loads the component.html layout .(You can find the file in templates/_system/component.html.) If you examine this template file closely you will notice that it only renders the component.
Tips and tricks
you can override the _system layouts in your own templates, simply copy the file in your own template root directory and the system will use them instead of the default ones. This allows you to easily style the offline, error, … pages Joomla! 1.5 outputs.
Rendering only the raw component output
Old way Joomla! 1.0 : index.php?option=com_mycomponent&no_html=1
New way Joomla! 1.5 : index.php?option=com_mycomponent&format=raw
How does this work ?
What happens is you are now telling the system to use a different output format called ‘raw’ instead of ‘html’ the default one. The system will load the JDocumentRAW output format to render the document and will only output whatever the component creates.
Tips and tricks
You can use the ‘format’ specifier to make the system use the feed format. The feed format has a renderer for Atom1.0 and RSS2.0. All you need to do is give JDocument the necessary info to create the feed and he will do the rest, allowing you to easily switch between Atom and RSS output.
There is alot more that this baby can do, in a next blog post I’ll try to dive into some of the more advanced uses of JDocument. Have fun coding !