Migrating DOCman to Joomla! 1.5


Last week I was at the Dutch Joomla BootCamp, which was organised by our friends from Jira. Johan gave one of his famous unstoppable sessions about the Joomla framework and the MVC model. Jisse talked about templates, and brought along the very first copy of his new book on templates (a rather thorough one I must add, it goes beyond any book on templates I’ve seen — too bad it’s in Dutch only for now).

Finally, I gave a presentation about migrating a Joomla! 1.0 site to Joomla! 1.5, and took the opportunity to announce the migrator plugins for DOCman.

Com_migrator

Com_migrator is a component written by J! Core developer Sam Moffat. The latest version 1.0RC6 was released this week. You install it on your old J!1.0 site (or even Mambo!) and it will take a snapshot of your database. During the installation of J!1.5, you can upload the snapshot (an SQL file). The new site will now contain the contents of the old site. A great feature of com_migrator is the ability to load additional plugins for 3PD extensions, such as DOCman. These plugins expand the snapshot with the data from the extension.
With a little knowledge of phpMyAdmin, you can also use the migrator to copy data from a DOCman installation on a site to an existing J!1.5 installation.

You can download the DOCman migrator plugins at Joomlacode.org, where you can also find the com_migrator component. Extract the plugins’ zip file and read the included README.php file for detailed instructions. We’ve also opened a new forum category where you can discuss DOCman migration.

Good luck migrating!

Read more

Joomla! Coding Practices: Tables and Primary Keys

When you’re defining one or more tables to use in your component, it’s always a good idea to put some thought in how you’ll name them. First of all, we have of course the #__ prefix, which Joomla! replaces with the user defined prefix. The default is jos_, which stands for ‘Joomla! Open Source’, a leftover from the Mambo days.

Next, we want to prevent name collisions. Component names in Joomla! are unique, so using that for the first part of your table names will fix that: #_mycomponent. Don’t use #_com_mycomponent, that’s unnecessary luggage.

Let’s take a classic example: a component that manages a book collection, called com_library. The table name should reflect the contents of the table. This is always plural: you use a table to store multiple items.

Bad: #__library_book

Good: #__library_books

Even if your component uses only one table, you shouldn’t use #__mycomponent. You might need more tables later, eg #__library_authors and #__library_publishers.

Finally, you always need to define a primary key. Most people simply use id for this, or something like bId for the books table, aId for the authors etc. A better idea is to use the table name, in singular, followed by id.

#__library_books -> library_book_id

#__library_authors -> library_author_id

There are some very important advantages to this naming strategy. It’s easier for you or other people reading your code, what tables belong to what component, and what’s in them. Relations between tables are now very clear as well. #__library_books for example has two additional fields called libray_author_id and library_publisher_id, which of course link an author and a publisher to the book.

But more importantly, it’s easy to write code now that can detect those relations automatically. As your com_library becomes smarter, you could add data mapping functionality that can understand the relations between tables, without the need to hardcode them.

Finally, in most situations, you’ll want to use auto_increment for primary keys. As we’re all moving to PHP5.2 and along with that, hopefully MySQL 4.1 or 5, we can make use of new feature: the SERIAL keyword. SERIAL is just an alias BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE. This allows your primary keys to be as big as possible (and it’s easier to remember as well).

In Joomla!, we’re still stuck with backwards compatibility, but hopefully, these coding conventions will be picked up in a future version. Component developers can already start using them. The possibilities are endless.

Read more

Joomla! 1.5 – Generating raw ouput

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 :

<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 :

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 !

Read more

Joomla! 1.5 – Using JFactory and jimport() sensibly

David raised an interesting question in his very first post on the Joomla! forums, about using jimport() for classes that are deeply nested in the framework’s directory structure. The answer is simple: don’t load those classes. Problem solved! Right ?

Well, right, but why can’t you load them?

What is jimport?

Joomla!’s framework is located in /libraries/joomla. Instead of using require_once to load those files, you use the jimport() function. It uses a syntax with dots: to load /libraries/joomla/utilities/utility.php, you write jimport(‘joomla.utilities.utility’); The JUtility class is now available for you to use in your code.

jimport('joomla.utilities.utility');
echo JUtility::dump($myvar);
// dumps the contents of $myvar to the screen

The same thing goes for files that are nested deeper, like /libraries/joomla/application/component/view.php:

jimport('joomla.application.component.view');
class MycomponentViewItems extends JView
{ /* ... */ }

In J!1.5RC4, jimport got a little smarter. When using PHP5, instead of loading the file right away, the filename and the classname are registered, and loading is deferred until the class is actually needed. So when looking at our first example:

jimport('joomla.utilities.utility');
// at this point, utility.php is not yet loaded

echo JUtility::dump($myvar);
// when the JUtility class is needed, utility.php is loaded.

(This may look a little unnecessary: why not load the file right away, if we’re going to need it anyway? For now, let me just say that there are a number of scenario’s where this is a good idea, like in legacy mode. We’ll deal with those in another blog post.)

So what’s happening? jimport looks at the last part of the ‘joomla.utilities.utility’ string, adds a ‘J’ prefix, and registers the resulting ‘JUtility’ as the class name for utility.php. When you use JUtility, in the example above, or in MyClass extends JUtility, or in class_exists(‘JUtility’), the file utility.php is loaded.

The problem

David wonders in his post what happens when you want to use JSessionStorageDatabase, located in /libraries/joomla/session/storage/database.php. According to what I wrote above, you need to use jimport(‘joomla.session.storage.database’). However, this would register JDatabase as the classname, but in fact it should be JSessionStorageDatabase. Trying to use the class results in an error, because the file containing it isn’t being loaded. In reality, we never need to load classes like JSessionStorageDatabase in our code. Joomla! has factories for that.

About JFactory

Your code doesn’t have to worry about how to instantiate certain objects. The specifics are all handled by JFactory and a bunch of getInstance methods. Eg. JFactory::getDBO() might give you a JDatabaseMySQL object or a JDatabaseMySQLi object, or perhaps even a JDatabasePostgresSQL object in a later version. JFactory::getSession() gives you a JSession object. This object contains a JSessionStorage object, which can be JSessionStorageDatabase or JSessionStorageApc or any other. The point is: you don’t need to worry about it. JFactory (and JSession::getInstance(), JDatabase::getInstance(), …) take care of all that.

The only classes you need to use jimport for are classes with a single name like JFoo, not classes like JFooBar. And most importantly, always look at JFactory first, to see if you can get what you need there.

Read more