Selectors
Last updated
Last updated
Selectors are a powerful tool, allowing you to select multiple items within your project based on the information stored in their fields.
In Kumu, you can always select items using your mouse and keyboard:
Clicking one element, connection, or loop to select it
Hold the shift key and click to select multiple items
Hold the shift key, then click-and-drag to select a group of items
Once you have an active selection, you can do all sorts of things: decorate your selection, change field values for your selection, focus on your selection, etc. Long story short, selections are extremely useful in Kumu!
But what if you need to select a large group of items that are densely interconnected with other items that you don't want to select? You can't hold shift & click-and-drag, because you'll select some unwanted items in that area. You could hold shift and click on each individual item, but that could take a reaaally long time for bigger maps.
The solution: selectors!
Think of selectors as a super-powered mouse & keyboard—they allow you to click on a lot of elements, connections, and loops extremely quickly and with perfect precision. Learning how to recognize, read, and write selectors will definitely come in handy when you're working in Kumu.
Check out the overview video below to learn the basics of selectors, then read through the rest of this guide for detailed instructions.
Before you start: use fields to add additional information to your elements, connections, and loops.
You can use selectors in the search bar on your map to select multiple items.
If you'd rather write your selector instead of use the selector builder, just type an equal sign = in the search bar, then write your selector. Press enter on your keyboard to select all items that match your selector.
There are several places in the Basic Editor where you can use selectors:
The Connect By tool and decoration builder allow you to use the same selector builder from the search bar, and the filter and showcase tools allow you to either use the selector builder or write your own selector.
The Advanced Editor is where selectors really shine. Advanced decorations, filters, focuses, controls—you name it! Almost every block of code in the Advanced Editor contains some sort of selector.
In all of the guides on this documentation site, keep an eye out for Advanced Editor instructions—they'll teach you how to use selectors to enhance all of Kumu's most powerful tools.
In this section, we'll teach you how to write all kinds of selectors, which fall into these categories:
We'll also teach you how to chain selectors together to run complex queries involving AND and OR logic.
After you read this section, check out our selector reference—it's a great cheat sheet for every possible selector in Kumu.
You can also use our experimental selector builder interface to write selectors for you!
All shorthand selectors use slugs—pieces of text that have had all letters converted to lowercase, all special characters removed, and all spaces and replaced with hyphens. To learn more about recognizing, reading, and writing slugs, check out our full guide on slugs.
The universal selector is just an asterisk *, and it matches all elements, connections, and loops—everything on the map!
Selecting all elements, connections, or loops is simple:
Selecting all of a specific type is pretty simple too. For elements, just take the element type and turn it into a slug. For connections, turn the connection type into a slug and add -connection.
Selecting specific items by label is—you guessed it—pretty simple! Just turn the item's label into a slug, then add # in front of it:
In Kumu, you might sometimes assign custom, unique IDs—see our guide on avoiding duplicates for more info on when and why you would want to do this.
If you have custom IDs in your project, you can use those IDs in shorthand selectors. The syntax is the exact same as the label selector: create a slug of the ID, then add # in front of it:
Behind the scenes, Kumu assigns a unique ID to each element, connection, and loop, as soon as you create the items. We call this a "system ID", and you can use this in shorthand selectors, too!
System IDs are created as slugs by default, so to turn turn them into selectors, all you need to do is add a # in front:
System IDs are guaranteed to be unique and permanent.
To select by tag, simply turn the tag into a slug, then add a . to the front of it:
The presence/absence selector allows you to select items based on whether they have any value or no values in a given field. To select by presence (any value in the field), turn the field name into a slug, and put it inside of square brackets:
To select by absence (no values in the field), just follow the same steps, but put a ! in front of the field name's slug:
While the shorthand selectors are great for many cases, they're only supported for the fields and selections described above. For all other fields, or for more complex selections, you can use longhand selectors. Longhand selectors have three parts:
Field name
Operator
Field value
And the syntax is as follows:
Replace field name and field value with a name and value from your project, depending on what you are trying to select, and keep them wrapped in "" double quotes. field name and field value are not case-sensitive in selectors.
Then, replace operator with a logical operator recognized by Kumu, for example, = (equal to) or > (greater than). You can see the full list of operators and their meanings in the selector reference.
Here are some examples:
When using the Type field in longhand selectors, you need to specify whether it is Element Type, Connection Type, or Loop Type. For example, use "connection type" instead of just "type" when selecting by connection type.
Here are a few more examples, using relative operators (greater-than, less-than, greater-than-or-equal-to, and less-than-or-equal-to):
Note also that these examples use team-members as the field name, instead of "Team Members". This works just fine, because you're allowed to use the slug of field-name instead of using "field name" wrapped in the double quotes. It's up to you!
You can also use relative operators with the built-in created and updated fields to select items by when they were created or most recently updated in Kumu:
Pseudo-selectors allow you to select elements, connections, and loops based on information stored outside of their profiles—for example, in the profile of an adjacent element, or in the focus settings of your view.
With the :from and :to pseudo-selectors, you can select connections based on the elements those connections are attached to. The basic syntax is :from(selector) and :to(selector).
To build your own, just replace selector with any valid selector. For example:
Use the :directed, :undirected, and :mutual pseudo-selectors to select connections based on their direction.
When you click and hold on an element, you'll apply the focus effect to your map. The element you clicked will be the root of the focus, and the focus will extend a certain distance away from the root.
You can also select multiple elements or connections before you apply the focus effect. In that case, all the elements and connections you selected will be considered focus roots.
Use the :focus selector to select your focus root(s).
In graphs and networks, an element that has zero connections is often referred to as an orphan. In Kumu, you can use the :orphan pseudo-selector to select all the orphans on your map.
If you're using loops in your map, you can use the :loop pseudo-selector to select elements and connections that are part of a specific loop or loops.
The syntax is an element or connection selector with :loop() at the end of it. You can also put a loop selector inside the parentheses to specify the loop or loops.
The :not pseudo-selector is useful when you want to select items that do not match a selector. The basic syntax is :not(selector).
To build your own, just replace selector with any valid selector. For example:
Traversals allow you to select elements based on the structure of your map. For example, you can select elements based on:
Which other elements they are connected to or from
The information stored in connection's profiles (including connection direction)
The basic syntax is selector arrow selector. You'll replace the first and last selector with any valid selector (including another traversal), and you'll replace arrow with one of the following options:
-->
Connected to
<--
Connected from
<-->
Connected to or from
Here are some examples:
You can also add any valid connection selector inside of the arrow to specify exactly which connections are allowed:
When you add connection selectors in the middle, be sure to put two dashes on the outside:
If you're writing a shorthand selector for connection type, for example, strong-connection, you can omit the -connection. Taking the example from above:
The selectors we've covered so far are building blocks. You can combine those building blocks to create complex queries involving AND and OR logic—this action is called chaining selectors.
AND
Only items that match all selectors in the chain will be selected
Write selectors back-to-back, with no white space or punctuation in between
OR
Items that match any selector in the chain will be selected
Join selectors with a comma
Here are some examples of selectors chained in different ways:
In the upper left of the map, click "Search" next to the search icon to start searching. Then, click the rocket icon on the far right to bring up the selector builder, and use it to build out your selector.
