Tutorials Hello World
If don't have your development environment or ClearOS source code ready, please jump to the Getting Started document to read about how to get that done. If you already have everything ready to go, let's dive into the Hello World app.
If you want to work on an existing app, try your hand at this 'Hello World' app first, or create a new one first. But if you have mad skillz and would like to modify an existing one, please review this guide on How to modify an existing app in ClearOS.
Creating the Skeleton
To get going quickly, we're going to create the Hello World app in a personal development directory. The app can be deleted or moved later, this is just a convenient place to start. Make sure you are logged in as your normal user account (not root) and run the following to start the new app:
mkdir ~/apps cd ~/apps/ clearos newapp
You will be prompted for the basename, full name, and source code management type (git or svn). Use the following parameters for your Hello World app:
- basename: hello_world
- fullname: Hello World
- type: git
A basic skeleton for the app will be created, but the web engine still needs to know where to find your new app! Add the following configuration option to the ~/.clearos file:
<?php \clearos\framework\Config::$apps_paths = 'apps';
After making the change, the webconfig engine needs to be restarted with the new configuration:
If all goes will, you will be able to see your app in webconfig. Point your browser to your development environment to see the results – https://w.x.y.z:1501/app/hello_world You can find the app in the menu at
Before diving into the code, take a look at the directory structure of an app:
cd ~/apps/hello_world ls -al
For those of you already familiar with CodeIgniter or the Model-View-Controller (MVC) pattern, the directory layout should look familiar. The following table describes the purpose of each of the directories. Don't worry too much about it now - we'll dive into each one in more detail later on in this tutorial.
|controllers||The “C” in MVC (Model-View-Controller)|
|deploy||App information, install scripts, default configuration and other helper files|
|libraries||The “M” in MVC (ClearOS only uses libraries - similar to models)|
|views||The “V” in MVC|
The base English translation file is a good place to start – language/en_US/hello_world_lang.php. The first thing to notice is the path and filename. This is the convention used by the CodeIgniter framework, so we'll stick to it. The translation is a PHP string array that is typical in the PHP world:
$lang['hello_world_app_name'] = 'Hello World'; $lang['hello_world_app_description'] = 'Hello World - a description goes here.';
Go ahead and change the translations and then see the results in your web browser. When you need to add a new translation tag, this is the place to do it.
Once your app is complete, you will be able to upload the file to the translation server to make it available to the translation team. Once the translations have been completed, you can export the translations to populate subdirectories (fr_FR, de_DE, etc) inside of the language directory.
Now that you have a feel for the translation engine, the next place to poke around is the the deploy/info.php file. This file contains general information about the app, including:
This file is also used for packaging and building RPMs. For your Hello World example, only the barebones are required in the info.php. For more complex apps, you will see:
- dependencies (e.g. app-pptp requires the pptpd RPM)
- file manifests
- directory manifests
- and more
<?php ///////////////////////////////////////////////////////////////////////////// // General information ///////////////////////////////////////////////////////////////////////////// $app['basename'] = 'hello_world'; $app['version'] = '1.0.0'; $app['release'] = '1'; $app['vendor'] = 'Vendor'; // e.g. Acme Co $app['packager'] = 'Packager'; // e.g. Gordie Howe $app['license'] = 'MyLicense'; // e.g. 'GPLv3'; $app['license_core'] = 'MyLicense'; // e.g. 'LGPLv3'; $app['description'] = lang('hello_world_app_description'); ///////////////////////////////////////////////////////////////////////////// // App name and categories ///////////////////////////////////////////////////////////////////////////// $app['name'] = lang('hello_world_app_name'); $app['category'] = lang('base_category_system'); $app['subcategory'] = 'A Hello World Subcategory';
Before moving on to the coding details, we are going to jump ahead to the RPM packaging stage. Make sure you are in the base directory of your app and run the following:
The packaging/app-hello-world.spec RPM spec file is automatically created using the deploy/info.php details! For those of you who are not familiar with packaging RPMs, this “spec” file is the configuration file used to generate an RPM. Since all ClearOS apps use the same underlying structure, RPM-izing is automated – you do not have to delve into the complexities of building RPMs. In fact, go ahead and build the RPM now:
Near the bottom of the output, you should see something like:
Wrote: /home/username/rpmbuild/SRPMS/app-hello-world-1.0.0-1.username.src.rpm Wrote: /home/username/rpmbuild/RPMS/noarch/app-hello-world-1.0.0-1.username.noarch.rpm Wrote: /home/username/rpmbuild/RPMS/noarch/app-hello-world-core-1.0.0-1.username.noarch.rpm
If a day ever comes where ClearOS apps are ported to Debian/Ubuntu, dpkg – the equivalent to RPMs in Debian/Ubuntu – would be abstracted away from app development as well. If you are interested in the details of the RPM spec file, please take a look at the ClearOS Packaging developer guide.
Okay, here comes the coding. ClearOS is built on CodeIgniter, a very popular PHP framework using Model-View-Controller (MVC) architecture. If you are not familiar with MVC, take a look at the wikipedia article to get a general idea. Don't worry if it's still fuzzy after reading the article, just a general feel is all you need for now.
Since we're not re-inventing wheels, all the documentation and tutorials for CodeIgniter are applicable to ClearOS development. If you are not familiar with CodeIgniter, the following tutorial is a very good place to start. When watching the video, keep the following ClearOS-isms in mind:
- Each app in ClearOS has it's own base directory that contains the subdirectories: controllers, views, etc. In a default CodeIgniter install, all apps would be mixed together in the single application directory – that's what you will see in general CodeIgniter documentation and tutorials.
- In the first couple of minutes, config file changes are discussed. This is not necessary on ClearOS.
- Libraries are always used instead of Models in ClearOS. This makes it easier to support command line tools and REST-like interfaces.
- All ClearOS controller - including Hello World - extend ClearOS_Controller instead of the default CI_Controller.
Go ahead and experiment with the Hello World app. If you are looking for another example, the date app is a good one.
Now that controllers are under your belt, it's time to move on to views. We're jumping over the Models tutorial for now, but we will circle back around to that tutorial next.
As you will see in the tutorial, you can write out raw HTML in the view. Though that's certainly possible, this is not done in ClearOS apps. Instead, standard CodeIgniter functions are used along with a few extensions specifically built for ClearOS. Avoiding raw HTML makes it possible to guarantee a more consistent look and feel using themes, for example a warning box in the Hello World app should look the same as the warning box in other apps.