New post: Weekly update for 18 Jan 2019

[ryan]

I'd planned on writing up a blog post today and bumping the PW version up to 3.0.125, but working on documentation pages ended up taking up most of the day. My hands are getting a bit tired from all the writing, so I'll keep this post short. ? I'll have a more formal post with more on the 3.0.125 version next week. 

People have been asking for more information on the various ProcessWire API access methods, as well as more information on the Functions API. I've written up a new documentation page that covers all the details. Though it's become a bit long, so next week I might split off the Functions API part into a separate child page. But for now, this is what I've got—the new documentation page is located here:

https://processwire.com/docs/start/api-access/

In addition, the ProcessWire API Explorer module has been updated to support documentation for ProcessWire's procedural functions this week. And as a result, our online API documentation page now covers them all too. I spiffed up the phpdoc on all of them (and in some cases re-wrote the content) in preparation for that. For those that were asking for more documentation on the API functions, this page also has a section dedicated for those. Here's a direct link to our more than 50 procedural functions available in PW that previously didn't have any online documentation: 

https://processwire.com/api/ref/functions/

 

[Jonathan Lahijani]

Quote

Changing shoes does not cause you to become confused, thinking you are now a different person.

This is great life advice!

[Jonathan Lahijani]

In regards to API Variables in the documentation, is there a reason why the $notices variable is not listed with all the other API variables?  It does have its own documentation page:
https://processwire.com/api/ref/notices/

Also, same for $options, which I got a mixed response about here (2015):

 

[adrian]

Ryan - thanks for all the work on those docs. I'm afraid my concerns around mixing approaches in the examples on the homepage still stand, but it's definitely great having the differences / pros / cons documented, even if a little verbosely at the moment.

I am kinda curious why the procedural functions are documented now. Perhaps there are still several that don't have object oriented versions, but I guess for consistency I'd rather see them all have an OO version available and make it clear that those are the primary methods to use. Or do you find yourself using the procedural versions in certain situations still? Could you please document when you would use these over their OO versions?

[teppo]

Quote

• Not all API variables are available as functions. Only those that are likely to be needed on the front-end of a website or application are available as functions. As a result, it’s a very specific list of functions that does not change based on what modules are installed, etc. (this might also be seen as a benefit in clarity for some)
• API variables provided by 3rd party modules are not available as functions (other than through the wire() function) unless the module developer has opted to create one.

The first bullet point seemed to answer my question from the previous thread: module's can't add features to the Functions API, it's immutable in that regard. The second bullet point, on the other hand, seems to contradict the first one: module developers can indeed create new functions for API variables, effectively adding to the Functions API – even if behind the scenes the implementation isn't identical.

It might be worthwhile clarifying the wording here a bit, I at least found this part confusing. Leaving the "it's a very specific list of functions that doesn't change" part out and perhaps adding "By default" before "Only those that are likely" would be an improvement – unless I'm misunderstanding the whole thing?

Also, a table of contents would be really nice for these longer pages.

---

Overall I think it's great that there's now documentation for a lot of stuff that was completely missing before. I do agree with @adrian in that the new documentation is a bit verbose, though. It's a lot to browse if I simply want to get the facts.

My own writing style tends to be extremely verbose, so I should know ?

@ryan, would be possible to allow others to somehow make suggestions to the content of the site (and particularly docs) without having to open a new issue for every suggestion? It'd be amazing if we could somehow make some kind of change suggestions and submit them directly via the site, perhaps publicly – or at least for a limited group of volunteer editors.

Trust me, I do realise that keeping everything up to date, managing the core, writing weekly posts, and whatnot must be an unbelievably time-consuming job. Just looking for ways the community could perhaps participate.

[cstevensjr]

I actually like the verbose style for this type of documentation.  Ryan has significantly filled in the gaps of missing centrally located documentation.  There's much to read now.  I find that better to have than the typical documentation that is full of bullet points.  I truly hope he continues along this path because I believe it helps everyone in learning the more technical parts of ProcessWire.

