PW 3.0.39 core updates & demo site update

[ryan]

This week has been busy! We've got updates to our demo site, a new functions API, and other core additions that you may find useful in template files.

https://processwire.com/blog/posts/processwire-3.0.39-core-updates/

[Ivan Gretsky]

It is always important to eat your own dog food. It is interesting how coming to site design with PHPStorm at hands can change the whole API paradigm at once)

1. As now we have at least 3 ways to call an API variable it would be incredibly important to have a detailed explanation about how to take a decision what to choose. Most of us used to use $page, but newcomers starting with demo profile will be using page(), and we are not even touching on wire() and $wire. It seems like @ryan is more into the function interface (you wouldn't be inventing it other way, would you). Please consider making an article about when to choose what, if you got time.
2. I really like the regions functionality, but the + at the beginning and at the end seems magical and probably goes against the initial functional interface intention to have closer IDE integration. I do not think this could be advised by IDE (or am I missing something?) Is there or should there be other more convenient way to append and prepend to regions?

[ryan]

Quote

 …it would be incredibly important to have a detailed explanation about how to take a decision what to choose. 

I recommend using API $variables for most cases, but here are a few instances where you may prefer the function versions:

• If an API variable is out of scope (like in a function), then you may find the new function versions very useful.
• If your editing environment provides more benefits to you for using the function versions (like auto-completion and docs) then that's also a compelling reason to use them too. This is something we haven't been able to provide before now. 
• If both of the above apply to you, then also use the functions API where you would have previously used wire(). 
• If neither of the above apply to you, then just use API $variables (fewer characters to type, and no questions about what instance). 

Basically, use whatever provides the most benefits to your scenario. For all practical purposes, $page and page() are synonymous. 

Quote

…but newcomers starting with demo profile will be using page(), and we are not even touching on wire() and $wire. It seems like @ryan is more into the function interface (you wouldn't be inventing it other way, would you). 

I don't see any reason to use $wire in template files–that's really more for core use.

The new skyscrapers template files were specifically developed to demonstrate the API variables as functions for that blog post. Basically, I wanted to show you how they work rather than just telling you. So I went out of my way to use them for this particular case. 

I personally use API variables in my sites, though will be glad to have the convenience of more options when needed. Function alternates to our API variables have been requested multiple times. That's because it's more friendly in how it enables communication between developer and editing environment. I agree that's a good reason to have them. However, you'll likely only want to use them if you find them beneficial in this way.

Quote

I really like the regions functionality, but the + at the beginning and at the end seems magical and probably goes against the initial functional interface intention to have closer IDE integration. I do not think this could be advised by IDE (or am I missing something?) Is there or should there be other more convenient way to append and prepend to regions?

It's completely IDE friendly, and that's actually one of the reasons for this approach versus using user defined $variables for regions. We're just working with strings here. Keep in mind the "+" is only something you add to the region name if you specifically want to prepend or append to an existing value that's already present in there… and most usages probably won't involve that. I'm not sure how to make prepending or appending more convenient than adding a single "+" character to the region name. I'm lazy and don't like to type a lot, so gravitate towards the simplest possible solution. But always open to suggestions. 

 

[horst]

On 1.11.2016 at 9:30 AM, Ivan Gretsky said:

I really like the regions functionality, but the + at the beginning and at the end seems magical and probably goes against the initial functional interface intention to have closer IDE integration. I do not think this could be advised by IDE (or am I missing something?) Is there or should there be other more convenient way to append and prepend to regions?

@Ivan Gretsky, I like your point and request for a more detailed explanation to the pro and cons in use cases of API-vars and API-functions!

But to be honest, with the region function you overcomplicate things. When you want to use the region function, you will use it all over your tempate files and I'm pretty sure, that you know how it works. (Means, you don't need your IDE telling you about it) But if you really need it, just let out the + sign for a moment, listen to your IDE, and then prepend or append the "+ sign". Ok?

 

@ryan the prepend and append plus-sign is the best of all.
The region function is the best, but with the plus-sign functionality it is top of the best!

[Ivan Gretsky]

My opinion is that there always should be a verbose, but obvious way to do things. And a cool shortcut way like the +. The verbose obvious and native to PHP way would probably be the 3rd argument.

With variables we just do .=, which is a language native construction and easy to understand by anybody, not only someone like @horst , me or anyone who loves PW and reads every blog post.

[szabesz]

Hm. But there exits the "verbose way" of implementing this brand new "+" thingy. Its verbose counterpart is the classic way of doing things: variables and standard PHP concatenation. Why should we make a shortcut verbose? That is a contradiction... Am I missing your point?

[Ivan Gretsky]

One might want to use regions to make them easier to pass around and not to conflict with existing variables. But anyone coming to project from outside of PW has to read the blog or the code to guess what that + means.

[tpr]

There could be a region_append, region_prepend or similar functions, or perhaps a third argument append/prepend. I'm fine with the + too, and while I see it's benefits I think I will not use it as it doesn't fit in my workflow.

[horst]

For me, it fits perfectly, as I dropped using the SPEX module now, since region() is available.

Before that, I used $spex->slot(). Now I'm able to define the main regions in my template prepend file like:

// header nav
region('headernav', "");

// the body content:
region('content', "");
region('sidebar', "");

// all JS codes that should executed at document.ready event,
// after jQuery and main.js are loaded:
region('JSdocReady', "new myObj().init();\n");

and now, along the way, I can add more code / markup to them. Why I like to use region() over a php var (like $content .= ...), is, that it stands out in the code and indicates (for me) that this is not locally used var, but one of the main buffers that get echoed in the template append file.

So, yes, its a personal preference. (That wasn't available before.)

[Robin S]

I started changing over my default site profile that I use as a base for new projects to use the functions API and region() function.

Then I realised that neither of these will suit me because the functions can't be interpolated in strings the way variables can. I much prefer string interpolation over concatenation - I find it more concise and easier to read.

The main attraction to me was the IDE code completion. Pasting the following at the top of each template file does the trick and isn't much hassle.

namespace ProcessWire;
/**
 * ProcessWire API variables
 *
 * @var $page Page
 * @var $pages Pages
 * @var $modules Modules
 * @var $user User
 * @var $users Users
 * @var $permissions Permissions
 * @var $roles Roles
 * @var $input WireInput
 * @var $sanitizer Sanitizer
 * @var $session Session
 * @var $log WireLog
 * @var $cache WireCache
 * @var $datetime WireDateTime
 * @var $files WireFileTools
 * @var $mail WireMail
 * @var $config Config
 * @var $database WireDatabasePDO
 * @var $fields Fields
 * @var $templates Templates
 * @var $languages Languages
 * @var $wire ProcessWire
 * @var $procache \ProCache
 **/

A similar thing can be done for region variables to avoid IDE 'undefined variable' notices.

/**
 * Template region variables
 *
 * @var $headline
 * @var $content
 * etc
 **/

I've set these up as a file template in PhpStorm so they appear automatically for each new PHP file created in the project.

[Robin S]

@ryan, could you please make a full profile of the updated Skyscrapers demo available? So it is easily installable for people to try out, like the previous version. It has come up a couple of times in the forums recently.

[szabesz]

On 2016-11-4 at 4:48 AM, Robin S said:

I've set these up as a file template in PhpStorm so they appear automatically for each new PHP file created in the project.

Here is what works with NetBeans:

/* ----------------------- ProcessWire API variables ------------------------ */
// <editor-fold>
/* @var $page Page */
/* @var $pages Pages */
/* @var $modules Modules */
/* @var $user User */
/* @var $users Users */
/* @var $permissions Permissions */
/* @var $roles Roles */
/* @var $input WireInput */
/* @var $sanitizer Sanitizer */
/* @var $session Session */
/* @var $log WireLog */
/* @var $cache WireCache */
/* @var $datetime WireDateTime */
/* @var $files WireFileTools */
/* @var $mail WireMail */
/* @var $config Config */
/* @var $database WireDatabasePDO */
/* @var $fields Fields */
/* @var $templates Templates */
/* @var $languages Languages */
/* @var $wire ProcessWire */
/* @var $wire \ProCache */
// </editor-fold>

NetBeans seems to be picky about the way you "format the comment", hence the explicit code folding and the variables separated into their own comment lines.

[Thor]

On 11/1/2016 at 5:30 AM, Ivan Gretsky said:

It is always important to eat your own dog food. It is interesting how coming to site design with PHPStorm at hands can change the whole API paradigm at once)

1. As now we have at least 3 ways to call an API variable it would be incredibly important to have a detailed explanation about how to take a decision what to choose. Most of us used to use $page, but newcomers starting with demo profile will be using page(), and we are not even touching on wire() and $wire. It seems like @ryan is more into the function interface (you wouldn't be inventing it other way, would you). Please consider making an article about when to choose what, if you got time.
2. I really like the regions functionality, but the + at the beginning and at the end seems magical and probably goes against the initial functional interface intention to have closer IDE integration. I do not think this could be advised by IDE (or am I missing something?) Is there or should there be other more convenient way to append and prepend to regions?

I purchased PHPStorm a month ago. It would be great if someone could post some tricks or hacks on how to integrate it with the PW API, so you can just use PW code directly without having to copy and paste from the reference site. I'm new with both, so anything that helps it's a nice addition. Both PHPstorm and ProcessWire seem to match great together and while PHPStorm has support for some frameworks out of the box, PW would be a great addition.