Leaderboard

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 ?

I have mentioned this one before, but I think it's weird that we have a $urls variable, but not a $paths variable. With the functions API we actually have both urls() and paths() which seems like a weird inconsistency to me. Is there a reason for no $paths variable? Even the docs (https://processwire.com/api/ref/functions/paths/) suggest: // basic usage $paths = paths();

You wouldn't ever want to set a formatted value, but for a lot of cases there's no easy way for PW to detect if value X being set to field Y is formatted or not. Think of scenarios where the value being set to a field is some variable that has been built up earlier the dev's code. If the formatted value is a different type of data than the unformatted value (e.g. object vs string) then maybe PW could detect that but there are lots of cases where the formatted and unformatted values are both strings but with one or more textformatters applied to the formatted value. I think we need another nice verbose documentation page explaining output formatting because it's definitely not a simple thing to get one's head around. ?

I might have this wrong, but isn't the important thing that output formatting be off when you get and set values? It's not enough that it simply be off at the moment the page is saved. Doing the following doesn't solve the "problem" of output formatting... $page->foo = $page->bar . ' baz'; $page->of(false); $page->save(); ...and so likewise some feature that automatically turned off output formatting within the save() method wouldn't be a solution either. Output formatting has to be turned off earlier in the process of getting and setting values and PW can't automatically know when to do that, so it has be done manually by the developer. Edit: to clarify regarding getting values - output formatting only needs to be off if you are going use that value in a field you are setting.

Ryan, thanks for the update. It would be great to get an update of "Selectors as regular and associative arrays".

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.

You are getting hit by a variables scope issue. You cannot use global variables like $modules directly inside a function. Instead, use this (there are other variants - see the new docs here) wire('modules');

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.

@ryan - I have been thinking about that save() API example on the homepage and my complaint about the fact that as is it will fail with an error. It has made me wonder why the pages->save() method can't automatically turn off outputformatting itself? So I started looking around and found @thetuningspoon 's excellent thread here: https://processwire.com/talk/topic/10485-simplify-output-formatting-when-saving-pages-via-the-api/ Obviously when saving via the admin, PW takes care of turning off outputformatting, so, I am curious why it can't handle this for us automatically via the API as well. I know you must have a good reason (you always do), but the only thing I can think of is that it's basically an educational thing - it helps users to understand what output formatting is. If so, I agree this is important to understand, but I still don't see why the save method can't do this for us. Thanks for your thoughts on this.

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.

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/

Hey mdp, regarding your questions: The code you pasted will be called whenever any select element (or other input element, for that matter) with the class sort-select. This part is the key: $('.sort-select') That's a jQuery selector, the dot symbolizes a class selector (it mimics CSS selectors). If you want to do the same thing for an element with an id, use a pound sign instead instead: // select the element with id 'sort-select' $('#sort-select') // select any element that has either the class or the id 'sort-select' $('.sort-select, #sort-select') A cleaner, native way to handle this are GET-parameters in the url. First, you need to include a submit button in the form: <form id="sort-select" method="get"> <select name="sort"> <option value="-likes">Sort by: # Recommendations</option> <option selected value="title">Sort by: Title (A-Z)</option> <option value="-title">Sort by: Title (Z-A)</option> <!-- ... --> </select> <input type="submit" value="Submit"> </form> Just a side-note, your HTML attribute values should be encased by quotes. Also, the options need closing tags to be valid HTML5. I also removed the onchange attribute, though you can keep it in if you want to automatically trigger the submit. This is actually all that is needed! Since the form doesn't have an action attribute, it will go to the same page the form is on. The selected sort-option will be included in the targeted URL as a GET-parameter, where it can be picked up by PHP to generate the results listing. The onchange-attribute does the same thing, it basically auto-submits the form whenever you change the value of the select input (the code in the skyscraper.js file does the same thing, by the way). However, by including the submit-button, you make the entire form more accessible and ensure it will even work if JavaScript is disabled.

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.

This code in the ckeditor custom settings activates the browsers native spellchecker (we use the languagetool plugin for Firefox/Chrome): disableNativeSpellChecker:false

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.

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?

