ProcessWire Weekly #208

Latest core updates: ProcessWire 3.0.101 introduces a new $sanitizer->truncate() method

In his latest post at the processwire.com blog Ryan talks about ProcessWire 3.0.101, which is now available via the dev branch from GitHub. This version includes a number of minor bugfixes and small improvements, but also one whole new feature: the $sanitizer->truncate() method.

How to truncate text in ProcessWire >= 3.0.101

This new feature started from a feature request made by Adrian, turned into a simple function within Sanitizer, and finally evolved into what we now have in the core: new WireTextTools class, accessible via the $sanitizer->truncate() method.

Here's how Ryan explains the reasoning behind this new feature:

There are a lot of uses for text truncation, but a universally common one in ProcessWire is for generating a short summary from body copy, like for search results, featured pages or the like. Truncated text is not just a shorter copy of a string. Instead, it needs to be smarter than that, making sure to truncate in places that don't break words.

In other words the truncate method is much more than just a wrapper for substr(): it needs to strip unwanted markup while potentially retaining some tags, it needs to take characters, words, and paragraphs into account, and it might have to trim some stuff from the end result – or add something to it. Truncating text is far from simple.

Now, the solution Ryan introduced for us in the form of the truncate method should be able to handle most of the typical cases – and probably plenty of the rare edge cases as well – right out of the box. In order to do that it has to accept various options as well:

// Truncate string to closest word within 150 characters;
// this is the most basic, but also likely the most common usage.
$s = $sanitizer->truncate($str, 150);
// Truncate string to closest sentence within 300 characters
$s = $sanitizer->truncate($str, 300, 'sentence');
// Truncate with options
$s = $sanitizer->truncate($str, [
'type' => 'sentence',
'maxLength' => 300,
'visible' => true,
'keepFormatTags' => true,
'more' => '…'
]);

You can find more about the available options from Ryan's post, but to summarise: this method may seem simple, but it has to do a lot to do its job well. Considering that and the fact that it solves a really common need, it makes a lot of sense to have it built-in within the core.

Other use cases for WireTextTools

Although truncating text is currently the main purpose of WireTextTools, some of the features required by truncation might be quite useful on their own. In order to use them you'll have to get a new instance of WireTextTools, either initiating it yourself or requesting it from $sanitizer->getTextTools(). The methods currently available are markupToText(), fixUnclosedTags(), collapse(), and getVisibleLength().

You can read more about the Sanitizer truncate method, its use cases and available options, and other methods provided by the WireTextTools class from Ryan's post at the processwire.com blog. And in case you have any feedback, feel free to leave a comment to that post. Thanks!

Weekly forum highlights, tutorials, and other online resources

Here's a list of support forum highlights and other useful and/or interesting resources. As always, please let us know if there's anything important we've missed, so that we can include it in one of our future issues.

• First of all, we have a tutorial from Maurizio Bonani for building a protected area to a ProcessWire website. Although the tutorial talks about a basic reserved area, we might add that this is actually a rather in-depth look at the whole topic, so there's definitely a lot to learn from here.
• Our second highlight comes from Jens Martsch: a case story for the P. Jentschura website, titled "How we helped P. Jentschura to increase the conversion rate, win new customers and measure success." This article is currently only available in German, but once again Google Translate does a decent job if you prefer English.
• Although this project could've been one of our site of the week candidates, this time we're posting it here instead: Typografics have set up a fundraiser webshop in order to participate in the 1000km cycle ride against cancer. I'd say that they deserve a ton of credit for both taking part in this event, and for the fundraiser site itself. Definitely go check them out, and if you're based in the Belgium, feel free to order some of their wares as well.
• This one doesn't have much documentation available, but in case you're into all that fancy headless CMS stuff it could be really interesting: a boilerplate profile combining ProcessWire and React. This project is based on an earlier one called ProcessVue, which merged ProcessWire with Vue.js. Seems like a good place to start if you're a ProcessWire user interested in React – or vice versa.
• Our final item for this week is an article by Jeevanism labeled ProcessWire CMS – A review. You can probably guess what this is all about, so if you'd like to hear what others think of ProcessWire, you might want to check this one out as well :)

