The Joomla! Community Magazine™

Write your own App using Joomla! Platform

Written by | Thursday, 01 December 2011 00:00 | Published in 2011 December
A few days ago Joomla! platform version 11.3 was released. More and more people are wondering what Joomla! platform is about. The following article is a chapter of the upcoming Joomla! Development Beginner's Guide which will be released as a free pdf as soon as possible. The term Joomla! platform is quite new. It was introduced with the release of Joomla! 1.6 in January 2011.
Write your own App using Joomla! Platform http://cmsexpo.net/joomla-concept

History

Since the beginning of Mambo/Joomla!, there are files called mambo.php and joomla.php in the CMS package.

In Joomla! 1.0 these files contain 6,153 lines of code. These files also include a few other files and they were just "big". They were a reservoir for code which was used by core and third party extensions.

The files grew and grew and over the time it became jPlatform, a kind of operating system for Joomla, and the CMS as a sort of application that runs on it.

Since Joomla! 1.6 the platform has been separated from the CMS.

The Joomla! platform is the framework on top of which the Joomla! CMS operates.

The idea of this separation was born after the launch of Joomla! 1.0 in the year 2005 and it took nearly six years to implement it. It will change the way developers, architects and service providers deal with Joomla! in the future.

Many companies and organizations have requirements that go beyond what is available in the basic Joomla! CMS package. Think of integrated e-commerce systems, complex business directories or reservation systems.

Let’s have a closer look.

Numbering

What confuses me most when I heard of it for the first time was the numbering. But I found a very simple answer to that.
The numbering scheme for the platform consists of the year number followed by a sequence number, so 11.1 was the first release in 2011. The next release was 11.2.
The first release in 2012 will be numbered 12.1.

Release cycle

Every three months a new version of the Joomla! platform will be released.

Package content

The platform package consists of the files stored in the folder /libraries and /media and has no graphical user interface.
The platform source code is stored in the Git version control system GitHub.

Advantages and benefits of the separation

  1. It allows developers to use the Joomla Platform independently of the CMS.
    This means that you’ll have the choice between different CMSs on top of the Joomla! platform in the future. This is really revolutionary! Joomla! is the only system in the world which provides that.
    There is still one core CMS provided by the Joomla! project but other projects like Molajo could use the Joomla! platform as a base, too.
  2. It allows developers to contribute / add features more quickly.
    In the past it was very frustrating to experience that good code wasn’t always included into Joomla! core. With the Joomla! platform stored on GitHub, it is very easy to fork it for your own purpose and it is easy, too, to integrate your code in the main branch.
  3. 3-month release cycle
    With this short release cycle it is possible to add features into the platform much quicker than into the CMS. This is useful for extension developers to add core features which are necessary for their extension.
  4. It encourages recruitment of more developers, including larger corporations, who may have not, otherwise, contributed.
    This point is crucial and it will work when the responsible team for the platform starts embracing these new faces!

Using the Joomla platform

First of all you have to download the platform.

You find the latest version on GitHub (https://github.com/joomla/joomla-platform).

Afterwards you have to extract the file in your public webserver directory (htdocs) and create a folder for your applications (cli).

In the folder /docs you find the documentation and the coding standard of the platform. The files are in docbook format and it's a bit tricky to view them. Elkuku provides a public filter for the documentation where you can download the docs as pdf (http://elkuku.github.com/joomla-platform/).

Test your environment

The Joomla! platform provides no graphical user interface (GUI) in a browser like the Joomla! CMS so we have to use the command line interface (CLI) for our very first steps.

Depending on the operating system and the LAMP stack you are using it can be possible that PHP isn't installed correctly. You can check by entering the command php -version in your command line interface (Terminal in OSX, Command Prompt in Windows, Shell in all ..ix systems). I am using OSX and MAMP and the result looks like this

web hagengraf$ php -version
PHP 5.3.6 with Suhosin-Patch (cli) (built: Sep  8 2011 19:34:00)
Copyright (c) 1997-2011 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies

Hello World

To start simple we begin with the hello world example. Create a file hello.php and put it into /cli (Listing 1).

<?php
// TODO Do we need this statement?
define( '_JEXEC', 1 );
// Import of necessary class file
require_once ( '../libraries/import.php' );
// Load JCli class
jimport( 'joomla.application.cli' );
// Extend JCli class
class HelloWorld extends JCli
{
  // overwrite method
  public function execute( )
  {
    // print something
    $this->out( 'Hello World' );
  }
}

// TODO ... how to describe the next statement easily :)
// First try: Call of the static method execute in the derived class HelloWorld?
JCli::getInstance( 'HelloWorld' )->execute( );
?>

Listing 1: hello.php

Execute your shiny new app with the command php hello.php and the result will look like this

cli hagengraf$ php hello.php
Hello World
cli hagengraf$

Well, to be honest, I was happy when I saw the result for the first time but it didn't blow me away :).

Let's do another example

Your last Tweets

Do you have a twitter account? Let's create an interactive app using the Joomla! platform and read the last tweets (listing 2)

<?php
define('_JEXEC', 1);
require_once '../libraries/import.php';
jimport('joomla.application.cli');

class TwitterFeed extends JCli
{

  //Get Latest Tweet
  function latest_tweet( $username, $count = 5 )
  {
    $url = "http://twitter.com/statuses/user_timeline/$username.xml?count=$count";
    $xml = simplexml_load_file( $url ) or die( "could not connect" );
    $text = '';   
    foreach( $xml->status as $status )
    {
      $text .= $status->text . '
            
';
    }
    return $text;
  }

  public function execute()
  {
    $this->out( 'What is your twitter handle?' );
    $username = $this->in( );

    $this->out( 'How many tweets to view?' );
    $count = $this->in( );

    $tweet = $this->latest_tweet( $username, $count );
    $this->out( $tweet );
  }

  protected function fetchConfigurationData()
  {
    return array();
  }
}

JCli::getInstance('TwitterFeed')->execute();

Listing 2: twitter.php

When you launch the app with php twitter.php it will ask you for a twitter user name and how many tweets you want to see. Then it will display the tweets!

cli hagengraf$ php twitter.php
What is your twitter handle?
hagengraf
How many tweets to view?
5
Did you know? Member for 8 years 7 weeks :) http://t.co/L8tzB2kz #drupal #wordpress
 
