The access.php File

Access settings for both boxes and forms are contained in access.php files, which act a lot like Apache's .htaccess files do.  They even inherit from parent folders, so you can define a single access.php file for a whole bunch of boxes.  In this case, let's create an access.php file and put it in the same folder as our index.php file.  In it, we'll put:

; <?php /*

sitellite_access = public
sitellite_status = approved
sitellite_action = on

; */ ?>

This tells Sitellite that the box is public, approved, and that it can be called as an action.  Now try loading the aforementioned URL and see what happens.  Not bad, eh?

And of course, passing parameters to a box from the URL is the same as passing parameters to any ordinary web page request.

Here are some additional values that may be present in an access.php file:

• sitellite_access - The access level of the current box or form.
• sitellite_action - Whether to allow direct URL access (ie. via the myapp-boxname-action syntax) to the current box.  This can also be changed to sitellite_inline, sitellite_sidebar, or any number of custom contexts as well.  The only limitation to context naming is that it shouldn't conflict with the other attributes listed here.
• sitellite_chdir - Whether to stay in the default directory or chdir() to the box's own folder during execution.
• sitellite_exit - Whether to automatically exit upon completion of the execution of the current box or form.
• sitellite_fname - Whether to use specific script names instead of just index.php, in which case you can have multiple box scripts in the same folder.  Note that this limits the ability to use the settings.php files properly, and also limits the fine-grained control via access.php files, but is useful for porting 3rd-party apps to Sitellite quickly.
• sitellite_goto - A page or other box or form in Sitellite to send the user to if they try to access a box they don't have permission to access.  The default action is to simply return false and output nothing.  This allows you to easily send users automatically to a login or registration page when they need additional authentication to access parts of your apps.
• sitellite_inline - Whether to allow inline access (ie. via the Xed WYSIWYG editor's box chooser wizard dialogue -- coming in Sitellite 4.2 this summer) to the current box.
• sitellite_rewrite_pattern - An optional Perl-compatible regular expression to use to transform the output of a box before passing it along.  This is useful mainly for converting internal application links to be Sitellite-compatible when porting 3rd-party apps to Sitellite.
• sitellite_rewrite_replace - The replacement string to the sitellite_rewrite_pattern regular expression.
• sitellite_status - The status of the current box or form.
• sitellite_team - The team of the current box or form.
• sitellite_template - The template to use when rendering this box or form.
• sitellite_template_set - The template set to use when rendering this box or form.

The $box array

Since boxes are loaded within a separate namespace than the global one, global variables and objects aren't accessible directly, but instead must be explicitly imported into the current namespace.  However, Sitellite does provide several variables defined specifically for the use of your box.  The first of these is the $box array.  Typing the following into our test box will display for you the contents of the $box array:

<?php

info ($box);

?>

As you will see, this array has two elements in it: context and parameters.  First I'll describe what the context is/does, and then I'll discuss the parameters.

Switching contexts

Since boxes can be called in so many different ways (the 5 we saw above), it can be useful for a box to react differently depending on the way in which it is called.  For example, if a box is called in a sidebar, it may be innappropriate to call page_title(), which would override the title already set for the current page.  For this, we have the concept of contexts.

By default, there are 4 types of contexts, but you can also specify custom ones manually, if you should so desire, via the loader_box() function.  The 4 core contexts are:

• normal
• inline
• action
• sidebar

A normal box call means it is called from a main template, or from another box.  An inline box call means that it is called from inside the contents of a web page, via the <xt-box name="box/name" /> tag (in Sitellite 4.2, there will be a box chooser in Xed to make this easier to accomplish).  An action box call means that it is called directly from the URL.  And finally, a sidebar box means that it is called by the sitellite/sidebar box, which provides a standard means of grouping and managing sidebar elements in Sitellite.

To do different things depending on the context, you might structure your PHP code as follows:

<?php

switch ($context) {
   case 'action':
      page_title (intl_get ('My Very Own Box'));
      break;
   case 'inline':
      printf ('<h2>%s</h2>', intl_get ('My Very Own Box'));
      break;
   case 'normal':
   default:
      // leave it to the caller to set the title
}

// output the rest as usual

?>

You probably noticed here that I used $context instead of $box['context'].  A hint to save you some typing, both $box['context'] and $box['parameters'] are accessible as just $context and $parameters.

Next: The $parameters array

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

Home   More Applications Stories