If you're interested in ProcessWire news, discussions, and updates, there's always something going on at the support forum. Since we're only able to include a tiny selection of all that in our weekly updates, head down to the forum for more.

Module preview: RockFinder

Please note that this module is currently an alpha release. Consider this an early sneak peek: syntax and features are subject to change, and the module should only be used for testing or development purposes. Never install alpha modules on a live website!

RockFinder – formerly known as RockSqlFinder – is a module that Bernhard Baumrock has built and describes as a "highly efficient and flexible SQL finder module". What this means in practice is that the RockFinder module aims to provide an alternative for the built-in page finding in the core, particularly for cases that require extreme speed – or where the number of processed objects could cause vast increase in memory usage.

What RockFinder adds to the mix is support for writing selector queries and specifying the fields you want returned, and then converting all that into raw SQL. You can either use the resulting SQL yourself, or you can ask the RockFinder module to execute it, providing you with the resulting PHP objects.

The module's API has a few advanced options as well, but here's a very simple example of the syntax:

// initiate RockFinder with selector and field names:
$finder = new RockFinder('template=person, limit=5', [
    'first_name',
    'last_name',
]);
// get the resulting SQL:
$sql = $finder->getSQL();
// execute the SQL and iterate over resulting array of objects:
foreach ($finder->getObjects() as $p) {
    // ...
}

You can find more details about the RockFinder module from the RockSqlFinder support forum thread or the RockFinder GitLab repository. While we'd like to stress that this is still in an early development release, if you're interested in seeing how it works for you, go give it a try and let Bernhard know via the support forum how it went. We're sure that he'd appreciate some feedback.

For those who prefer stable and well tested solutions, we'll be sure to keep you posted once this module reaches sufficient level of maturity. Until then, it's better to stick with the built-in core solutions, such as $pages->find() or (in case you're processing large quantities of pages) $pages->findMany().

Big thanks to Bernhard for sharing your work with us. We're eagerly waiting to see this module in a more polished form, so keep up the great work!

Site of the week: Bedrohte Ordnungen – The Threatened Orders research project

Our latest site of the week represents a University of Tübingen research project called Bedrohte Ordnungen, or The Threatened Orders.

The research project focuses on how people and societies deal with – or have in the past dealt with – crises, catastrophes, and other extreme situations. The goal is to figure out what our society can learn from past crises and catastrophes, and the timespan of the study ranges all the way from antiquity to today.

The design and development of the Bedrohte Ordnungen website was a co-project of ED DESIGN and DITHO. The site consists of a detailed introduction to the research project, and twelve research cases in multimedia format. Although the site is for the time being only available in German, an English version is in the works. That being said, this site is already a great resource for non-German speakers who can tolerate the slight quirks of Google Translate.

The content of the site is interesting, well authored, stylishly laid out, and rich in media elements: images, animation, sound, and video. The dynamic front-end fits this site like a glove, and the animations, page transitions, and other effects give it a very compelling look and feel. All in all the whole experience feels less like a regular website, and more like an interactive presentation or exhibition of sorts.

Regarding the behind the scenes stuff, Diogo of ED DESIGN – the developer behind the implementation of the site – has shared a bit of info via the support forum. Based on his post we know, among other things, that this site utilizes a Repeater based content block strategy, and includes two 3rd party modules: AdminOnSteroids and ColorPicker. Though the front-end isn't built with a front-end framework, there are a some smaller dependencies – such as Owl Carousel, Jarallax, and the Plyr media player.

Thanks to the folks at ED DESIGN and DITHO for sharing this site with us, and our congratulations to the client – University of Tübingen – for their newly released, ProcessWire powered website!

Stay tuned for our next issue

That's it for the 208th issue of ProcessWire Weekly. We'll be back with more news, updates, and content Saturday, 12th of May. As always, ProcessWire newsletter subscribers will get our updates a few days later.

Thanks for staying with us, once again. Hope you've had a great and productive week, and don't forget to check out the ProcessWire forums for more interesting topics. Until next week, happy hacking with ProcessWire!