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
shiftkey and click to select multiple items - Hold the
shiftkey, 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.
<iframe src="https://player.vimeo.com/video/171843678" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>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.
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.
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.
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!
* // select everything
Selecting all elements, connections, or loops is simple:
element // select all elements
connection // select all connections
loop // select all loops
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.
person // select all elements with "Person" element type
future-project // select all elements with "Future Project" element type
personal-connection // select all connections with "Personal" connection type
business-connection // select all connections with "Business" connection type
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:
#jeff-mohr // select element "Jeff Mohr"
#thinking-in-systems // select element "Thinking in Systems"
#b1 // select loop "B1"
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:
#project-1234 // select the item with id "project-1234"
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:
elem-1h04vQRH // select the element with the system id "elem-1h04vQRH"
conn-9Gp2zuYg // select the connection with the system id "conn-9Gp2zuYg"
loop-mt57r8Gb // select the loop with the system id "loop-mt57r8Gb"
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:
.mission-critical // select anything tagged with "Mission Critical"
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:
[element-type] // select any item with anything in the "element type" field
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:
[!element-type] // select any item (including connections and loops) with no value in the "element type" field
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:
["field name" operator "field value"]
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:
["element type" = "person"] // select all items whose element type equals "Person"
["description" *= "kumu"] // select all items whose description text contains "kumu"
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):
[team-members < 20] // select all items that have a number less than 20 in the Team Members field
[team-members > 20] // select all items that have a number greater than 20 in the Team Members field
[team-members <= 20] // select all items that have a number less than or equal to 20 in the Team Members field
[team-members >= 20] // select all items that have a number greater than or equal to 20 in the Team Members field
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:
[created > 2017] // select all items that were created after the year 2017
[updated < 2017-10-01] // select all items that were updated before October 1, 2017
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:
:from(organization) // select all connections that are coming from elements with type “organization”
:to(#my-element) // select all connections pointing to an element with the label "My Element"
Use the :directed, :undirected, and :mutual pseudo-selectors to select connections based on their direction.
:directed // select all directed connections
:undirected // select all undirected connections
:mutual // select all mutual connections
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).
:focus // select all focus roots
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.
:orphan // select all orphaned elements
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:
:not(organization) // select any item that doesn't have the element type "Organization"
:not(:orphan) // select any item that is not an orphan, i.e. any item that has 1 or more connections
:not([tags ~= "blue"]) // select any item whose Tags field does not include the tag "blue"
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)
<iframe width="560" height="315" src="https://www.youtube.com/embed/tw7Q-Kuzo8g" frameborder="0" allowfullscreen></iframe>
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:
| Arrow | Meaning |
|---|---|
-->
| Connected to |
<--
| Connected from |
<-->
| Connected to or from |
Here are some examples:
person --> organization // Select all elements with the type "Person" that are connected to elements with the type "Organization"
person <-- organization // Select all people that are connected from organizations
person.democrat <--> person.republican // Select all people tagged as Democrats who are connected to or from a person tagged as Republican
You can also add any valid connection selector inside of the arrow to specify exactly which connections are allowed:
person.democrat --[strength > 5]--> person.republican // Select all people tagged as Democrats who are connected to a person tagged as Republican, via a a connection whose strength is greater than 5
When you add connection selectors in the middle, be sure to put two dashes on the outside:
/* Two dashes, then a connection selector, then two more dashes. */
--strong-connection--> // Connected to, via a connection with the type Strong
<--weak-connection-- // Connected to, via a connection with the type Weak
<--connection--> // Connected to or from, via any connection
If you're writing a shorthand selector for connection type, for example, strong-connection, you can omit the -connection. Taking the example from above:
// These two selectors select the exact same thing
person.democrat --strong--> person.republican
person.democrat --strong-connection--> person.republican
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.
| Logic | Description | How to use in Kumu |
|---|---|---|
| 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:
person[description] // select all items with the element type "Person" AND any value in the Description field
organization, person, project // select all elements with the element type "Organization" OR "Person" OR "Project"
woman.young.influential // select all elements with the type "Woman" AND the tags "Young" AND "Influential"
:to(nonprofit):from(donor, foundation) // select all connections leading to elements with the type "Nonprofit" AND leading from elements with the type "Donor" OR "Foundation"
:mutual[strength > 1] // select all mutual connections whose Strength is greater than 1
:directed[connection-type = "donation"] // select all directed connections whose connection type is Donation