I also like that community members are actively asking to contribute to making the documentation meaningful.  The active positivity of community members and the quality of thoughtful or extremely helpful answers given are what makes being on this forum truly unique.

[adrian]

1 hour ago, cstevensjr said:

I actually like the verbose style for this type of documentation. 

I do like the style - sorry if that came across incorrectly. I just it could be trimmed a little, but not a big deal.

[Zeka]

Ryan, thanks for the update. 

It would be great to get an update of  "Selectors as regular and associative arrays".

[ottogal]

15 hours ago, adrian said:

my concerns around mixing approaches in the examples on the homepage still stand

I share this opinion. As far as I see, some of the listed Benefits of the functions API are especially relevant vor beginners, whereas the potential drawbacks mostly refer to situations not occuring to beginners. So I would suggest to use the functions in all the basic examples for beginners, and additionally give them hints to the alternatives (firstly the variables) and link them to the API access documentation.

[szabesz]

15 hours ago, ottogal said:

I would suggest to use the functions in all the basic examples for beginners

23 hours ago, teppo said:

the new documentation is a bit verbose, though

If I was Ryan – which I'm not ? – I would create a short intro for newcomers (I do not use the word "beginners" on purpose because a pro PHP developer can still be new to ProcessWire) and even this short intro should be clearly divided into two sections: one for frontend development recommended best practices and one for module development recommended best practices. At the end of this introductory article, I would link to this verbose one we currently have.

[teppo]

About verbosity: I don't find it inherently bad either. Don't get me wrong – I truly enjoyed reading this post. There's always room for such text, and I love the way Ryan explains things. It just makes sense.

That being said: if and when someone is only just trying to figure out how the API works – say, they're evaluating a number of platforms, and want to see which one makes most sense – it would be best for both us and them to have a short version available. Key points only: what are the methods they can use to access the API, where and why they should use each method, and finally "read more" -links for more details about each method.

I've been digging into a lot of new tools recently, and I can say from experience that it makes worlds of difference for a newcomer how fast and easy they can get the basics in. It's the worst if you have to spend loads of time digging into terminology, long posts discussing philosophy and behind-the-scenes implementation, or other things that don't really matter at that point, just to know if this actually is the platform you want to invest your time in.

It should be an incremental process: start from the basics in an easy-to-chew package, and continue building up from there. You don't want to drop a mountain of information onto a newcomer on one go ?

[adrian]

EDIT: I see that the functions in question are tagged as pw-internal so I guess that's why they are not listed so you can probably ignore this post!

@ryan - regarding the new procedural functions docs, it seems like there are several ones missing. Not sure if these are intentionally not listed or it's a bug in your API Explorer code.

I have been updating the API Explorer in Tracy and on first glance I have noticed that you're missing tabIndent(), wireEncodeJSON, & wireDecodeJSON in the main Functions.php file and in FunctionsAPI.php you're missing the inputCookie(), inputGet(), and inputPost() functions. However I expect there might be others also missing.

I haven't committed these changes to Tracy just yet, so here's a screencast of what it is finding.

[Tom.]

I think that the new documentation is more confusing than previously. 

At the begging it only shows a handful of variables, so I use $files->render() to put the header and footer in each template. I don't use Regions or anything like that as we very rarely have absolute consistency between each page. For example sidebar etc. We often keep the design across each page but the layout is different depending on the content.

$files is now hidden a long with a lot of other variables. As far as I can tell, we are pushing the Functions API unless there is a reason not to use it (multi-install etc.). That's great but the documentation isn't the same. For example $files has everything in there render() etc. Meanwhile the files() page just has $wireFileTools = files(); and nothing else.

I feel like if we are going to favour the Functions API there needs to be an emphasis on this in the API Reference. At the moment it's a little... overwhelming? 

I feel like it should be a tabbed layout, where the variable API is under a different tab, then the functions API is first. I also think that it should be listed as it was previously. I don't know, it kind of feels like we are pushing the Functions API as it's beginner friendly, but the documentation for that part is definitely not beginner friendly. 

