Making PW more userfriendly

[thetuningspoon]

Just to correct the quote above, delayed output is more scalable, not less scalable. Direct output is what doesn't scale, but it doesn't really matter when it comes to the default profile. 

 

I have worried about this aspect a little bit: making something as easy-to-understand as possible, versus showing what is a best practice. Delayed output is just as simple as direct output (not to mention it uses a lot less code), but it's not as easy to understand at the very beginning. 

 

On one hand the PHP developers evaluating ProcessWire cringe when they see the direct output method used in the old default (now classic) profile. On the other hand, beginners find it easier to relate to since it's common in other platforms. Both are our audience. If people think delayed output isn't beginner friendly enough, perhaps we need to have two versions of the default site profile. A beginner edition and an intermediate edition. 

 

Attached is a beginner edition of the default site profile. @Woop if you or anyone else gets a chance to take a look, please do and let me know if you think this is a more beginner friendly approach. I think it probably is, even if it isn't an approach I'd suggest someone use for anything but smaller sites. 

 

site-beginner.zip

 

To install, just grab a fresh copy of ProcessWire 2.5.0+. Place the contents of the zip in a /site-beginner/ directory and then load the installer from your browser. For site profile, select "Default (Beginner Edition)". 

 

The readme file in /site/templates/ has also been updated in this profile to reflect the structure of the template files. 

 

As for re-writing the text in the default profile (something mentioned way earlier) I agree on this and I need to talk to Joss. But I think getting the template files as simple as possible is a bigger priority at the moment. I think a lot of people installing CMSs for evaluation are more interested in the system and templates than in what demo content is in the fields. But for those that do read it, we can do better. 

I don't understand how delayed output is more scaleable, and I definitely think it is more confusing for your stated target audience. I actually find the opposite to be true for me in terms of scaleability (or at least flexibility), because delayed output forces me to use the same overall structure (the variable "bins") for all of my pages. It also forces you to write all of your markup in a php-first way (unless you know how to use output buffering) instead of an html-first approach, which I think is more appropriate for template files and easier for front-end developers to work with. When I do find myself repeating myself in the template files, I can just use php includes for any section of code that is used in more than one template.

Don't get me wrong, I love php. I just think that it should be as "loosely coupled" from the markup as possible. When it's time to write html, I want to think more about html and less about php.

[pwired]

instead of an html-first approach, which I think is more appropriate for template files and easier for front-end developers to work with. When I do find myself repeating myself in the template files, I can just use php includes for any section of code that is used in more than one template.

Has this something to do with pw 2.5.0 because the header.inc and footer.inc in that version are gone ?

Although you can re-create them for your self at any time can´t you ? I also like those .inc files

because with them I can let pw manage my markup in an easy way. Has one of your pages a different look,

just include different .inc files with the same output between the html tags. Someone said that those .inc files

are not safe because the code inside can be read by anyone over a direct internet url.

Further I have not the faintest idea about what delayed ouput is let alone it´s advantage.

https://processwire.com/docs/tutorials/how-to-structure-your-template-files/page4

[diogo]

Someone said that those .inc files

are not safe because the code inside can be read by anyone over a direct internet url.

That's true, but not inside PW

[Nico Knoll]

I'm kind of always using .inc files in my projects. head.inc, foot.inc and functions.inc. I like this file ending, too 

[teppo]

.inc is sometimes (including in the "Essential PHP Security", unless my memory fails me) considered bad practice, mainly because it has to be separately handled by .htaccess rules. If .htaccess fails for whatever reason, your .inc files are suddenly world-readable.

 

