New to PW? How to Structure Your Site

[Joss]

This is an excerpt from an ongoing larger work that I am playing with so has a couple of references to things you haven't read - but it might be useful anyway.

I notice that some new PW users are a bit confused about how they should structure their site within the /site/templates/ directory, so this is just some general waffle addressing that confusion rather than telling you what to do.

Structuring Your Site

Here is a question that comes up in the forum more times than just about anything else:

“I need to build a site that will have this bit as part of that bit and will need to have something over there while the bit under here relates to the image that isn't there and the entire lot needs to be static html….”

What underlies the question and all its variant cousins is:

“Is there a set way to structure the files for my site?”
 

No.

To be honest I am pretty tempted to finish this chapter here because that one little word really does sum up the entire point about ProcessWire, PHP, MySQL, Apache, JQuery and anything else that makes this system tick. None of it, including ProcessWire, is about how you want to structurally create your website; they are all tools that enable you to construct your site how you wish.

Part of the problem, it seems, lies in the various demos and profiles that sdemonstrate how ProcessWire works and what it does. The very fact that they exist at all means that someone had to build them, and to do that, they had to structure them ... obviously.

Developers and designers that have come to PW from other content management systems and who are used to having to follow fairly limiting guidelines automatically assume that the demo they are looking at represents how they MUST put the site together. Then they look at a different demo by another plonker and it is built in a completely different way. Bugger.

The PW Templating System

Most content management systems have a templating system of some sort or another. Sometimes it is based on a third party markup system, sometimes it is based around the idea of a huge amount of files that if you want to change you have to build overrides and put them in certain directories and then work out how to strip out all the ccs that is still in there.

Some of them, particularly the ones that go on about CCK (Content Construction Kit, whoever that is) allow you a ton of versatility as long as you don’t mind that all the fields come complete with huge amounts of pointless nested DIVs and CSS referenced from one of the moons of Mars.

Some have had this amazing idea that it is somehow really clever to separate the idea of an overall theme from the way components are laid out and therefore put them in completely unrelated parts of the file structure (some in the core that will be rendered useless at the next update). Anyone used Magento?

The joke here is, of course, that none of this is about what a CMS is meant to do, it is about how to display the OUTPUT of a CMS, but somewhere down the line the two have got confused and the Content Management part of the system is now telling the public website part of the system how to do its job.

And that brings me neatly to the ProcessWire Templating System.

Which doesn’t exist.

PW is a true CMS in that it gives you two layers of tools:

• Firstly it provides a way of storing, managing and processing data.
• Secondly, it provides an API that allows you to retrieve and manipulate that data.

The bit it doesn't do is build your website for your – you are the designer or developer, you are probably the best tool for that job!

There are a few rules … well, there is one rule actually, which we covered earlier: template files must have a php suffix and be kept in the templates directory.

So, whether you construct your site using header and footer files included into your main templates, or whether you use a delegated approach or just one core template that you use to drag in markup from other files, or whether you use the API directly into a template, or as part of a php function or stored in a separate file, or whether you use jquery, ajax, JavaScript or anything else, this is all up to you and is NOT part of the PW system.

It is back to how we started (in the main tutorial) with just one line of PW markup in an empty PHP file.

<?php
echo $page->title;
?>

Now throughout this tutorial I will probably stick to some pretty basic construction – I will tend to use the API and PHP directly into a template file and possibly use an included header and footer just to reduce the amount of markup kicking around.

However, this is not necessarily the best way of creating a website in PHP and PW, it is just a nice clear way; that is all. The PW forums have all kinds of discussions on different approaches for using PW and PHP and files and so do forums and blogs all over the web. The very fact that PW does not rely on one particular way to construct a website means that all those ideas from all over the place are perfectly valid and can probably be used in PW.

Freedom is a wonderful thing, and so is a proper CMS.

Joss

[pwired]

That's why I like this forum so much, non coders are not left out

but are also learned into pw to become part of the scene.

[bwakad]

You are right, - like me - many have ask this. It takes us a long time to think 'out of the box' coming from joomla, wp or any other similar cms. But even if you mention, any site has a different structure, it still does not tell newbies where to start. In fact, I made the mistake starting from foundation site profile - which of course is good. But the logic that goes around in skyscrapers is more meant for me being a newbie.

So, what I am doing now is write everything down in a tabel:

Parent:    Admin>template: name | label | field(s) - Admin>page: name - Server>templates: filename - and front-end menu item

Children: Admin>template: name | label | field(s) - Admin>page: name - Server>templates: filename - and front-end menu item

In this way I can see the connection what's going on and especially where it would be called and displayed.

For instance, I renamed the field "architects" to "companies".

I then had to resemble this change in setup>template>architects - and under input-tab, renamed the architects.php as well.

The field also uses a selectable parent page named "Architects" I had to rename that through >pages to.

Since my menu item was called "Architects" I had to search where this was taken from, it was in _out.php, so I changed that.

Of course since some things change - especially in php, you need to open up all files to find reference to this fields - but long live sublime!

So, practise is good for learning. And I think this is what people mean when they talk about structure:

fields (back-end) are used on templates (back-end);

pages (back-end) use templates (back-end), and contain content;

templates (back-end) use most-of-the-time .php files on the server in templates folder - those on the server display content;

and if you look at the back-end - setup>templates - advancedTAB - under 'rename' only then you will find out which actual .php file is used.

from there you need to - kinda like - backtrace the steps.

For me this works, but of course you would need a working example like skyscrapers - no disrespect to other site profiles.

And by the way, I really had to think differently:

processwire "site profile" - is called template/theme by other cms;

processwire "templates" in topics/tutorials are usually those in the back-end - but many times it is not clear - and that is where confusius starts to fog our mind....

processwire "pages" - is just an entry in the DB.

[kongondo]

...... I made the mistake starting from foundation site profile - which of course is good. But the logic that goes around in skyscrapers is more meant for me being a newbie.....

well this is interesting...most of us tell newbies to forget about the skyscrapers profile (because it is advanced; not for newbies!) for a while until they get a grip of the default profile; 

[DaveP]

I think, following on from bwakad's comments and kongondo's (understandable) reaction is that the takeaway here is that you can't have too many example site profiles.

What 'clicks' with one new user may well be different from what another new user has an epiphany with.

[clsource]

I like to read the code, then read the forums, then be happy .

It's just a shift in the way to do things in processwire that many people

could not understand at first sight because they are used to work with more

strict cms.

I love processwire because it can fits in any solution, little or big, and gives you the freedom to architect the way you need to.

good read @Joss