Jump to content

Template Tutorial?

ritch0s

By ritch0s,
in API & Templates

 Share

Recommended Posts

ritch0s Newbie

ritch0s

Posted
Posted

Hi, I've been reading about processwire and it sounds like a really interesting concept but I'm having trouble understanding it fully. I've been looking through the source code of the files in the template folder of a new install and trying to figure out how they relate to the templates category in the admin panel, but I'm having trouble.

What I think would be really useful is a screencast / video tutorial of a static xhtml website being integrated with processwire making it editable for a client. I think having a relatable scenario like this will help newbies such as myself to understand how to use processwire in a real situation. For example the static site could be a common situation such as a basic portfolio website consisting of an about page, products page (with multiple products), blog page and contact page. The video could show the thinking process for each situation and how to create the pages with processwire making it easy for a non-technical client to update.

Another idea perhaps a more advanced version could be a video showing the approach and breakdown of how the author (Ryan) made some of his sites in the site showcase.

This project seems really interesting but it looks to me it requires a different way of thinking to solve the problem and therefore it does have a learning curve. Perhaps other newbies could give their experiences in this matter as maybe it's just me?

Thanks.

Link to comment
Share on other sites
Adam Kiss Hero Member

Adam Kiss

Posted
Posted

Hi Rith0s!

Isn't there actually a video???  :D

Anyway, I'll try to clarify a little here:

1. thing to know: one template in admin = one template file in /site/templates/. Whatever content is using this template, PW will try to parse contents of page through that php file.

2. template consists of PHP code to pre-process data and HTML output. HTML output (for convenience) can be also in external code called with require/include/flush or any other method, so you modify just one master template.

