Can anybody tell me how Joomla! 1.5 will be able to give just raw output so I can generate XML or JSON for my dynamic pages?

This is a common question for developers that are diving a bit deeper into Joomla! 1.5 and want to integrate AJAX functionality into their extensions. They quickly find that index.php always generates code within the XHTML-template and thats not what they need. Instead they want to generate XML for evaluating in JavaScript without any XHTML wrapped around it. Sounds familiar ? Well, here is how you can do this with Joomla! 1.5.

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.

Format

A format is the type of document that gets created, for 1.5 the supported formats are html (default), pdf, feed, error and raw.

Renderer

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 placeholders in the template files. Like :


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 :

index.php?option=com_content&view=section&id=3&format=feed&type=rss

or with search engine friendly url’s on this becomes :

index.php/faq.feed?type=rss

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 !

By the way: I’m blogging live from the Joomlatools Doccamp in Brussels!

  • Fred

    Thank you, thank you, thank you! I was totally stuck writing a joomla web application that requires raw output. After weeks of traversing the web for a solution, I landed on your post. Totally solved my problem. Thank you!

  • iMike

    Hi

    Your knowledge is above mine, though greatly appreciated i’m a noob and simply want my joomla 1.5 contact form loading on a blank page. How do i achieve that?

    Thanks!

  • http://johan.janssens.me Johan Janssens

    What do you exactly mean with loading on a blank page ? Can you explain a bit more in details ?

  • Rune Madsen

    Great post! I’m trying to get my head around this, but it seems a bot unstable.

    If I try to render a raw output, I get this:
    500 – View not found [name, type, prefix]: frontpage,raw,contentView

    If I try to feed a specific article, I get the same error message.

    What can be the problem with this?

  • Rune Madsen

    Great post! I’m trying to get my head around this, but it seems a bot unstable.

    If I try to render a raw output, I get this:
    500 – View not found [name, type, prefix]: frontpage,raw,contentView

    If I try to feed a specific article, I get the same error message.

    What can be the problem with this?

  • Johan

    Hi, great post. I have tried to use your tips.

    When I use &tmpl=component, I get the template’s HTML and HEAD tags etc around it.
    How do I render the clean component without any of the other things from the Joomla template?

    I also tried to create a RAW view, but when using that, I cannot load the component template, it just outputs whatever I output explicitly in that view – not the component template.

    Thanks!

  • http://johan.janssens.me Johan Janssens

    To be able to render a raw format you need to specify format=raw and create a view.raw.php file to handle the output.

  • http://johan.janssens.me Johan Janssens

    To be able to render a raw format you need to specify format=raw and create a view.raw.php file to handle the output.

  • http://johan.janssens.me Johan Janssens

    Your best option would be to create a different template, something like tmpl=raw, do be able to do this you would need to add a raw.php file to your own template and then have it not output the html head.

  • Prog

    Correct the error in line:
    Old way Joomla! 1.0 : index.php?option=com_mycomponent&no_html=1
    Should be
    Old way Joomla! 1.0 : index2.php?option=com_mycomponent&no_html=1

  • http://www.mss.co.ke/ Paul S

    Thanks so much for this. I thought i’d have to start hacking away at the Joomla core to achieve this, I’m so happy to see that Joomla has already implemented this in a structured fashion, and that someone has taken the time to blog about it in such a clear manner. (Wish I had found this article three days ago)

  • http://www.pyrameda.com/Tools/ Lav

    Thank you! I have spent the last few days crawling the web looking for a post which explains how to generate a raw output from Joomla. This was very useful and worked like a charm for us…

  • hoapq

    Hi.
    Now i user joomla 1.5.10 but when i do like you tutorial:
    New way Joomla! 1.5 : index.php?option=com_mycomponent&format=raw
    but the website return error 404: not found.
    Can you tell me why?
    Or i have config something.
    Thanks

  • Pedro Renan

    good post

  • Tore B. Krudtaa

    Hi…

    Okay so the new way (joomla 1.5) is:
    index.php?option=com_mycomponent&format=raw

    I have tried this without any luck (against a module):
    index.php?option=mod_mymodule&format=raw

    Is it possible to make this work against a module at all?
    If so, how do I do it.
    Reason I’m asking is that my module output some content
    that should be possible use pagination using AJAX.
    So I want to just call my module when user click one of the
    pages (in my custom “paginator”) that are not active.
    And just return the new content without having to refresh
    the whole page.

  • http://willdaniels.co.uk Will Daniels

    Thanks for the guidance here! The structure of the whole thing is much clearer to me now. One problem though…

    Is format=raw supported when set in the component’s router? It still seems to be trying to load the HTML view (which doesn’t exist) unless I add format=raw explicitly to the query string. Am I missing something here?

  • Stef

    unfortunately things are not as simple as that.

    After activing the Apache mod rewritte, I have my url like :

    http://www.mywebsite.com/component/option,com_myism/format,raw/jFunction,givepic/userId,933/view,tools/

    The format=raw is totally ignored by the engine. The script uses index.html.php and not index.raw.php , which is a huge problem in that case.

    Problem doesn’t occur without the SEF.

    Any idea in that case?

  • Pingback: Tweets that mention Joomla! 1.5 – Generating raw ouput | Joomlatools Blog -- Topsy.com