Learning Nooku Part 2: Displaying a Simple Text

This is Part 2 of a series of posts where I document my learning process in studying Nooku. I’m a total Noob to Nooku so this might help other Nooku noobs to learn the framework.

You can read the Introduction of Learning Nooku Here. 

Update: Download the component at this stage here - com_awesome-part2.zip

In order to understand the Nooku Framework, I want to know what it does for me so I’ll also know what’s left for me to do. The first thing I want to know are the Magics that I can use.

In documenting this learning process, I’m looking at com_harbour. It’s a sample component for Nooku. But I won’t reference code examples from com_harbour here. I’ll just use it as a jumpstart, then anything I want to do for my first simple app, I’ll find out through experimentation.

In order to fully understand how Magic works in Nooku, I need a bit of experimenting. What is the bare minimum amount of files needed to display a simple text, “Whatever”? Of course you can simply echo text from the entry point. But if we want to use the MVC, we’ll follow the convention.

So I’ll make my first Joomla Component powered by Nooku. I’ll name it com_awesome. As a start, I’ll just make it display any text like “Hello World”.

The Dispatcher

In my entry point for Joomla(the first file that Joomla executes when running the component), I’ll put the dispatcher.

administrator/components/com_awesome/awesone.php

<?php
// Check if Koowa is active
if(!defined('KOOWA')) {
    JError::raiseWarning(0, JText::_("Koowa wasn't found. Please install the Koowa plugin and enable it."));
    return;
}

// Create the controller dispatcher
echo 
KFactory::get('admin::com.awesome.dispatcher')->dispatch(KRequest::get('get.view', 'cmd', 'dashboard'));

From the code alone, I can see that KFactory is used to call a dispatcher object. Inside KFactory::get() is a key or identifier that maps to the dispatch object. I noticed that KFactory::get is commonly used in Nooku applications. Looking at the code, I think KFactory::get instantiates and returns objects according to the identifier, if the object is already instantiated, KFactory::get will return the same instance.

So in the entry point, the controller is dispatched. This is the first magic that I encountered. I am calling a dispatcher, but I don’t need to create a dispatcher file. If Nooku doesn’t find a dispatcher in your component, it will fall back to its default dispatcher. If I want to override the dispatcher, I just have to create com_awesome/dispatcher.php and extend the ComDefaultDispatcherDefault class.

<?php

class ComAwesomeDispatcher extends ComDefaultDispatcherDefault 
{

}

While finding out about this pattern, I was overwhelmed by the many things that was going on in the source code. ComDefaultDispatcherDefault extends KDispatcherDefault extends KDispatcherAbstract which extends KControllerAbstract which extends KObject and implements KObjectIdentifiable.

Whew! I initially thought that I’ll find a dispatch method somewhere along the hierarchy. But I didn’t find it. Digging deeper, I found out that I was actually calling _actionDispatch from ComDefaultDispatcherDefault. Maybe I don’t need to explain in detail what I found out but suffice it to say that the more I dig deeper, the more I find awesomeness. It is simply “genius”! I can already imagine how I can put those things into good use!

So we don’t need to create a dispatcher file unless you really really need to override Nooku’s default dispatcher.

While going through this learning process, I learned this very important concept in Nooku: For things you don’t create, Nooku has a fall back. What you’re actually writing is the code that’s unique to your application!

The Model

Note: This section is now irrelevant. The 99-toolbar branch of Nooku(which will soon be merged with the 0.7 trunk) has fixed this issue. (Edited Sept 29, 2010)

One thing I realized while experimenting on Nooku is that it is very Database-centric framework. Most of the Magic happens by automagically doing the most common tasks in accessing and displaying database data. 

So by now I’ve just created one file. That is the component’s entry point. From there I called the dispatcher. By default, the dispatcher tries to access the “dashboard” view. The second magic that I encountered was when I tried to access the component without creating any other files. I encountered this error:

Table ‘database.jos_awesome_dashboards’ doesn’t exist of the following query : SHOW FULL COLUMNS FROM `jos_awesome_dashboards`

I soon realized that Nooku is trying to do its magic by falling back to a default model object for me which seems to automagically gets data from the database. But I don’t want this yet as I simply want to display text. So I had to override the default Model by creating an empty base Model.

So here’s what I did. I created /com_awesome/models/dashboards.php and created this class

<?php
class ComAwesomeModelDashboards extends KModelAbstract
{
	
}

By creating this class, Nooku doesn’t fall back to the default Model. It uses this Model which extends the most basic and core Model Class in Nooku which doesn’t have any Magic in it. 

This removed the error but I encountered another error which is related to the View.

The View

If there is nothing different in what you want to do, you don’t need to create a controller and a model, and a view class. All I want to do here is to display text. I’ll proceed in creating a view template. Going back to the dispatcher I noticed that I’m passing a default view variable.

KFactory::get('admin::com.awesome.dispatcher')->dispatch(KRequest::get('get.view', 'cmd', 'dashboard'));

