PW 3.0.240 – Core updates

[ryan]

The core dev branch version has been bumped up to 3.0.240 this week. As always, see @teppo's excellent ProcessWire Weekly for details on what has been added recently. More can also be found in the commit log. This week adds the ability to hook into ProcessWire's admin live search to add your own custom results. This is useful for modules or for your own hooks placed in /site/templates/admin.php. Previously, only modules implementing the SearchableModule interface could manipulate the admin search engine results. Now there's another even simpler way to do it. We'll focus on examples placed in /site/templates/admin.php, but they could also go in /site/ready.php, /site/init.php or in an autoload module's init() or ready() method. 

The following is a simple example for when one types "today" into the search engine, it returns search results of pages that were modified today. 

$wire->addHook('ProcessPageSearchLive::findCustom', function(HookEvent $event) {
  $data = $event->arguments(0); // array 
  $search = $event->object; // ProcesPageSearchLive 
  $group = 'Pages modified today'; // description of this type of search
  if($data['q'] === 'today') {
    $items = $event->wire()->pages->find("modified>=today, include=unpublished"); 
    foreach($items as $item) {
        $search->addResult($group, $item->title, $item->editUrl); 
    }
  }
}); 

The point of that example is just to demonstrate something simple. In reality, that example isn't that useful because you can already type "modified>=today" to get the same results in the search engine. So let's look at a potentially more useful example. 

There have recently been requests for better "id" search support in the search engine. In this next example, we add support for "id=123" searches, where it will match templates, fields or pages having id "123" (or whatever ID you specify). Further, it will also support it if you just type "123" on its own. Here's how we might accomplish that below. We'll limit this particular type of search to the superuser since this hook doesn't have any access control checking. 

if($user->isSuperuser()) {
  $wire->addHook('ProcessPageSearchLive::findCustom', function(HookEvent $e) {    
    $search = $e->object; /** @var ProcessPageSearchLive $search */
    $data = $e->arguments(0); /** @var array $data Search data */
    $type = $data['type']; // what to search
    $q = $data['q']; // search query text

    // support search of "id=123" or just "123"
    // skip search if not an "id" search, or query is not a number
    if(($type != 'id' && !empty($type)) || !ctype_digit($q)) return;
    
    // reduce default search operator "%=" to just "=" (if used)
    $operator = trim($data['operator'], '%'); 
  
    // search for id in templates, fields and pages
    foreach(['templates', 'fields', 'pages' ] as $apiVarName) {
      $apiVar = $e->wire($apiVarName); // get API var
      $selector = "id$operator$q"; // selector i.e. id=123 or id<10, etc.

      // some additional considerations for page ID searches
      if($apiVarName === 'pages') {
        // PW already handles "id=123" for pages, so skip that kind
        if($type === 'id' && $operator === '=') continue; 
        // add more to selector for page searches
        $selector .= ", include=all, limit=$data[limit], start=$data[start]";
      }
    
      // find by selector
      $items = $apiVar->find($selector);
    
      // tell ProcessPageSearch which results we found
      foreach($items as $item) {
        $title = $item->get('title|label|name'); 
        $url = $item->editUrl();
        $search->addResult($apiVarName, $title, $url);
      }
      // optionally return false to tell it to stop searching after this hook
      // which would prevent the default behavior of the search engine
      // $e->return = false;
    }  
  });
}

As you may (or not) know, the search engine displays help if you type the word "help". Help for the search engine usually consists of example searches and descriptions of what those examples do. If we want to add some help for our example above, we could add this to to the top of our hook above, perhaps right after the $data = $e->arguments(0); line:

if(!empty($data['help'])) {
  return $search->addHelp('ID Search Help', [
    'id=1234' => 'Find templates, fields, pages with id 1234', 
    '1234' => 'Same as above but “id=” is optional', 
  ]);
}

That's the gist of it. These are fairly basic examples but hopefully communicate enough to show that you can add any kind of results you want into the search engine. Right now it's pretty simple and enables anyone with a ProcessWire site to add custom results into the admin live search. But if you find your needs go beyond this, the SearchableModule interface does support more options too. It's also worth using TracyDebugger to examine the $data array that the hook receives, as there are several other things in there you may find useful as well. Thanks for reading and have a great weekend!
 

[wbmnfktr]

4 hours ago, ryan said:

As you may (or not) know, the search engine displays help if you type the word "help".

That really works. I didn't know that. Not at all.

 

TIL: something new, again.

Have a great weekend @ryan and everyone that is reading this.

[FireWire]

4 hours ago, ryan said:

As you may (or not) know, the search engine displays help if you type the word "help"

🤯 <- me, pretty much all the time with ProcessWire.

Fantastic stuff. Thanks as always, and happy Friday everyone!

[wbmnfktr]

5 minutes ago, FireWire said:

🤯 <- me, pretty much all the time with ProcessWire.

Fantastic stuff. Thanks as always, and happy Friday everyone!

Imagine we could clone @ryan. (super villain laughing in the background)

 

[Jan Romero]

Mind blown. I wish I had known this years ago 😄