Check out the PLUs (Page Lister URLs) module. Or if you want to go the hook route try manipulating the defaultSelector property of the Lister: $wire->addHookBefore('ProcessPageLister::execute', function(HookEvent $event) { // Only for the initial load, not for subsequent user changes if($event->config->ajax) return; $lister = $event->object; // Do something here to identify if this is the lister you want to modify and return early if not // Then manipulate the defaultSelector property... // E.g. append to the existing defaultSelector $lister->defaultSelector .= ', your_field=your_value'; });

This is actually most likely a problem with allowPath() method in WireFileTools.php, introduced in an attempt to fix some issues with temp directory (if I remember correctly). All backslashes are replaced with forward slashes so your UNC notation \\host-name\share-name\file_path becomes //host-name/share-name/file_path. Double forward slashes are recognized as URL or some extra slashes, and an exception is thrown. The solution would be not to use UNC notation but rather map a drive to your share and use a drive letter.

Perhaps you need to check $item->template->hasField('id') instead.

True. Although the code suggested in the message would still resolve the issue so long as you haven't overwritten $page. If things go in the direction that I think Ryan has hinted at of the Functions API being the new default approach then maybe we'll see message references to API variables start switching over to the Functions API equivalents.

Of course, but even if you haven't overwritten $page, if you are using page() and you get a message to do $page->of(false) it is still confusing.

It's sort of breaking a cardinal rule in the first line though. If people overwrite core API variables then confusing error messages would be just the beginning of their troubles. ?

Wow, yeah i didn't know $mail was a global variable... I updated the readme a bit; i think a lot if people might be overriding the global mail, because using the examples on this; So we should show both versions; they both seem to work the same. I commented out the public send();

On mobile right now, but try Adrian's modulesettingsimportexport module. It allows you to export/import module settings. Works great for me.

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

Hey @adrian, it is possible to export a panel's infos or a global diagnostic to a text file in the goal to compare for example, two site-dumps with a diff tool or even a text editor ? I mean, at this moment I am comparing load as others speed load informations of a big site between the prod and dev server - switching my browser tabs to do comparisons - and so I was thinking that I would like to generate/export a TracyDebugger report with all the diagnostics to be able to easily compare them on my computer. If this feature is implemented, please tell where to find it, I can't see it ☺️

Here is a more sophisticated version if you have a large number of siblings and don't want to include all of them in the pager navigation. <?php // Limit for number of sibling links $limit = 9; // Get the number of visible siblings $num_siblings = $page->parent->numChildren(true); // The default start value is zero $start = 0; // If the number of siblings is greater than the limit then we need to adjust the start value if($num_siblings > $limit) { // Get the halfway point of the limit $half_limit = floor($limit / 2); // Get the index of the current page relative to its siblings $index = $page->index(); // Adjust the start value to keep the current page within the sibling links if($index > $half_limit) $start = $index - $half_limit; if($num_siblings - $start < $limit) $start = $num_siblings - $limit; } $items = $page->siblings("start=$start, limit=$limit"); // Next page and previous page relative to current page $next_page = $page->next(); $prev_page = $page->prev(); ?> <?php if($items->count > 1): ?> <ul> <?php if($prev_page->id): ?> <li><a href="<?= $prev_page->url ?>">Previous</a></li> <?php endif; ?> <?php if($start > 0): ?> <li>&hellip;</li> <?php endif; ?> <?php foreach($items as $item): ?> <li class="<?= $page === $item ? 'current' : '' ?>"><a href="<?= $item->url ?>"><?= $item->index() + 1 ?></a></li> <?php endforeach; ?> <?php if($num_siblings > $start + $limit): ?> <li>&hellip;</li> <?php endif; ?> <?php if($next_page->id): ?> <li><a href="<?= $next_page->url ?>">Next</a></li> <?php endif; ?> </ul> <?php endif; ?>

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):

This is great life advice!

That's not how MarkupPagerNav works. The MarkupPageNav module is useful when you want to stay on one page which is listing summaries from a PageArray of other pages. The pagination is for those summaries, so if with no limit applied a selector would return a PageArray of 20 pages and you wanted to show 4 summaries per page (limit=4) on some overview page then MarkupPagerNav would create 5 links. But you always stay on the overview page - the links in the pager don't take you to the individual pages that the summaries are for. So technically you could create a pager on the Table on Contents page, using a PageArray of child pages with a limit of 1, and then output the whole content of the child page in your foreach loop. But instead I think you want visitors to actually visit those child pages, not just stay on the Table of Contents page. So what you want is a normal menu for the pages in your PageArray. You can create this any way that you like to create menus in your site, but here is an example: <?php $items = $page->siblings(); $next_page = $page->next(); $prev_page = $page->prev(); ?> <!-- Add whatever classes or extra markup you need to this unordered list --> <?php if($items->count > 1): ?> <ul> <?php if($prev_page->id): ?> <li><a href="<?= $prev_page->url ?>">Previous</a></li> <?php endif; ?> <?php foreach($items as $key => $item): ?> <li class="<?= $page === $item ? 'current' : '' ?>"><a href="<?= $item->url ?>"><?= $key + 1 ?></a></li> <?php endforeach; ?> <?php if($next_page->id): ?> <li><a href="<?= $next_page->url ?>">Next</a></li> <?php endif; ?> </ul> <?php endif; ?>

I don't think RF changes any lower/uppercase. Quickly googling for "case sensitivity table mysql" returns tons of results though, suggesting it may have to do with how mySQL handles case-sensitivity on different OS... just one random example: https://searchdatacenter.techtarget.com/answer/Naming-and-renaming-MySQL-files-for-case-sensitivity

Correction to this: in the blog post Ryan mentions the wire-prefixed Functions API methods and explains that they have the benefit of being always available regardless of config settings (essentially the same thing that the comments in the FunctionsWireAPI.php file say) – but there is a comment to the blog post in which he mentions that these are actually "for an internal core purpose". @ryan, this might be one of the things that should be clarified somewhere: if wire-versions of the Functions API methods are indeed not intended for public use, it should probably be mentioned somewhere (other than a single comment to the Functions API announcement blog post). If one reads the blog post and doesn't check all the comments, or checks the code / code comments directly (which is a common thing to do in our context), this is currently not obvious.

OT, but though to mention it here. I have been working on a site profile (still in alpha >>> it's been ages! other things got in the way) inspired by the Electron API Demos app that will do this and more. Essentially, it teaches you to use the API. On install, you get nothing but the 'blank profile'. You choose a topic and It teaches how to accomplish what is covered in that topic, e.g. the AP to create/edit/delete fields, templates, pages, etc.

Quick Actions Utility Actions Shortcut Actions Tracy Shortcuts Utilities