Repository files navigation

Adds taxonomy filtering and aggregation support toWPGraphQL.

• WPGraphQL Filter Query
  • WPGraphQL limitation
    • Solution
  • What are Filters (and Aggregates)
    • Use Case Example
  • Querying with Filters
  • Advanced Queries
    • Multiple Comparison Operators on one Taxonomy
    • Multiple Relation Operators on Multiple Taxonomies
    • Nesting Relation Operators on Multiple Taxonomies
  • Readable Filter Queries
  • Dependencies
  • Install and Activate
  • Contributing
    • Requirements
    • Getting Started
    • Testing
    • Linting
    • VSCode

The introduction of WPGraphQL helped make access to WordPress headless data even easier than via REST, but there are still some areas and use-cases that are outside that repository’s existing focus or scope. From interfacing with the WPGraphQL team it was noted that there was a community desire for a query filter argument implementation to extend the existing plugin, which could support scenarios such as thetaxQuery candidatehere.

In collaboration with the WPGraphQL team we built this plugin to:

• Add afilter WPGraphQL input argument connection, for all Post types, which supports the passing of multiple Taxonomies for refinement.
• Add anaggregation field connection, available in the body of all Post types, which can return a sum of the names of each Taxonomy that occurs, and a count of the number of occurrences of each, in each query response.

Filters allow the limiting of Post results byTaxonomy fields & values. Aggregates give a summary of such Taxonomies available to a given query - based on a sum of the resulting Posts associated Taxonomies. So, if one queried all Posts onfood (this would need to be the name of a related Taxonomy here) from a Lifestyle blog, one might expect to receive all food-related Posts, plus the sum of all Taxonomies that occurred within the Posts' results - such assweet orsavory, but probably nothome decor oryoga (unless a topic related to bothfood andyoga perhaps).

Broadly speaking, WordPress Taxonomies have two default types:Categories & Tags.Categories are more of a grouping mechanism, which supports hierarchy and siblings (animal-> feline-> tiger, lion, cat), whereasTags are more for additional shared information (green, heavy, out-of-stock). This plugin supports both of these Taxomonies within both Filters and Aggregates.

Using an example of a fictionalSample Clothing Store WordPress site we can further illustrate the use of filters. Here, the products are separated into 4, sometimes overlapping, Categories:Sport,Formal,Footwear andAccessories - there will be no inheritance Categories in this simple example, but some sibling Categories. There are 6 possible Tags also available, for further information on and grouping of the stock, and for shared traits:Keep Warm,Keep Cool,Waterproof,On Sale,Cushioning, andGym. The 12 products are shown in the image below - 4 in each Category, but one can seeLeather Shoes shares both Formal and Footwear Categories, whileGym Trainers shares both Sport and Footwear Categories. The blue numbers below each product show their associated Tags.

Now, if we pictured this sample store having its own website frontend (reading from our WordPress Headless WPGraphQL) which could display all of the products, and allow filtering by the Categories and Tags e.g.query #1 image.

In this query the customer has visited perhaps aFeatured Sportswear & Footwear section, from one of the website’s homepage links, which automatically filter-queried the products by the given Categories ofSport & Footwear, while also returning the Aggregations of still-applicable Taxonomies (by name & occurrence count).

From this filter-by-category view the customer could then further refine what products they are interested in, by selecting only certain Tags from the Aggregated Tags returned (which was all 6 in this example). Next, in thequery #1 image below, one can see some of the Tag boxes being checked so that, byquery #2, we can see the products returned from the filter-by-category-and-tag query have gone from 6 (Gym T-shirt, Hoodie, Sweat Pants, Leather Shoes, Sandals, Gym Trainers) to 4 (Gym T-shirt, Sweat Pants, Sandals, Gym Trainers) in number.

We can see in both query results that:

• Of the 6 Products returned inquery #1, there were occurrences of all 6 Tags with a sum of 15 instances (again, the aggregate/ sum of Tags, by name & counts).
• Byquery #2, even though we specified 2 tags to filter by, the 4 Products returned contained a total of 4 associated Tags (each had both specified & unspecified Tags) and 12 instances.

