Accessing app-wide properties

Sometimes it's handy to be able to define certain values in a place accessible to multiple boxes, instead of redefining a variable in each box.  For this, Sitellite provides a properties.php file inside the conf/ folder in each app, which is automatically loaded whenever any box or form inside the app is loaded.

Looking at the properties.php file for a complete and highly configurable app like the built-in news app, you will see quite a long list of appconf_set() declarations.  This is how properties are defined in the properties.php files.  For example, to set a global 'limit' property for all of our app's data paging screens to use, you might say:

<?php

/**
 * Sets the number of items to show on a single screen.
 */
appconf_set ('limit', 10);

?>

That's all there is to it.  The values defined can be of any type, strings, integers, arrays, objects, you name it.

You could also instead define a constant instead of using appconf_set(), however your constant ought to be prefixed with the name of your app, so that you don't run into naming conflicts when calling multiple apps on a single screen (ie. as sidebars).  For example, the equivalent to our setting above would be:

<?php

/**
 * Sets the number of items to show on a single screen.
 */
define ('MYAPP_LIMIT', 10);

?>

To make use of an app's properties in a box, you can say:

<?php

echo appconf ('limit');

?>

Or if you used a constant:

<?php

echo MYAPP_LIMIT;

?>

Or from a SimpleTemplate:

{appconf/limit}

Or as a constant:

{MYAPP_LIMIT}

Both ways are quite easy to write.  The advantage of the appconf_set() method is that it can store complex types as well as simple ones, which constants cannot do.  So for the sake of consistency, I generally stick to appconf_set().

Accessing SAF classes

SAF provides hundreds of classes across dozens of packages which cover lots of different bits of functionality that you can use to enhance your boxes and apps, or to speed and ease the development of them.  To call a class from within SAF, you can use the loader_import() function.  For example, here is a quick mini calendar script using the saf.Date.Calendar.Mini class:

<?php

loader_import ('saf.Date.Calendar.Mini');

$cal = new MiniCal ($parameters['minical']);

$cal->addLink (5, '/index/myapp-eventlisting-action?id=3');
$cal->addLink (16, '/index/myapp-eventlisting-action?id=5');

echo $cal->render ();

?>

The path "saf.Date.Calendar.Mini" is translated into saf/lib/Date/Calendar/Mini.php automatically for you by the loader_import() function.  The benefit of this is that you never have to call a file explicitly by its name, so you don't have to hard-code directory paths.  With this method, if you wanted to move SAF to a new location, you could do so and only have to change a global configuration option for all the scripts to know where to find it still.  It also lets you specify additional starting points than just "saf", including "pear" and "ext" which are aliases of saf/lib/PEAR and saf/lib/Ext, respectively, and also the names of all the apps in Sitellite.

Accessing classes within our app

If I create a class called Foo and saved it to inc/app/myapp/lib/Foo.php, I could load it with the following import call:

<?php

loader_import ('myapp.Foo');

// start using Foo...

?>

It's that simple.  Or if you wanted to use a class from another app, you could do so just as easily:

<?php

loader_import ('cms.Versioning.Rex');

// start using Rex...

?>

It's that easy!

A little security-through-obscurity

One thing I left until last, because it makes the examples a little longer, is how to hide your boxes from direct access, so that you can be sure they're being called through Sitellite, which also ensures that Sitellite's access control is applied to them.  To do this, simply add the following to the top of your boxes and forms:

<?php

// BEGIN KEEPOUT CHECKING
// Add these lines to the very top of any file you don't want people to
// be able to access directly.
if (! defined ('SAF_VERSION')) {
    header ('HTTP/1.1 404 Not Found');
    echo "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n"
        . "<html><head>\n<title>404 Not Found</title>\n"
        . "</head><body>\n<h1>Not Found</h1>\n"
        . "The requested URL " . $_SERVER['PHP_SELF']
        . " was not found on this server.<p>\n<hr>\n"
        . $_SERVER['SERVER_SIGNATURE'] . "</body></html>";
    exit;
}
// END KEEPOUT CHECKING

// box code goes here

?>

This will cause the script to immitate an Apache 404 error message when the script is accessed directly (ie. /inc/app/myapp/boxes/boxname/index.php).  This has the advantage of confusing potential hackers who might be profiling your site, as opposed to simply exiting.

Conclusion

As you can see, Sitellite presents a very powerful and carefully thought-out framework upon which to base your web applications.  The Sitellite app and box model grew out of years of commercial web development in PHP, and the key thing we tried to do with it was to build on PHP's strengths and uniquenesses, as opposed to simply immitating the Java way of doing things, which may be very well suited to compiled languages like Java, but not necessarily to highly dynamic languages like PHP.

Page 1: As I mentioned in my previous ar...
Page 2: Calling our box
Page 3: The access.php File
Page 4: The $parameters array
Page 5: Accessing app-wide properties

All Tutorials