Minimal Application Skeleton

Your Directory Location

Because Solar is geared toward distributing applications, you need to create your own "vendor" ("master" or "channel") directory where your classes will be stored. This directory name will be the prefix on all your class names. It can be anywhere in the file system.

$ mkdir /home/username/Vendor

Config and Front Controller

Edit Solar.config.php to recognize your vendor directory (along with the Solar directory) for page controllers. Remember, for security reasons, your config file should not be in the document root.

$ cd /path/to/config
$ mate Solar.config.php
<?php
$config = array();

// ...

$config['Solar_Controller_Front']['classes'] = array(
    'Solar_App',
    'Vendor_App',
);

// ...

return $config;
?>

Also, make sure the bootstrap script has the Vendor directory in the include_path along with Solar itself.

$ cd /home/username/public_html
$ mate index.php
<?php
// Path to PEAR libraries, where Solar is installed,
// **and** to the Vendor PHP libraries.
set_include_path('/home/username/pear/php:/home/username');

// Windows folks should use a "\" and ";" separators
// set_include_path('c:\path\to\pear;c:\home\username');

// You could also use something like the following to be OS-independent:
// set_include_path(realpath('./relative/path/to/Solar') . PATH_SEPARATOR . realpath('.'));

// Load and start Solar
// ...
?>

App Directory Setup

In general, your vendor library should be structured like the Solar library. Since we're doing an application skeleton, we'll need an "App/" directory.

$ cd /home/username/Vendor
$ mkdir App

The Vendor directory now looks like this.

Vendor/
    App/

We'll call our application "Example"; it needs a directory, and subdirectories for its locale files, view files, etc.

$ cd /home/username/Vendor/App
$ touch Example.php
$ mkdir Example
$ mkdir Example/Helper
$ mkdir Example/Layout
$ mkdir Example/Locale
$ mkdir Example/View

The Vendor directory now looks like this.

Vendor/
    App/
        Example.php
        Example/
            Helper/
            Layout/
            Locale/
            View/

Page Controller and Action

Edit your Example.php page controller to make it extend Solar_Controller_Page; give it a default action of 'index', a view-variable of 'output', and a method for the 'index' action.

$ cd /home/username/Vendor/App
$ mate Example.php
<?php
Solar::autoload('Solar_Controller_Page');
class Vendor_App_Example extends Solar_Controller_Page {

    protected $_action_default = 'index';

    public $output = '';

    public function actionIndex() {
        $this->output = "I am the vendor example";
    }
}
?>

View

Now create the related view for the index action.

$ cd /home/username/Vendor/App
$ mate Example/View/index.php
<html>
    <head>
        <title>Skeleton App</title>
    </head>
    <body>
        <p><?php echo $this->escape($this->output) ?>
    </body>
</html>

Now you should be able to browse to http://127.0.0.1/index.php/example/ and see some output.

Locale

Create a locale file for US English in the Locale/ directory:

$ cd /home/username/Vendor/App
$ mate Example/Locale/en_US.php
<?php
return array(
    'TEXT_EXAMPLE' => 'I am a translated vendor example',
);
?>

Now edit actionIndex() to use a locale key instead of a hard-coded string ...

$ mate Example.php
<?php
public function actionIndex() {
    $this->output = 'TEXT_EXAMPLE';
}
?>

... and edit your view file to translate that key with the getText() helper.

$ mate Example/View/index.php
<html>
    <head>
        <title>Skeleton App</title>
    </head>
    <body>
        <p><?php echo $this->getText($this->output) ?>
    </body>
</html>

Now when you browse to http://127.0.0.1/index.php/example/ you will see the translated output. If you add other locale files, such as es_ES.php, and use Solar::$locale->setCode() to change locale codes, those translations will appear instead.

Layout

Notice that our view script has more to it than just the "core" page content (the $this->output portion). Normally you will want to be able to use the same header and footer portions across all actions in your applications. Let's create a "layout" file to do that for us.

Create a basic layout file called "main.php":

$ cd /home/username/Vendor/App
$ mate Example/Layout/main.php
<?php /* header portion */ ?>
<html>
    <head>
        <title>Skeleton App Layout</title>
    </head>
    <body>

        <h1>Skeleton Application</h1>

        <?php
            /* page controller output */
            echo $this->layout_content;
        ?>

<?php /* footer portion */ ?>        
    </body>
</html>

Now go back and edit your view script so that it only generates the bare minimum of output:

$ mate Example/View/index.php
 <p><?php echo $this->getText($this->output) ?></p>

Finally, tell your page-controller class what layout to use by setting the $this->_layout property.

$ mate Example.php
<?php
Solar::autoload('Solar_Controller_Page');
class Vendor_App_Example extends Solar_Controller_Page {

    protected $_layout_default = 'main';

    protected $_action_default = 'index';

    public $output = '';

    public function actionIndex() {
        $this->output = 'TEXT_EXAMPLE';
    }
}
?>

Now when you browse to http://127.0.0.1/index.php/example/ you will see the new page with a heading, and the translated output from the action. All other views in your page-controller will use the same layout, unless you change the $this->_layout property to a different layout. (To turn off layout use, just set $this->_layout_default to an empty value.)