Calling our box

There are five ways of calling a box in Sitellite, which we'll explore below.

XT

The easiest way for us to see our new box in action is to place a call to it from our main XT templates.  So in your inc/html/default/html.default.tpl file, add the following line somewhere prominent, so that you'll be able to see it in your browser when you visit your Sitellite test site:

<xt:box name="myapp/hello" />

A trick to help with XT template design is to include fake content between the opening and closing XT tags, which you can use to see how your styles will look before plugging your templates into Sitellite.  For example:

<xt:box name="myapp/hello">
    hello world
</xt:box>

If you load your template in a browser, but not through Sitellite (ie. go to the URL http://www.yourWebSite.com/inc/html/default/html.default.tpl), you'll be able to see the template render the text "hello world" without the need of Sitellite's assistance.  This is one of those design benefits of the XT template format.

Anyway, if you visit your Sitellite site now, you should see the text "Hello, World!" (as opposed to "hello world") in your web pages.  This is the first way to call a box.

You can also pass parameters to the box as attributes of the XML tag, for example:

<xt:box name="myapp/hello" to="Lux">
    hello world
</xt:box>

I'll show you how to access these parameters in just a minute.

Inline

The second way to call a box is from within a web page.  To do this, add a new web page or edit an existing one, then click on the "Source" tab at the bottom of the Xed WYSIWYG editor.  Enter the following somewhere into your web page source:

<xt-box name="myapp/box" />

Notice that I used a dash instead of a colon this time.  This is because when you go back to the WYSIWYG view, you'll see that the box is visible in the editor, however Internet Explorer doesn't like displaying styles on XML elements with namespaces (ie. with the colons), which are necessary to make inline boxes visible in the editor (with the exception of using style references like "xt\:box", which is not as nice of a solution).

Now if you save your web page and view it in your browser, you will see the text "Hello, World!" added to your web page.

In Sitellite 4.2, you will be able to add inline boxes via a "Box Chooser" app, which will work similarly to the current Image Chooser in Xed.

PHP (other boxes)

The third way to call a box is to do so directly via the Sitellite API, from another box.  I'll show you how to do this by adding a call to an existing box into our box, instead of going through the process of creating another box then calling our first box from that one.  Anyway, add the following to your current box:

<?php

echo 'Hello, World!';

echo loader_box ('sitellite/nav/breadcrumb');

?>

You'll now see a breadcrumb display next to the "Hello, World!" in your site.  You can also pass parameters to your box this way as well, for example:

<?php

echo 'Hello, World!';

echo loader_box (
    'sitellite/nav/breadcrumb',
    array (
        'caption' => 'You are here',
    )
);

?>

Pretty straight-forward so far.  Note that I broke the loader_box() call into multiple lines, for the sake of legibility.  I'm big on legibility.  I don't subscribe to the mantra "It was hard to write; it should be hard to read."  Although, it is mildly amusing. :)

SimpleTemplate

A fourth way to call a box is from within a SimpleTemplate file.  Let's change our box code to say the following:

<?php

echo 'Hello, World!';

echo template_simple ('hello.spt');

?>

Now create a file called inc/app/myapp/html/hello.spt with the following contents:

{box sitellite/nav/breadcrumb}

This will display the breadcrumb again next to our "Hello, World!"  Nice and easy.  We can also pass parameters to boxes from our template by changing it to say this:

{box sitellite/nav/breadcrumb?caption=You are here}

Parameters are passed in SimpleTemplate as you would parameters in a URL.  It's simple for me to parse (being the author of SimpleTemplate) and it's familiar to most Internet users (especially developers, I hope ;)).

Actions

Speaking of URLs, the fifth and final way to call a box is as an action, which is to specify the box name within the URL itself, like this:

http://www.yourWebSite.com/index/myapp-hello-action

However, if you try this out, you'll notice that it doesn't load our box.  This is because unlike the other methods of calling a box, which are considered "trusted", the URL is coming directly from the visitor, and so it is considered "untrusted" unless you give it the appropriate access settings.

Next: The access.php File

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