This above example uses, by default, anand relationship between the specified Taxonomies, but this plugin supports bothAND plusOR relationships within its filters - these are therelation operators. In this example a multiple-equality ‘in’ ‘comparison’ operator is used as the comparison for filtering, but this plugin supports all of the following comparison operators:eq,notEq,like,notLike,in,notIn.

Given theSimple Clothing Store website above, we can start seeing how one would go about benefiting from filter queries inquery #1 and #2. To replicate the backend needed to supply such frontend functionality we must first create a WP instance withWPGraphQL & ourWPGraphQL Filter Query plugins installed and activated. Then we need to clear any default data and add the 4 Categories, 6 Tags, and 12 Products (as Posts) from our earlier data, and establish the specified relationships between our Products, Tags and Categories. Once this is done one can begin querying the data via WPGraphQL’s inbuilt GraphiQL IDE (a familiarity with this is assumed).

Thequery #1 should look roughly like this, with Filter by Category:

queryQuery1 {posts(filter: {category: {name: {in: ["Sport","Footwear"] } } }) {nodes {title    }aggregations {tags {keycount      }categories {keycount      }    }  }}

Query #2 builds on 1, with the addition of selected (UI-checked) Tags to Filter.

When we add Tags to the filter an implicit Relation Operator ofand is applied between the Category and the Tag objects -if (Category-match && Tag-match) return Post(s).

queryQuery2 {posts(filter: {category: {name: {in: ["Sport","Footwear"] } }tag: {name: {in: ["On Sale","Gym"] } }    }  ) {nodes {title    }aggregations {tags {keycount      }categories {keycount      }    }  }}

If thequery #2 was taken a step further to perhaps exclude theGym Tag, we could see onlySandals would make a return asOn Sale. This is the lowest level of chaining operators, and the relation operator for these will always beand. We also see a new Comparison Operator, coupled with the previous one:notEq:

queryProductsByFilterNotEqGym {posts(filter: {category: {name: {in: ["Sport","Footwear"] } }tag: {name: {in: ["On Sale","Gym"],notEq:"Gym" } }    }  ) {nodes {title    }aggregations {tags {keycount      }categories {keycount      }    }  }}

This plugin supports 4 root filter query arguments presently:

• 2 Taxonomies: ‘Tag’ & ‘Category’ (Covered already)
• 2 Relation Operators:or &and
  • These cannot appear as siblings, so use one or neither, per nested object
  • These accept an array of root filter query objects (so, each object of array itself can have Taxonomies, or/and Relation Operators, recursively)
  • Nested filter query objects can be nested up to 10 times presently

Givenquery #2 as a starting point, we could separate the two Tags to be searched into their own filter query object, inside anor Relation Operator and get the same result (Also switched the Comparison Operator here toeq, vsin as there was only one Tag comparison made in each object now):

queryProductsByFilterOROperator {posts(filter: {category: {name: {in: ["Sport","Footwear"] } }or: [        {tag: {name: {eq:"On Sale" } } }        {tag: {name: {eq:"Gym" } } }      ]    }  ) {nodes {title    }aggregations {tags {keycount      }categories {keycount      }    }  }}

If we simply swap the Relation Operator toand now on this previous query our results now must contain both Tag Comparison Operator matches, rather than either or. This eliminatesSandals, which only had theOn Sale Tag, but not theGym one.

queryProductsByFilterANDOperator {posts(filter: {category: {name: {in: ["Sport","Footwear"] } }and: [        {tag: {name: {eq:"On Sale" } } }        {tag: {name: {eq:"Gym" } } }      ]    }  ) {nodes {title    }aggregations {tags {keycount      }categories {keycount      }    }  }}

Using the relation operators are powerful, and were made to be siblings of Taxonomies, but, for greatest clarity do not reply on the implicitand relation of siblings at filter query level. As mentioned, nesting of queries is available via relation operators, up to a depth of 10, but this may be somewhat unreadable, like nested callbacks.

In order to use WPGraphQL Filter Query, you must haveWPGraphQL installed and activated.

WPGraphQL Filter Query is not currently available on the WordPress.org repository, so you mustdownload it from Github.

Learn more about installing WordPress plugins from a Zip file.

• Docker

To get started with the dev environment run

make

make test

make lint

Install the following plugins to gain formatting and lint errors showing up in the editor