Sitebox Templates
It’s often not enough to output the same html for every request, so Sitebox uses a template system to allow flexible html output.
The template system is very similar to the one used by Django. So if you know how Django templates work, you’ll feel right at home with Sitebox templates. They are designed to feel comfortable to those used to working with HTML.
A template is a simply a .html file with special tags in the html that gets processed during rendering. For instance, a tag might output the value of a variable.
Here is a simple Sitebox template, that illustrates the basic template features:
We will describe this example in detail below.
Outputting a variable
When a template is rendered by Sitebox, it is given a set of variables that can be used to control the output that is generated.
For instance, to output the value of a variable you should use the output variable format:
{{ variable_name_here }} | Outputs the variable "variable_name_here" |
---|
Common variables
There are some variables that are always passed to a sitebox template.
All values posted in a form submit (POST) or in the query string to a page, are automatically added as template variables prefixed with ”POST_” and ”GET_” respectively.
Additionally, these variables are always accessible:
{{ sitebox_app_root }} | The url root for the current sitebox.
Example: http://gameid-123456.fb.playerio.com/fb/my-facebook-site/ |
---|---|
{{ sitebox_page_path }} | The page path of the current page.
Example: /games/aroundtheworld |
{{ sitebox_gameid }} | The GameID of the game that owns the site.
Example: my-game-id-123456789 |
{{ http_referer }} | The value of the http referrer header of the request.
Example: http://apps.facebook.com/mygame/index.html |
{{ http_accept_language }} | The value of the http accept language header of the request.
Example: en-gb,en |
{{ http_user_host }} | The IP address of the user.
Example: 184.154.213.98 |
{{ http_user_country }} | The country code of the user after doing a GeoIP lookup of the user's address.
Example: us |
{{ http_server_time }} | The current time on the server, in UTC.
Example: 2012-03-30 10:41:24 UTC |
{{ http_server_unixtime }} | The current unixtime on the server.
Example: 1333104084 |
Tags
Tags look like this: {% tag %}, and involve processing instead of just directly outputting some variable.
For instance, you could use the {% if %} tag to control whether to show a given piece of content depending on whether the browsing user is logged in or not:
There are many different tags available, and you can find documentation for each in the Tags Reference section below.
Template inheritance
Often, you’ll want to include the same header and footer in every page of your site. Sitebox templates makes it easy to accomplish this without copy-pasting the same header/footer into every template.
The way it works is that you can mark one template as extending another with the {% extends %} tag, and then define which blocks of the parent template will get replaced.
This is most easily explained with an example. Let's say you got one file, index.html which extends master.html:
index.html:
master.html:
When a request comes in for index.html, Sitebox will merge the two templates by replacing all the blocks in master.html with the same named blocks from index.html.
In our case, this will result in the following merged template being rendered:
index.html merged with master.html:
Tags Reference
Below you'll find a tags reference that you can use to refer to the exact syntax of the various template tags.
Extends
{% extends 'path-to-master.html' %} |
---|
The extends tag is used to define which template to extend with the blocks of the current template, as described in Template Inheritance
Sample
In this sample, the extends tags says that the template extends the "master.html" file
located in the same folder as the template.
Block
{% block name-of-block %} ... {% end %} |
---|
The block tag does two different things depending on where it's being used.
- If the block tag is in a master template, then it defines where to put blocks with the same name from any template that extends from the master.
- If the block tag is in template that extends another template, then it defines what content to put into the block with the same name in the master.
For more information, have a look at Template Inheritance
Sample: Usage in master template
In this sample, the block tags define which parts of the master template can be replaced
by other templates extending from the master.
Sample: Usage in child template
In this sample, the block tags define what content to put into the
blocks of the master template can be replaced.
Include
{% include 'path-to-include.html' %} |
---|
The include tag can be used to include one template in another, as if it was part of the original template. This is very similar to the concept of Server Side Includes.
Sample
This sample uses include to include common header and footer html into the page.
Require Session
{% require_session %} |
---|
The require_session tag is used to tell Sitebox that the current page requires that the user is authenticated (has a valid session) before being allowed to view the page. See Requiring Authentication for Facebook specific information.
If the tag is included in a master template, then all templates extending that template will also require authentication.
Sample
This page will always require authentication before allowing the user to view the page.
Print Variables
{% print_variables %} |
---|
The print_variables tag outputs all the variables passed to a template in a pretty html table.
The tag is useful for debugging purposes when you want to see what's being passed to a page.
Sample
This page will just print out the variables being passed to the template at runtime.
Url
{% url 'path-to-file' %} |
---|
The url tag converts a relative path from the template to a file in GameFS to the full url of the latest version of that file using the GameFS Content Delivery Network.
You must always use this tag when embedding static resources (stylesheets, javascripts, images, etc..) into a page.
See Resource Urls for more information.
Sample
This page uses the url tag to embed a stylesheet, a javascript and two images.
Swf
{% swf src='path-to-flash.swf' width=400 height=500 args... %} | |
---|---|
src | The relative path to the flash file from the location of the template file. Required. |
width | The width of the flash object. Required. |
height | The height of the flash object. Required. |
id | The html id to give to the flash object. |
version | The required flash player version in format major.minor.release.build |
expressinstall | A GameFS path to the SWFObject expressinstall.swf file used for express updates of the users flash player. You get the file here |
play, menu, quality, scale, salign, wmode, bgcolor, base, swliveconnect, devicefont, allowscriptaccess, seamlesstabbing, allowfullscreen, allownetworking | All these arguments are standard Flash arguments and are passed directly to the flash object that gets embedded on the page. |
Any other argument | If you specify any other argument, it will be passed to the Flash file as a FlashVar. |
The swf tag does two things for you:
- It outputs the javascript and html required to use SWFobject to insert a Flash file in the page.
- It passes all template variables into the Flash file as FlashVars, so everything that’s available to the template is available inside Flash.
The tag expects the SWFObject javascript file to be included on the page.
Sample
This sample embeds a Flash file into the page with width=760, height=500 and custom
FlashVar "myflashvar" set to the value "game".
PayVault
{% payvault provider='...' %} | |
---|---|
provider | Which PayVault provider to use, so far superrewards, gambit, tapjoy, and trialpay are supported. Required. |
width | The width of the IFrame, defaults to 728. |
height | The height of the IFrame, defaults to 2700. |
frameborder | The frameborder attribute of the IFrame, defaults to 'no'. |
scrolling | The scrolling attribute of the IFrame, defaults to 'no'. |
connectuserid | The connectuserid of the user who should be awarded the Coins. In a Facebook App context, this defaults to 'fb' + fb_user_id, which ensures a seamless integration with QuickConnect for Facebook. |
gender, age, mode, vc, iphone, page, n_offers, mode, payout_min, payout_max, page_points | If you are using the provider superrewards, you can supply these optional GetBuyCoinsInfo arguments. Please see the SuperRewards PayVault documentation for more information. |
gender, dob, email, city, state, zip, currency | If you are using the provider gambit, you can supply these optional GetBuyCoinsInfo arguments. Please see the Gambit PayVault documentation for more information. |
The payvault tag embeds an offer IFrame from any of the PayVault providers that support that, which currently is SuperRewards and Gambit. This tag allows you to very quickly make a page for your Facebook app that lets your players complete offers for your virtual currency, or buy it directly, so that they can spend it in your game.
Sample
This sample embeds a SuperRewards IFrame into the Facebook App page with a height of 1000px and 20 offers per page, and ensures this is only displayed if the user is authenticated.
If
{% if expression %} ... {% else expression %} ... {% else %} ... {% end %} |
---|
The if tag is used to conditionally output content depending on whether an expression evaluates to true or false.
You can include as many {% else another-expression %} tags as you want and one final {% else %} tag for when none of the expressions evaluated to true
Sample
This sample checks the 'fb_is_logged_in' variable to determine what message to show
Sample
This sample looks at the 'sitebox_page_path' variable to tell the user
which page they're on.
Comment
{% comment %} ... {% end %} |
---|
Anything inside the comment tag will be removed during parsing and not appear in the output.
Sample
This sample comments out some old code, and will output "I'm version 1.0"