Blame | Last modification | View Log | Download
Welcome to the Default Site Profile (Intermediate Edition)==========================================================This is a plain text document. If you are currently online withinternet access, you will find it much nicer to read an HTMLformatted version of this document located at:http://processwire.com/docs/tutorials/default-site-profile/If you are just getting started with ProcessWire, you mightalso want to look into the beginner edition of this site profile.Need multi-language support? The multi-language version of thisdefault site profile is a good place to start.Both the beginner and multi-language versions of this siteprofile are available as installation options when installingProcessWire.Introduction============Just getting started with ProcessWire and aren't totally clear on whattemplate files are? The good news is that template files aren't anythingother than regular HTML or PHP files, and you can use them however youwant! This particular site profile uses a strategy called Delayed Output,but you should use whatever strategy you prefer.If you know enough to create an HTML or PHP document, then you alreadyknow how to use ProcessWire template files. The only difference is thatProcessWire provides your template files with certain variables thatyou may choose to use, or not use. Most notable is the $page variable,which contains all the fields of text or other information containedby the page being viewed.For instance, $page->title contains the text contained in the Titlefield of the current page, and $page->body contains the text for theBody field of the current page. You can choose to output those whereveryou want. A really simple template file might look like a regular HTMLdocument except for where you want to output the dynamic portions (liketitle and body). Here's an example:<html><head><title><?= $page->title ?></title></head><body><h1><?= $page->title ?></h1><?= $page->body ?></body></html>That's all that a template file is. Now when we're building somethingfor real, we like to save ourselves as much work as possible and avoidwriting the same HTML markup in multiple places. In order to do thatwe'll usually isolate the repetitive markup into separate files orfunctions so that we don't have to write it more than once. That'snot required of course, but it's a good strategy to save you time andmake it easier to maintain your site further down the road.Template file strategies========================The two most popular strategies for template files are:1. Direct Output is the simplest strategy and the one used by theClassic Site Profile. While it doesn't scale as well as otherstrategies, it is a very good point to start from. If you'veever worked with WordPress templates, chances are you alreadyknow how Direct Output works. If you'd rather get started withthis strategy, we recommend installing the Classic Site Profilerather than this one. Read more about the Direct Output strategy:http://processwire.com/to/direct-output/2. Delayed Output is the strategy used by this site profile. Itis also quite simple but involves populating content toplaceholder variables rather than outputting directly. As aresult it may take a few more seconds to understand than directoutput, but the result is more scalable and maintainable. Readmore about Delayed Output here:http://processwire.com/to/delayed-output/How this Default Site Profile works===================================This Default Site Profile uses the Delayed Output strategy. Here'show it works:1. The initialization file is loaded (_init.php).We use it to define placeholder variables for content regions.2. The template file is loaded (i.e. home.php or another).We use it to populate values into the placeholder variables.3. The main output file is loaded (_main.php).It is an HTML document that outputs the placeholder variables.Below are more details on exactly what takes place and in the threesteps outlined above:1. The initialization file is loaded (_init.php)---------------------------------------------We define placeholder variables for the regions in our page inthe _init.php file. These placeholders can be anything that youlike (and in any quantity) and usually depends entirelyon the needs of your site design and content.In this default site, our needs are simple so we've definedplaceholders for just 3 regions on the page. We usually namethese regions something consistent with the HTML tag, id or classattribute just for ease of readability, but that's not required.These are the three placeholder variables we've defined in this site:$title - The headline or title (we use for <title> and <h1>)$content - The main page content (we use for <div id='content'>)$sidebar - Sidebar content (we use for <div id='sidebar'>)The leading "$" is what designates them as placeholder variables.We do this in a file called _init.php. ProcessWire knows to loadthis _init.php file first, before our actual template file. Wedefine these placeholder variables simply giving each a defaultvalue, or by just making them blank. Go ahead and take a look atthe _init.php file now if you can. But to summarize, here's howyou define a blank placeholder variable:$content = '';And here's how you define a placeholder variable with an initialor default value:$content = "<p>Hello World</p>";Here's how we would populate it with a dynamic value from $page:$content = $page->body;The last thing we want to mention about _init.php is that wemight also use it to load any shared functions. You'll see a linein this site's _init.php the includes a file called _func.php.That file simply contains a shared function (used by multipletemplate files) for generating navigation markup. This part isnot so important for now, so come back to it once you understandhow everything else works. But the point to understand now isthat the _init.php file initializes everything that may be usedby the site's template files.2. The template file is loaded (i.e. home.php or another)------------------------------------------------------Next, ProcessWire loads the template file used by the page beingviewed. For example, the homepage uses home.php. We use ourtemplate file to populate those placeholder variables we definedin _init.php with the values we want.For instance, most often we populate our $content variable withthe body copy from the current page:$content = $page->body;But we might also do something more like append some navigationunder the body copy or prepend a photo... the sky is the limit.$content = "<img src='/photo.jpg'>" . $page->body;Our search.php template file for example, populates $content witha list of search results.Because our placeholder variables were already defined in the_init.php file with default values, our template file (likehome.php or basic-page.php) need only focus on populating theplaceholder variables that you want to modify. It does noteven need to mention those placeholder variables that it doesn'tneed or doesn't need to change.3. Everything gets output by _main.php-----------------------------------After ProcessWire has loaded our template file (i.e. home.php) itthen knows to load the _main.php file last. In the case of thissite, our _main.php file is an entire HTML document that outputsour placeholder variables in the regions where they should appear.For example, the $content variable gets output in #content <div>like this:<div id='content'><?= $content ?></div>Please go ahead and take a look at the _main.php file for context.Note that our _main.php uses "<?php echo $content; ?>" style,rather than "<?= $content ?>" style, like shown above, just incase you happen to be running an older version of PHP. But morethan likely you can use the shorter syntax when preferred, as thetwo are functionally equivalent.More template file resources============================- How do template files work?https://processwire.com/api/templates/Official documentation on template files.- API variableshttps://processwire.com/api/variables/We mentioned $page above, but here are all the other API variablesyour template file can make use of.- API cheatsheethttp://cheatsheet.processwire.com/Once you've got the basics down, this cheatsheet is invaluable indescribing all the properties and functions available to yourtemplate files.Tutorials that help with template files=======================================- Hello Worlds Tutoral, by Ryan Cramerhttp://processwire.com/docs/tutorials/hello-worlds/The Hello Worlds tutorial gently introduces ProcessWire and templatefiles, starting from a blank slate.- "But what if I don't know how to code?", by Joss Sanglierhttp://processwire.com/docs/tutorials/but-what-if-i-dont-know-how-to-code/This particular series of tutorials will not only introduce you toProcessWire, but step by step, will give you those small bits of codingknowledge that will get you going and open up this amazing world of aContent Management Framework.- Installing a CSS Framework, by Joss Sanglierhttp://processwire.com/docs/tutorials/installing-a-css-framework/A quick demonstration about how easy it is to use one of the many CSSframeworks available to designers.- How to structure your template files, by Ryan Cramerhttp://processwire.com/docs/tutorials/how-to-structure-your-template-files/This tutorial contrasts and compares the direct output and delayedoutput strategies and more. It is a very good introduction to usingProcessWire template files.