If no view variable is passed through $_GET, the default value dashboard will be used. From my readings about Nooku, I found out that passing the controller value through $_GET is a bad practice. So what Nooku expects is the view which makes your application “RESTful”(as Johan puts it).

So to create a view, I created /com_awesome/views directory. Then I created /com_awesome/views/dashboard directory, then I created /com_awesome/views/dashboard/tmpl directory, and finally, I mistakenly created a /com_awesome/views/dashboard/tmpl/default.php file. I said it’s a mistake, I initially thought it was the most natural thing to do, but this mistake helped me understand another fundamental concept in Nooku.

If you also commit my mistake you’ll get this error Template "com_awesome/views/dashboard/tmpl/form.php" not found. Why? Because dashboard is singular. And by default, when you access a singular view, Nooku assumes that you are trying to edit an object. So I went ahead and created a /com_awesome/views/dashboard/tmpl/form.php file. I placed a text like “This is form.php” in that file.

Now if I access my component using index.php?option=com_awesome, the text I put in /com_awesome/views/dashboard/tmpl/form.php is displayed and l also noticed that there are 3 standard action buttons on the top right corner - Save, Apply, Cancel.

This seems to be the default Nooku behavior if I don’t override the fallback classes. In this case, since I did not create controller, model and view classes, Nooku uses the default classes from com_default - the first layer of fallback. If I don’t have com_default Nooku will fallback even deeper using classes from its core.

So I don’t need to create classes, I just created 2 files and a directory hierarchy, and bahm! I am displaying something.

What is “com_default”?

com_default is Nooku’s first layer of fallback. It is located in Joomla’s site and admin component directory. It contains many “common” things found in Joomla applications so it’s the developer’s responsibility to extend it or even ignore it completely if you don’t need any of its functionality. This is where many of the Nooku magic for Joomla is located. I am yet to tap the pool of magic that can be found here, but I’ll learn as I go on.

So now I know that if I want to do something unique for my application, I’ll extend the classes found in com_default. That’s great! It’s like auto-pilot with easy manual override.

Extending or Overriding “com_default”

The first thing I want to do is to make dashboard be a dashboard. I don’t want Nooku to assume that I’m accessing an Object’s form template. So I want Nooku to display /views/dashboard/tmpl/default.php by default.

Digging the code, I found out that I should change the layout by creating a “dashboard controller”. Create com_awesome/controllers/dashboard.php and put this code:

<?php

class ComAwesomeControllerDashboard extends ComDefaultControllerDefault {

    protected function _initialize(KConfig $config) {
        $config->append(array(
            'request' => array('layout' => 'default'),
        ));

        parent::_initialize($config);
    }
}

Here I’m simply changing the layout to default which would normally be form. By doing this I can now create /com_awesome/views/dashboard/tmpl/default.php and that’s what Nooku will display.

How About the Toolbar Buttons? I just have to override the default view class by creating /com_awesome/views/dashboard/html.php and I put this code:

<?php
class ComAwesomeViewDashboardHtml extends ComDefaultViewHtml
{
    public function display()
    {
        //Reset the toolbar
        KFactory::get('admin::com.awesome.toolbar.dashboard')
            ->reset();

        return parent::display();
    }
}

So here I have just overridden the default view class and “reset” the toolbar object. Just like everything else in Nooku, since I don’t have a /com_awesome/toolbars/dashboard.php file, Nooku goes deeper. com_default doesn’t have it too, so it’s in the core, Nooku falls back deeper and used KToolbarDefault.

Summary

I have now created the simplest application in Nooku which simply displays text. This may be a very simple app, but by doing this, I understood some fundamental things which are very important in understanding Nooku:

• Nooku has layers of fallbacks. It is called “Cascading Class Override System”. To make things clearer, here’s the sequence from top to bottom:
  • Named Component Specific - Your most specific class based on the view e.g. ComAwesomeControllerDashboard in com_awesone/controllers/dashboard.php
  • Named Component Default - Your app’s general class e.g. ComAwesomeController in /com_awesome/controller.php
  • Default Component Default - General class from com_default, ComDefaultControllerDefault in /com_default/controllers/default.php
  • Framework Default - Found in the Nooku core e.g. KControllerDefault
• com_default is the first layer of fallback, it provides many common tasks found in Joomla. Developers would usually extend it and just change some things that are unique to their application.
• The view variable is important in Nooku. Making it singular or plural will cause Nooku to treat it accordingly. In this case, a singular view dashboard makes Nooku assume that we’re accessing an object, and it looks for the form.php file by default. To change this behavior, you have to override the controller, and the view class.

Have you also noticed? The Class naming convention is consistent with the file structure. Maybe you can figure it out already just by looking at the code. You also don’t need to “require_once” the files. Nooku auto-loads the files based on the ClassName.

Next, I’ll learn more about how to display data from the Database.