Another thing for me is if you look at a Functions API function in the documentation the left hand sidebar pushes you towards the Variable API, I can see that also get confusing. I think because the Functions API and variable API are essentially the same, I feel like having them all mashed together will get confusing with beginners using a mixture of both in their templates.

 

EDIT:

I just found out that you can't use the Functions API while using files()->render(), so in my _header.php page() returns 

Fatal Error: Uncaught Error: Call to undefined function page() in _header.php:5

I guess it's something to do with scoping. So it's looking for the template _header? I'm unsure exactly. Would this also be the case for rendering fields? Like repeaters etc.

If this is the case, I really can not agree that using Functions API is more beginner friendly. I do like the way it looks but I'm unsure if it's better for beginners at all.

I mean, I'm definitely not a beginner and it's confusing to me.

EDIT 2:

After some research, you have to use $this->page('title') or $this->page()->title which is longer than $page->title. I guess maybe I'll look at a markup region method. Maybe I should be updating my template rendering approach? It would be good if there was a guide of "Best Practice in ProcessWire 2019" or something. At the moment things are lost in blog posts etc. Would be good just to have a new "Starter guide" page that talks about preferred output methods especially when it can cause issues with the functions api. Having looked at markup regions in the past, I just don't know if they are more confusing as it requires a more advanced setup such as editing the config page, but also looking at site-default site profile, the site content is passed through as a variable, which to me just doesn't feel right with more advanced layout websites.

EDIT 3:

Okay, so after some playing around, you can use a traditional approach to the templates using Functional API. files()->render() does not work, however, wireRenderFile() does. I don't have the technical knowledge as to why. But if you use wireRenderFile() you don't have to use $this->page() but page() will work fine. It's definitely a different way at looking at ProcessWire. I'm just keen to keep myself up to date with the latest, lets say 'code style guide' as that's important to me. If we are favouring the Functional API in future, then I'd want to start using it straight away.

EDIT 4:

Sooo.... wireRenderFile() works on the homepage, but not any other page so it seems. Yeah, this is just really confusing for me. It's a shame because I do really like the more shorthand way of writing. I just think it's not as simple as $page as it seems to be causing confusion with rendering files. I've tried every method and here is what I've found. 

Homepage:
Works with wireRenderFile() and use of page(), it also works with files()->render() and the use of $this->page()

Any other page:
Doesn't seem to work with anything, you can use wireRenderFile() or files()->render() with $page but any form of include or render on a non homepage doesn't work with Functions API. 

EDIT 5:

Okay, I haven't gone back and updated the OP, because I would like to document the experience of someone new exploring the Functions API. It appears that any wireRenderFile or files()->render() will work if you define the ProcessWire namespace within the _header.php, I don't know if this is an issue with the TemplateFile compiler. But if you define the namespace at the top of an included file, everything works as intended. 

EDIT 6:

Having played with the Functions API for a while, I think it's definitely cleaner. I think one thing could be improved. So: 

// This is what it looked like
echo $page->featured_post->title;

// Which then becomes
echo page('featured_post')->title;

/*
This feels strange to me because I like $page->featured_post->title as it feels like you're drilling down the array. However page('featured_post')->title feels slightly different. I can't say exactly why, but I feel like the following would be good:
*/
echo page('featured_post.title');

// I also think the same for pages if it's used in GET context, however this may cause confusion as this wouldn't work as a selector. But I guess they will have to know the different anyway.
echo pages(1, 'title');

 

[kongondo]

3 hours ago, Tom. said:

Another thing for me is if you look at a Functions API function in the documentation the left hand sidebar pushes you towards the Variable API,

I noticed this as well and was going to comment about it :-). You are right it currently lacks consistency. When viewing API variables, the sidebar is in context. It should be the same when viewing Functions API.

I also agree with all the other points you've raised @Tom.

@ryan,

Could you please consider reverting the API reference to the single column it used to be? Maybe it's just me, but I am finding the two-column layout confusing. My suggestion would be:

