How to Create a Custom Views Argument Plugin in Drupal

When you're building a site, it's standard to set up "pretty URLs". For example, we'd rather see /catalog/accessories than /taxonomy/term/18 and we'd rather see /about-us than /node/19. With Drupal, we use the Pathauto module to configure these types of standard content paths. But in some cases, there's no option to create a nice URL pattern, so we end up seeing those URLs.

This happens with Views that are filtered by a taxonomy term in the URL. The result is that you end up seeing taxonomy term IDs in the URL (e.g. catalog/19/search) rather than a pretty URL (e.g. catalog/accessories/search).

In this tutorial, I'll walk you through how to create a field that is used to make generate URLs for Views pages that take taxonomy terms as contextual arguments. Using this approach, a site editor will be able to configure what the URL path will look like.

Assumptions

It has been assumed that you know:

The basic concepts of Drupal.
How to configure fields.
How to configure a view with a contextual filter.
How to create a custom module in Drupal.
How to create a custom plugin in Drupal.

The solution

We're going to use the core taxonomy argument plugin (Drupal\taxonomy\Plugin\views\argument\Taxonomy) to help us fix this problem. The plugin takes a term ID from the URL and passes it to Views. We'll override the plugin so that it takes a string from the URL (slug), and then looks up the associated term ID. All the rest of the functionality we'll leave as is.

Step 1: Content and field configuration

To make the example work, we need the following configuration to be in place (most of this you get out-of-the-box with Drupal, you'll just need to add the Slug field):

A taxonomy vocabulary named tags.
Tags should have the following field:
- Field name: Slug
- Machine name: field_slug
- Type: Text (Plain)
- Size: 32 characters
A content type named article.
Article should have the following field:
- Field name: Tags
- Machine name: field_tags
- Type: Entity reference (to taxonomy terms from Tags)
- Number of values: At least one

Step 2: Create a custom module

Create a custom module called custom_views_argument. Declare a dependency on the views module in the .info.yml file.

Step 3: Implement hook_views_data_alter()

Reference: custom_views_argument.module

The hook_views_data_alter() hook tells Views about the various database tables, fields and the relevant plugins associated to them. We implement this hook to tell Drupal to include our custom argument plugin which we will create in the next step.

Step 4: Create a custom views argument plugin

Reference: CustomTaxonomySlug.php

Next we implement the CustomTaxonomySlug class with a proper annotation @ViewsArgument("custom_taxonomy_slug"). This tells the Views module that the class is a special class which implements a custom Views argument plugin. We extend the Drupal\taxonomy\Plugin\views\argument\Taxonomy class and override one important method CustomTaxonomySlug::setArgument().

public function setArgument($arg) {
  // If we are not dealing with the exception argument, example "all".
  if ($this->isException($arg)) {
    return parent::setArgument($arg);
  }
  // Convert slug to taxonomy term ID.
  $tid = is_numeric($arg)
    ? $arg : $this->convertSlugToTid($arg);
  $this->argument = (int) $tid;
  return $this->validateArgument($tid);
}

All we do here is catch the argument from the URL and if it is a slug, we use a convertSlugToTid() method to retrieve the underlying taxonomy term ID. That is it! The rest of the things are handled by the taxonomy plugin.

Step 5: Create Demo Content

Now that everything is in place, we'll put our solution to the test. Start by creating some demo content. Create 2-3 articles and assign them some tags. The tags are created, however, they don't have a slug.

Once done, go to the Admin > Structure > Taxonomy > Tags page and edit the tags and give them nice URL slugs containing only English alphabet letters, numbers and dashes. For real projects, you might need to use a custom or contrib module to automatically generate slugs (see the machine_name module).

Step 6: Configure a View

Now we're all set! The last step is to create and configure a View which will put everything together.

Create a View of Content. You can name it Blog.
Create a page display and set it's URL to /blog/%.
Add a relationship to taxonomy terms referenced from field_tags.
- We do this to be able to use the Slug field in a filter.

Configure a relationship with taxonomy terms

Now, define a contextual filter for the Slug using the custom argument plugin which we created.
- Click on the Add button for Contextual filters
- Choose the Slug filter which we created. It should have the name we had defined in our plugin, i.e. Custom: Has taxonomy term with slug.
- Optionally, specify a validation criteria for Taxonomy Term and specify the Tags vocabulary.

Configuring the custom views argument plugin for contextual filters

Save the view for the new configuration to take effect.

And we're done! If you visit the /blog/SLUG, you should see all the articles which have the taxonomy term associated to SLUG. Here, SLUG refers to the value you put in the Slug field for the tag. E.g. if you have a tag named Accessories and you wrote accessories in the Slug field, you should go the the URL /blog/accessories.

Next steps

See the code for the custom views argument plugin on GitHub.
Read more about hook_views_data() and hook_views_data_alter().
Read more about the Plugin API in Drupal.

If you're looking for hands-on training about how to develop Drupal modules, we offer professional Drupal training online and in-person. See the full Drupal Module Development training curriculum for details.

Blog