What Are Templates?
Templates exist as a collection of PHP files in the ~/templates/ folder. Inside ~/templates/, files are organized into the following folders based on how the file is used:
ajax/basic/callouts/layouts/routed/
AJAX
When using AJAX requests in your site, simply create a file in the ~/templates/ajax/ folder. To help in obscuring your file structure, files placed in this folder are accessible via WWW_ROOT."ajax/file_name_without_extension/". You can also create sub directories inside the ajax/ folder, which will be interpreted as sequential segments of the requested URL, similar to the way routed templates function. For example WWW_ROOT."ajax/sub-directory/file_name_without_extension/" will look for the file matching the last segment of the URL in the specified sub directory.
You can read more about how AJAX files are routed in the Special Paths & Routing section.
Basic
Basic templates primarily display static, page-based content. Users can edit basic template resources in the 'Pages' section of the admin area and these are made available as variables in the file ~/templates/basic/{template-id}.php.
Layouts
Layouts control the front-end structure of your site, and tell BigTree which pieces of the markup to use when constructing a page. Standard BigTree naming convention dictates that partial layouts—that is, layouts that are primarily used as components of other layouts—have an underscore at the beginning of the file name. As your site grows in complexity, you may wish to organize all of your partials into a partials/ folder inside of ~/templates/layouts/.
The default.php layout is very simple: it instructs BigTree to arrange a page using a header, the rendered basic or routed content, and a footer.
<? include "_header.php" ?>
<?=$bigtree["content"]?>
<? include "_footer.php" ?>The $bigtree["content"] variable (in beta 4 and lower, this variable was $content) contains rendered content from a page template file in either basic/ or routed/, depending on whether you are viewing a static or routed page. The content is stored in an output buffer before it is applied to a layout and sent to the browser. This 'inside-out' method is an important element of how BigTree renders a page and can be utilized in any number of ways, including sending custom headers to the browser.
When BigTree finishes installing, _header.php, and _footer.php, within the ~/templates/layouts/ folder, are completely empty. BigTree imposes no structural requirements on your site, so feel free to delete these files and use your own. Despite being primarily a CMS, BigTree is a great platform for powering web apps and services.
You can change the layout that loads your template by reassigning the $bigtree["layout"] variable to the name of the layout file, without the .php extension (in beta 4 and lower, this variable was $layout), in the template file. For example, if you want your template to load within the home.php layout you would add:
$bigtree["layout"] = "home";
Routed
When a browser requests a page with a routed template, BigTree will search that template's directory looking for a file or a folder that matches each portion of the url path. It will begin with the first part of the URL after the page route and attempt to find a match. If it finds a file, it will render that file. If it cannot find a file, but does find a folder, it will render default.php, if it exists. If BigTree can find neither of these, it will throw an error.
Portions of the URL path that appear after a match will be appended to the array $bigtree["commands"]. These can be used as variables to fetch specific module data or define an action.
You must manually handle any 404 errors that occur within a routed template.
Creating a Template
To create a basic or routed template, find the Templates section of the Developer area and click "Add Template" in the toolbar. To add an Ajax template or a new Layout, simply create the new file in the proper directory. The big difference between the two methods is that Ajax and Layouts do not need to be internally registered with BigTree, they are simply available to you as the developer when structuring your page.
Resources
Any page-specific resources you want to access through your templates need to be added to the resources list. Resources require a unique ID, title, and form field type with the option of providing a subtitle for more detailed user instructions. Read more about the default Field Types.
How BigTree Stores Content
BigTree uses PHP and HTML to control the structure and presentation of your content. To fully utilize templates, you should first understand how BigTree stores your content in the database.
Content is attached to pages as an array of values related to resource ID keys. For example, a page that contains a header and some content may have a JSON-encoded resources database entry that looks like this:
{"page_header":"The Header","page_content":"The content."}BigTree will decode this to a key=>value paired array:
Array (
[page_header] => "The Header",
[page_content] => "The content."
)In the above example, the resource ID page_header has a value "The Header," and the resource ID page_content has a value "The content."
Displaying Content
To present this content on the page, you can simply echo the resource ID as a variable in your PHP code. A template utilizing page_header and page_content might look like this:
<h1><?=$page_header?></h1>
<?=$page_content?>Note: We prefer using the php shorttags syntax <?=''?> when building our templates, but if you prefer to write <?php echo ''; ?>, you may. We simply like the brevity.
Looping Through Items
Sometimes your resource will be an array of items, like a photo gallery. To display arrays of data, use a foreach loop. In PHP, they are written as follows:
<? foreach ($photo_gallery as $image) { ?>
<img src="<?=$image["file"]?>" alt="<?=$image["title"]?>" />
<? } ?>Displaying Content Anywhere
Once a piece of content is in BigTree, it can be used anywhere. Just because content is associated with one page doesn't mean it can't be published in a variety of places. Using $cms->getPage(), you have access to the resources of any page in your BigTree site.
<?
$newPage = $cms->getPage($id);
echo $newPage["resources"]["page_header"]; // new page's header
?>