This link: https://processwire.com/api/ref/

leads to a one-column layout page with short summaries of the topics (lack of a better word) in the API reference. Something like:

API Reference

API Variables

These are Lorem ipsum dolor sit amet, consectetur adipiscing elit. An est aliquid, quod te sua sponte delectet? Duo Reges: constructio interrete. Videsne quam sit magna dissensio? Quis est tam dissimile homini. An potest, inquit ille, quicquam esse suavius quam nihil dolere? At hoc in eo M. Si quicquam extra virtutem habeatur in bonis. Et quidem iure fortasse, sed tamen non gravissimum est testimonium multitudinis. Read More... (linking to ..api/ref/api-variables/)

Core Classes

Quippe: habes enim a rhetoribus; At multis se probavit. Quid, quod homines infima fortuna, nulla spe rerum gerendarum, opifices denique delectantur historia? Unum est sine dolore esse, alterum cum voluptate. Quodsi ipsam honestatem undique pertectam atque absolutam. Itaque eos id agere, ut a se dolores, morbos, debilitates repellant. Read More...(linking to ..api/ref/core-classes/)

Functions

Tantum dico, magis fuisse vestrum agere Epicuri diem natalem, quam illius testamento cavere ut ageretur. Homines optimi non intellegunt totam rationem everti, si ita res se habeat. His similes sunt omnes, qui virtuti student levantur vitiis, levantur erroribus, nisi forte censes Ti. Read More...(linking to ..api/ref/functions/)

Etc..

When I land on the API Variables page, all I would see are API Variables stuff, with the contextual sidebar menu  showing API Variables stuff only ($page, $pages, etc). When I land on the Functions page, I would see the Functions stuff with a contextual sidebar showing Functions stuff only.

 

Verbosity

I agree with previous comments about verbosity on this page but since this is a getting started section, maybe it's not too bad. And it's one of those things; some like verbosity, others don't. I know and appreciate it took a lot of time to write this up. Writing documentation is not easy. However, if you take some time away from the writing, step aside and revisit it later, you will see stuff like these jump at you:

Under the section You are always accessing the same exact thing.  The word 'Regardless' is used 5 times :-). 

Quote

Regardless of which way you access an API variable,

but regardless of what shoes you wear, 

Regardless of what shoes you wear, those shoes are still walking the same person

Regardless of which way you access the API variables

This part is always the same, regardless of how

 

What I am saying is that there is room to make this documentation a bit tighter and to the point without losing the audience to curtness/brevity. 

That aside, please consider removing this line:

Quote

You might even come across more but the above are those you are most likely to see at some point.

I think it is leading to more questions without providing answers. For a getting started section, I would expect to at least see a link to 'come across more'. I would ask, what are those more? Why are there more? Where would I come across them?

 

Other Minor Issues

Quote

Each API variable has a unique name to distinguish it from others. For instance, the “pages” (plural) API variable provides access to loading and saving pages, the “page” (singular) API variable provides access to the page being viewed

I'm not sure how the 'pages' plural and 'page' (singular) phrases will work when the site gets translated to other languages. Other languages will not be able to state: plural and singular in the same way. I suggest instead, to highlight or bold the words.  I think it is pretty clear that pages and page are different.

 

There were some other things but I forget. I may revisit this post or post another later ?.

[szabesz]

1 hour ago, kongondo said:

Could you please consider reverting the API reference to the single column it used to be? Maybe it's just me, but I am finding the two-column layout confusing.

Me too, and even in the case of the blog listing and similar. To tell the truth, I never liked the current trend of putting everything into "cards" when a sidebar+vertical listing page is the most usable layout. Cards are stylish but at cost of usability and I think it is a high price to pay, in my designs I try not to use them without a serious and valid reason.

For the time being, I started to browse the site under the 960px viewport by turning on the inspector so that I do not have to resize the whole window. This way I get one column only.

Edited January 21, 2019 by szabesz
typo