3. PW2 gives you few global variables to use in your template:

  • $page (current page, it's fields [also in global $fields], and various (and some advanced too!) methods)
  • $pages (connector to PW2 page tree)
  • $input
  • $session
  • $sanitizer

Full list with explanation here: http://processwire.com/api/variables/

More info about templates: http://processwire.com/api/templates/

Also, here is one of my templates with comments (hope it helps):

<?php
/*
 * Template: members.php
 *
 * Shows list of members based on date
 */

require_once '_inc/_functions.php'; //various functions

if (!empty($page->body)){ //if we have $page->body (i.e. if field 'body' is filled)
	$o = new OutputArray('<h1>Heading 1</h1>');
	//OutputArray is my own class. It's just an array to put strings into and then output on one place,
	//because it's faster than multiple $string .= 'addThis';
	$o->add('<div class="tinymce">'.$page->body.'</div>');
}else{
	$o = new OutputArray();
}

$o->add('<h2>Heading 2</h2>');
$o->add('<ul class="clenovia">');

//here I get one page (by url) and then all of it's children (which is my members template, grouped in group 1) into $clenovia
$clenovia = $pages->get('/s/clenovia-zboru/')->children('sort=sort');
$i = 0;
foreach($clenovia as $c){
	$foto = $c->foto->size(160,160);
	$o->add(s(CommonHTML::getPart('clen_zboru'), false,
		(++$i%3===1)?' class="cl"':'', $foto->url, $c->title, $c->uloha
	));//here I ouput HTML for each of members of group 1 – s() is my shortened sprintf() function
}
$o->add('</ul>');

$o->add('<h2>Pravidelní spolupracovníci</h2>');
$o->add('<ul class="clenovia">');

//here I get another pageand then all of it's children (members, group 2) into $clenovia
$clenovia = $pages->get('/s/pravidelni-spolupracovnici/')->children('sort=sort');
$i = 0;
foreach($clenovia as $c){
	$foto = $c->foto->size(160,160);
	$o->add(s(CommonHTML::getPart('clen_zboru'), false,
		(++$i%3===1)?' class="cl"':'', $foto->url, $c->title, $c->uloha
	)); // output HTML again
}
$o->add('</ul>');

/*
* OUTPUT
*/

include("./head.inc"); // here I include $page headers – <head> section, <body> opening, navigation and everything BEFORE content

// Not really necessary, but wanted the markup to line up with where it left off in header include,
// so put four tabs before the bodycopy before outputting it: – I left here Ryan's template text. I am rebel!
echo "\t\t\t\t".$o->render();

include("./sidebar.php"); //my sidebar custom code (which again works with $pages...)
include("./foot.inc"); //end of content <div>, GA, </body> and that's all folks

I tried to add as much comments as I can, although I'm not sure I made myself particulary clear :) But I sure hope it helps  ???

  • Like 1
Link to comment
Share on other sites
ryan Hero Member

ryan

Posted
Posted

These are good questions, and perhaps a video would be a good way to demonstrate some of them. But the goal is not to give you a different way of thinking. Instead, the goal is to work with your existing way of thinking and development style. The goal is to get out of your way and support you rather than tell you what to do.

Each template is a PHP file and you use it in the same manner that you would use any other PHP file. The only difference between a template (PHP) file and a regular PHP file is that ProcessWire provides you with some API variables giving you access to the data specific to the page being viewed. There are other things it gives you, but just understanding that point is the main thing you need to know. Whether you use the API variables is entirely up to you. It's certainly feasible that your templates could be nothing but HTML (though maybe not that useful, except for something like your 404 page template).

Adam did a good job of demonstrating a template as a PHP file, because you can see that 90% of what is in his template is his own PHP code that isn't necessarily specific to ProcessWire. In fact, I don't recognize some of the classes he's referencing because they are his own. He uses the API functions vars/functions where appropriate to pull in the data he needs, and then uses his own PHP code (and it looks like some of his own libraries) to output it in the manner he wants.

Your own templates need not be this advanced, nor do you need to know as much PHP as Adam does to make effective use of templates. In fact, I think you can even make very effective use of templates without knowing much PHP at all. But for people that know PHP and have a way of doing things, ProcessWire is not going to get in their way.

Because templates are PHP files, what a given template looks like and how you work with it is a bit of an open ended question. There is no right answer to that question, as so much of it comes down to your development style. ProcessWire is really designed to work within your existing development approach rather than trying to dictate your approach. For instance, some will use templates as just HTML files with occasional API variables to output a value for a given page.  

<html>
...
<div id='bodycopy'>
   <?=$page->body?>
</div>
...
</html>

Using templates in this manner, you don't need to know PHP, and you might not even know you are using it at all.

While the other end of the spectrum is to use template files as MVC controllers, or controllers for another PHP application, and then grab their output, i.e. 

<?php

$out = new TemplateFile("./includes/my_markup.html"); 
$out->set('headline', $page->get("headline|title")); 
$out->set('body', $page->body);
$out->set('sidebar', $page->sidebar); 
$out->set('navigation', $pages->find("parent=/"));
echo $out->render();

Note: The TempateFile is a class included with ProcessWire that you can use if you want to... it's what ProcessWire uses to render it's templates too.

A more common approach is for your template to include a header (of HTML and/or PHP), output a content area, and then include the footer (of HTML and/or PHP):

<?php include("./head.inc"); ?>

<div id='bodycopy'>
   <?=$page->body?>
</div>
<div id='sidebar'>
   <?=$page->sidebar?>
</div> 

<?php include("./foot.inc"); ?>

Another approach is to populate placeholder variables and then include another file to output them:

<?php

$headline = $page->title; 
$bodycopy = $page->body;
$sidebar = $page->sidebar; 

// render a ready-to-output subnav <ul> list 
$subnav = $page->children()->render(); 

// get photo from current page if available, otherwise get it from homepage
if($page->photo) $photo = $page->photo; 
   else $photo = $pages->get("/")->photo; 

// make the photo 300x200
$photo = $photo->size(300, 200); 

// main.inc is just HTML and outputs the vars we populated above in the right places
include("./main.inc");

But these are just a few examples of many possibilities. What I woud recommend is getting familiar with the templates that are included with the basic site profile. Then post questions about any parts that don't make sense, and we'll be happy to help. When you are feeling comfortable with the basic site profile, send me an email asking for the skyscrapers profile, and I will email this to you. This example goes a little further than what's in the basic site profile, but I think it's good to understand the basic profile first.

Also, if you want, tell us what other CMS platforms you've used and I can explain what's similar and different in how you use templates in ProcessWire.

Thanks,

Ryan

  • Like 1
Link to comment
Share on other sites
ritch0s Newbie

ritch0s

Posted
  • Author
Posted

Thanks for your replies, there's a lot of information there. I'll take your advice and try and take it onboard.

I still think a screencast/video showing a plain html page/site being integrated would be useful. Just like nettuts.com uses videos, they are an effective teaching tool. Although I realise that your typical user might not be a newbie, but still.

Link to comment
Share on other sites
martinluff Full Member

martinluff

Posted
Posted

Hi ritch0s - great you took the time to try the PW

I think you're making good points... The great strength of ProcessWire is that you can mold it to pretty much any method of working you prefer - but that also makes it a little more challenging to grasp than systems where there's a more prescribed way of doing things. I think more tutorials will follow in time - remember this is a very new system ;)

If you've digested the stuff from Adam and Ryan and it's still a bit of a mystery - do come back and ask some more questions - I'll do my best to help out (I'm pretty new around here too - and nothing like trying to explain a new system to someone else for learning it yourself ;)

Link to comment
Share on other sites
Guest

Guest

Posted
Posted

I think the main reason why PW2 is so powerful may also make it be misunderstood, since having all that freedom might seem intimidating.

We all have different approaches as to how to tackle this or that issue when presenting data, but we could also present newcomers some sort of an example or guide, like training wheels on a bike.  I think I can come up with such a thing :D  I'll tell you when I'm done :D

Link to comment
Share on other sites
  • 4 weeks later...

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share
Go to topic listing

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...