If you missed the happy twittering, last week at the Joomla! Day Chicago there was a spontaneous gathering of developers--yes, that includes you Ryan Ozimek--shut up in a room having a  great time writing platform applications. As Nicholas  Dionysopoulos said to me “I guess that will put an end to the incessant "why did we have to separate the platform from the CMS" question. To be honest, I had the same question myself, until Joomla! Day Chicago and the awesome (and immensely fun and productive) Joomla! Platform session :)” Nick already even proposed a CLI application to include in the core of the CMS.

What exactly is a “Platform Application”? Well you already know three of them: the Joomla! CMS, the Joomla! CMS Administratror, and the Joomla! CMS Installer. Ok, so what more could anyone possibly need? In truth the sky is the limit. The Joomla! Platform can be used to build all kinds of PHP applications, some of which may work with the CMS and some of which are totally separate. Building a simple platform application is even  easier than building a simple module. In fact, you can do it in just one file.

Ryan and others wrote up some examples in the documentation wiki. We’ve also started a downloadable collection of them over here: Example Applications.  On the platform there are two kinds of applications: Command line and Web. For the CLI the Hello World and Hello You ones are by Ryan, the Twitter one by Steven Pignataro and the Joomla! Rocks one by Javier Gómez (apologies if I have gotten these credits wrong). I made the sample web app. Dustin Clute also offered up a CLI app that uses a Daemon (though he also found a library bug).So far these are all simple; they don’t have configuration files and they don’t use a database. However there is no limit on any of that, and we’ll be adding some more complex ones.

And now it’s time for you to join the fun by trying these and making your own. When you have made one, please add it to the collection so we can have some fun applications to play with.

Running platform applications

So what do you actually do with the files?

First, you need to make sure you have a copy of the platform on your web server. You can go to github and download a zip file of the current version from the download button. Save it locally and unzip it

To run the mywebapp application put unzip the file to the root of the platform and browse to it. So if you put the platform in the platform folder locally http://localhost/platform/mywebapp.

For a CLI app put it in the same place, at the root of your platform.

To run a CLI application and actually more or less see them run you need to be at the command line of a web server. How you get there depends on your operating system and also whether you have a local installation. If you have a localhost you can go to Terminal (on Linux or Mac or CMD on Windows) or else you need to ssh into your remote host using something like puTTy.

Once you are there type

php helloworldapp.php

And you should see Hello World. Or something else if you try a different one.

Building a Platform Application

Once you see how they are made, you can make your own. For a CLI application all you really need is a class and an execute method. Here’s Ryan’s:

<?php
define('_JEXEC', 1);

require_once ( '../libraries/import.php' );
jimport( 'joomla.application.cli' );

class HelloWorld extends JCli
{

        public function execute( )
        {
                $this->out( 'Hello World' );
        }        
}

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

So, he pulled in import.php which starts the whole process of bootstrapping.

Then because he was building a CLI he extended JCli.

Then he made a simple method that just is going to ouput “Hello World.”

Finally he instantiates the JCli object and we’re off done.

I saw what Ryan did, and then I decided we needed a Hello World web app. I did it with two files, myapp.php and application.php.

In application.php I put my class, which extends JApplication and has the method render.

<?php
/**
 * @copyright   Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
 * @license		GNU General Public License version 2 or later; see LICENSE.txt
 */

// no direct access
defined('JPATH_PLATFORM') or die;

/**
 * Joomla! Application class
 *
 * Provide many supporting API functions
 *
 * @package	Joomla.MyWebApp
 * @subpackage	Application
 */
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');
		
	} 
}

You can see that I decided to use two of the APIs, for date and current URI.  That’s just so we know it’s not simply a php file but actually a Joomla Platform app. Then mywebapp.php was:

<?php
// Usually this will be in the framework.php file in the includes folder.
require_once JPATH_PLATFORM.'/import.php';

// 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();

You can see that this looks a lot more like what you see in the index.php file of a CMS installation. Define the constants, then do the import (just like in the CLI example) and jimport the libraries you need.  Then since I didn’t have a database or configuration.php file, set the session to false, instantiate the application, and use the render method to get the page. Tada!

Okay, so now it’s your turn. Make an application and share it, whether in the wiki or in our code.joomla.org repository.  Don’t forget to tweet your success :).

 

update: Okay, okay, I cleaned up the mark up.EW