@brianronnow can you give me the wrong link, then I will update it
 
@brianronnow oh sorry :) the correct answer is 243 pages
 
@brianronnow the last update was 2 days before JDay Denmark

We are getting more advanced :)

The handling has still the feeling of being involved in a movie like War Games from the eighties but hey, it uses twitter, asks for input and shows me tweets on a command line - wow!

A Web App

The difference between our first examples and an application which runs in a browser is the use of HTML code. If we print out the HTML code it can be rendered to a web page via a browser.

In our first web app we just want to show the base path of the application and the actual date. The output in the browser should be like this:

My Web Application

The current URL is http://localhost/jplatform/
The date is 2011-11-21 15:03:11

To try this out we need two files, an index.php file and an application.php file in the includes folder. If you want to create one web application based on one Joomla! platform you have to place the index.php in the root directory of the Joomla platform and the application.php in a new folder called includes.

- build

- docs

- includes

-- application.php

- libraries

- media

- tests

index.php

The index php consist of the following statements (Listing 3). Code is collected from different parts of the platform and in the end your app is launched with the statement command $app->render();.

<?php

if (file_exists(dirname(__FILE__) . '/defines.php'))
{
    include_once dirname(__FILE__) . '/defines.php';
}
 
// Define some things. Doing it here instead of a file because this
// is a super simple application.
define('JPATH_BASE', dirname(__FILE__));
define('JPATH_PLATFORM', JPATH_BASE . '/libraries');
define('JPATH_MYWEBAPP',JPATH_BASE);
 
// Usually this will be in the framework.php file in the
// includes folder.
require_once JPATH_PLATFORM.'/import.php';
 
// Now that you have it, use jimport to get the specific packages your application needs.
jimport('joomla.environment.uri');
jimport('joomla.utilities.date');
 
//It's an application, so let's get the application helper.
jimport('joomla.application.helper');
$client = new stdClass;
$client->name = 'mywebapp';
$client->path = JPATH_MYWEBAPP;
 
JApplicationHelper::addClientInfo($client);
 
// Instantiate the application.
// We're setting session to false because we aren't using a database
// so there is no where to store it.
$config = Array ('session'=>false);
 
$app = JFactory::getApplication('mywebapp', $config);
 
// Render the application. This is just the name of a method you
// create in your application.php
$app->render();
?>

Listing 3: index.php

You find the code for the application in listing 4

<?php
// no direct access
defined('JPATH_PLATFORM') or die; 
final class JMyWebApp extends JApplication
{
  /**
  * Display the application.
  */
  public function render()
  {
    echo '<h1>My Web Application</h1>';
    echo 'The current URL is '.JUri::current().'<br/>';
    echo 'The date is '. JFactory::getDate('now');
  }
}
?>

Listing 4: /includes/application.php

If you are used to the Joomla! CMS you can use all bits and pieces you already know and build your own application.

I took the three examples from the Joomla! documentation page (http://docs.joomla.org/How_to_create_a_stand-alone_application_using_the_Joomla!_Platform) and in the end I was impressed by the possibility of building something completely new based on the Joomla! code.

Multiple Web Apps

In our first example we installed exactly one web app (myapp) on one Joomla platform. If that suits you, everything is fine. Imagine you have several apps you want to run on one Joomla! platform installation. For this purpose you need an additional bootstrap.php file (listing 5) and the following directory structure:

- build
- docs
- libraries
- media
- tests
- cli <- only if you have cli apps 
- web <- the folder for the web apps
-- myapp <- the folder of one app
--- includes
---- application.php
--- index.php
-- anotherapp <- the folder of another app
--- includes
---- application.php
--- index.php
- bootstrap.php

The file bootstrap.php consists of one line of code and is necessary to show your web app the way to the Joomla! library folder.

<?php
require dirname(dirname(__FILE__)).'/jplatform/libraries/import.php';

Listing 5: bootstrap.php

More Resources

There is a place on GitHub where examples are collected (https://github.com/joomla/joomla-platform-examples).

They are prepared in the multiple apps structure I described above.

You can download, extract and execute the examples in your Joomla! platform folder.

Read 49406 times
Tagged under Developers