Though a lot has to go wrong before this can happen (and even then it's usually far from critical), so far I haven't heard any compelling reasons to use .inc instead of fail-safe alternatives, such as .php (or .inc.php, if that .inc is somehow really important).

[Peter Falkenberg Brown]

Dear Pete,

Here you go guys: https://processwire....plates/?p=22762 (found via a link halfway down this article: http://www.flamingru...in-processwire/ )

I know ryan has explained this several times over the years but I agree that as one of the real "what the heck?" points that come up when you're first exploring ProcessWire some page dedicated to it on the site and linked to wherever fields are mentioned might not be a bad idea

That's a helpful post; thank you. In fact, I think I read that before.

I think that a more comprehensive post with benchmarks and every possible advantage to the one-field-per-table method, pointed at both techies and corporate types, would be even more powerful.

Yours,

Peter

[woop]

.inc is sometimes (including in the "Essential PHP Security", unless my memory fails me) considered bad practice, mainly because it has to be separately handled by .htaccess rules. If .htaccess fails for whatever reason, your .inc files are suddenly world-readable.

Though a lot has to go wrong before this can happen (and even then it's usually far from critical), so far I haven't heard any compelling reasons to use .inc instead of fail-safe alternatives, such as .php (or .inc.php, if that .inc is somehow really important).

I think Ryan solved it nicely by adding underscore to the included files. It makes it easier to get an overview of your files when template files and head includes doesn't look the same in the file browser.

[Christophe]

Perhaps there's a better place to post this. Feel free to move it.

I'm learning Python for Informatics currently. There are also some videos.

I've just found this, from the same source, that could be interesting for php beginners: http://www.youtube.com/playlist?list=PLlRFEj9H3Oj5F-GFxG-rKzORVAu3jestu

Starting from "PHP-Intro Chapter 3 - Overview", I suppose.

http://www.php-intro.com/

I'll surely look at least at the videos .

[Christophe]

Why not a (comic) book like http://mislav.uniqpath.com/poignant-guide/ or http://natecooper.co/2014/08/build-your-own-website-a-comic-guide-to-html-css-and-wordpress/ - just found this latter one yesterday - (or a manga-style book) for example ?

Just an idea.

[bernhard]

I don't understand how delayed output is more scaleable, and I definitely think it is more confusing for your stated target audience. I actually find the opposite to be true for me in terms of scaleability (or at least flexibility), because delayed output forces me to use the same overall structure (the variable "bins") for all of my pages. It also forces you to write all of your markup in a php-first way (unless you know how to use output buffering) instead of an html-first approach, which I think is more appropriate for template files and easier for front-end developers to work with. When I do find myself repeating myself in the template files, I can just use php includes for any section of code that is used in more than one template.

Don't get me wrong, I love php. I just think that it should be as "loosely coupled" from the markup as possible. When it's time to write html, I want to think more about html and less about php.

ok your question was some days ago but anyway: this post from ryan should give you an answere!

as far as i understand, the main benefit is that you can define things wherever you want and then do the output at the right position. if you had a slider in a sidebar for example and needed a special stylesheet for that slider it would be too late to include that with a html-first approach. outputting everything afterwards lets you add $stylesheets[] = 'slider_style.css'; wherever you want and then put it out in your <head> right in place like this:

<head>
   ...
   foreach $stylesheets
       echo <link ... stylesheet_name.css>
</head>
<body>

    <div id="main"></div>
    <div id="slider"></div>

</body>

[thetuningspoon]

ok your question was some days ago but anyway: this post from ryan should give you an answere!

as far as i understand, the main benefit is that you can define things wherever you want and then do the output at the right position. if you had a slider in a sidebar for example and needed a special stylesheet for that slider it would be too late to include that with a html-first approach. outputting everything afterwards lets you add $stylesheets[] = 'slider_style.css'; wherever you want and then put it out in your <head> right in place like this:

<head>
   ...
   foreach $stylesheets
       echo <link ... stylesheet_name.css>
</head>
<body>

    <div id="main"></div>
    <div id="slider"></div>

</body>

Hi BernhardB, thanks for the reply. You can still do this with the direct output method (and in fact I do quite often). Simply define your array/variables at the beginning of your template file, and then have your head.inc file process them. For example, I use Ryan's stylesheet and script arrays at the beginning of my template file for adding on scripts that are unique to a particular template, and then I have my head.inc loop through those and create the markup.

[Soma]

@everfreecreative

The thing is if you have like a lot of templates you'll have to do this for every template, once you want to change something on that part you'll have to edit all templates, so it doesn't scale well and isn't as flexible. If you wanted to conditionally not include header and footer, you'll have to edit all templates again. Once you want to be able to be more flexible with different layout types you're left with editing all templates to implement some logic. Once you decide you need to have different main container template for certain templates ... it doesn't scale as well. 

Of course to some extend you can incorporate things before the header include, but what if you have some after you wanted to add a css or js or something else? Maybe you want to be able to render a widget (page) inside content generation, that has a module or partial, that then wants to load conditional things like assets, you can't with your approach as the header is already "rendered".

[thetuningspoon]

Hi Soma, thanks for your thoughts. I can see how there are plusses and minuses to each method in terms of flexibility and scalability under different scenarios. For me personally, I haven't encountered any of the issues you mention, but most of my projects don't use more than 5 or 6 templates with actual output. There are really so many different ways of structuring your site in ProcessWire that it's hard to make comparisons apples to apples.

My main concern with the delayed output is that it introduces an extra step that obfuscates how ProcessWire works and might turn new users off for that reason. And, two, because it requires you to write most of your html like this:

$mainOutput .= "<p>Some stuff</p>";
$mainOutput .= "<div>Some more stuff</div>";

Which--for a front end developer--is just yucky.

[Soma]

Hi Soma, thanks for your thoughts. I can see how there are plusses and minuses to each method in terms of flexibility and scalability in different situations. For me personally, I haven't encountered any of the issues you mention, but most of my projects don't use more than 5 or 6 templates. There are really so many different ways of structuring your site in ProcessWire that it's hard to make comparisons apples to apples.

Yeah there's pros an cons. But it seems you never had done bigger complex sites where there's a lot of demand for modularity and flexibility. I simply wouldn't be able to do what I do currently (project) with that old default approach. And I used many different approaches on PW projects. That's why one have to come up with other approaches. 

My main concern with the delayed output is that it introduces an extra step that obfuscates how ProcessWire works and might turn new users off for that reason. And, two, because it requires you to write most of your html like this:

$mainOutput .= "<p>Some stuff</p>";

$mainOutput .= "<div>Some more stuff</div>";

Which--for a front end developer--is just yucky.

You can for sure, but sorry, if that's your main concern, I have to tell that's just not true. It's not required at all. It's just an (bad?) example by Ryan. You don't have to do that and there's a lot of ways you can avoid that. I use delayed output with using templates only as a controller that defines a layout template, load, or delegates and renders widgets/partials/content using view templates etc, where there's mainly the plain html tags with some php used as "template engine", it's only basic presentational logic.

Maybe also have a look at the Spex template helper module.

[LostKobrakai]

An addition to Soma's argument. You don't need to write the markup as php strings if you use templates, which you later parse to a string you can store in a variable. It's actually quite easy: 

$template = new TemplateFile($config->paths->templates . "PATH_TO_TEMPLATE");
$template->set("headline", $page->title); // Will be $headline in the template-file

$markup = $template->render();

This way you can write markup, as you do now, for single parts of the page, which you can dynamicly stitch together on page render. This should be more scaleable than copy pasting them from one template to another. 

[WillyC]

yule can.alsos do this new.stuffs pwire2.5

 renders /site/templates/willyc.php

echo wireRenderFile( 'willyc', array('headline' => $page->title) );

or.this

wireIncludeFile( 'willyc', array('headline' => $page->title) ); 

[LostKobrakai]

Does this work in 2.5 stable? Thought it's been added only on the dev version.

[thetuningspoon]

An addition to Soma's argument. You don't need to write the markup as php strings if you use templates, which you later parse to a string you can store in a variable. It's actually quite easy: 

$template = new TemplateFile($config->paths->templates . "PATH_TO_TEMPLATE");
$template->set("headline", $page->title); // Will be $headline in the template-file

$markup = $template->render();

This way you can write markup, as you do now, for single parts of the page, which you can dynamicly stitch together on page render. This should be more scaleable than copy pasting them from one template to another. 

Yes, I am familiar with this since I'm using that exact technique in a process module I'm working on. I saw how Ryan was using it in parts of FormBuilder and was wondering how it worked, so I looked into it and saw how it uses php output buffering behind the scenes. Of course, this is how ProcessWire templates work in the first place.

For most users, I think having to build an entire templating engine on top of ProcessWire's already existing templating engine is just too meta.

Also, please bear in mind though that I'm not "copy pasting" from one template to another, but using includes. You can also have includes within includes, and conditional logic for displaying includes, so it can be quite flexible.

[Soma]

Yes, I am familiar with this since I'm using that exact technique in a process module I'm working on. I saw how Ryan was using it in parts of FormBuilder and was wondering how it worked, so I looked into it and saw how it uses php output buffering behind the scenes. Of course, this is how ProcessWire templates work in the first place.

For most users, I think having to build an entire templating engine on top of ProcessWire's already existing templating engine is just too meta.

Also, please bear in mind though that I'm not "copy pasting" from one template to another, but using includes. You can also have includes within includes, and conditional logic for displaying includes, so it can be quite flexible.

I think you do maybe not really understand and my fault to mention "template engine".

There's not template engine other than what PW has. I don't have a "template engine" on top of already existing template engine. I'm just using <div><?php echo $variable ?></div> and some simple logic if and foreach's, no template engine at all. Anyway  It's all there and you don't have to built something, just structure differently.

[Wanze]

@everfreecreative

You may want to check out my module: http://modules.processwire.com/modules/template-engine-factory/

It basically is a wrapper around the "internal ProcessWire template engine" with the option to add Smarty or Twig as external engines.

The basic idea is that your regular template files are controllers which delegate the output to a corresponding template file. If you need MVC in ProcessWire, this module can help you.

*Advertisment mode off* 

Cheers

[Joss]

I have to say that working within the templates directory, however you decide to do it, is hardly building a template engine.

What really worries me about a lot of this is that there seems to be a fear of writing ordinary html with some css bunged in.

However you decide to organise your structure, however you decide to piece the bits together, in the end, that is all you are doing.

[thetuningspoon]

Sorry, I mean "template engine" in the generic sense of building the final view that users see and the process for generating that. I'm not talking about a language like smarty or anything like that. Sorry, I'm not really up on all the lingo and proper terminology for these things.

I'm just wary of unnecessary complexity, that is all. What you do in your own ProcessWire install is none of my business  After all, the beauty of PW is it's flexibility and the fact that it doesn't force you to do things a certain way. I just know that I would have been turned off if the workings of the PW templates weren't immediately clear to me when I first found it. This is from someone who came from building sites with pure html, pages, css, and a few php includes, so that is the world I'm from, take it or leave it

[teppo]

When I started working on my first ProcessWire site I liked that by simply opening the basic-page.php template file (obviously connected to basic-page template), I could instantly see how everything worked. It was easy to start from there, building more complexity and adding those "advanced tricks" if/when needed.

Things like delayed output, appendTemplateFile/prependTemplateFile, etc. raise the bar of entry, that's just how it works. They're things you won't simply "get on the first sight". You'll have to dig through other template, config and README files (or docs) to understand what's going on.

However you look at it, things that "just magically do something" may be helpful and ease your workload once you understand how they work, but also tend to add to the frustration a new user feels getting used to the system. Personally I believe that the "first dive" into a new system should be as easy and enjoyable as possible. Anything that complicates things is likely to increase the bounce rate.

[Nico Knoll]

I'm doing PW sites for almost four years now I think and still be using head.inc and foot.inc and do some $template->render() stuff for parts of my site. So I think you can just use the way you're more comfortable with.

[Joss]

When I rewrite my old simple site tutorial, I will be recommending the blank install and then I will take the most logical route so that the html is really staring people in the face. If the HTML is recognisable and familiar, they will have a better chance of understanding what they need to learn.

However, I will, as I have done before, make sure that new users realise that this is not what you MUST do, but rather what you CAN do.

The problem with tutorials, as with demo installs, is that you have to decide on just one method to avoid confusion - it is difficult to avoid newcomers believing that this is the way they have to do things.