# Welcome Looking to learn how to use Kumu? You're in the right place. We've broken up the docs into a few different sections based on your level of experience with Kumu: ### I'm just getting started If you're new to Kumu, try working through the Getting Started section: * [Five-minute quickstart](#five-minute-quickstart) * [Building your first map](/getting-started/first-steps#build-your-first-map) {% hint style="info" %} Need some inspiration? [Find some Kumu Projects in the Wild here.](https://kumu.io/kumu/projects-in-the-wild#projects-in-the-wild) Want to add your Kumu project to this map? [Submit it here.](https://form.typeform.com/to/aUUuSLnj) {% endhint %} ### I'm ready to dive deeper Once you've gotten the hang of Kumu, explore the Guides section: * [Decorate](/guides/decorate) * [Filter](/guides/filter) * [Cluster](/guides/clustering) ### I think I'm missing something... Feeling a bit lost in the Guides section? No worries! Try getting some more background information on Kumu from the Overview section: * [Types of accounts](/overview/accounts-and-workspaces) * [Kumu's architecture](/overview/kumus-architecture) * [User interfaces](/overview/user-interfaces) ## Five-minute quickstart Ready to dive in? * [Read the First Steps guide](/getting-started/first-steps) * [Watch one of our recorded webinars](https://www.youtube.com/playlist?list=PLsVcVdCluYH75u3tWtR6iZwIepfnAfZHt) * [Read up on Systems Practice](https://blog.kumu.io/systems-practice-abridged-a5dc8f0beda6) * [Learn how to map your system in Kumu](/disciplines/system-mapping) * [Learn how to map a network in Kumu](/disciplines/sna-network-mapping) ## Want to talk to a human? If you run into any challenges, send us an email at . We're always happy to help! # Kumu 101 Kumu can be used in many different ways and for many different types of projects, but there's definitely a shared set of skills you need to know to get started with Kumu. To make sure you have a solid foundation of knowledge to build on, you can use this list of questions to guide you through all of the core Kumu concepts: * [What are the main use cases for Kumu?](#what-are-the-main-use-cases-for-kumu) * [What are the key difference between accounts and workspaces?](#what-are-the-key-differences-between-accounts-and-workspaces) * [Once I have an account, how do I get started with my first project?](#once-i-have-an-account-how-do-i-get-started-with-my-first-project) * [Where can I go to learn more about Kumu?](#where-can-i-go-to-learn-more-about-kumu) * [If I get stuck, where can I go for help?](#where-can-i-go-for-help-or-to-show-off-my-awesome-work) In the past, we've run live webinars to work through each of these questions. You can check out a live recording of a Kumu 101 webinar below, or, if you would rather get the answers in writing, keep reading! {% embed url="" %} ## What are the main use cases for Kumu? Kumu aims to help make sense of our messy world, specifically through **system mapping** and **network mapping**. Those two disciplines include many different kinds of visuals: causal loop diagrams, stock-and-flow diagrams, stakeholder maps, actor maps…you get the idea! Each of these visuals has it’s own unique characteristics, but at their core, all of them consist of shapes connected by lines. But compelling maps aren’t just shapes and lines—a great map takes multiple layers of complicated information, sculpts them into a story, and ultimately allows an audience of readers to extract valuable insights, even if the readers have never seen a system map or network map before. So—whether you’re mapping systems, networks, causal loops, or stakeholders—as long as you’re goal is to make sense of complexity, Kumu would love to help! ## What are the key differences between accounts and workspaces? Each person who wants to edit any Kumu projects needs an account. An account is free to create, and it allows you to log into Kumu and access all of your projects, and projects that you’ve been given access to. With your account, you also get a **Basic workspace**. In Kumu, workspaces are like folders, where you organize related projects. Your Basic workspace is a great place to keep personal projects. If you have projects that multiple people need to collaborate on, you can create a **Pro workspace** (or upgrade your initial Basic workspace to Pro), and invite your collaborators to join the workspace. For more info on the differences between accounts and workspaces, be sure to check out our [pricing page](https://kumu.io/pricing) and [our full guide on workspaces](/overview/accounts-and-workspaces). In the Kumu 101 recording, you'll hear me refer to "personal accounts" and "organizations". We renamed "organizations" to "workspaces", but their features and functionality did not change. ## Once I have an account, how do I get started with my first project? Awesome, you’ve signed up for an account! From there, I recommend working through our [First Steps](/getting-started/first-steps) guide, which goes through everything you need to know to hit the ground running. ## Where can I go to learn more about Kumu? To help you learn more about Kumu, we've put together some great resources. First and foremost is this documentation website, where you can find guides on everything there is to know about Kumu. You can also subscribe to [our blog, In Too Deep](https://blog.kumu.io/) and check out the [In Too Deep podcast](https://intoodeep.buzzsprout.com/). In those two spaces, we talk and write not only about Kumu and its features, but also about systems thinking, network science, other products we build at Kumu, and the big ideas that inspire us. ## Where can I go for help (or to show off my awesome work)? If you get stuck and need advice, feel free to email us at . We're always happy to help. And if you have awesome work to share or showcase, we’d love to see it as well! ## Want to support Kumu? We build tools that help people tackle tough problems. We believe deeply in the importance of getting Kumu into the hands of the organizations, communities and change makers that need it most. Our commitments to free public projects, reasonable pricing, and non-profit discounts mean that many of you feel like you get tremendous value from the tool without having a way to give back. If you resonate with [our manifesto](https://kumu.io/manifesto) and would like to support our team as we continue to build the next version of Kumu (and other tools for wrangling complexity), then we’d love to have you here as a [supporter on Patreon](https://www.patreon.com/kumu/membership). # First steps This overview is a great place to start if you're new to Kumu. Take some time to read it through from end to end! #### Jump to a section * [Create an account](#create-an-account) * [Create your first project](#create-your-first-project) * [Picking a template](#picking-a-template) * [Build your first map](#build-your-first-map) * [Decorate elements and connections](#decorate-elements-and-connections) * [Refine your view](#refine-your-view) * [Add a contributor](#add-a-contributor) ## {% embed url="" %} ## Create an account Create an account by visiting . You'll use this account to sign in to Kumu and manage all of your projects inside of [workspaces](/overview/accounts-and-workspaces). ## Create your first project To create your first project, visit your [dashboard](https://kumu.io/dashboard) and click on the **NEW PROJECT** button. Work through the next couple of screens to name your project, decide whether it will be public or private, give it a description, etc. During this process, you'll also create your first map, and Kumu will ask you to pick a template for your map. ## Picking a template After creating a new project in Kumu, your next step is to pick which template you want to use for your first map: ![Template Selection](/files/jmnJLyyfdAPc1rHKqKhW) We recommend most people start with the **system**, **stakeholder**, or **SNA** template, unless they have a good reason to do otherwise. Below is a description of each template's effect: * **System template.** Pick this template if you are creating a system map, causal loop diagram, or a stock and flow diagram. You'll position elements manually in a fixed position. * **Stakeholder template.** Pick this template anytime you are mapping the people and organizations involved in a system, and the relationships between. Elements will float around, finding their final position automatically. * **SNA template.** Pick this template anytime you are mapping large networks (1000+ elements). This template uses our "fast" mode, which draws elements as squares and connections as straight lines to improve performance. Elements are positioned automatically and will float around. * **Custom template.** Pick this template if you'd like to start out without any custom decorations or settings. Elements will float to find their final position and are displayed as small, grey circles. Not sure which one you need? [Check out our full guide on templates](/guides/templates). ## Build your first map Once you've chosen a template, you'll land on this screen: ![](/files/8Fh91hxxw3eHtKfseeTB) This is your blank canvas, where you'll add elements (circles) and connections (lines) to visualize your system or network. If you're mapping a system, you will probably be adding loops (groups of two or more connections) as well. At this point, you need to decide how to get all of this information into the map. There are three basic ways to do this: ![](/files/TIgVv2EDs82ea4Wdcmwr) In this guide, we'll cover how to build your map by hand. If you'd rather import from a spreadsheet or Google Sheets, [check out our full guide on imports](/guides/import). ### Build your map by hand Building your map by hand is a good choice for system maps or smaller network maps. If your map will have less than 50 elements, you can probably build it comfortably by hand. There are two ways to build a map by hand. 1. [The green ![](/files/StAlX36U4ik5HBj2TktC) button](#the-green-button) 2. [Sketch mode](#sketch-mode) #### The green button Click on the green button at the bottom of the map, and you'll see several options: * Add element * Add connection * Add loop * Sketch * Import Try clicking on the first option, **Add element**, to create a new element. Kumu will prompt you to give the element a label and press the `enter` key on your keyboard. Voila! You've added your first element. Add a few more elements, then try selecting **Add connection** from that menu to connect your elements. Once you have a few connections, you can select **Add loop** to create a group of connections. {% hint style="info" %} Tip: Speed up this process by using keyboard shortcuts! Press `E` to add an element, `C` to add a connection, and `L` to add a loop. Or, hold `alt` on Windows/`option` on Mac, then click the map to add an element. Hold `alt` and click-and-drag from an element to create a connection. {% endhint %} #### Sketch mode If you're building your map by hand, you should definitely give sketch mode a try! Click the green button and select **Sketch** to activate sketch mode. Once sketch mode is activated, you can add an element by clicking anywhere on the map, and you can add a connection by clicking and dragging from an existing element. {% hint style="info" %} Quickly enter sketch mode by pressing `K` on your keyboard, and press the `esc` key to exit. While in sketch mode, you can move elements by holding the `alt` key on your keyboard, then clicking and dragging the element. {% endhint %} ## Decorate elements and connections Once you have built part of your map, it's the perfect time to learn how to use decorations to bring the data to life. It's possible to [change the color or size of individual elements and connections](/guides/decorate/direct-decorations), but it's much faster and more scaleable to create decoration rules based on the information stored inside your elements and connections. To add that information, you'll use the panel on the left side of the map, which is called the **profile**. ### Use the profile to add additional information Each element, connection, and loop has a profile that can be used to store additional information in various fields. ![](/files/9h9akZUrdfaoxgFQhz3i) Label, Type, Description, and Tags are all examples of fields. Use these fields to provide additional context for each element and connection, and click **+NEW FIELD** to add a custom field. For this walkthrough, fill out the Type field for each of your elements—try to use a few different values so that you can assign decorations to them. ### Create your first decoration Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map to open up the Basic Editor. You'll see the most popular settings listed, allowing you to easily size or color elements by a field. There's more options here, but let's start with the most basic ones! For the full explanation of each possible setting, visit [the Basic Editor guide](/overview/user-interfaces/view-editors#basic-editor).
If you have filled out the Type field for your elements, try selecting **Element Type** from the dropdown menu next to **Color by**. Kumu will automatically color-code all of your elements by Type, and you can click the expand icon to choose a different color scale. Your first decoration is complete! If you like what you see, click **SAVE** at the bottom of the Basic Editor, and click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) again (or press `T` on your keyboard) to return to your map. When you're ready to add more customized, detailed decorations, take a look at our [decorations guide](/guides/decorate). ## Refine your view Great work so far—you've created a project, started building your first map, and even added decorations to liven things up. But as you expand your map with more data, you will probably want to view different slices of the data at different times, so you can tell a story without overwhelming your map readers. To do that, you'll use **filter**, **focus**, **showcase**, and **cluster**—four different ways to refine what is visible or dominant in the map. {% hint style="info" %} Settings for filter, focus, showcase, and cluster can be saved to a View, allowing you to easily switch between different refined versions of your data. To learn more, [check out our guide on Views](/guides/views). {% endhint %} ### Filter Filters make it easy to show and hide elements, connections or loops based on data stored in the profile. To experiment with filters, just open the Basic Editor, and select **Filter**.

Filter menu

If you're filtering by element or connection type, simply un-check the types you want to hide. To filter using other fields, use the **Also include** and **But ignore** tools. Click the rocket ship icon in each of those tools to select what you want to hide or make visible. {% hint style="info" %} If you've hidden certain elements and connections using the Type checkboxes above, you can use the Also include tool to bring things back into view. But, you first have to un-check some of the boxes above, or this tool will have no effect. {% endhint %} {% hint style="info" %} Use the But ignore tool to hide elements and connections from your map. Anything you add here will override the settings in the checkboxes above and the Also include tool. {% endhint %} ### Focus Focus works by showing only the portion of the network within a certain number of connections. Focus is activated in one of two ways: 1. Click and hold on any element or connection, OR 2. Select one or more elements, connections, or loops (press `shift` and click to select multiple items), then click the focus button in the bottom right of the profile. Once focus is activated, everything except your selected items will be hidden from the map. Press the `+` key on your keyboard to extend the focus further out from your selection, and press the `-` key to narrow the focus back to your selection. Also, you can click and hold on any element to bring that element's direct connections into view. ![focus animation](/files/EoX56mTsItHcfil9gqFv) If you'd like to clear your focus and bring back the full map, click the focus icon on the right (underneath the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)) and select **Clear**. {% hint style="info" %} To extend focus to a specific degree, use the numbers `0-9` on your keyboard. To quickly clear your focus, press the `esc` key. {% endhint %} ### Showcase Showcase is similar to filter, which allows you to show or hide elements, connections, and loops based on the information they contain. But, instead of hiding your data, showcase will make it translucent, fading it into the background.

Showcase

Experiment with showcase by opening the Basic Editor, and clicking **Showcase**. ![Showcase basic editor](/files/dg6zR8A23dbPESLOMYc3) Click the rocket ship icon to build the selection of items that you want to showcase. ### Cluster Clustering allows you to connect elements based on the data in their fields, and it's particularly useful on stakeholder and network maps. To set up your first cluster, open the Basic Editor, and use the dropdown next to **Connect by** to select a field. (If you've followed this guide all the way through, **Element Type** is a great first choice). When clustering is activated, Kumu will create new elements to represent each possible value for the field that you chose, and it will draw a connection between your elements and the value(s) in their field. For example, if you have an element with the element type "Organization", Kumu will create an element labelled "Organization" and connect your element to it. To add multiple cluster rules, click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)to the right of the **Connect by** tool. ![Cluster basic editor](/files/EasfTuEHKzXyNXBi59Iz) Just click **Add rule** to cluster by any of the information inside your elements. [Check out our full clustering guide](/guides/clustering) to learn more. ## Add a contributor Building maps in Kumu can be a lot of work! Inviting somebody else to contribute to your project is a great way to reach your final destination more quickly. Even if your project is small and manageable, it's a good idea to let someone else weigh in on your data and design to make sure your story gets told effectively. To add a contributor to a project, click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left of your project, then select **MEMBERS** from the sidebar. ![](/files/sWYpF67y6V7L0NankBSS) In the **Username** box, type the Kumu username of the person you want to add (if they don't have a username, they can get one for free at ) and click **Add contributor**. For more info on collaboration in Kumu, visit [our full guide on collaboration](/overview/collaboration). {% hint style="success" %} You've completed the Getting Started series! For additional help, you can browse our other guides or email us at . We're always happy to help! {% endhint %} # Quick tips Quick tips are short, 1-2 minute videos answering common questions about Kumu. Click play below to watch the videos and use the menu in the upper right of the player to switch to a different topic or specific question. {% embed url="" %} Click on the playlist in the upper right corner of the Youtube embed above to access the videos listed below: * [How do I link to a specific element in the map?](https://www.youtube.com/watch?v=iORN_mRpkMI) * [How can I use the spreadsheet to wipe the existing map content?](https://www.youtube.com/watch?v=2fHS2DzPDMU) * [What's the difference between Personal (Basic) and Organization (Pro) accounts?](https://www.youtube.com/watch?v=Tr2V2mGT550) * [How do I add a filter dropdown to my map?](https://www.youtube.com/watch?v=lBAQgllfAJA) * [How do I add a field with a list of values to pick from?](https://www.youtube.com/watch?v=Y-HZbKc3VRs) * [How do I change what is included in my element labels?](https://www.youtube.com/watch?v=tqF5xJ9MfZo) * [How do I re-use existing elements when clustering?](https://www.youtube.com/watch?v=8PuNQHdaAUw) * [How do I calculate how many connections an element has?](https://www.youtube.com/watch?v=1o0AraW1MbM) * [How do I build a presentation?](https://www.youtube.com/watch?v=t8_Gc0_lNqY) * [How do I scale elements or connections based on field data?](https://www.youtube.com/watch?v=KZjn99tLrHs) * [How can I include a list of elements in my map overview?](https://www.youtube.com/watch?v=4m_f4Mu03nI) * [How can I crowdsource data using Google Sheets?](https://www.youtube.com/watch?v=0eZQ2MPGzv4) * [What are some of the most useful keyboard shortcuts?](https://www.youtube.com/watch?v=D5SQ4SzMtns) * [How do I upload images?](https://www.youtube.com/watch?v=bA71RjEIvdI) * [How can I add unique IDs to my import?](https://www.youtube.com/watch?v=hoEJ-FXkbnA) * [How do I share my map with others?](https://www.youtube.com/watch?v=_MUbryyy8Dw) * [How can I save different results for the same metric?](https://www.youtube.com/watch?v=YZuJheC3zNc) * [How can I use Table to quickly build out my map?](https://www.youtube.com/watch?v=t1lDPgcmr-I) * [How can I add descriptive labels to my map?](https://www.youtube.com/watch?v=PGZZui7XASk) * [How can I import data with dates?](https://www.youtube.com/watch?v=efnNdrEGDZ8) * [How do I get the perfect screenshot?](https://www.youtube.com/watch?v=66dz3DFJZi4) * [How do I color code elements?](https://www.youtube.com/watch?v=a0FgR7gXFVk) * [What are traversals, and how do I use them?](https://www.youtube.com/watch?v=tw7Q-Kuzo8g) * [How do I create geographic maps?](https://www.youtube.com/watch?v=0WQ0dS5CIGM) * [What are controls, and how do I use them?](https://www.youtube.com/watch?v=eBo1St2laTw) * [What are underlays, and how do I use them?](https://www.youtube.com/watch?v=2dmzQ-2rIrQ) * [How do I size my elements?](https://www.youtube.com/watch?v=ej9IONabGH8) * [What is a view?](https://www.youtube.com/watch?v=3zyf7sbgO7I) * [What are the building blocks of Kumu?](https://www.youtube.com/watch?v=VzNdrLLlJIU) * [How can I make my network map more readable?](https://www.youtube.com/watch?v=YJ-310nhDns) * [How can my readers easily switch between views?](https://www.youtube.com/watch?v=GTGbmis2RZk) * [What is a "profile" in Kumu?](https://www.youtube.com/watch?v=Nsu1vXD_v0s) * [How can I quickly show basic info about an element, connection, or loop?](https://www.youtube.com/watch?v=8BsjL6iXO5g) # Webinars Webinars are live sessions where we spend an hour diving deep on a single Kumu topic. Click play below to watch webinars, and use the menu in the upper left of the player to switch to a specific topic. {% embed url="" %} # Kumu's architecture We've designed Kumu from the ground up to be a powerful, flexible mapping machine, capable of mapping complexity of all kinds. Through that process, we've settled on a specific **architecture**—a way of organizing and visualizing data and information—that makes it possible to create many different kinds of maps. System maps, network maps, stakeholder/actor maps, community and asset maps, mind maps, concept maps...the list goes on! In this guide, we'll explain each of the building blocks that make up Kumu's architecture. Take 10 minutes to read through and learn the difference between each building block—it will be really helpful in the long run! {% embed url="" %} #### Jump to a section * [Elements, connections, and loops](#elements-connections-and-loops) * [Fields](#fields) * [Projects](#projects) * [Maps](#maps) * [Views](#views) * [Trash](#trash) ## Elements, connections, and loops In Kumu, you can use **elements**, **connections**, and **loops** to represent your system or network. Visually speaking, elements are circles, connections are lines between the elements, and loops are groups of two or more connections. ![Elements, connections, and loops](/files/QRXjpkHEyjo6mX1KuR0Q) You can use these visual components in all kinds of different ways, but here are some common uses that we see: | Elements | Connections | Loops | | ----------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | | Factors in a system (causes and effects) | Cause-and-effect relationships | Causal loops | | Stocks | Flows | Sub-systems | | Decisions, chances, and ends in a decision tree | Paths along the decision tree | Multi-part decisions | | Steps in a process | Paths from one step to the next | Sub-processes | | People | Interpersonal relationships | Sub-networks or communities | | People & organizations | Connect people to the organizations they're affiliated with | Sub-networks or communities | | Authors & books/articles they've co-authored | Connect authors to their books/articles | Sub-networks or communities | | Stakeholders & areas of interest | Connect stakeholders to the areas they're interested in | Sub-networks or communities | | Funders, non-profits, and population groups | Connect funders to non-proftis, and connect non-profits to the populations they serve | Sub-networks or communities | | Companies and sectors/industries | Connect companies to their sectors/industries | Sub-networks or communities | For instructions on how to create elements, connections, and loops in Kumu, check out the [Building your first map](/getting-started/first-steps#build-your-first-map) section of our First Steps guide. ## Fields Each element, connection, and loop can hold additional rich information about the item. This information is stored in **fields**, which have two components: a name, and a value. The most basic field is named "Label". Any value you add to an element's or loop's "Label" field will be displayed as a text label underneath or on top of that element or loop. (Connection labels are hidden by default, but it's possible to show those labels as well). In addition to "Label", there are three other pre-named fields: 1. **Type** — a field designed to help you separate your items into categories. For example, you elements might have "Person" or "Organization" in their type field, to clarify what the element represents. 2. **Description** — a field designed to hold longer descriptions of an item. Descriptions can include multiple paragraphs, and even images and videos. 3. **Tags** - a field designed to hold multiple values that each describe your item in a different way. For example, a connection between a person and a non-profit might have "Strong relationship", "Board Member", "Donor", and "Advocate" all stored as separate values in the Tags field, adding rich detail to the person's relationship with the organization. Beyond those four pre-named fields, you can create as many custom fields as you want—you can have a "Website" field, a "Net Assets" field, a "What do you want to learn?" field, etc. Fields can be created and edited using [profiles](/guides/profiles): ![profile](/files/9h9akZUrdfaoxgFQhz3i) For more information on fields and how to create and customize them, [check out our full guide on fields](/guides/fields). ## Projects **Projects** are the top level of Kumu's architecture. Think of projects as a "buckets" that contain everything defined above: elements, connections, loops, fields, views, and maps. Within a project, you can have both Maps and Views. There's an important distinction to be made between a project, a map, and a view: the project contains the master list of elements, connections, and loops, while the map and the view simply borrow a collection of data from that list. If you edit an element, connection, or loop while working on a map or view, you're not just editing the map or view—you're actually editing the project's master list. If you ever find yourself creating multiple maps within one project, it's very important to remember that concept, because when you edit an item (for example, change an element's Label, Type, or any other field value) those changes will be applied to **every other map** that is borrowing the same item from the project's master list. If you only have one map in your project, don't sweat this detail! Projects can also remember a few more important things: * The project's privacy level (public or private) * Any [presentations](/guides/presentations) you have created to share your work * Any [contributors](/overview/collaboration) that can edit your project * Any [add-ons](/guides/add-ons) that have been installed on the project * Any [license](/guides/licensing) you have added, to tell people how they can or cannot share or re-use your work Click on the ![](/files/ZXqtary8OskQSi5XYgWD) menu in the top-left corner of your project to change any project settings. You create new projects and see all your existing projects on your [dashboard](/overview/user-interfaces/dashboard). ## Maps In Kumu, a **map** is a collection of elements, connections, and loops—each map can remember a full list of which elements, connections, and loops should be included. In addition, a map can remember specific positions for all of its elements, and it can remember the positions of any labels that represent loops. A map can also remember a few default settings: * **Default view** — the view whose rules will be applied to the map by default. * **Default element behavior** — tells the map whether new elements should stay in a fixed position by default, or float around, relying on their connections to pull them into a final position * **Default connection direction** — tells the map whether new connections should be "Directed" (arrow on one end), "Undirected" (no arrows), or "Mutual" (arrows on both ends) by default Finally, a map can remember a rich description about itself, called a "Map Overview", which Kumu displays next to the map so your audience can read it: ![map overview with video](/files/HV9iFAXwudKSmWr76wOU) {% hint style="info" %} To create a new map: click on the first dropdown next to the project title in the top-left corner of your screen, and choose **+ NEW MAP.** {% endhint %} For more info on how to build the basic structure of your map, check out our [full guide on the map editor](/overview/user-interfaces/map-editor). ## Views A **view** is a collection of rules that affect the visual appearance of your elements, connections, and loops. There are a lot of different kinds of rules that you can create. For example: * All elements with "Person" in their Type field should be colored blue. * All connections with "Very Weak" in their Tags field should be filtered out (temporarily hidden). * Connections should be drawn between all the people who have the value "Finance" in a field named "What do you want to learn?". Note that these rules are not tied to specific elements, connections, or loops, but instead are designed to act on groups of items, based on data and information inside of them—the rules in your views are all **data-driven**. Whether you have ten, one-hundred, or even one-thousand elements, the first rule from the list above is going to find *every single element* with "Person" in the Type field and color it blue. It gets better! Let's say you add some elements and connections to Kumu and apply a few rules, just so you can build a prototype visualization with the data you have on hand. Then, you decide that the prototype looks good, so you load in your full dataset, adding tens or hundreds more elements and connections to the visualization. Good news: **your view rules will apply to all the new items**. No need to re-create every rule from your prototype! All view rules are completely scaleable—Kumu will apply them to any and all new data you add, whether you're adding new elements, connections, and loops, or just adding new values to your fields. {% hint style="info" %} To create a new view: click on the first dropdown next to the project title in the top-left corner of your screen, and choose **+ NEW VIEW.** {% endhint %} To learn more about building views and creating specific types of rules, check out the guides below. There's a lot to learn about views! But don't feel like you need to learn it all at once. You can get a lot of value out of Kumu without knowing all this information, but this is a great place to return to when you feel ready to take your Kumu skills to the next level. | Guide | Main idea | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | [View editors](/overview/user-interfaces/view-editors) | Learn your way around the user interfaces that allow you to edit views. | | [Decorate](/guides/decorate) | Change visual appearance of items (color, size, pattern, shadow, image, etc.). | | [Filter](/guides/filter) | Temporarily show or hide items. | | [Showcase](/guides/showcase) | Make certain items translucent, fading them subtly into the background. | | [Focus](/guides/focus) | Focus on a single element, hiding everything else. Then, expand outward to reveal more elements and connections, step-by-step. | | [Cluster](/guides/clustering) | Connect elements automatically, based on the information in their fields. | | [Bridge](/guides/bridge) | Connect elements based on their "mutual friends" (elements they're both connected to). | | [Imported views](/guides/imported-views) | Import rules from another view, so that you don't have to re-build them. | | [Controls](/guides/controls) | Customize the way people interact with your map. | | [Layouts](/guides/layouts) | Change the way Kumu positions your elements. | ## Trash Last but not least, Kumu's architecture includes the **trash**. The trash is a list of all the elements, connections, and loops that, once upon a time, were the the lifeblood of your system map, the all-powerful hubs of your network map, the social-media-savvy influencers of your stakeholder map...until you realized that the data was totally inaccurate, imprecise, full of typos (*\*gasp\**), or duplicated (*\*shudder\**), and deleted it using the [little trash can icon](/overview/user-interfaces/map-editor#side-panel) . All prose aside, the trash is where your project stores the items that have been deleted from every single map. From time to time, you may want to empty it out by following these steps: 1. Click the Project Settngs icon ![](/files/RqKpvO0s8xxWy6htbEd1) in the upper left corner to bring up the project menu 2. Select TRASH from the menu on the left 3. Use the dropdown menu to review and destroy items individually, or just click **Destroy All**. After you do this, there's no going back! But, we should give credit where credit is due: the trash is your last line of defense against accidentally deleting data (a.k.a. hard work, time, and effort) from your project. If you ever think that you've deleted something accidentally, and you need to recover it from the trash, [check out this guide](/frequently-asked-questions/my-map-disappeared-how-do-i-bring-it-back#has-the-data-been-deleted), or just [ask for help](/about-kumu/where-can-i-get-help), and the Kumu team will find a solution. # Accounts and workspaces Each person who wants to use Kumu signs up for their own **account**. Kumu accounts are free, and you don't have to enter a credit card or any other payment method to get started. After you [log into your account](https://kumu.io/login) with your username and password, you'll be able to access all of your projects, as well as projects you've been invited to collaborate on. Projects are organized in **workspaces**, and projects come with different features and costs based on what type of workspace they're in. When you first sign up for a new Kumu account, Kumu automatically creates your first workspace for you, so you have somewhere to start creating projects. That workspace is a **Basic** workspace (more on that in the next section) by default. Looking to upgrade your default workspace to Pro? Head over to [your Workspace settings](https://kumu.io/settings#workspaces), select your workspace from the list, and click the button to upgrade to a Pro workspace. Each workspace has a name, and the [slug](/guides/slugs) of a workspace's name will appear in all of the URLs for the workspace's projects and presentations. Your default Basic workspace's name will match your account username. ## Types of workspaces Workspaces can either be **Basic** workspaces or **Pro** workspaces. Projects in your workspaces will have different features and costs depending on their workspace's type. [Visit our pricing page](https://kumu.io/pricing) for full details, but here are some of the highlights: * Basic workspace projects have all the core features you need to start mapping, but Pro workspace projects add collaboration features, like activity feeds, real-time commenting, more granular access control, etc. * Both workspace types allow for unlimited public projects and unlimited collaborators * Basic workspaces are free to create, and each Pro workspace has a $10/month base fee, billable only to the workspace owner (not the members) * Each private project inside a Basic workspace costs $9/month, and each private project inside a Pro workspace costs $20/month ### Which type of workspace should I choose? Basic workspaces are a great fit for **individuals** working on their own projects, or [collaborating](/overview/collaboration#add-a-contributor) with a few other people. Basic workspaces are also a good option for teams of people that only have one designated Kumu expert, who builds and manages all of the Kumu projects for the team. Pro workspaces are a great fit for **teams of people** that have several active Kumu users. You can collaborate efficiently and securely with clients, colleagues, board members and more! Pro workspaces are also really useful when you're creating Kumu projects for clients, and you'd like your clients to be able to check in on your progress and give feedback. Pro workspaces give you fine-grained access control: give others view, edit, or admin rights to a project. Add members to the organization and group them into teams to assign permissions more efficiently. You'll also be able to see detailed activity feeds, comment on your map in real time, enhance security with two-factor authentication, and much more. To see the full list of Pro workspace features, check out [our pricing page](https://kumu.io/pricing) and [our full guide on Pro workspaces](/guides/pro-workspaces). # Kumu.io and Kumu Enterprise We offer two Kumu products: Kumu.io and Kumu Enterprise. **Kumu.io** is the online version—you can [sign up at any time online](https://kumu.io/join) for a free account. **Kumu Enterprise** has the same software and features as Kumu.io under the hood, but you can keep your activity fully separate and isolated from the activity of everyone who uses Kumu.io. ## Which product is right for me? Kumu Enterprise is the right choice for teams that are working with highly sensitive data and need deep control over how it's secured—more control than you get when uploading data to Kumu.io. Enterprise versions are also a great option for teams that are legally required to store their data in a specific geographic location (Kumu.io stores data across the world). To get started with Kumu Enterprise and learn more about its security features, please [visit our Enterprise website here](https://kumu.io/enterprise). If you need help with installing, configuring, or upgrading your Enterprise version, [see our full Enterprise guides](/enterprise/index). For anyone who doesn't have these higher security needs, Kumu.io will be a much more streamlined, and a just as powerful option. For any additional questions on Kumu Enterprise, please reach out to ! # Billing At Kumu, we use an automated billing system to accept payments for private projects and [Pro workspace](/guides/pro-workspaces) fees. Amounts can be billed on either a monthly or annual basis. If you choose to be billed on an annual basis, you'll receive a 20% discount. We handle all payments with [full PCI-compliance](https://www.pcisecuritystandards.org/) through [Stripe](https://stripe.com/), the industry standard, and you can use any credit card that is [accepted by Stripe](https://stripe.com/payments/payment-methods-guide#cards). We do not store any sensitive billing information on our own servers. To change the credit card you use with Kumu, you can do the following: 1. Decide which [workspace](/overview/accounts-and-workspaces) you want to add card details to (you can add different credit cards to each of your workspaces, making it easy to separate personal bills and work-related bills). 2. [Go to your list of workspaces](https://kumu.io/dashboard#workspaces) and select the workspace from the list 3. In the Billing section of the workspace's settings, add your credit card details. Kumu charges you based on two factors: 1. Whether you have a Basic Workspace or a [Pro Workspace](/guides/pro-workspaces) 2. The number of private projects you have in your workspace #### Monthly billing If you are on a monthly billing cycle, Kumu will bill your account on the same day each month. Basic Workspaces are free, and each private project costs $9/month. Pro Workspaces are $10 per month, and each private project costs an additional $20/month. To add more private projects to a monthly Basic or Pro workspace, you can [create a new project](https://kumu.io/new) and use the New Project form to set the project to **Private**. ![New private project](/files/pa01ooJYtO3I6gZpJDRd) To remove private projects from the monthly bill in a Basic workspace, you can use the [project admin menu](/guides/project-admin) to delete the project, transfer it, or make it public. In a Pro workspace, you can do the same, but you also have the option to [archive](/guides/pro-workspaces/archiving-projects) the project. When your bill is increased or decreased during a billing cycle, Kumu's billing system automatically **prorates** the final charge based on the amount of time left in your cycle, and incorporates the proration into the next bill. #### Annual billing To switch your account to annual billing: 1. Click on the Workspaces tab in your Dashboard 2. Click on the workspace you'd like to change the billing frequency for 3. Make sure to use the button "Add card" to add a credit card, if you hadn't already done so 4. Click on "Switch to yearly billing and save 20%" below the **Billing** header. You'll be charged immediately. ![Switch to annual billing](/files/KH0c89V2Zrxh8qzLLubH) #### Adding private projects to the annual plan If you are on an annual billing cycle, Kumu will bill your account once per year based on the type of workspace you have, and a pre-set private project limit. If you **add** a new private project, your private project limit will increase, and you'll be charged a pro-rated amount for the rest of the annual billing cycle *immediately*. This also means that deleting and archiving private projects *will not* automatically reduce your annual bill; it will only make more private projects available under your total private project limit. However, you can increase or decrease your private project limit at any time during the year, and this *will* increase or decrease your next bill. To adjust your private project limit, go to the billing settings for your personal account or organization, and use the interface to add or subtract private projects. ![Annual project limit](/files/aE8hSwSoVG5Uriaaidlf) When your bill is increased or decreased during a billing cycle, Kumu's billing system **prorates** the final charge based on the amount of time left in your cycle, and (if applicable) charges the card on file immediately. {% hint style="info" %} When you increase your private project limit on an annual plan, a prorated charge will be billed immediately to the credit card on file. If you need to pay by invoice instead of by credit card, please [reach out Kumu support](mailto:support@kumu.io) before increasing your project limit. {% endhint %} #### Enterprise billing If you're using the [Enterprise version of Kumu](/overview/kumu-io-and-kumu-enterprise), you'll be billed according to how many users you have, instead of how many projects you have. Enterprise customers are billed annually, and seats are sold in packs of 5 users. ## Free trials When you create a new workspace (including the Basic workspace that Kumu creates for you when you first sign up), you automatically receive a 7-day free trial of private projects in that workspace. At any time during your free trial, you can add a credit card to your billing settings to start a subscription plan as soon as the free trial ends. If you haven't added a credit card before the free trial ends, your private projects will be locked (you won't be able to view or edit them), and Kumu will prompt you to make your projects public or update your billing settings in order to unlock. ## Payment receipts Our billing system automatically sends a receipt to the email on file each time a payment is made. From time to time, these receipts might get sent to your email's spam folder—if you don't see a receipt, be sure to check there first. For a Basic Workspace, if you want to change the email that receipts are sent to, you can go to the [profile section of your account settings](https://kumu.io/settings#profile). To do this for a Pro Workspace, you can go to your Pro Workspace's[ dashboard](/guides/pro-workspaces#create-a-pro-workspace) and scroll down to the profile section. ## Paying by invoice If you can't enter a credit card into Kumu's website for repeat billing, you can pay by invoice instead. An invoice will allow you to make a one-time payment via credit card, ACH transfer, or a check in the mail. To request an invoice, you can [email support@kumu.io](mailto:support@kumu.io). {% hint style="success" %} Have any other questions about billing? Send an email to and we'll get back to you! {% endhint %} ## Downgrade or cancel your Kumu subscription Kumu charges you based on two factors: 1. Whether you have a Basic Workspace or a Pro Workspace 2. The number of private projects you have in your workspace You can downgrade or cancel your plan at any moment. Follow [this guide](/frequently-asked-questions/how-do-i-downgrade-my-subscription) to learn how to do this in your account. *Note: When your bill is increased or decreased during a billing cycle, Kumu's billing system automatically **prorates** the final charge based on the amount of time left in your cycle, and incorporates the proration into the next bill.* # User interfaces At Kumu, we try to make it as easy as possible for you to get ideas out of your head and onto the screen, so that you can spend less time fiddling with menus and modals, and more time winning hearts and minds with your awesome visualizations! The key to all of that lies in Kumu's user interfaces—the tools that you use to create elements, connections, and loops, to design views, to build maps, and to assemble a project that draws insight from your data. We're constantly iterating on these interfaces to make them more effective and intuitive, so if you ever have suggestions, don't hesitate to [let us know](/about-kumu/where-can-i-get-help). Here are a few guides on how to use Kumu's current interfaces: * [Dashboard](/overview/user-interfaces/dashboard) * [Map editor](/overview/user-interfaces/map-editor) * [View editors](/overview/user-interfaces/view-editors) * [Settings](/overview/user-interfaces/settings) # Dashboard Your Kumu dashboard is where the fun begins! After you [sign up for an account](https://kumu.io/join) or [log into your account](https://kumu.io/login), you'll be redirected to your [account dashboard](https://kumu.io/dashboard): ![dashboard](/files/qj65h1v5D71Kl5K4WTcs) When you're logged in, you can always find your dashboard at . The main section of your dashboard lists all the [projects](/overview/kumus-architecture#projects) that you own, as well as the projects you can contribute to. Your own projects will have your avatar next to them, and projects that you don't own will have the avatar of the project owner. If you're looking for a specific project or group of projects, use the dropdown menus above your project list to filter and sort. Or, if you don't have any projects yet, click the **New Project** button to get started! You'll notice that, above the project list and dropdown menus, there are two tabs: **Projects** and **Workspaces**. Click the Workspaces tab to see a list of which [workspaces](/overview/accounts-and-workspaces) you belong to, or create a new workspace. ![workspaces tab](/files/W4T35ML48aPIIGfbdGew) ## Pro workspace dashboard When you belong to a [Pro workspace](/guides/pro-workspaces) in Kumu, you can view a separate dashboard that belongs to the Pro workspace. ![Pro workspace dashboard](/files/PPqEjGkHQ3DwwfG76fSL) On this dashboard, you can see a list of projects owned by the Pro workspace, as well as a list of Pro workspace members and teams. For more information about adding members and creating teams, check out the [full guide on Pro workspaces](/guides/pro-workspaces). Although your personal dashboard is always accessible from [the same link](https://kumu.io/dashboard), the link to your Pro workspace's dashboard depends on the Pro workspace's name. It follows this pattern: ``` https://kumu.io/workspaces/WORKSPACE-SLUG/settings ``` Replace `WORKSPACE-SLUG` with the [slug](/guides/slugs) of your Pro workspace's username to build a direct link to your dashboard. If you're an owner of the Pro workspace, you can scroll down on this dashboard to access your settings for [branding](/guides/pro-workspaces#branding), billing, and your Pro workspace's profile. That's it for dashboards! Don't miss our guides on Kumu's other key interfaces, the [map editor](/overview/user-interfaces/map-editor), [view editors](/overview/user-interfaces/view-editors), and [settings menus](/overview/user-interfaces/settings) # Settings You can edit settings for each [project](/overview/kumus-architecture#projects), [map](/overview/kumus-architecture#maps), and [view](/overview/kumus-architecture#views) in Kumu. ![settings locations](/files/Iame3KnIObEAaAakNTKn) ## Project settings Project settings are accessed via the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left of your screen (on the [top toolbar](/overview/user-interfaces/map-editor#top-toolbar)). ![project settings](/files/6F4YqmFNsPqIXKS5HbCT) Within the project settings, you have the following options: * **Overview.** Add a project overview and a [license](/guides/licensing) for everyone to see. * **Presentations.** Create, edit, and publish [presentations](/guides/presentations) to walk others through your project. Break down your complex project using the slide format of presentations, adding text, images, videos, and fully interactive map slides. * **Activity feed.** Use the activity feed to keep tabs on who’s making each change across your project (only visible for projects created in [Pro workspaces](/guides/pro-workspaces)). * **Help.** Access how-to videos, the Kumu Docs and a list of keyboard shortcuts. * **Fields.** Manage the [fields](/guides/fields) for your project. Add and edit new fields, change field relevance (which fields appear in the profiles for elements, connections, and loops), and manage field appearance and behavior. * **Members.** Give other people access to edit your map. [Learn more about collaborating in Kumu](/overview/collaboration). * **Embeds.** Create a shareable link to a map, or create an iFrame to [embed your map](/guides/share-and-embed) on another site. * **Trash.** View and empty the [trash](/overview/kumus-architecture#trash) for your project. * **Admin.** Change privacy, rename the project, [archive the project](/guides/pro-workspaces/archiving-projects), or delete the project. You can also enable/disable the image proxy when [working with images](/guides/decorate/images). * **Add-ons.** Install one of Kumu's [add-ons](/guides/add-ons). * **Fork project.** Create a copy of a project. [Learn more about forking](/guides/forking). * **Switch project.** Navigate back to your [dashboard](/overview/user-interfaces/dashboard). * **New project.** Create a new project. ## Map settings Map settings are accessed from the map sidebar via the ellipsis icon ![](/files/VopOl7sKWEPqgeFdgzTC) in the upper right corner of the [side panel](/overview/user-interfaces/map-editor#side-panel). ![map settings](/files/QNCgMs4TSz5UCwnif2YP) Each map has the following available actions: * Rename map * Duplicate map * Delete map * Make this the default map And each map has the following settings: * **Default view.** Select the default view for a map. This is the view that will automatically load when someone visits the map. * **Default element behavior.** Set whether new elements should be fixed or floating. [Learn more about fixed and floating layouts](/guides/layouts). * **Default connection direction.** Set whether new connections should be undirected, directed, or mutual. * **Undirected.** No arrows will appear at either end of the connection. * **Directed.** An arrow will appear at the **To** end of the connection. * **Mutual.** Arrows will appear at both ends of the connection. ## View settings View settings are accessed via the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map. If you want to save, rename, duplicate, or delete a view, you can click the ellipsis icon in the upper right. You can also use that icon to set the default view for the current map. ![view settings](/files/jS443s21kJHymYEC8dSx) To learn more about editing the view itself (for example, adding decorations, filtering, changing default settings, etc.), [read the guide on View Editors](/overview/user-interfaces/view-editors). {% hint style="info" %} Pro tip: right-click on any blank space in your map to access a quick-access toolbar that allows you to edit or delete your Project, Map or View. You can also use it to hide the direct decorations toolbar, reset your view, or access Kumu Support through here! {% endhint %} # Map editor The map editor is where you'll build the basic structure of your [map](/overview/kumus-architecture#maps). ![map editor](/files/VAs88hHPGB8lPjD31BRl) ## Top toolbar In the upper left of your map editor, you can find the **top toolbar**. First, you'll see a menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) , which you can use to access [project settings](/overview/user-interfaces/settings#project-settings). Next to that icon, you'll see the project name, followed by two dropdown menus. The first dropdown menu allows you to create new maps and navigate to different maps within your [project](/overview/kumus-architecture#projects). The second dropdown menu allows you to create new [views](/overview/kumus-architecture#views) and apply different views to the current map. ## Create, rename, duplicate or delete a map * To create a new map: click on the first dropdown next to the project title in the top-left corner of your screen, and choose **+ NEW MAP.** * To rename a map: click on the first dropdown next to the project title in the top-left corner of your screen, hover over a map, and choose the edit pencil. Alternatively, right-click on any blank space in your map, click on Map, choose Rename Map. * To duplicate a map: right-click on any blank space in your map, click on Map, choose Duplicate Map. **NOTE:** making changes to a duplicate map *may* affect your original map. Read more about that in [this guide](/overview/kumus-architecture#projects). * To delete a map, click on the first dropdown next to the project title in the top-left corner of your screen, hover over a map, and choose the trash icon. Alternatively, right-click on any blank space in your map, click on Map, choose Delete Map. ## Bottom toolbar In the bottom right corner of your map editor, you'll see a toolbar with several icons that let you take useful actions within your project. * ![](/files/wevRCVwqm7uka10ab8S5) The magic wand brings up a [quick actions](/overview/user-interfaces/quick-actions) menu that allows you to search for tools, actions, and how-to videos * ![](/files/82VjPpkEmeRSUvRntrCt) The flask gives you access to [social network analysis metrics](/guides/metrics) and [community detection](/guides/metrics#community-detection) * ![](/files/Nzt0jZ6RBkdLvDYtRA7B) The chat bubble opens up [Discussions](/guides/pro-workspaces/discussions), where you can chat with your team and attach comments to the map * ![](/files/JJrklDnnmDJVyMm6hphf) The table brings up Kumu's [Table](/guides/table) tool * ![](/files/85Iec8el3u6fav5F4OZg) The download icon exposes several [export](/guides/export) options * ![](/files/nZ5o6HQW9oMgHTFnh8vo) The share icon will help you [share or embed](/guides/share-and-embed) your project * ![](/files/UpdF4QUyRc3ZM4yoMP3v) The ellipsis brings up miscellaneous actions, like entering fullscreen or preview mode ## Side panel Under the top toolbar, you'll see the **side panel**. When you first open your map, or when you click on the background of your map, this side panel will show the Map Overview, where you can add general information about your map to help your readers understand it. {% hint style="info" %} Tip: use [Markdown](/guides/profiles/markdown) to help you style text in the side panel, and add images and videos. {% endhint %} When you select an individual element, connection, or loop on the map, the side panel will show that item's [profile](/guides/profiles). ![profile](/files/9h9akZUrdfaoxgFQhz3i) Inside the profile, you can add and edit information about the selected item. You can also use the icons in the bottom right of the profile to: * ![](/files/ZH4UDZa6U2QhbG5nVC9w) Attach a comment to your selected item * ![](/files/Jro2DddYKlXS0e746Pq3) Pin an element in a [fixed position](/guides/layouts/fixed) * ![](/files/dEUau2Ivcv84gIJXigIK) Change [connection direction](/frequently-asked-questions/how-do-i-add-arrows-to-my-connections) * ![](/files/4ASQ8036lRmMWotKC2fO) Add [delay markings](/disciplines/system-mapping#add-delay-markings) * ![](/files/O0NawCLz26T3pYmkZTU4) Activate [focus](/guides/focus) * ![](/files/CKHiZpg8ml8i7onI7W3d) [Decorate](/guides/decorate) the item * ![](/files/GqgzmWNqjjqMyWhh6dAT) [Delete](/frequently-asked-questions/how-do-i-delete-data-from-my-project) the item #### Multiple selections If you select multiple elements, connections, or loops, the side panel will show the **Multiple selections** tool, which allows you to add information or change information across all the selected items in just one step. It's a big time-saver! ![multiple selections](/files/voZbmNAghLRzHtRLOIHN) Finally, the side panel is also home to Kumu's Metrics tool. To learn more, check out the [full guide on metrics](/guides/metrics). You can show and hide the side panel by pressing `Tab` on your keyboard or by clicking the three gray dots to the right of the panel: ![close side panel](/files/YPy4KlNEYxpGpG4T1aN3) ## Canvas The star of the show, of course, is the map's canvas, where all of your elements, connections, and loops are displayed. To add new items to the map, click the green button at the bottom of the canvas. For more guidance on building your map, [check out our First Steps guide](/getting-started/first-steps#build-your-first-map). By default, your canvas will have a search bar in the upper left, a zoom toolbar in the upper right, and a settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) under the zoom toolbar. If you have added a [legend](/guides/legends) to your map, it will appear in the lower left of your map's canvas by default. Click on the search bar to search across the current map or across all maps. After you click on the search bar, you can also click on the rocket icon ![](/files/hnLxVe0GJLgW3aMjsSeF) to bring up the [selector](/guides/selectors) builder, which is useful when you want to select multiple items based on the information in their profiles. Use the zoom toolbar (or scroll up and down with your mouse/touchpad) to change your zoom level, and click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)to access Kumu's [view editors](/overview/user-interfaces/view-editors). If you ever want to remove or reposition the search bar, zoom toolbar, settings icon, or legend, [check out our guide on controls](/guides/controls). Happy mapping! # View editors Kumu allows you to create multiple different views to visualize your data in multiple different ways. ## Create, rename, duplicate or delete a view * To create a new view: click on the first dropdown next to the project title in the top-left corner of your screen, and choose **+ NEW VIEW.** * To rename a view: click on the first dropdown next to the project title in the top-left corner of your screen, hover over a view, and choose the edit pencil. Alternatively, right-click on any blank space in your map, click on View, choose Rename View. * To duplicate a view: right-click on any blank space in your map, click on View, choose Duplicate View. **NOTE:** making changes to a duplicate view *may* affect your original view. Read more about that in [this guide](/overview/kumus-architecture#projects). * To delete a view, click on the first dropdown next to the project title in the top-left corner of your screen, hover over a view, and choose the trash icon. Alternatively, right-click on any blank space in your map, click on View, choose Delete View. ## Visualizing your data with views You can edit [views](/overview/kumus-architecture#views) with two different editors: the Basic Editor and the Advanced Editor. The Basic Editor allows you to click through different menus to access many of Kumu's powerful features—decorations, filtering, clustering, layouts, and more. The Advanced Editor allows you to write code in Kumu's CSS-inspired coding language to access all of the same features. There are also some features of Kumu that can only be accessed through the Advanced Editor, but if you're unfamiliar with coding, we recommend starting with the Basic and switching to the Advanced as needed. The features that are exclusive to the Advanced Editor are thoroughly documented on this site, and if you ever need help writing some code, just reach out to the Kumu team! ## Basic Editor To open the Basic Editor, open your map and click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map.
You'll see Kumu's most commonly used view settings: ### Size by **Size by** allows you to scale the size of your elements based on numbers stored inside them. For example, if you have a map of organizations, you could create a field called "Net Assets" and fill out the numbers for each element. Then you can use the Basic Editor to scale the size the organizations according to their Net Assets, allowing you to quickly compare everyone's resources.

Size by

Don't like the default sizes? Click the expand icon next to the **Size by** dropdown to fine-tune your sizing options. Note that if you don't have any fields with numbers, the **Size by** dropdown menu won't have any options in it. If you don't have this kind of data available, try using Kumu's [Metrics](/guides/metrics) feature to create some! Need more precise control over your sizes? Check out our guide on [refining your decorations](/guides/decorate#refine-your-decorations). {% hint style="info" %} Are your fields with numbers not showing up in the **Size by** dropdown? Try [changing the field type to "Number"](/guides/fields#customize-a-field). {% endhint %} ### Color by **Color by** allows you to color-code your elements based on any field. Select a field from the dropdown, and any elements that have data in that field will be colored! Don't like the default colors? Click the expand icon next to the **Color by** dropdown to fine-tune your coloring options. This example colors by Element Type using the `bujumbra` scale: ![bujumbra color by](/files/00suYM3xaNRp2vWsaqW8) The default color scale, `neon2`, can support seven different colors. If you need more colors (for example if you have 10 or 11 different element types), [check out our color reference](/overview/advanced-editor-hub/color-reference) to find a scale that will work for your data. If you color by a multi-pick field like Tags, Kumu will color code your elements with flags (colored arcs around the outside of your elements). Each flag represents one of the possible values in the multi-pick field. ![Flags example](/files/YAAsQnCrviMSPtUGL86A) To learn more about flags, [read the full guide](/guides/decorate/flags). Need more precise control over your colors? Check out our guide on [refining your decorations](/guides/decorate#refine-your-decorations). ### Shape by **Shape by** allows you to shape your elements based on any field that can hold only one value. Select a field from the dropdown, and any elements that have data in that field will get a new shape!

Shapes

To learn more about shapes, [read the full guide](/guides/shapes). ### Customize Defaults The [default view settings](/guides/default-view-settings) is your one-stop-shop for adjusting the underlying settings in your [view](/guides/views). Templates, layouts, default element and connection styles, and more, can all be changed with default view settings.

Customize defaults

### Connect by **Connect by** allows you to activate clustering on your map. Clustering is a powerful tool that allows you to connect elements based on the data in their fields, and it's particularly useful on stakeholder and network maps. When clustering is activated, Kumu will create new elements to represent each possible value for a field of your choice, and it will draw a connection between your elements and the value(s) in their field.
[Check out our full clustering guide](/guides/clustering) to learn more. ### Filter **Filter** allows you to show and hide elements, connections or loops based on data stored in the profile. Click on **Filter** to open up your filter settings. ![filter](/files/NNNxeotagUmPJbD0pzMO) [Check out our full filtering guide](/guides/filter) to learn more. ### Showcase **Showcase** is similar to Filter, which allows you to show or hide elements, connections, and loops based on the information they contain. But, instead of *hiding* your unselected data, showcase will make it translucent, effectively *fading it* into the background.

Showcase

To learn more about Showcase, [find our full guide here](/guides/showcase). ### More Underneath the three core tools in the "Structure" section of the Basic Editor, you'll see a **MORE** link. Clicking this link will bring up a list of three additional features. Follow these links below to learn more about any of these individual options: * [Bridge](/guides/bridge): draw connections between any two elements that are connected to a *mutual* element * [Snap-to](/guides/layouts/snap-to): arrange a custom selection of elements in a perfect *circle* or *line* * [Grids & Guides](/guides/underlays): use a grid-based layout for arranging with numerical field data. ### Add custom control **Controls** is a super powerful feature that allows you to customize how people interact with your maps. You can use them to add buttons, images, text and more to your map! You can also use interactive controls to transform the current view's setting, such as filter, focus, and clustering.

Controls in the upper left corner

Check out [our full controls guide](/guides/controls) to learn more. ### Decorate Elements & Decorate Connections If you need more precise control over the size and color of your decorations, you can choose either of the last two options on the list. If you click **Decorate elements,** Kumu will bring up the custom decoration builder for elements, which allows you to decorate your map in great detail. Similarly, if you wish to decorate your connections, choose **Decorate connections** to bring up the decoration builder for connections.

Custom decorations builder for elements

To learn more about how to add custom decorations, find the [full guide here](/guides/decorate/data-driven-decorations#use-decoration-builders-to-create-custom-decorations). ### Existing custom decorations If you have already one or more decorations to your map, the Basic Editor will show those existing decorations underneath the **Rules** section (below Decorate connections). They'll be listed in chronological order from top to bottom (the most recently created decoration rules will be at the bottom of the list). This section of the Basic Editor shows each decoration's legend label you added through the Decoration Builder. You can click the pencil icon next to a decoration to edit it, or click the delete icon to delete it.

Custom decorations

## Advanced Editor To open the Advanced Editor, click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the Basic Editor, then click **SWITCH TO ADVANCED EDITOR** at the bottom of the Basic Editor. ![](/files/pdYQD3QB363E4EPudl5t) Everything you change in the Basic Editor is automatically coded into the Advanced Editor, and most Advanced Editor code follows the same pattern: ```scss selector { property: value; } ``` `selector` can be replaced with any valid [selector](/guides/selectors), and you can read our [property reference](/overview/advanced-editor-hub/property-reference) to find documentation on `properties` and their possible `values`. You can also use some standard [CSS properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) throughout the Advanced Editor. ### At-rules At-rules are pieces of code in the Advanced Editor that look and behave a bit differently, compared to the usual `selector {property: value;}` code. They start with an `@` symbol, and they give Kumu special instructions on how to display your map. #### @controls `@controls` allow you to customize how people interact with your maps. If you have coded in any `@controls`, they will show up at the top of your Advanced Editor code. To learn more about `@controls`, [read the full guide](/guides/controls). #### @import `@import` rules allow you to import code from one of your project's views to another. To learn more about `@import` rules, [see our full guide](/guides/imported-views). #### @settings Unless you have coded in `@controls` or `@import` rules, your Advanced Editor code will have a block of `@settings` code right at the top, where you can adjust default view settings like layout, template, render quality, and more. [Check out our default view settings guide](/guides/default-view-settings#change-default-view-settings-in-the-advanced-editor) to learn more about `@settings`. #### @view `@view` can be used to define partial views. You can find more info in the [full guide on partial views](/guides/partial-views). ## Saving changes Whether you're using the Basic Editor or Advanced Editor, your changes don't get saved automatically. However, as soon as you make a change, Kumu will show a prompt at the bottom of the view editors to either **SAVE** your changes or **REVERT** to your last saved version. A best practice when working in the view editors is to save your changes frequently! This will allow you to revert when you need to, without undoing a lot of progress that you wanted to keep. # Quick Actions Kumu's Quick Actions menu is your one-stop-shop for useful functions, features, and how-to videos. If you can't quite remember where to find something in Kumu's [user interfaces](/overview/user-interfaces), you can use the Quick Actions menu to search the entire software. To bring up the Quick Actions menu, click the magic wand on the [bottom toolbar](/overview/user-interfaces/map-editor#bottom-toolbar) or press `W` on your keyboard. You'll be greeted with a list of helpful options: ![quick actions modal](/files/NylPbqGLvoOONhkYfQnQ) Search for the feature you're looking for, and the list of options will filter itself to match your keywords. We're always adding new items to the list of options in the quick actions menu. If you think we missed something important, just email and let us know! # Collaborating and sharing Whether you're working in a public or private project, Kumu makes it easy to collaborate with others and share your work. This guide is a hub of information related to collaborating and sharing, including these topics: * [Public vs. private projects](#public-vs.-private-projects) * [Adding contributors](#add-a-contributor) * [Handling conflicting changes](#handle-conflicting-changes) * [Creating presentations](#create-a-presentation) * [Creating share/embed links](#create-a-share-embed-link) * [Creating screenshots](#create-a-screenshot) ## Public vs. private projects When you create a new project from your [Kumu dashboard](/overview/user-interfaces/dashboard), you'll be prompted to choose whether it should be public or private, and the option you choose will affect how you can share your finished project. **Public projects** can be viewed by anyone who has the link, and they can be edited by you and anyone you [add as a contributor](#add-a-contributor). They are also indexed by search engines—that is, people can potentially find your project online if they search for the right keywords. Finally, public projects can be [forked](/guides/forking) by other Kumu users, allowing them to build upon your work and offer new insights. Public projects are free, and you can create as many as you want, no matter what account you own or plan you're subscribed to. We love it when you share your work, but we know that it's sometimes necessary to keep it under wraps! For that purpose, we offer **private projects**. Private projects don't get indexed by search engines, and they can only be viewed by you and anyone you have added as a contributor. Private projects are a paid service—check out [our guide on accounts and workspaces](/overview/accounts-and-workspaces) to see a full list of pricing options. Both public and private projects can be shared using [presentations](#create-a-presentation) and [share/embed links](#create-a-shareembed-link), and private projects allow you to password-protect your presentations for an added layer of security. Finally, you can learn more about privacy and security by visiting our [privacy policy](https://kumu.io/privacy) and our [security policy](https://kumu.io/security). And, if your privacy needs are particularly strict (e.g. data needs to be stored in a specific geographic area, or you need to have deeper control over security technology), we recommend checking out [Kumu Enterprise](/overview/kumu-io-and-kumu-enterprise). ## Add a contributor #### Add a contributor to a Basic workspace project To add a contributor to a project inside a [Basic workspace](/overview/accounts-and-workspaces), you first need to make sure the contributor has their own Kumu account. If they don't have one yet, they can [sign up for free](https://kumu.io/join). Once they have signed up, you can [open your project settings](/overview/user-interfaces/settings), click on **MEMBERS**, type in the contributor's Kumu username, and click "Add contributor". ![add contributor](/files/0H4tqNKtR64NYj2xjWqz) Anytime you add a contributor to a project (public or private) owned by your personal account, you are granting them view **and** edit access. However, they won't be able to add other contributors, change project privacy, or rename, transfer, or delete the project. #### Add a contributor to a Pro workspace project When you're adding a contributor to a project in a Pro workspace, you have a few more options. For simpler use cases, you can follow exactly the same steps outlined above for adding collaborators to a Basic workspace. After you add someone to a project, you'll be able to choose whether they have view-only, edit, or admin access. In more complex cases, though, you might want to give somebody a certain level of access to all projects in the Pro workspace. To do that efficiently, you'll invite them as a **member** of your Pro workspace. See [our full guide on Pro workspaces](/guides/pro-workspaces) for more info on how to add members and set their access levels for your projects. ## Handle conflicting changes If you're editing your project, and somebody else is editing at the same time, their changes won't appear on your screen in real-time (and vice-versa). Instead of showing real-time changes, Kumu waits until you refresh the page to sync you up with your team and show you the most up-to-date version of your project. If you happen to edit the same part of the map at the same time (whether that's an element name, map description, view, or something else), Kumu will detect this and prompt you to review any conflicts. **Let's walk through a quick example.** Say you and a teammate both happened to be mapping influential people in Silicon Valley one afternoon. You both click on Reid and decide that his bio needs a bit of sprucing up. You save your changes and SURPRISE! The below screen pops up to let you know that you're not the only one editing Reid's bio today. ![Conflicts Step 1](/files/WZgzIJDRJnCCIHUUUnJs) You click "Get started" and see a window that highlights the changes between your version and the version on our servers. Lines you've added show up as blue text with a "+'' sign in front. Lines that you've deleted or someone else has added show up as red text with a "-" sign in front. ![Conflicts Step 2](/files/F5HS1xKLOjBUolajVrQ1) Now you're in charge. Choose which text you want to keep and which you want to remove. Make any remaining corrections and then remove any "+" or "-" added in the merge process. You're finished when you see all grey text: ![Conflicts Step 3](/files/T8NqPKjbphTeGw4mFDU7) If there are multiple conflicts, you'll be taken through each conflict one by one. Once you see this screen: ![Conflicts Step 4](/files/EZY3CJ8HV4LtLjmX4Bez) ...you're all set. If only handling conflicts in the real world was this easy! ## Create a presentation Presentations combine the best of PowerPoint, Prezi, and Kumu into one easy-to-use tool. You can create a new presentation and edit existing presentations by clicking the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left of your map, then clicking **PRESENTATIONS**. For more info on the power of presentations, watch the video below, or [check out our full guide on presentations](/guides/presentations) {% embed url="" %} ## Create a share/embed link Share/embed links make it easy to send somebody an interactive, read-only version of your map, or embed that version on a blog or website. To create a share/embed link, click the ellipsis icon in the [bottom toolbar](/overview/user-interfaces/map-editor#bottom-toolbar), then choose "Share / embed this map". For more information about share/embed links, including customizeable options, [check out the full guide](/guides/share-and-embed). ## Create a screenshot If you need to share a static screenshot of your map (for example, in another presentation software or in print), there are two ways to go about it. #### PNG To quickly snap a PNG screenshot of your map, click on the export icon in the bottom-right corner of your project and select "Export to PNG". Note that the screenshot will be taken at your current position and scale on the map—if you'd like everything to be centered, click the zoom-fit icon in the zoom toolbar, or press `\` on your keyboard. {% embed url="" %} When Kumu brings up your screenshot, you can right-click the image and select "Save image as..." to save the image to your computer. #### PDF If you need a hi-res screenshot that can scale up or down to any size (for example, when you're printing a Kumu map on a large poster), you can create hi-res PDF files. Click the export icon in the bottom-right corner of your project and select "Export to PDF". Fill out any of the layout info for your PDF and click "Export PDF" at the bottom. PDFs are free and unlimited for all projects in all workspaces. {% hint style="info" %} Want to make sure your labels are readable on your PDF or screenshot? [Learn how to remove label overlap](/guides/layouts/remove-overlap). {% endhint %} {% hint style="info" %} PDFs can only be created for maps, not for full [presentations](/guides/presentations). {% endhint %} # Actions and permissions When you're using Kumu, every action you take falls into one of the following categories: * Changing account or workspace settings * Creating a new project * Viewing a project * Editing a project (e.g. adding elements, adding fields, changing the view, changing settings, etc.) * Exporting a project (to Excel, JSON, or as a screenshot or PDF) * [Forking](/guides/forking) a project * [Administrating a project](/guides/project-admin) (changing project privacy, renaming a project, transferring project ownership to another workspace, or deleting a project) * [Granting project access](/overview/collaboration#add-a-contributor) to other Kumu users * [Commenting on a project](/guides/pro-workspaces/discussions) (only available for [Pro workspaces](/guides/pro-workspaces)) * Adding members to a Pro workspace * Creating teams in a Pro workspace In order to take certain **actions**, you need to have certain **permissions**. In this guide, you'll find a breakdown of who is able to take each action. ## Basic workspace actions and permissions For a Basic workspace, the **workspace owner** (the person who created the workspace) is the only person who has permission to change workspace settings, such as profile info, username and password, or billing info. The workspace owner is also the only person who can create a new project in the workspace. The table below breaks down all other actions, and who has permission to take those actions: | Action | Who can take this action for a public project? | Who can take this action for a private project? | | ------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- | | Viewing a project | Anyone, even if they don't have a Kumu account | The workspace owner and project contributors | | Editing a project | The Basic workspace owner and project contributors | The Basic workspace owner and project contributors | | Exporting a project | The Basic workspace owner and project contributors | The Basic workspace owner and project contributors | | Forking a project | Anyone with a Kumu account | The Basic workspace owner | | Administrating a project | The Basic workspace owner | The Basic workspace owner | | Granting project access to other Kumu users | The Basic workspace owner | The Basic workspace owner | | Commenting on a project | No one (Pro workspaces only) | No one (Pro workspaces only) | For more info on how to add project contributors, check out our guide on [collaboration and sharing](/overview/collaboration). ## Pro workspace actions and permissions For a Pro workspace the **workspace owners** are the only people who have permission to change account settings, such as profile info, username and password, or billing info. Pro workspace owners are also the only people who have permission to invite new people to the workspace or give them direct access to a project (without inviting them to the workspace). ![member settings](/files/TQIN1kVLUuTY6Huav4c4) When Pro workspace owners invite a new person to the workspace, they can choose whether that person will be another **owner** or just a **member**. When owners give a new person direct access to a project, they can choose whether that person will be an **observer**, a **contributor**, or a **manager**. ![member settings](/files/sWYpF67y6V7L0NankBSS) Finally, Pro workspace owners and members are also allowed to create **teams** within their workspace. Pro workspace owners can add people to any team at any time, then give the entire team a specific kind of access to a project (e.g. one team might have view-only access to a project and edit access for different project). Within teams, certain people can be **maintainers**. Maintainers, like workspace owners, have the ability to add and remove people from the team, and appoint other maintainers. ![pro workspace team members](/files/yszpinBYjp6nMBJXeckK) That's a lot of different roles! Here's a quick recap of the vocabulary: * People in a Pro workspace can be **owners** or **members** * People with access to a Pro workspace's project can be **observers**, **contributors**, or **managers** * Some people on teams can be **maintainers** Each of these roles has different **permissions** to take **actions** in the Pro workspace's projects. The table below summarizes all project actions, and who can take those actions: | Action | Who can take this action for a public project? | Who can take this action for a private project? | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Creating a project | Pro workspace owners and members | Pro workspace owners and members | | Viewing a project | Anyone, even if they don't have a Kumu account |
  • Pro workspace owners and members
  • Teams with any kind of access to the project
  • Project observers, contributors, and managers
| | Editing a project |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with edit access to the project
  • Project contributors and managers
|
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with edit or admin access to the project
  • Project contributors and managers
| | Exporting a project |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with edit access to the project
  • Project contributors and managers
|
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with edit or admin access to the project
  • Project contributors and managers
| | Forking a project | Anyone with a Kumu account |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with admin access to the project
  • Project managers
| | Administrating a project |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with admin access to the project
  • Project managers
|
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with admin access to the project
  • Project managers
| | Granting project access to other Kumu users |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with admin access to the project
  • Project managers
|
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with admin access to the project
  • Project managers
| | Commenting on a project |
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with any kind of access to the project
  • Project observers, contributors, and managers
|
  • Pro workspace owners, and the workspace member that created the project, if applicable
  • Teams with any kind of access to the project
  • Project observers, contributors, and managers
| For more info on how to add project contributors, check out [our full guide on Pro workspaces](/guides/pro-workspaces). ## Finding out which workspace a project is in There are two different ways to find out which workspace a project is in. First, if you have been [added as a contributor](/overview/collaboration#add-a-contributor) to the project, you can go to your [account dashboard](https://kumu.io/dashboard) and find the project in the list. Underneath the project's name, you'll see the workspace's name. ![project owner username under project name](/files/6NrmphVmBGjs6rjROiey) You can also figure out who owns any project by looking at the project's URL. Every Kumu project URL starts with `https://kumu.io/`, followed by a [slug](/guides/slugs) or the workspace's name. For example, the project pictured below is owned by our Pro workspace, which is named "Kumu": ![project owner in URL](/files/UoORTZuxzjHx1wkA2pN6) # Security Have questions about security? Be sure to check out [Kumu's official security policy](https://kumu.io/security). If you're looking for more specific information, see our security FAQ below, and if you don't see what you're looking for, feel free to [contact support](mailto:support@kumu.io). #### How are passwords securely stored within the system (e.g. encrypted using a salted hash)? Passwords are stored securely using the bcrypt hashing algorithm. #### Does Kumu automatically log off, lock or terminate a session after a predetermined time of inactivity? We do not terminate sessions automatically based on inactivity. #### What logs or audit trails are produced by Kumu? All requests are logged by IP and logs are kept for two weeks. #### Is the data embedded in the logs? Project data is not included in the logs. #### Are successful/unsuccessful accesses logged? With client network addresses? Login attempts are logged but not closely monitored. Users are encouraged to use 2FA to further secure their accounts. #### How long are the logs retained? The audit trails we maintain internally only cover major events (such as account creation/deletion and project updates). These logs are retained indefinitely. # Advanced Editor hub One of Kumu's most unique features is the **Advanced Editor**, which allows you to write code in Kumu's CSS-inspired coding language to control a wide variety of powerful features. When we wrote these docs, we felt it best to dedicate an article to each individual feature, and explain in that article how you can use both the Basic Editor and the Advanced Editor to control the feature. The downside is that our info on the Advanced Editor is scattered across a lot of different articles! To solve that, we created this article, which links to all of the places where we explain how to use the Advanced Editor. {% hint style="info" %} More of a visual learner? [Check out the webinar "Intro to the Advanced Editor" here. ](https://www.youtube.com/watch?v=iPgLHTsQZ_w\&t) {% endhint %} We ordered and organized these links based on what we feel is the best path for a structured learning experience. ## Advanced Editor basics * [Advanced Editor section](/overview/user-interfaces/view-editors#advanced-editor) of the View Editors guide. Definitely start here! * [Default view settings](/guides/default-view-settings#change-default-view-settings-in-the-advanced-editor) * [Default view settings reference table](/overview/advanced-editor-hub/settings-reference) * [Selectors](/guides/selectors)\* * [Selector reference](/overview/advanced-editor-hub/selector-reference) * [Property reference](/overview/advanced-editor-hub/property-reference) {% hint style="info" %} It's best to briefly read about selectors, the selector reference, and the property reference, then frequently revisit those guides while you work with the features listed in the next few sections. {% endhint %} ## Most commonly used features * [Data-driven decorations](/guides/decorate/data-driven-decorations#decorate-in-the-advanced-editor) * [Flags](/guides/decorate/flags) * [Icons](/guides/decorate/icons) * [Label templates](/guides/decorate/label-templates) * [Popovers](/guides/decorate/popovers) * [Color reference](/overview/advanced-editor-hub/color-reference) * [Filter](/guides/filter#filter-in-the-advanced-editor) * [Showcase](/guides/showcase#showcase-in-the-advanced-editor) * [Focus](/guides/focus#focus-in-the-advanced-editor) * [Cluster](/guides/clustering#cluster-in-the-advanced-editor) * [Controls](/guides/controls#add-controls-through-the-advanced-editor) * [Controls reference](/overview/advanced-editor-hub/controls-reference) ## Less commonly used features * [Bridge](/guides/bridge#bridge-in-the-advanced-editor) * [Custom force-directed layouts](/guides/layouts/force-directed#change-the-forces-underlying-strengths) * [Geo template](/guides/templates/geo) * [Underlays](/guides/underlays) * [Workaround for background images](/guides/decorate/images#add-a-background-image) ## Fun features for power users! * [Scatter plots](/guides/layouts/scatter) * [Imported views](/guides/imported-views) * [Partial views](/guides/partial-views) # @settings reference In the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), the `@settings` block can be used to tweak default settings and add all kinds of powerful features to your view. The `@settings` block supports all decoration properties listed in the [property reference](/overview/advanced-editor-hub/property-reference), as long as you prefix each property with one of the following: * `*-` if you want to apply the rule to all items * `element-` to apply the rule to elements only * `connection-` to apply the rule to connections only * `loop-` to apply the rule to loops only But, `@settings` also supports its own list of exclusive properties. The table below lists all properties that can be used exclusively inside an `@settings` block, describes their effect on the view, and lists valid values for each property (when there are multiple valid values, we've listed them as separate snippets of `inline code`). There are just few more things you should know about the valid values listed below: | Where you see... | You can use... | | ---------------- | ------------------------------------------------------------------------------------ | | `selector` | Any [selector](/guides/selectors) | | `color` | Any CSS web color or hex color code | | `number` | Any number | | `'field name'` | The name of any of your [fields](/guides/fields), wrapped in single or double quotes | | `element type` | Any text/string value | All values are unitless. ## Supported properties
PropertyDescriptionPossible values
attenuationDetermines whether elements and connections maintain their size relative to the background map (available for the Geo template only)on off
background-colorSets the canvas' background colorcolor
background-opacitySets the opacity of items outside of a showcased selection0..1
bridgeActivates bridging. See the bridge guide for more information.element-selector
clusterActivates clustering. See the cluster guide for more information.'field name'element-selector by 'field name'element-selector by 'field name' as 'element type'
cullingDetermines whether elements and connections are hidden when the reader zooms in very closeon off
focusActivates focus. See the focus guide for more information.selector out number
font-cutoffSets the minimum font size at which labels will display when the map is zoomed out. Set to 0 to always display labels, regardless of zoom level.number
foreground-opacitySets the opacity of showcased items
number between 0..1
geo-locationSets the field that will be used to geo-locate elements'field name'
geo-styleSets the style of the geo mapauto streets satellite
ignoreIgnores a selection. See the filter guide for more information.selector
ignore-orphansHides any orphans (elements that have no connections). See the ignore orphans guide for more information.true false
image-cutoffSets the minimum zoom level at which images will display when the map is zoomed out. Set to 0 to always display images, regardless of zoom level.
number between 0..1
includeIncludes a selection. See the filter guide for more information.selector
layoutSets the layout typeforce static scatter
layout-bounds-xmaxSets a maximum x coordinate that grid and guide lines can extend tonumber
layout-bounds-xminSets a minimum x coordinate that grid and guide lines can extend tonumber
layout-bounds-ymaxSets a maximum y coordinate that grid and guide lines can extend tonumber
layout-bounds-yminSets a minimum y coordinate that grid and guide lines can extend tonumber
layout-gravitySets the gravity for the force-directed layoutnumber
layout-gridDetermines whether a grid will be shownon off
layout-grid-colorSets the color of the gridcolor
layout-grid-offsetSets the space between grid linesnumber
layout-grid-widthSets the thickness of grid linesnumber
layout-guide-colorSets the color of guide linescolor
layout-guide-widthSets the thickness of guide linesnumber
layout-guidesSets the x or y coordinate for each guide line, or the origin and radius of a circlex(number)y(number)circle(x, y, r)circle(r)
layout-particle-chargeSets the particle charge for the force-directed layoutnumber
layout-presetChooses a preset version of the force-directed layoutauto dense hairball
layout-spring-lengthSets the spring length for the force-directed layoutnumber
layout-spring-strengthSets the spring strength for the force-directed layoutnumber
layout-xSets the field used to determine elements' x coordinate in the scatter layout'field name'
layout-x-multiplierSets a number that will be multiplied by each elements layout-x field to determine their final x coordinatenumber
layout-ySets the field used to determine elements' x coordinate in the scatter layout'field name'
layout-y-multiplierSets a number that will be multiplied by each elements layout-y field to determine their final y coordinatenumber
notification-colorSets the color of asterisks created by Issuescolor
profileControls whether or not profiles can be openedon off
qualitySets the render qualityfast best
radarDetermines whether a radar will be shownon off
radar-axesSets the labels for radar axesAxis 1, Axis 2, Axis 3...
radar-font-colorSets the color of radar labelscolor
radar-font-familySets the font family of radar labelsfamily-namegeneric-family
radar-font-sizeSets the font size for radar labelsnumber
radar-ring-colorSets the color between radar ringscolor
radar-ring-opacitySets the opacity of radar rings0..1
radar-ring-sizeSets the distance between radar ringsnumber
radar-ring-size-innerSets the radius of the inner radar ringnumber
radar-ringsSets the labels for radar ringsRing 1, Ring 2, Ring 3...
rendererChooses which rendered will be usedcanvaswebgl
scale-maxSets the maximum allowed zoom levelnumber
scale-minSets the minimum allowed zoom levelnumber
selection-colorSets the color of the ring that appears around selected elementscolor
showcaseActivates showcase. See the showcase guide for more information.selector
templateChooses a templatecausal-loopcustomgeosnastakeholderstock-and-flowsystemssystems-leverage
themeSets the view's overall themelight dark
# @controls reference While it's possible to [build controls using the Basic Editor](/guides/controls#add-controls-through-the-basic-editor), using the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) is the only way to unlock the full flexibility of controls. This guide lists each `property` that can be used in the Advanced Editor, each possible `value` the properties can accept, and which `@controls` can recognize the properties and values. There are two reference tables in this guide—the first lists properties for **static** controls (nothing happens when map readers click on these controls), and the second lists properties for **interactive** controls (map readers can interact with the map by clicking on these controls). All values are unitless. If you find a property or a value that's not documented here, [let us know](mailto:support@kumu.io)! [Jump to the reference for interactive controls](#interactive-controls). ## Static controls
PropertyDescriptionValid ValuesLegendImageLabelTextTitleSNA Dashboard
background-colorDefines background color of controlcolortruetruetruetruetruetrue
colorDefines color of control's textcolortruetruetruetruetruetrue
font-familyDefines font family of control's textfamily-name generic-familytruetruetruetruetruetrue
font-sizeDefines size of control's textnumbertruetruetruetruetruetrue
font-styleDefines style of control's textnormal italictruetruetruetruetruetrue
font-weightDefines weight of control's textnumbertruetruetruetruetruetrue
heightDefines height of controlnumbertruetruetruetruetruetrue
marginDefines space between the control and other controls on the mapnumbertruetruetruetruetruetrue
metricsDefines which metrics will be included in the dashboardelement-count connection-count density reciprocity diameter average-degree average-path-lengthfalsefalsefalsefalsefalsefalse
opacityDefines opacity of the control0..1truetruetruetruetruetrue
paddingDefines space between the control's border and its contentsnumbertruetruetruetruetruetrue
srcDefines the source of the imageurlfalsetruefalsefalsefalsefalse
text-alignDefines alignment of text within the controlcenter left rightfalsefalsetruetruetruefalse
valueAny plain text string. Markdown and some HTML allowed.stringfalsefalsetruetruetruefalse
widthDefines width of controlnumbertruetruetruetruetruetrue
## Interactive controls
PropertyDescriptionValid ValuesFilterShowcaseFocusClusterTagged TimelineView Toggle
asDefines how the control is presentedlabels buttons dots dropdowntruetruetruetruetruetrue
background-colorDefines background color of controlcolortruetruetruetruetruetrue
byDefines the field to filter, showcase, or cluster by''Field Name'truetruetruetruetruetrue
colorDefines color of control's text (labels, placeholders, and summaries only)colortruetruetruetruetruetrue
defaultDefines which options should be selected by defaultnone show-all select all ''field value 1', 'field value 2',...truetruetruetruetruetrue
exceptAllows you to remove field values from the available choices''field value 1', 'field value 2',...truetruetruetruetruetrue
font-familyDefines font family of control's text (labels, placeholders, and summaries only)family-name generic-familytruetruetruetruetruetrue
font-sizeDefines size of control's text (labels, placeholders, and summaries only)numbertruetruetruetruetruetrue
font-styleDefines style of control's text (labels, placeholders, and summaries only)normal italictruetruetruetruetruetrue
font-weightDefines weight of control's text (labels, placeholders, and summaries only)numbertruetruetruetruetruetrue
heightDefines height of controlnumbertruetruetruetruetruetrue
labelAdds a label above the control'My Label'truetruetruetruetruetrue
marginDefines space between the control and other controls on the mapnumbertruetruetruetruetruetrue
modeControls how the selection is showcased. normal is the default and showcases the selection plus any connections between the showcased elements. loose showcases the selection plus neighboring elements. strict only showcases the selection itself.normal loose strictfalsetruefalsefalsefalsefalse
multipleControls whether more than one option can be selected at a timetrue false match-alltruetruetruetruetruetrue
onlyAllows you to explicitly define which field values should be included as available choices''field value 1', 'field value 2',...truetruetruetruetruetrue
opacityDefines opacity of the control0..1truetruetruetruetruetrue
optionsAllows you to explicitly define which options should be included as available choices''partial-view-1', 'partial-view-2',...truetruetruetruetruetrue
outDefines the level of connections you'd like to see (out 1: first-degree only, out 2: first- and second-degree, etc.)numberfalsefalsetruefalsefalsefalse
paddingDefines space between the control's border and its contentsnumbertruetruetruetruetruetrue
placeholderThe text to display when nothing is selected
(for as: dropdown only)		stringtruetruetruetruetruetrue
rangeDefines the years that should be includedyear..yearfalsefalsefalsefalsetruefalse
summarySummarizes the options that have been selected
(for as: dropdown only)		stringtruetruetruetruetruetrue
targetDefines which items will be affected by the controlselectortruefalsefalsefalsefalsefalse
widthDefines width of controlnumbertruetruetruetruetruetrue
# Color reference Below are details on the different color palettes and scales that Kumu supports. Use these with the [Color by](/guides/decorate#color-by) tool in the Basic Editor, or use them in the [Advanced Editor](/guides/decorate#decorate-in-the-advanced-editor) with the `categorize()` and `scale()` functions. ## Named color scales Kumu has built-in support for a number of named color scales, including all [ColorBrewer](http://bl.ocks.org/mbostock/5577023) scales. ### Sequential and diverging Both sequential and diverging color palettes are great when you are trying to show quantitative data or data that has a meaningful order.
YlGnYlGn
YlGnBuYlGnBu
GnBuGnBu
BuGnBuGn
PuBuGnPuBuGn
PuBuPuBu
BuPuBuPu
RdPuRdPu
PuRdPuRd
OrRdOrRd
YlOrRdYlOrRd
YlOrBrYlOrBr
PurplesPurples
BluesBlues
GreensGreens
OrangesOranges
RedsReds
GreysGreys
PuOrPuOr
BrBGBrBG
PRGnPRGn
PiYGPiYG
RdBuRdBu
RdGyRdGy
RdYlBuRdYlBu
SpectralSpectral
RdYlGnRdYlGn
nauticalnautical
deepseadeepsea
heatheat
flamingoflamingo
coffeecoffee
stoplightstoplight
### Qualitative Qualitative color palettes are best when you are trying to show data with discrete values that don't have an inherent order.
bujumbrabujumbra
neonneon
neon2neon2
olympicolympic
AccentAccent
Dark2Dark2
PairedPaired
Pastel1Pastel1
Pastel2Pastel2
Set1Set1
Set2Set2
Set3Set3
Here's an example of how to use a named color scale: ```scss element { color: scale("net worth", bujumbra); } ``` ## Inverting a color scale Any color scale can be inverted by adding `-inverted` to the name. ## Defining your own color palette You can define your own color palette for elements by using a comma separated list of color values. ```scss @settings { element-color: categorize("community", #5BC1AE, #009CDB, #F6882B, #8E278F); } ``` For [flags](/guides/decorate/flags), the code is slightly different: ```scss @settings { element-flag: "Tags" with #5BC1AE, #009CDB, #F6882B, #8E278F; } ``` ## Setting explicit stops for color values in categorize() It's also possible to specify which value should receive a certain color for elements. ```scss @settings { element-color: categorize("element type", #5BC1AE "Person", #009CDB "Organization", #F6882B "Region"); } ``` For [flags](/guides/decorate/flags), the code is slightly different: ```scss @settings { element-flag: "Tags" with #5BC1AE "Person", #009CDB "Organization", #F6882B "Region; } ``` # Property reference Beneath views, Kumu uses a powerful CSS-based language to control the appearance of your maps. If you're familiar with CSS, the advanced view editor will quickly become your best friend. The view builder only exposes a small set of the available properties. Being able to write views by hand is the only way to harness the full power of Kumu. **Note:** We've adopted standard CSS properties and values wherever possible, straying where conventional values were irrelevant or misleading (eg `display: map` vs `display: block`), and adding properties specific to Kumu (such as `bullseye-color`). There are just few more things you should know about the valid values listed below: | Where you see... | You can use... | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `color` | Any CSS web color or hex color code | | `colorPalette` | The name of one of our [color palettes](/overview/advanced-editor-hub/color-reference) | | `'Field name'` | The name of any of your [fields](/guides/fields), wrapped in single or double quotes | | `number` or `[number]` | Any number | | `number number` | Any two numbers separated by a space, e.g. `5 10` | | `0` | Only the number `0` | | `0..1` | Any number between `0` and `1` | | `generic-family` | The name of any CSS web safe font family | | `family-name` | The name of any font family. `freight-text-pro` and `proxima nova` will always work, but other non-web-sage font families will only work if your reader has the font installed on their device. | | `icon-name` | The name of any icon from the [Font Awesome](https://fontawesome.com/icons) collection. | | `icon-style` | `solid` or `regular` | | `https://...` | Any URL. URLs starting with `https` are safest and will work best within Kumu. | | `string template` | Any combination of letters, numbers, [supported markdown (including raw HTML)](/guides/profiles/markdown), or names of your fields wrapped in double curly brackets `{{}}`. Wrap the entire thing in double quotes. See our [label templates guide](/guides/decorate/label-templates) for examples. | | `auto`, `background`, `bold`, `bottom`, `center`, `circle`, `clip`, `contain`, `cover`, `dashed`, `gradient`, `hidden`, `inherit`, `italic`, `manual`, `map`, `none`, `normal`, `off`, `rectangle`, `solid`, `square`, `url`, `visible`, or `wrap` | That exact keyword | All values are unitless. ## Supported Properties The table below lists all of the properties recognized by elements, connections, and loops. Hover over the information icon at the far right of the table rows to see additional details and valid values for each property (when there are multiple valid values, we've listed them as separate snippets of `inline code`). If you find a property or a value that's not documented here, [let us know](mailto:support@kumu.io)!
PropertyDescriptionValuesElementsConnectionsLoops
arrow-colorOverride the arrow color for a connection.colorfalsetruefalse
arrow-heightUsed in combination with arrow-min-height to set arrow height.numberfalsetruefalse
arrow-min-heightUsed in combination with arrow-height to set arrow height.0falsetruefalse
arrow-min-widthUsed in combination with arrow-width to set arrow width.0falsetruefalse
arrow-visibilityControls arrow visibility for directed connections.visible hiddenfalsetruefalse
arrow-widthUsed in combination with arrow-min-width to set arrow width.numberfalsetruefalse
border-colorControls border color.colortruetruefalse
border-opacityControls border opacity.0..1truetruefalse
border-widthControls border width.numbertruetruefalse
bullseye-colorControls bullseye color.colortruefalsefalse
bullseye-opacityControls bullseye opacity.0..1truefalsefalse
bullseye-sizeControls bullseye size.0..1truefalsefalse
bullseye-visibilityControls bullseye visibility.visible hiddentruefalsefalse
colorControls shapes' color. (gradient only available for connections)

color

or

gradient(color, color)

truetruefalse
curvatureControls line curvature.0..1falsetruefalse
dashControls the length of connection dashes (first number) and the distance between them (second number).number numberfalsetruefalse
delay-colorControls color of delay markings.color inheritfalsetruefalse
delay-heightControls height of delay markings.numberfalsetruefalse
delay-positionControls delay markings' position along the connection.0..1falsetruefalse
delay-stroke-widthControls width of delay markings.numberfalsetruefalse
delay-visibilityControls visibility of delay markings.visible hiddenfalsetruefalse
delay-widthControls space between delay markings.numberfalsetruefalse
displayControls inclusion in the map. Hidden objects will be fully removed from the map.map nonetruetruefalse
flagDefines field and color scale for flags.'Field name' with colorPalettetruefalsefalse
flag-offsetControls space between flags and their elements.numbertruefalsefalse
flag-sizeControls thickness of flags.numbertruefalsefalse
font-colorControls label font color.colortruetruefalse
font-familyControls label font family.family-name generic-familytruetruefalse
font-sizeControls label font size.numbertruetruefalse
font-styleControls label style.normal italictruetruefalse
font-weightControls label font weight.normal boldtruetruefalse
heightControls height of elements that are squares and/or rectangles.auto numbertruefalsefalse
iconAdds an icon as the item's image.icon-name icon-name icon-style offtruefalsefalse
icon-colorControls the icon color.colortruefalsefalse
image-sizeControls image size.cover containtruefalsefalse
image-urlProvides source url of image.url(http://...)truefalsefalse
image-visibilityControls image visibilityvisible hiddentruefalsefalse
labelReplaces the default label with a label template.none string templatetruetruetrue
label-visibilityControls label visibility for all types.visible hiddentruetruefalse
layerControls whether an item is in the foreground or background.auto backgroundtruetruefalse
lengthControls connection resting length.numberfalsetruefalse
marginControls amount of space between the border of an element and its connections.number nonetruefalsefalse
opacityControls loop label opacity and element opacity.Number between 0..1truetruetrue
outline-colorControls the color of selected elements' outlines.colortruefalsefalse
outline-offsetControls the distance between selected elements and their outlines.numbertruefalsefalse
outline-opacityControls the opacity of selected elements' outlines.0..1truefalsefalse
outline-widthControls the width of selected elements' outlines.numbertruefalsefalse
paddingControls amount of space between the border of an element and its contents (image or bullseye).numbertruefalsefalse
path-opacityControls connection opacity.0..1falsetruefalse
patternControls connection pattern. Equivalent of style.solid dashedfalsetruefalse
pointer-eventsControls whether or not an item can be clicked.auto nonetruetruetrue
popoverSets the popover contentnone string templatetruetruetrue
prepost-insetControls the inset of pre-labels and post-labels.numberfalsetruefalse
prepost-offsetControls the offset of pre-labels and post-labels.numberfalsetruefalse
profileControls whether or not the profile can be openedtrue falsetruetruetrue
scaleControls element and connection scale (multiple of base size).numbertruetruefalse
shadow-colorControls shadow color.colortruefalsefalse
shadow-opacityControls shadow opacity.0..1truefalsefalse
shadow-sizeControls shadow size.1..5truefalsefalse
shadow-visibilityControls shadow visibilityvisible hiddentruefalsefalse
shapeControls shape.circle square rectangletruefalsefalse
sizeControls base size.numbertruetruefalse
strengthControls connection strength.0..1falsetruefalse
styleControls connection style. Equivalent of pattern.solid dashedfalsetruefalse
text-alignControls alignment of element labels.bottom centertruefalsefalse
text-overflowControls text wrapping and truncating.off auto auto [number] manual wrap wrap [number] clip clip [number] nonetruetruetrue
visibilityControls visibility. Hidden objects will still affect layout and metrics.visible hiddentruetruefalse
widthControls width of elements that are squares and/or rectangles.auto numbertruefalsefalse
# Selector reference Selectors provide a powerful, friendly way to slice through maps, based on [Cascading Style Sheets (CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS) selectors. If you're familiar with CSS, you'll feel right at home. If you haven't seen or used CSS, don't worry! All the selector patterns you'll ever need are documented in this reference. To see examples of how selectors can be used, check out our [general guide on selectors](/guides/selectors). There are two reference tables on this page. The first shows you all the different kinds of selectors you can use in Kumu, and the second table gives details about logical operators that can be used inside of certain selectors. In the first table, you'll notice that the word "slug" appears a lot. A [slug](/guides/slugs) is a piece of text that has had all letters converted to lowercase, all special characters removed, and all spaces and replaced with hyphens. So, when you see something like `type-slug` in the table below, this will be replaced in your custom selector with something like `private-company` or `individual` or another "slug" version of an element type. ## Selectors ## Operators | Operator | Description | | -------- | ----------------------------------------------------------- | | `=` | is equal to | | `!=` | is not equal to | | `^=` | starts with | | `$=` | ends with | | `*=` | text contains | | `~=` | list of values includes (this operator matches full values) | | `>` | is greater than | | `>=` | is greater than or equal to | | `<` | is less than | | `<=` | is less than or equal to | | Selector | What It Selects | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `*` | All elements, connections, and loops | | `element` | All elements | | `connection` | All connections | | `loop` | All loops | | `type-slug` | All elements whose element type slug matches `type-slug` | | `type-slug-connection` | All connections whose connection type slug matches `type-slug` | | `#label-slug` | The item whose label slug matches `label-slug`. | | `#assigned-id-slug` | The item whose [assigned ID](/frequently-asked-questions/how-do-i-avoid-duplicating-data) slug matches `assigned-id-slug`. | | `#system-id` | The item whose system ID matches `system-id`. | | `.tag` | All items whose Tags field contains `tag`. Note that this selector starts with a dot `.` | | `["field name" operator "field value"]` | All items that have a [field name and field value](/overview/kumus-architecture#fields) that meet the condition of the `operator` (valid operators are listed below this table) | | `["field name"]` | All items that have any value in the field whose name matches `field name` | | `[!"field name"]` | All items that have no value in the field whose name matches `field name` | | `:from(selector)` | All connections coming from an item that matches the `selector` | | `:to(selector)` | All connections going to an item that matches the `selector` | | `:directed` | All directed connections | | `:undirected` | All undirected connections | | `:mutual` | All mutual connections | | `:focus` | All items at the root of a [focus setting](/guides/focus) | | `:orphan` | All elements that have zero connections (including connections that have been filtered out) | | `:not(selector)` | All items that do not match the `selector` | | `:loop(selector)` | All items that are part of a loop matching `selector` | | `this-selector --> that-selector` | All items matching `this-selector` connected to items that match `that-selector` | | `this-selector <-- that-selector` | All items matching `this-selector` connected from items that match `that-selector` | | `this-selector <--> that-selector` | All items matching `this-selector` connected to or from items that match `that-selector` | | `this-selector <--connection-selector--> that-selector` | All items matching `this-selector` connected to or from items that match `that-selector` via connections that match `connection-selector` | # SNA / Network Mapping This guide walks you through the basics of network analysis using Kumu. We'll walk through four parts: 1. [Collecting the data](#collect-the-data) 2. [Getting the data into Kumu](#get-the-data-into-kumu) 3. [Using Metrics to analyze your network](#use-metrics-to-analyze-your-network) 4. [Helping others to understand your map](#help-others-understand-your-map) Looking for more background about network analysis before you get started? Check out [Social Network Analysis Made Easy](https://speakerdeck.com/jeffcmohr/social-network-analysis-made-easy): {% embed url="" %} ## Collect the data Data can be collected with a survey, pulled from existing data sources, or populated from your own personal knowledge. #### Surveys Surveys ask participants both relational and demographic questions. There are a number of both free and paid tools for survey analysis: * [Google Forms](https://docs.google.com/forms) (Free) * [Survey Monkey](https://www.surveymonkey.com/) (Free & Paid) * [Survey Gizmo](https://www.surveygizmo.com) (Free & Paid) You can also find survey tools built specifically for social network analysis, for example [sumApp](http://greaterthanthesum.com/sumapp/) or [Polinode](https://polinode.com/). Spend time thinking deeply about the questions in your survey. You can ask open-ended questions: * Who do you work with? * Who do you turn to for new ideas? * Who do you turn to for advice? Or you can ask questions about specific individuals: * How does working with this person affect your energy levels? * How many times have you interacted with this person in the last 7 days? Each of the various relational questions get at a different kind of network. It may be a network of trust, idea sharing & innovation, collaboration, or any other relationships that are important. Here are the three questions from the sample survey: * **Information Sharing Network** - At least twice in the last month, have you received information from this person that you need to do your job? * **Problem Solving Network** - At least twice in the last month, have you gone to this person for help with technical work-related problems? * **Support Network** - At least twice in the last year, have you gone to this person for help with a difficult situation at work? #### Existing data sources Sometimes you'll already have access to the type of data needed to run a social network analysis. You might use email traffic, lists of "friends" or "followers" from a social network, information about board membership, or even data from your CRM platform. The key here is to be both creative and honest about what the data represents. For example, how helpful is the fact that someone is a "friend" of yours on LinkedIn? Have you ever accepted a connection to someone you didn't really know all that well? (We're definitely guilty of this!) A rule to remember: when the data is easy to access or already collected, be thoughtful and intentional about what story you want to tell and which pieces of the data you want to visualize. #### Personal knowledge For certain networks, it's not plausible to collect information via surveys, and you don't have data lying around. In those cases, it's often best to rely on personal knowledge of who knows whom—or even crowdsource this information by pulling together a team of people from the network and building out the links one by one. When you're taking this approach, your dataset will usually be smaller than that dataset you can get from a survey or an existing data source. That's okay! You can still use Kumu to create a great visualization, and if you plan to expand your data in the future, you can build a proof-of-concept map in Kumu that will be ready to grow along with your dataset. ## Get the data into Kumu The first step, before you can get the data into Kumu, is to [sign up for an account](https://kumu.io/join) and [create a new project](https://kumu.io/new). If you're not sure which account type is right for you, check out our [full guide on accounts and plans](https://github.com/kumu/docs/blob/main/overview/accounts-and-plans.md). Once you have your new project open, you can get the data into Kumu in one of two ways: **importing a spreadsheet** or **building by hand**. For more information on imports, [check out our imports guide](/guides/import). If you're building your map by hand, [check out our First Steps guide](/getting-started/first-steps#build-your-map-by-hand) for more guidance. There are a few subtleties to how you structure your data for easiest use within Kumu. We've laid out some of those below: **Use connection type to differentiate relationships among people** Say you ask two questions on your survey: one that asks questions getting at the relationships that represent the **trust** network and another that probes for the relationships that represent the **innovation** network. When structuring your data, use "trust" or "innovation" as the connection type for each connection, and you'll be able to quickly switch between the "trust" and "innovation" network in Kumu using [filters](/guides/filter). **Element types make two (or more) mode networks a cinch** Sometimes you're looking to understand more than just how people are connected to each other. You may want to include organizations, projects, alma maters, and more. Simply differentiate these elements using the element type field and you can easily filter them as needed. **Don't forget about the power of clustering!** [Clustering](/guides/clustering)) makes it easy to turn information stored in the [profile](/guides/profiles) of any element into a dynamic network. Storing information about the organization someone works for within the profile? Use clustering to then transform that data into explicit connections on your map. This can be a big time saver and value-add if you don't already have connection data created. ## Use Metrics to analyze your network Social network analysis metrics provide clues to tell you who may be playing important (or not so important) roles across your network. For example: * **Degree** counts the number of connections attached to each element. Useful for identifying hubs in your network or for predicting single points of failure. * **Betweenness** tells you how many times a given element is the bridge (or bottleneck) between other elements in the network. * **Closeness** tells you how close one element is to all other elements in the network. Useful for identifying which elements can quickly spread good (or bad) information or effects. ![metrics tool](/files/FjtQQc5TX37en1iMYbJR) To learn how to calculate these metrics and more in Kumu, check out our [full guide on metrics](/guides/metrics). ## Help others understand your map At this point, you should have a basic network visualization in Kumu, with valuable information (including metrics) stored in the profiles of each item on the map. Now, it's time to use a few of Kumu's most powerful tools to help other people understand your map. #### Untangle the "hairball" Often, when you visualize a complex network, it looks like a "hairball"—a tangled-up mess of data that isn't very insightful, like this map: ![hairball](/files/GeWoNOt6OmvsnrO2kqu5) If you have this problem, you can use Kumu's layout settings to spread the map out a bit. Here's what the map looks like after applying the "hairball" layout setting: ![hairball layout preset](/files/ZmeuxcGtpTToQanyocVr) It's much less dense, and when you zoom in, it's much more readable! To learn how to change layout settings on your map, [check out our guide on default settings](/guides/default-view-settings). If your network looks like a hairball, you can also use Kumu's **focus** feature to focus on smaller pieces of the network, expanding and contracting your focus with the click of a button. To learn more about focus, [check out the full guide](/guides/focus). #### Decorate your map In Kumu, decorations are one of the best ways to guide your readers through your map. Most people use decorations to change the size and color of elements and connections based on the information their profiles—for example, this map of companies and their relationships uses colors to indicate industry (Higher Education, NGO, Consulting, etc.) and size to represent the betweenness metric: ![Innovation Lab Network](/files/nR6YaKEpzuwOYkr72jWF) But that's just the tip of the iceberg! To learn how to do this and more with decorations, [check out the full guide](/guides/decorate). #### Share your map Sharing your map can be as simple as sending a [shareable link](/guides/share-and-embed) to your readers, but there's no guarantee that they'll be familiar with network maps, let alone how to read and draw insight from one. Depending on your audience, you might want to use **map overviews** or **presentations** to add the right amount of additional context and reading instructions. Map overviews can be added to the [side panel of the map editor](/overview/user-interfaces/map-editor#side-panel), and they're a great tool when you need to provide just a few paragraphs of information, or perhaps an embedded video. ![map overview with video](/files/HV9iFAXwudKSmWr76wOU) If you have a lot of information to give to your readers, or many different views of your map that you want them to see, try [creating a presentation](/guides/presentations). Presentations in Kumu can seamlessly walk readers through different sections or views of your network, slide by slide. {% embed url="" %} For more information on sharing Kumu maps or collaborating with others, [check out the full guide](/overview/collaboration). Still have questions? Don't hesitate to [ask for help](/about-kumu/where-can-i-get-help)! # Systems mapping Looking to create engaging system maps with the power to change hearts and minds? You've come to the right place! Kumu enables you to build interactive maps with narratives, links, video and other background for each element, connection, and loop in the map. {% hint style="info" %} Need more background about system mapping before you get started? \ Check out the [Systems Practice course on +Acumen](https://www.plusacumen.org/courses/systems-practice) or download [The Omidyar Group's Systems Practice workbook](https://github.com/kumu/docs/blob/main/content/Workbook-012617.pdf). {% endhint %} {% embed url="" %} You can also check out some of the Kumu team's thoughts on the system mapping process in one of the following blogs: * [Making Systems More Approachable Part 1](https://blog.kumu.io/making-systems-more-approachable-37896c5cd482) * [Making Systems More Approachable Part 2](https://blog.kumu.io/making-systems-more-approachable-part-2-94c5b552ed3d) * [Systems Practice, Abridged](https://blog.kumu.io/systems-practice-abridged-a5dc8f0beda6) Now, let's get practical! ## Pick a template Kumu comes with several pre-built templates that help you hit the ground running. When you're creating a new system map, you'll be prompted to pick one of these templates—we suggest you start with our system template.

The template picker

## Build your map by hand Building your map by hand is a great choice for most system maps. If your map will have less than 50 elements, you can probably build it comfortably by hand. (If not, check out our guide on [importing data into Kumu](/guides/import).) There are two ways to build a map by hand: 1. The green button 2. Sketch mode #### The green button Click on the green button at the bottom of the map, and you'll see several options: * Add element * Add connection * Add loop * Sketch * Import Try clicking on the first option, **Add element**, to create a new element. Kumu will prompt you to give the element a label and press the `enter` key on your keyboard. Voila! You've added your first element. Add a few more elements, then try selecting **Add connection** from that menu to connect your elements. Once you have a few connections, you can select **Add loop** to create a group of connections. Then, click on the connections you'd like to have as part of your loop. Add a label for the loop and hit `enter` on your keyboard to finish up. ![](/files/PQsJDuur4BmborApZnRu) Some systems thinkers like to mark their loops as "reinforcing" or "balancing". To do this, we recommend adding "R" or "B" (for reinforcing and balancing) to your loop label, which will describe the dynamic at play (R: Trust in Government). You can even add a numerical label if that further helps differentiate your loops or guide readers through the story (R15: Trust in Government). To edit an existing loop, click on its label on the map, then click the edit icon () in the profile, or press `L` on your keyboard. You can then click connections to add/remove them from the loop. We automatically position the loop label at the center of the connections, but you can click-and-drag the loop label to another location if you want to reposition it. To move an entire loop (including all of its connections), hold down the `alt` key on your keyboard, then click-and-drag the loop label. {% hint style="info" %} Tip: Use keyboard shortcuts to speed up the building process! Press `E` to add an element, `C` to add a connection, and `L` to add a loop. {% endhint %} #### Sketch mode If you're building a system map by hand, you should definitely give sketch mode a try! Click the green button and select **Sketch** to activated sketch mode. Once sketch mode is activated, you can add an element by clicking anywhere on the map, and you can add a connection by clicking and dragging from an existing element. {% hint style="info" %} Quickly enter sketch mode by pressing `K` on your keyboard, and press the `esc` key to exit. While in sketch mode, you can move elements by holding the `alt` key on your keyboard, then clicking and dragging the element. {% endhint %} ## Refine your map's appearance Once you've added the elements, connections, and loops to your system map, it's time to start refining the visual appearance. Below are a few techniques that will be helpful along the way. #### Change the curvature of connections Often, you'll want to change the curvature of a connection to make it fit better around the rest of the map. To do this, just click-and-drag the connection, close to the middle of it (if you click-and-drag on either end of the connection, you'll detach it from the element on that end). You'll see the curvature changing, and once you release, the connection will stay in that position. Note this only work for connections where both elements that are part of that connection are pinned in place (which is the default setting on the system template). ![curved connections in a system map](/files/j7eC5AZFNJl0IsqvxWFn) #### Change connection arrows In the systems template, connections are "directed" by default, meaning that they will show up with an arrow on one end. But, you might sometimes want to flip the direction of the arrow, remove the arrow, or add arrows to both ends of the connection. To flip the direction of a connection, you can click on the connection that you want to change, then click the direction button **REVERSE** to flip the connection. To remove an arrow, you can click "Undirected", and the arrow will disappear. To add an arrow on the other side of the connection, select "Mutual". {% hint style="info" %} To change the arrows for multiple connections at a time, hold down `Shift` on your keyboard and click on connections to select more than one. Then, follow the same steps above to make your changes.\ \ You can also press `Shift` + `C` on your keyboard to select all connections. {% endhint %} #### Add delay markings Sometimes, system mappers will add two parallel lines intersecting a connection to indicate that there is an implicit time delay in the relationship—one factor *does* affect the other, but it might take a long time to do so. To add this delay marking to a connection, you can select the connection, then click the delay icon in the lower right of the connection's profile. {% hint style="info" %} To add delay markings for multiple connections at a time, hold down `Shift` on your keyboard and click on connections to select more than one. Then, follow the same steps above to make your changes.\ \ You can also press `Shift` + `C` on your keyboard to select all connections. {% endhint %} #### Force line breaks in element labels In the system template, element labels are placed in the center of your element circles by default. This usually looks great, but sometimes, your labels might be overflowing past the boundaries of the circle. To fix this issue, you can manually add line breaks in your labels to make sure your labels fit inside the circles as best as possible. To manually line break, just type a double space wherever you want to see a line break in the label of any element, connection, or loop. ``` A long element label // no line break A long element label // line break betwen "long" and "element" ``` Or you can choose to have Kumu enter a line break automatically at a certain number of characters. Visit [this guide](/frequently-asked-questions/how-do-i-control-text-wrapping) to learn how to do that. #### Change colors and sizes One of the best ways to make your system map look sharp is to decorate your elements and connections with color. If some elements are more important than others, you can also change their size to make sure they stand out. To learn how to take these steps, [check out our full guide on decorations](/guides/decorate). ## Add rich detail to your map Once you've built your map #### Marking connections as same or opposite If you're looking to indicate whether a connection has a same or opposite causal relationship (whether the first element increases or decreases the second element), there are a few ways to go about it: **Using the connection label** If you're just looking to have "same" or "opposite" show up on the connection as a label, click to select the connection and then add "same" or "opposite" as the label. You can do this by clicking "add label" placeholder in the connection profile. You'll see the text appear on the connection on the map. **Using types** Another option is to add "same" or "opposite" as the connection type. If you're using the systems template, your connections will automatically be decorated: "same" connections will be solid lines, and "opposite" connections will be dashed lines. Some system mappers like to go even further and include not just whether a connection is same or opposite, but also the **+** and **-** labels on the "from" and "to" ends of a connection. We've customized the behavior of the type field for connections to allow for creation of these labels. The table below lists the value to add as the connection type and the corresponding behavior it creates: | Value | Behavior | | ------ | ---------------------------------------------------------------------------- | | **+** | adds a **+** to the "from" end of the connection | | **-** | adds a **-** to the "from" end of the connection | | **++** | adds a **+** to both ends of the connection | | **--** | adds a **-** to both ends of the connection | | **+-** | adds a **+** to the "to" end and a **-** to the "from" end of the connection | | **-+** | adds a **-** to the "to" end and a **+** to the "from" end of the connection | \ Simply add the value to the "type" field on any connection: ![connection type](/files/U5hpJj6V2vB0GeNdLH05) And we'll automatically add the pre- and post-labels for you: ![pre and post labels](/files/mWKSICEti67vVm5dnx6F) **Using pre-labels and post-labels** We also support custom pre-labels and post-labels—just add two new [fields](/guides/fields) to your connections and name the fields `Prelabel` and `Postlabel`. Anything you type in those fields will appear at the start and end of the connection. ![custom post-labels](/files/koDHUCYJFmOWpd5rLRJv) #### Add narratives and other background information One of the challenges with many system mapping platforms is that they don't allow for extensive narratives and information to be saved for each element, connection, loop and map. Instead, you're left with a simple graphical map that's nearly impossible to decode on your own. Kumu allows you to add rich narratives and information easily for any and all levels of your map. Start by using the map overview to add a description of the overall map and key dynamics at play. Then, click on a loop and use its profile to include a narrative that describes the behavior, both current and historical, and includes links to any supporting research that led to the creation of the loop. For specific elements, provide a quick definition to ensure there isn't confusion. And for connections, include a brief description of why two elements are causally related. Don't forget to cite your sources! ![System map in Kumu](/files/EUX8KtjQCyymbW6ePWw3) #### Strengthen your narrative using links to elements and loops Ever gotten lost in someone's description of a system map, wondering why you can't find what they're talking about in the map narrative? Good news! Kumu allows you to create links to elements and loops within your description. When someone hovers their cursor on the link, the map will pan and zoom to that location on the map. To learn add these links, [read more about our Lists widget](/guides/widgets#lists). #### Add trends, needed change, and other information To add custom data to your map, like trends or needed change, try [creating new fields](/guides/fields) and filling them out for each element, connection, or loop. It is often quite helpful to walk a group through the exercise of discussing how a given factor has been trending over time. Is the relevance or availability for the factor increasing or decreasing? If you save this information in a custom field, you could, for example, select all the factors that have been decreasing, and use [decorations](/guides/decorate) to color them dark red. Another helpful piece of data is whether a given factor needs to significantly increase, increase, stay the same, decrease, or significantly decrease going forward. By using this data and adding a color scale to the values, you can quickly see where the most change needs to happen in a given map. You can even add data like **% complete** to be able to track the status of your implementation efforts and your progress with a systems intervention. Use a color scale to automatically darken the elements as they reach a higher completion percentage, and lighten them if the completion percentage is low. The great part about Kumu is you don't need to just pick one of these ways to decorate! Using [views](/guides/views), you can easily switch between different perspectives to highlight different information. ## Share your system map Now that your map is built, refined, and enriched in Kumu, it's time for the real work to begin: sharing! In Kumu, it's possible to [create a shareable link](/guides/share-and-embed) for your map, but we recommend [creating a presentation](/guides/presentations) instead, so you can break your system map down into smaller pieces, explaining each one to your map readers. ![presentation slides](/files/7d84WxitM2XL55flzcR5) When you finish your presentation, you'll be able to send a link to your readers, embed it on a website, or even project it onto a screen. Published presentations are fully interactive, so viewers will be able to zoom in and out, click on loops to see narratives, and explore your system map in its entirety. # Systems Practice workbook Are you working with the Systems Practice workbook, either through the [+Acumen course](https://www.plusacumen.org/courses/systems-practice) or directly with The Omidyar Group? If so, you're in the right place. This guide provides a step-by-step approach on how to use Kumu alongside a systems practice. ![](/files/YyrYA6b7OL3XXAiXjp7b) [Download the TOG Systems Practice workbook](https://github.com/kumu/docs/blob/main/content/Workbook-012617.pdf) **New to using Kumu?** Kumu is a collaborative, web-based platform for creating interactive system maps. If you're not already familiar with Kumu, click on the links below to explore existing projects build using Kumu: * [Hewlett Foundation’s The Madison Initiative](https://kumu.io/hewlettfoundation/hewlett-foundation-madison-initiative) * [Hawaii Quality of Life](https://hiqol.kumu.io/hawaii-quality-of-life) ## Creating your first project If you don't already have a Kumu account, sign up for one by visiting . Once you've created an account, visit your [dashboard](https://kumu.io/dashboard) and [create a new project](https://kumu.io/new). #### Choosing a template Since you're building a system map, make sure to choose the "systems" template.
#### Inviting someone to collaborate If you'd like to collaborate on your map with other team members, open your map and then use the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left corner to access the project settings. Click on the **MEMBERS** section, then add an email address to invite someone to collaborate. If that person already has a Kumu account, they'll immediately get access. If not, we'll send an invitation asking them to sign up for Kumu, then we'll automatically add their new account to the project. ![](/files/0H4tqNKtR64NYj2xjWqz) ## Building your first loop Watch this video for an overview on how to build your first loop in Kumu: {% embed url="" %} #### The green button Click on the green button at the bottom of the map, and you'll see several options: * Add element * Add connection * Add loop * Sketch * Import Try clicking on the first option, **Add element**, to create a new element. Kumu will prompt you to give the element a label and press the `enter` key on your keyboard. Voila! You've added your first element. Add a few more elements, then try selecting **Add connection** from that menu to connect your elements. Once you have a few connections, you can select **Add loop** to create a group of connections. {% hint style="info" %} Tip: Speed up this process by using keyboard shortcuts! Press `E` to add an element, `C` to add a connection, and `L` to add a loop. Or, hold `alt` on your keyboard, the click the map to add an element. Hold `alt` and click-and-drag from an element to create a connection. {% endhint %} #### Sketch mode If you're building your map by hand, you should definitely give sketch mode a try! Click the green button and select **Sketch** to activated sketch mode. Once sketch mode is activated, you can add an element by clicking anywhere on the map, and you can add a connection by clicking and dragging from an existing element. {% hint style="info" %} Quickly enter sketch mode by pressing `K` on your keyboard, and press the `esc` key to exit. While in sketch mode, you can move elements by holding the `alt` key on your keyboard, then clicking and dragging the element. {% endhint %} #### Indicating the causality of a connection Whenever you add a connection, it's a good practice to indicate the causality of a connection (how one factor affects another). The Systems Practice guide recommends using the following options: * ++ (as one factor increases, the other also increases) * \-- (as one factor decreases, the other also decreases) * +- (as one factor increases, the other decreases) * -+ (as one factor decreases, the other increases) To indicate the causality of a connection, first click on the connection so that the [profile](/guides/profiles) appears on the left side of your screen. You'll see a placeholder at the top that says "add connection type". Click that placeholder, then choose which of the above best represents the causality of the connection. You'll then see the corresponding "+" or "-" appear at the ends of the connection. #### Creating a loop label You'll continue adding elements and connections until you have one or more loops. It can be helpful to explicitly name the loops you are building by adding a loop label. To add a loop label, click the green button and then choose "add loop". You then need to click on each connection that is part of the loop, then add a loop label, and finally hit enter. Now if you click on the loop label, you'll see a profile for the loop show up on the left hand side. Use this to include a narrative of the dynamics of the loop. **What should I use as a loop label?** We recommend using a combination of "R" or "B" (for reinforcing and balancing) plus a short label for the dynamic at play (R: Trust in Government) and even a numerical label if that further helps differentiate your loops (R15: Trust in Government). **Made a mistake or need to edit the loop?** To edit an existing loop, click on the loop label and then click the edit icon . You can then click connections to add/remove them from the loop. #### Moving elements and loops and reshaping connections You can click and drag any element to move its location. You can also change the curvature of a connection by clicking and dragging the middle of the connection. If you want to move just the loop label, simply click and drag the label. If you'd like to move the loop label along with all the elements and connections in that loop, hold `alt` or `option` on your keyboard, then click and drag the label. ## Adding additional background and context using profiles Kumu makes it easy to add additional information about each element, connection, and loop using the [profile](/guides/profiles). #### Leverage analysis If you're using the +Acumen Systems Practice Course project, you'll automatically have a field listed in the profile called "leverage analysis". Click to edit the value of this field and you'll see there are 5 choices: * Frozen * Energy for change * Mixed bag * Bright spots * Ripple effects Use this field to indicate which elements, connections, and loops fall into each of the above categories. #### Defining elements/factors It can be helpful to have more than just a few works explaining what each factor is on your map. Add a definition of the factor and try linking out to other websites and sources that contain more information about that factor. You'll see a dashed rectangle towards the top of the profile for an element. Click where it says "add description" and then type in your definition and paste in any relevant links. Here's an example of a profile for an element with additional context included: ![System map in Kumu](/files/EUX8KtjQCyymbW6ePWw3) #### Custom fields Looking to track more information about each element, connection or loop? You can easily add a new field by clicking the "+ New Field" button in the profile of any element, connection or loop. For example, you might add a "Stakeholder working on this area" field and use that to list the relevant people and organizations working on a given element, connection, or loop. ## Bringing your map to life with decorations Once you've added additional background and context using the profile, you can then bring that context to life by creating [decorations](/guides/decorate) based on the values you've saved to the profile. Let's run through an example to color-code elements by the values in their leverage analysis field. 1. Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map to open the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) 2. Next to **Color by**, use the dropdown to select "leverage analysis" And you're done! All elements will now be be marked with colored arcs, and each colored arc represents one of the different options in your leverage analysis field. These arcs are called [flags](/guides/decorate/flags), and they are a decoration created specifically for fields that can hold more than one value. Flags are just one of many different element decorations in Kumu: ![Element decoration options](/files/jRInJdxoDuyDwetjB2zz) To learn how to create different element decorations, how to decorate connections, how to decorate specific groups of elements, and more, be sure to check out our [full guide on decorations](/guides/decorate). ## Refine your view Great work so far—you've created a project, started building your first map, and even added decorations to liven things up. But as you expand your map with more information, you will probably want to view different slices of the information at different times, so you can tell a story without overwhelming your map readers. To do that, you'll use **filter**, **focus**, **showcase**—four different ways to refine what is visible or dominant in the map. Follow these links for the full guides for each tool: * [Filter](/guides/filter) * [Focus](/guides/focus) * [Showcase](/guides/showcase) {% hint style="success" %} You've worked through Kumu's guide for Systems Practice—nice job! For additional help, you can browse our other guides or email us at . {% endhint %} # Activity feed With the activity feed in each project (an exclusive feature for [Pro workspaces](/guides/pro-workspaces)), you can keep tabs on who's working in the project and what kind of changes they're making. When multiple people are working inside a project, activity feeds are great for keeping everyone organized and giving help where it's most needed. ![Activity feed](/files/6c7ZKOjUDVO4ZKpwDEtU) To open up the activity feed pane, open up any project, then open the project settings menu (click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left of the screen). Click on "Activity" in the sidebar to see all kinds of project changes—adding new elements, editing profiles, updating views, creating new maps, etc. It will also show you who made those edits and when. Activity feeds are an exclusive feature for [Pro workspaces](/guides/pro-workspaces). If you [transfer an existing project](/guides/project-admin) into a Pro workspace, its activity feed will show all historical activity (not just the activity that happens after you transfer the project). # Add-ons Kumu offers a number of free and paid add-ons that give your project access to powerful features beyond Kumu's base functionality. All projects (public and private) have access to the same set of add-ons. Add-ons are activated on a project-by-project basis. To activate add-ons or adjust their settings, open [Project settings](/overview/user-interfaces/settings#project-settings) and select **Add-ons** from the sidebar. ## Free add-ons * [Classic SNA Metrics](/guides/metrics) * [Community Detection](/guides/metrics#community-detection) * [Google Sheets](/guides/import/google-sheets) * [Disqus](/guides/add-ons/disqus) # Disqus [Disqus](https://disqus.com/) is one of the leading comment systems. This add-on allows you to add a comment thread to every element, connection, loop, and map overview. ![](/files/daLxdCWs47T0zdQOfU7R) ## Installing the add-on First, if you don't have a Disqus account yet, you can [create a free account](https://disqus.com/profile/signup/). After you are logged into Disqus, you can follow [their Publisher Quick Start guide](https://help.disqus.com/en/articles/1717056-publisher-quick-start-guide). As you work through that guide, you'll set up a new Disqus site and be given a **shortname** for your site—you can find that below the box where you enter your site name, as shown in the image below: ![Disqus shortname](/files/5McCFQAdGxelUPqe8fMp) Copy that shortname, then return to Kumu, and open up the Add-ons menu in [project settings](/overview/user-interfaces/settings#project-settings). ![](/files/ujwinz8EKXVzE6r4pbTp) Activate the Disqus add-on by pasting in the shortname you copied before. ![](/files/3n8EK68ZnZM1EAdujMRL) Voilà! You'll now see the Disqus comment box on each element, connection and loop profile (as well as the map overview). # Bridge Kumu's **bridge** feature allows you to automatically draw connections between any two elements that have a "mutual friend"—an element in between that they're both connected to. For example, if two people are connected to an organization on your map, you can tell Kumu to bridge over the organization, connecting those two people directly and hiding the organization from view. ## Bridge in the Basic Editor The easiest way to bridge over elements is with the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor). Open the Basic Editor, then click **More Options**, and select **Build bridges across mutual connections**. Use the **Bridge** interface to set up rules for bridging over elements that meet a given [selector](/guides/selectors). ![](/files/xgPBPnWTfYKEd1K3yB9v) {% hint style="warning" %} **Kumu's Bridging feature has two caveats to remember:** * If your connections are *undirected*, Kumu will create two connections between the bridged elements. If you wish to de-duplicate these connections, [please follow this guide](/frequently-asked-questions/how-do-i-collapse-duplicate-connections). * If your connections are *directed*, Kumu will only bridge the elements where one connection is incoming and the other connection is outgoing. If all the connections are incoming to a common element, it doesn't work. As a workaround, you can use the "KUMU\_BRIDGE example" tab[ in this Google Sheet with custom Kumu formulas](https://docs.google.com/spreadsheets/d/1qRhkn6qECtBaAncWykMa0hAG97jPK6q_bODrwntqze8/edit?usp=sharing) (Click "File" > "Make a copy" to create your own editable copy of the sheet). If any of the above is unclear, don't hesitate to reach out to for help! {% endhint %} ## Bridge in the Advanced Editor To bridge using the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), here's the basic syntax: ```scss @settings { bridge: selector; } ``` `selector` can be any valid [element selector](/guides/selectors). You can separate multiple selectors with commas to bridge over multiple different groups of elements. For example, lets say you had a map of people connected to projects and organizations, and you wanted to connect people to people. Here's how you could use bridging to accomplish that (assuming project elements have the element type "Project", and organization elements have the element type "Organization"): ```scss @settings { bridge: project, organization; } ``` Voila! You've now mapped a detailed network of people, without having to gather additional data or re-structure your existing data. #### Combine clustering and bridging Bridging can also be used in combination with [fine-tuned clustering](/guides/clustering#fine-tune-cluster-settings) to draw connections directly between two elements based on the information in their fields. In the example above, imagine that, instead of a network of people, projects, and organizations, you only had: * A group of elements representing people * A "Projects" field inside each element, containing a list of each person's projects * An "Organization" field inside each element, indication which organization each person is affiliated with. Here's how you would cluster and bridge to build a network of people connected to other people, based on the projects and organizations in their fields: ```scss @settings { cluster: person by "Projects" as "Project", person by "Organization" as "Organization"; bridge: project, organization; } ``` When reading this code, Kumu will follow these steps: 1. Create a **new element** for each project and organization, with the element types set to "Project" and "Organization" respectively 2. Draw connections **from** each person **to** their projects and their organization 3. **Bridge** over the projects and organizations, connecting people directly to other people You can also bridge between the elements created by clustering. Let's say you were working with that same dataset (elements represent people, with project and organization data stored in fields) and you wanted to see a network of organizations connected to other organizations. Here's how you can do that: ```scss @settings { cluster: person by "Organization" as "Organization"; bridge: person; } ``` And remember: all of these settings are saved in [views](/overview/kumus-architecture#views), so you can quickly toggle between different bridge and cluster settings, showing radically different versions of your network without changing the underlying data in any way. Bridging has the ability to create a lot of new connections—so many that they might bog down your map! If you notice your map freezing or moving slowly after you bridge, check out our guide on [Kumu's data limits](/frequently-asked-questions/how-much-data-can-kumu-handle) for more tips on how to improve speed. # Cluster Clustering is a powerful tool that allows you to connect elements based on the data in their [fields](/guides/fields), and it's particularly useful on stakeholder and network maps. When clustering is activated, Kumu will create new elements to represent each possible value for a field of your choice, and it will draw a connection between your elements and the value(s) in their field. Here's a visual example—musical artists clustered by their genre: ![cluster by element type](/files/2inTc6iDAM12K9PuVYJl) This guide will make you an expert on clustering, one of Kumu's most unique and powerful tools! {% hint style="info" %} Before you start: [use fields](/guides/fields) to add additional information to your elements, connections, and loops. {% endhint %} ## Why is clustering valuable? There are hidden relationships in much of the data you have stored in spreadsheets; they're just not stored explicitly as connections. For example, you probably have a spreadsheet full of contacts, with one column storing the person's name and another column storing the organization she works for. If you imported this directly into Kumu, you'd end up with a map like this: ![Elements with no relationships](/files/9PZOb1ywBx9c9WEtaUJP) Not that eye opening, right? You could click on each element to open its profile, allowing you to see each person's organization, but it would take you a long time to gain any insight into your data. If you **cluster** these people by their organizations, you can start to get a better understanding of your network: ![Elements with relationships](/files/DkyQ5f3Sqq9yeRQMm19b) *Voila!* We used clustering to transform a rigid spreadsheet into a relationship map of all the people and organizations they work for. ## Cluster in the Basic Editor To set up your first cluster, click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map to open the Basic Editor, and use the dropdown next to **Connect by** to select a field. Every dataset is unique, but here are some ideas to get you started: **If your elements are people, cluster by...** * Tags * Skills * Teams * Interests * Projects * Organization * City **If your elements are organizations, cluster by...** * Tags * Initiatives * Populations served * Funding sources * Board members * Region * Sector If you need to restrict clustering to certain elements, cluster by more than one field, or customize the element type of the elements created by clustering, [learn how to fine-tune your cluster settings](#fine-tune-cluster-settings). ## Cluster in the Advanced Editor If you prefer working in the Advanced Editor, you can use the `cluster` property in the `@settings` block to activate clustering. Here's the simplest version of the cluster syntax: ```scss @settings { cluster: "Field"; } ``` Just replace `Field` with the name of any field in your project, and any element with data in that field with be clustered! If you need to restrict clustering to certain elements, cluster by more than one field, or customize the element type of the elements created by clustering, [learn how to fine-tune your cluster settings](#fine-tune-cluster-settings). ## Fine-tune cluster settings When you're using the Basic Editor's **Connect by** tool or the simplest version of the Advanced Editor's cluster syntax, cluster settings follow three default rules: 1. All elements on the map will be clustered by the field you chose. 2. You can only cluster by one field. 3. The new elements that get created by clustering will use the name of the cluster field as their element type (for example, if you cluster by "Organization", the created elements will have the element type "Organization"). These default rules often won't cause any problems for your map, but there are some cases where you will want to override them. To do that, you can use either the Basic Editor or Advanced Editor to fine-tune your cluster settings. ### Fine-tune in the Basic Editor To fine-tune your cluster settings in the Basic Editor, click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)to the right of the **Connect by** tool, and your Basic Editor will show you the **Cluster Settings** menu: ![Cluster basic editor](/files/EasfTuEHKzXyNXBi59Iz) Click the **Add rule** button to create a new cluster rule. Then, click next to "Connect" to bring up the Selector Builder, which allows you to narrow the [selection](/guides/selectors) of elements that will be clustered. Click next to "by" to choose which field those elements will be clustered by, and click next to "as" to change the element type that will be assigned to the elements created by clustering. (Wondering when it's useful to fine-tune the element type? [Jump to the explanation](#when-is-it-useful-to-fine-tune-element-type).) If you want to cluster by more than one field, just click the **Add rule** button and repeat the process! ### Fine-tune in the Advanced Editor In the Advanced Editor, here's the syntax for fine-tuned clustering: ```scss @settings { cluster: selector by "Field" as "Type"; } ``` Replace `selector` with any valid [selector](/guides/selectors). Replace `Field` with the name of the field you want to cluster by, and replace `Type` with the value that Kumu should set as the element type for each element created by clustering (make sure your `Field` and `Type` are wrapped in double quotes). (Wondering when it's useful to fine-tune the element type? [Jump to the explanation](#when-is-it-useful-to-fine-tune-element-type).) Here's an example that clusters all elements with the element type "Person" by their organization. The organizations that are added to the map will have the type "Organization". ```scss @settings { cluster: person by "Organization" as "Organization"; } ``` Multiple cluster rules can be added by separating them with a comma: ```scss @settings { cluster: person by "Organization" as "Organization", organization by "Sector" as "Sector"; } ``` ### When is it useful to fine-tune element type? Fine-tuning the element type is useful when you want to make sure that Kumu re-uses existing elements instead of creating new elements through clustering. When Kumu is about to create a new clustering element, it first searches the entire project for an element with a matching Label and Type. If it finds a match (on any map), it will re-use that element (complete with any Description, Tags, and custom field data as well). One use case for this feature is cross-matching multiple fields, such as "Skills needed" and "Skills offered". In that case, you're probably looking to see the overlap between who's looking to learn a skill and who might be able to teach it. To start, you would cluster all elements by "Skills offered", then add a second rule to cluster all elements by "Skills needed". If you don't customize the type of the elements created by this cluster setting, the types will default to "Skills offered" and "Skills needed", and you'll get two separate elements for each skill: one with the type "Skills offered" and the other with the type "Skills needed". ![cluster default types](/files/bw05i8PrjJ9eI8OFuLqu) But, if you set the element types to "Skill" for both clustering rules, Kumu will create only one element for each skill value—even though the values originated in different fields. ![cluster customized types](/files/tVqFkBCqEMGsVff6eJiz) ## Limiting which fields can be clustered If you'd like to hide certain fields from your Cluster Settings dropdown menus, you can click on an element, click on the downward arrow next to the field name, and use the field settings to disable clustering: ![clustering menu](/files/GLkrW0zmjyoG9lWp4NLH) If you want to disable clustering on any of the core fields (label, description, tags, or type), you can click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) , click **FIELDS**, select the field you want to disable, and un-check the clustering box in the Advanced Settings: ![advanced settings clustering menu](/files/zKSJ8jv1stMGpveDpE6v) # Controls Controls allow you to customize how people interact with your maps by adding buttons, dropdowns or toggles to your map. You can also use them to overlay metrics, images, text and more on! Interactive controls can be used to transform the current view's setting too, such as filter, focus, and clustering. {% embed url="" %} {% hint style="info" %} Want to dive a little deeper into controls? \ Check out our [Taking Control of Kumu webinar](https://youtu.be/H4mPfRw2cqM) {% endhint %} ### Add controls through the Basic Editor You can use the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) to add a few simple types of controls to your map. Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the editor, then click **Add custom control**. Kumu will open up the controls builder, with a few options pre-selected: ![controls builder ui](/files/TFeJLr8P27ZidkbYThuC) Use the dropdown menus in the controls builder to set up your control, then, when you're done, click the back arrow to return to the main screen, and click **SAVE**. {% hint style="info" %} Want to remove unneeded controls? You can use the [remove unneeded controls](<#remove-unneeded controls>) section of this guide to help troubleshoot. {% endhint %} ### Add controls through the Advanced Editor To unlock the full set of flexible controls features, you can use the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor). Here's an example of what controls look like in the Advanced Editor: ```scss @controls { top { showcase { by: "Element type"; } } } ``` In general, controls are defined with the `@controls` block, grouped into regions, and customized using properties. You can add multiple controls to a region, and even override or move Kumu's built-in controls. Here's the general syntax that shows how multiple regions can be used, and how multiple controls can be added to the same region: ```scss @controls { region { control { property: value; property: value; .... } another-control { property: value; property: value; ... } } another-region { some-other-control { ... } } } ``` #### Regions Adding a custom control to your map starts by picking where you want to place the control. Controls can be assigned to one of six **regions** on the map: * `top` * `top-left` * `top-right` * `bottom` * `bottom-left` * `bottom-right` ```scss @controls { top-left { title { value: "This map has a title!"; } } } ``` #### Control type After you set the region, you can choose what **type of control** you are adding. Here are the available control types: * `title`: [Title control](/guides/controls/title-control) * `text`: [Text control](/guides/controls/text-control) * `label`: [Label control](/guides/controls/label-control) * `showcase`: [Showcase control](/guides/controls/showcase-control) * `filter`: [Filter control](/guides/controls/filter-control) * `Focus`: [Focus control](/guides/controls/focus-control) * `cluster`: [Cluster control](/guides/controls/cluster-control) * `tagged-timeline`: [Tagged-timeline control](/guides/controls/tagged-timeline-control) * `color-legend`: [Color-legend control](/guides/controls/color-legend-control) * `image`: [Image control](/guides/controls/image-control) * `sna-dashboard`: [Social Network Analysis Dashboard control](/guides/controls/sna-dashboard-control) * `view-toggle`: [View toggle control](/guides/controls/view-toggle-control) #### Properties Controls are customized using **properties**, and each control understands a slightly different set of properties. In the example below, `by` is a property of the `showcase` control that accepts a field name (wrapped in quotes). ```scss @controls { bottom { showcase { by: "Element type"; } } } ``` For a full list of the properties that each control understands, read the individual control guides (linked above), or check out the [controls reference](/overview/advanced-editor-hub/controls-reference). Looking to change the order of the controls in your map? Have a look at [this guide](/frequently-asked-questions/how-do-i-change-the-order-of-control-options). #### Children Sometimes, controls need to work with complex lists of options. Since these would be overwhelming to define in a single line, the items are included as **children** of the control instead, and follow a similar syntax to the controls themselves. In the example below, we call the `option` blocks the "children" of the `showcase` control, and each child includes its own set of properties. ```scss @controls { top-left { showcase { option { label: "People"; selector: person; } option { label: "Orgs"; selector: organization; } } } } ``` You can read through the individual control guides (linked above) to see which controls accept children and which properties their children understand. #### Groups By default, controls are each stored on their own line, and they each have their own set of properties. However, if you want to display a group of controls on one line (for example, along the top of your map), and assign a few common properties and values (for example, `font-size: 16`) to all of them, you can use **groups**. To group controls, use the following `group` syntax: ```scss @controls { region { group { property: value; control { property: value; property: value; ... } another-control {...} an-additional-control {...} } } } ``` The properties that get set underneath `group` will apply to all controls nested inside the group. And before you ask—yes, it's possible to nest groups inside of other groups as well! ### Remove unneeded controls When you're adding [controls](/guides/controls) through the Basic Editor, you might sometimes add a duplicate control by accident, or add a control that says "No values found for \[some field name]". You can remove controls through the Basic Editor and the Advanced Editor. **Basic Editor** 1. Click the settings icon on the right ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the Basic Editor, then scroll down to "Add custom control"**.** You'll see all existing controls listed out below. 2. When hovering over an existing control, click on the edit pencil to edit your existing control, or click on the trash icon to delete it. **Advanced Editor** Open up the Advanced Editor (click Settings ![](/files/kiSpVh4lvjqzFXpigBKs) and then choose Switch to Advanced Editor at the bottom). Unless you have added [partial views](/guides/partial-views), there will be a block of code right at the top starting with `@controls`. ```scss // Line 1 of your Advanced Editor: @controls { ...There will be other code inside this block } ``` If you don't want *any* controls or "No values found for \[some field name]" messages on your map, simply delete the entire `@controls` block, then click "Save" at the bottom of the editor. If you have some controls in there that you would like to preserve, you'll first need to learn the basics of how to read `@controls` code, so that you can tell which controls you want to delete and which you want to keep. * If you want to delete all controls in a certain region of your map, then delete all the code saying `top`, or `top-left`, or `bottom` etc. Delete the whole block to delete all the controls in that region. * If you want to delete just one control, locate it in the list of your controls and delete that whole block. You can recognize a control block by the fact that the first line is `filter`, or `showcase`, or `cluster`, or `focus`. You can learn more about reading `@controls` code in [our full guide on controls](#add-controls-through-the-advanced-editor). Of course you can always send us an email at to help out! ### Built-in controls All of Kumu's built-in controls (search, zoom buttons, settings buttons, the [legend](/guides/legends)) are handled by the same platform that custom controls are built on. That means you can move the built-in controls around, omit ones you don't need, or even reset the built-in controls and start from scratch. Although you won't see it in your Advanced Editor, here's the default `@controls` code working behind the scenes: ```scss @controls { top-left { search {} } top-right { zoom-toolbar {} settings-toolbar {} focus-toolbar {} } bottom-left { legend {} } } ``` You can omit individual controls by including the region in your `@controls` block, without the control inside of it. For example, if you wanted to keep the search bar, but omit all other built-in controls, you could use: ```scss @controls { top-right {} bottom-left {} } ``` Note that if you add controls to a region in your code, but don't explicitly include the default control, it will be hidden. For example, this code will hide the `zoom-toolbar`, `settings-toolbar`, and `focus-toolbar`: ```scss @controls { top-right { title { value: "Oops! I hid some useful controls."; } } } ``` If you want to quickly start from scratch without any of Kumu's built-in controls, you can use `reset: true`. ```scss @controls { reset: true; top { title { value: "Check out my custom controls"; } } bottom { showcase { by: "Element type"; } } } ``` # Cluster control **When do you use it?** Add a control to activate [clustering](/guides/clustering) for a given field or set of selectors via a list of labels, buttons or a dropdown menu. ## Basic Editor To create a cluster control, follow these steps: 1. Click the settings icon on the right ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the editor, then click "Add custom control"**.** 2. In the menu that opens up, click on the first dropdown and change the value to "Cluster elements". 3. Use the other dropdowns to customize the look and location of your controls. 4. Click Save at the bottom to save your changes. 5. To add multiple controls, repeat steps 1-4 for each control. ## Advanced Editor Cluster by field: ```scss @controls { bottom { cluster { by: "Project"; } } } ``` Cluster using custom [selectors](/guides/selectors#selectors): ```scss @controls { top { cluster { as: buttons; option { value: person by "Project"; label: "Project"; } option { value: person by "Country"; label: "Country"; } option { value: person by "Organization"; label: "Organization"; } } } } ``` **Supported properties** * `by` is the field you'd like to use for clustering wrapped in double quotes. If you don't include `by: field` you need to list out each option - see "supported children" guidance below. * `as` controls how the control is presented. Do you want a list of labels, buttons, or a dropdown for activating clustering? * `labels` show options as a list of clickable labels * `buttons` show options as a group of buttons * `dropdown` show options as dropdown * `multiple` controls whether more than one value can be selected at a time * `true` allow multiple values to be selected * `false` only allow one value to be selected at a time * `placeholder` the text to display when nothing is selected (for `as: dropdown` only) * `summary` override the summary that's shown for the current selection (for `as: dropdown`). The summary will be shown regardless of what's selected so there's no need to use `placeholder` in this case. * `default` defines which field values should be selected by default (for `by: "field"` only). Use `select-all` to select everything by default. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the cluster control. **Supported children** If you want to use custom selectors to build clustering options, you'll need to list each option out separately. The options are defined by `option` blocks nested within the control and each `option` supports the following properties: * `label` the text to display for that option * `value` [advanced cluster rule](/guides/clustering#advanced-clustering) to cluster by * `default` * `true` value is selected by default * `false` value is unselected by default # Color-legend control **When do you use it?** Add a color legend to your map. ## **Advanced Editor** Build a color-legend manually: ```scss @controls { bottom-left { color-legend { color { value: red; label: "All the red things"; } color { value: blue; label: "All the blue things"; } } } } ``` Automatically build the `color-legend` from the `element-color` value in `@settings`: ```scss @controls { bottom-left { color-legend { colors: auto; } } } @settings { element-color: categorize("Element type", set2); } ``` **Supported properties** * `colors` defaults to `auto` and tries to build the list of colors and labels [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the color legend control. The `color-legend` can be customized using nested `color` blocks which support the following properties: * `value` the color itself ("red" or "#BA462F") * `label` the text to put next to the color # Filter control **When do you use it?** Add a toggle control that allows viewers to filter by field values or custom selectors. ## **Basic editor** To create a filter control, follow these steps: 1. Click the settings icon on the right ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the editor, then click "Add custom control"**.** 2. In the menu that opens up, the filter control will be activated automatically in the first dropdown "Filter elements by field". 3. Use the other dropdowns to customize the look and location of your controls 4. Click Save at the bottom to save your changes 5. To add multiple controls, repeat steps 1-4 for each control. {% hint style="info" %} **Note**: The filter control works with AND logic. This means that if you combine multiple controls on one map, the view will be filtered down to only those elements that satisfy *all* of the conditions of the controls. Looking for OR logic (showing elements that satisfy *at* *least* *one* of the conditions)? Take a look at our [Showcase control guide](/guides/controls/showcase-control). {% endhint %} ## Advanced Editor If you like to get into the nitty-gritty of the advanced editor, you can type out controls directly. The advanced editor also allows for more advanced controls, as explained below. Filter by field, basic syntax: ```scss @controls { top { filter { by: "element type"; } } } ``` Filter using custom [selectors](/guides/selectors#selectors): ```scss @controls { top { filter { option { label: "Influential"; selector: ["tags"*="influential"]; } option { label: "Emerging Leader"; selector: ["tags"*="emerging"]; } } } } ``` **Supported properties** * `target` a selector that controls which items the filter applies to. Defaults to `*`, which will apply the filter to all items. * `by` is the field you'd like to use for filtering wrapped in double quotes (if you don't include `by: field` you need to list out each option - see "supported children" guidance below) * `as` controls how the control is presented. Do you want a list of labels, buttons, or a dropdown for activating filter? * `labels` show options as a list of clickable labels * `buttons` show options as a group of buttons * `dropdown` show options as dropdown * `multiple` controls whether more than one value can be selected at a time * `false` allows the reader to only select a single option * `true` allows the reader to select multiple options * `match-all` allows the reader to select multiple options, and only shows items that match **all** of the selected options * `placeholder` the text to display when nothing is selected (for `as: dropdown` only) * `summary` override the summary that's shown for the current selection (for `as: dropdown`). The summary will be shown regardless of what's selected so there's no need to use `placeholder` in this case. * `default` defines which field values should be selected by default (for `by: "field"` only). Use `select-all` to select everything by default (or `show-all` for a similar effect without selecting everything by default). * `except` allows you to remove field values from the available choices. Wrap the values you want to remove in quotes and separate multiple values by commas. * `only` is similar to except but allows you to explicitly define which field values should be included as available choices. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the filter control. **Supported children** If you don't supply a field to filter by, each option must be listed separately. The available options are defined by `option` blocks nested within the control. Each `option` supports the following properties: * `label` the text to display for that option * `selector` the [selector](/guides/selectors#selectors) to use for the filter * `default` * `true` value is selected by default * `false` value is unselected by default ### More examples Filter elements by one or more skills using a dropdown: ```scss @controls { top { filter { target: element; by: "Skills"; as: dropdown; multiple: true; placeholder: "Select one or more skills" } } } ``` Filter by location, but only for items that have a location: ```scss @controls { top { filter { by: "Location"; target: ["Location"]; } } } ``` Filter connections by toggling between two types (with personal selected by default): ```scss @controls { top { filter { target: connection; as: label; multiple: false; option { label: "Personal"; selector: personal; default: true; } option { label: "Business"; selector: business; } } } } ``` Filter elements by type but select all types by default: ```scss @controls { top { filter { target: element; by: "Element type"; default: select-all; } } } ``` # Focus control **When do you use it?** The focus control allows you to use [focus](/guides/focus) on a specific field across all elements, meaning that the control will toggle on all elements with that field + their connections. You can indicate whether you want the connections to be "out 1" (only first-degree connections), or "out 2" (first- and second-degree connections), etc. {% hint style="info" %} Here are some great uses of the focus control: * Focus by the “label” field to quickly zoom in on one element and its neighboring connections * Focus by a specific field to quickly see which elements on the map have that value in their profile field, *and* what their immediate connections are {% endhint %} ## Basic Editor To create a cluster control, follow these steps: 1. Click the settings icon on the right ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the editor, then click "Add custom control"**.** 2. In the menu that opens up, change the value of the first dropdown to "Focus elements by field". 3. Use the other dropdowns to customize the look and location of your controls 4. Click Save at the bottom to save your changes 5. To add multiple controls, repeat steps 1-4 for each control. ## Advanced Editor If you like to get into the nitty-gritty of the advanced editor, you can type out controls directly. The advanced editor also allows for more advanced controls, as explained below. Focus by field, basic syntax: ``` @controls { top { focus { by: "element type"; } } } ``` Focus using custom [selectors](/guides/selectors#selectors): ```scss @controls { top { focus { option { label: "Influential"; selector: ["tags"*="influential"]; } option { label: "Emerging Leader"; selector: ["tags"*="emerging"]; } } } } ``` **Supported properties** * `by` is the field you'd like to use for filtering wrapped in double quotes (if you don't include `by: field` you need to list out each option - see "supported children" guidance below) * `as` controls how the control is presented. Do you want a list of labels, buttons, or a dropdown for activating filter? * `labels` show options as a list of clickable labels * `buttons` show options as a group of buttons * `dropdown` show options as dropdown * `multiple` controls whether more than one value can be selected at a time * `false` allows the reader to only select a single option * `true` allows the reader to select multiple options * `match-all` allows the reader to select multiple options, and only shows items that match **all** of the selected options * `placeholder` the text to display when nothing is selected (for `as: dropdown` only) * `summary` override the summary that's shown for the current selection (for `as: dropdown`). The summary will be shown regardless of what's selected so there's no need to use `placeholder` in this case. * `default` defines which field values should be selected by default (for `by: "field"` only). Use `select-all` to select everything by default (or `show-all` for a similar effect without selecting everything by default). * `except` allows you to remove field values from the available choices. Wrap the values you want to remove in quotes and separate multiple values by commas. * `only` is similar to except but allows you to explicitly define which field values should be included as available choices. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the focus control. **Supported children** If you don't supply a field to focus by, each option must be listed separately. The available options are defined by `option` blocks nested within the control. Each `option` supports the following properties: * `label` the text to display for that option * `selector` the [selector](/guides/selectors#selectors) to use for the filter * `default` * `true` value is selected by default * `false` value is unselected by default ### More examples Focus elements by one or more skills using a dropdown: ```scss @controls { top { focus { target: element; by: "Skills"; as: dropdown; multiple: true; placeholder: "Select one or more skills" } } } ``` Focus by location, but only for items that have a location: ```scss @controls { top { focus { by: "Location"; target: ["Location"]; } } } ``` Focus elements by type, but select all types by default: ```scss @controls { top { focus { target: element; by: "Element type"; default: select-all; } } } ``` # Image control **When do you use it?** The image control can be used to overlay an image on top of your map. This is a great way to add custom legends, charts, or graphics to support the current view. ## **Advanced Editor** ```scss @controls { bottom-right { image { src: "https://upload.wikimedia.org/wikipedia/commons/thumb/8/8d/President_Barack_Obama.jpg/220px-President_Barack_Obama.jpg"; height: 140; } } } ``` **Supported properties** * `src` the url of the image to include (must be wrapped in quotes) * `width` override the width of the image (optional) * `height` override the height of the image (optional) [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the image control. # Label control **When do you use it?** Add small bold text to your map. ## **Advanced Editor** ```scss @controls { bottom-right { label { value: "© 2016 Kumu Inc."; } } } ``` **Supported properties** * `value` is any plain text string. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the label control. # Showcase control **When do you use it?** Add a control to activate [showcase](/guides/showcase) for a given field or set of selectors via a list of labels, buttons or a dropdown menu. ## Basic Editor To create a showcase control, follow these steps: 1. Click the settings icon on the right ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the editor, then click "Add custom control"**.** 2. In the menu that opens up, change the first dropdown to "Showcase elements by field". 3. Use the other dropdowns to customize the look and location of your controls 4. Click Save at the bottom to save your changes 5. To add multiple controls, repeat steps 1-4 for each control. {% hint style="info" %} **Note:** The showcase control works with OR logic. This means that if you combine multiple controls on one map, the view will be filtered down to any elements that satisfy *at least one* of the conditions of the controls. Looking for AND logic (showing only elements that satisfy *all* of the conditions)? Take a look at our [Filter control guide](/guides/controls/filter-control). {% endhint %} ## Advanced Editor If you like to get into the nitty-gritty of the advanced editor, you can type out controls directly. The advanced editor also allows for more advanced controls, as explained below. **Example** Showcase by field: ```scss @controls { bottom { showcase { by: "State"; } } } ``` Showcase using custom [selectors](/guides/selectors#selectors): ```scss @controls { bottom { showcase { option { label: "People"; selector: person; } option { label: "Orgs"; selector: organization; } } } } ``` **Supported properties** * `by` is the field you'd like to use for showcasing wrapped in double quotes. If you don't include `by: field` you need to list out each option - see "supported children" guidance below. * `mode` controls how the selection is showcased * `normal` showcase the selection plus any connections between the showcased elements (default) * `loose` showcase the selection plus neighboring elements * `strict` only showcase the selection itself * `as` controls how the control is presented. Do you want a list of labels, buttons, or a dropdown for activating showcase? * `labels` show options as a list of clickable labels * `buttons` show options as a group of buttons * `dropdown` show options as dropdown * `multiple` controls whether more than one value can be selected at a time * `false` allows the reader to only select a single option * `true` allows the reader to select multiple options * `match-all` allows the reader to select multiple options, and only showcases items that match **all** of the selected options * `placeholder` the text to display when nothing is selected (for `as: dropdown` only) * `summary` override the summary that's shown for the current selection (for `as: dropdown`). The summary will be shown regardless of what's selected so there's no need to use `placeholder` in this case. * `default` defines which field values should be selected by default (for `by: "field"` only). Use `select-all` to select everything by default. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the showcase control. **Supported children** If you want to use custom selectors to build the showcase, you'll need to list each option out separately. The options are defined by `option` blocks nested within the control and each `option` supports the following properties: * `label` the text to display for that option * `selector` the [selector](/guides/selectors#selectors) to use for the showcase * `default` * `true` value is selected by default * `false` value is unselected by default ### Additional examples Showcase by state and include neighboring elements, allowing multiple states to be selected at the same time: ```scss @controls { bottom { showcase { by: "State"; mode: loose; multiple: true; } } } ``` Showcase by state using a dropdown menu, and include a placeholder with instructions: ```scss @controls { bottom { showcase { by: "State"; as: dropdown; placeholder: "Select a state"; } } } ``` Showcase by state and select all states by default: ```scss @controls { bottom { showcase { by: "State"; default: select-all; } } } ``` # SNA-dashboard control **When do you use it?** With the SNA Dashboard control, you can add a dashboard that shows key metrics for your network map. ![SNA Dashboard](/files/wrzeLoDxi3s23ac7SEYS) ## Advanced Editor Here's the syntax for adding the SNA Dashboard control in the Advanced Editor: ```scss @controls { bottom { sna-dashboard {} } } ``` You can also use the `metrics` property to specify exactly which metrics get included: ```scss @controls { bottom { sna-dashboard { metrics: element-count, connection-count, density, average-degree; } } } ``` ![SNA Dashboard with custom metrics](/files/YsyFUMXhZXj0u8ld4Yd1) Here are all the possible values you can use in the `metrics` property: * `element-count` * `connection-count` * `density` * `reciprocity` * `diameter` * `average-degree` * `average-path-length` [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the SNA-dashboard control. ## Available metrics The metrics currently available in the dashboard are: | Metric | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Total elements | A count of all the elements on your map | | Total connections | A count of all the connections on your map | | Density | Compares the number of actual connections to the number of potential connections in a network. \`1\` is the highest possible density number, and \`0\` is the lowest. | | Reciprocity | In a directed network, reciprocity measures the likelihood that two elements will have an equal number of connections traveling in either direction between them. | | Diameter | The shortest path between the two elements that are furthest apart in a network. If any part of your network is completely disconnected, the diameter will be infinity ∞. | | Average degree | Calculates the average number of connections across all elements in the network. | | Average path length | Calculates the average number of steps it takes to get from one element to another in the network. If any part of your network is completely disconnected, or if any element has only incoming or only outgoing connections, the average path length will be infinity ∞. | # Tagged-timeline control **When do you use it?** Filter a network over time using years defined in the tag field. *Note: If you include timeline data using the "tags" field, the controls will provide clickable dates that can be used to filter the map. We recommend using years to define when an element/connection was present. You can supply multiple years to be able to allow disjointed timelines (e.g. 2012, 2013, 2016 for an element that was part of the network until 2013, then left and joined again in 2016).* {% hint style="info" %} Want to learn more about why and how to use a Tagged-Timeline Control? \ [Check out this blog](https://blog.kumu.io/filtering-networks-over-time-using-custom-controls-dcb1382c9b7c). {% endhint %} ## **Advanced Editor** ```scss @controls { bottom { tagged-timeline { range: 2000..2016; target: element; } } } ``` **Supported properties** * `range` defines the years that should be included as clickable links. * `target` defines whether the filter should apply to elements, connections, or loops. To apply the filter to elements and connections, use `element,connection;`. * `multiple` by default the timeline allows you to select multiple years. Use `multiple: false` to only allow a single year to be selected instead. * `default` defines which values should be selected by default. Use `select-all` to select everything by default (or `show-all` for a similar effect without selecting). [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the tagged timeline control. # Text Control **When do you use it?** Add custom text to your map. ## **Advanced Editor** ```scss @controls { top { text { value: "Betweenness measures the number of times someone is on the shortest path between any two people."; } } } ``` **Supported properties** * `value` is any plain text string. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the text control. # Title Control **When do you use it?** Add a custom title to your map. ## **Advanced Editor** ```scss @controls { top { title { value: "2016 Network size by betweenness"; } } } ``` **Supported properties** * `value` is any plain text string. [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the title control. # View toggle control **When do you use it?** With the view toggle control, you can toggle between different [partial views](/guides/partial-views). ![view toggle gif](/files/0qSlJpPecEv0zHjJihi8) For full details on how to create partial views and toggle between them with the view toggle control, check out [our full guide on partial views](/guides/partial-views). # Decorations Decorations in Kumu allow you to change color, size, and other visual properties of elements, connections, and loops in your map. They are a powerful way to guide your map readers toward valuable insights about your system or network. ![Color and size decorations](/files/J8TXACe0osaDLyd4nuki) There are two types of decorations in Kumu: 1. [Direct decorations](/guides/decorate/direct-decorations) 2. [Data-driven decorations](/guides/decorate/data-driven-decorations) **Direct decorations** are the right choice if you just need to make some quick visual changes to a few specific elements, connections, or loops. They're also great if you're just getting started with Kumu and want to get a sense of what is visually possible. **Data-driven decorations** are the right choice if you want Kumu to decorate your map automatically, based on the data stored in [profiles](/guides/profiles). They're excellent in any situation where decorating each item individually would be tedious, and they're the best choice choice if your map is going to grow and add more data in the future. {% hint style="info" %} More of a visual learner? [Make sure to check out our webinar on "Kumu Map Design: From Good to Great".](https://www.youtube.com/watch?v=KJbjLCO1y5c\&t) {% endhint %} # Direct decorations Usually, it's faster and easier to decorate elements, connections, and loops according to the data in their [fields](/guides/fields)—for example, creating a decoration rule that selects all elements with the element type "Organization", and color-codes them based on their tags. But, if you haven't added field data, or you just want to tweak the style of one single item on the map, **direct decorations** is the perfect tool. To use them, simply hover over an element, connection, or loop, and the direct decorations toolbar will appear: ![direct decorations toolbar](/files/DiNoNwDFVodX9XHpEgct) If you'd rather have the toolbar appear when you click on an item instead of hover, add the following in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor): ```scss @controls { toolbar: click; } ``` If the toolbar is a distraction and you prefer to use rule-based decorations, you can disable the toolbar altogether: ```scss @controls { toolbar: false; } ``` ## Direct decorations reference The table below lists all of the icons you'll find in the direct decorations toolbar for elements, connections, and loops, and what action each icon exposes to you.
IconActionElementsConnectionsLoops
Edit label and typetruetruetrue
Edit font color, font size, font style, and font alignmenttruetruetrue
Edit colortruetruetrue
Edit size and/or shapetruetruefalse
Add an imagetruefalsefalse
Delete itemtruetruetrue
More optionstruetruetrue
Add a bordertruefalsefalse
Add a bullseyetruefalsefalse
Add a shadowtruefalsefalse
Change connection directionfalsetruefalse
Add delay markingsfalsetruefalse
Reset direct decorationstruetruetrue
Visit these docs!truetruetrue
## Undo direct decorations You can undo your direct decorations for either one, or all, of the entities on your map. To view what has been decorated with the toolbar, click on the Settings button on the right-hand side of your map and **hover** over the blue text "Disable direct decorations". You'll then see what elements/connections have been affected by direct decorations. If you wish to undo *all* of the direct decorations, you can **click** on "Disable direct decorations" to return your map to the way it was before. Similarly, if you want to enable direct decorations again, click on the same blue text that is now "Enable direct decorations". Another option is to disable direct decorations for one or a few single items on your map. To do so: 1. Hover over any element or connection 2. Click on the edit pencil to open the direct decorations toolbar 3. Choose the "More" icon at the end, 4. Click on the "Reset direct decorations" icon (represented as an eye with a dash through it) 5. In the next popup window, click "Reset". *Note that you can here also choose for a "hard reset", which resets the direct decorations of your entire map.* Similarly, if you wish to undo the direct decorations of only *a few* selected items, select those items first, and then follow the steps above. ## Caveats for direct decorations There are just a few additional things you should know about direct decorations: #### Direct decorations can't be used when importing from Google Sheets If you're data is coming in from a Google Sheet, you'll notice that the direct decorations toolbar doesn't show up. If you'd still like to use direct decorations, please switch to importing your data with Excel. #### Direct decorations always override decorations in your [Views](/guides/views). This includes all the code in your Advanced Editor. For example, if you direct decorate an element to color it blue, and then you use the view to color it red, it will still be blue. #### Direct decorations, just like element position and connection curvature, are stored separately for each map in the project. If you want to change the direct decoration for an item, you can [duplicate the map](/overview/user-interfaces/settings#map-settings) and make your changes in the new copy. #### When you're editing the map, the direct decorations toolbar will hide [popovers](/guides/decorate/popovers). However, anyone who has view-only access to the map or is viewing a [presentation](/guides/presentations) or a [shared/embedded map](/guides/share-and-embed) will still see your popovers (the direct decorations toolbar is hidden for them, since they can't make edits to your map). If you're building popovers and just want to see how they look before you publish, you can either follow the instructions above to turn off the direct decorations toolbar, or click the ellipsis icon in the bottom right corner and select "Switch to preview mode". # Data-driven decorations When you're visually decorating your maps in Kumu (e.g. color-coding, changing shapes and sizes, aligning text, etc.), **data-driven decorations** are usually the most efficient way to do so. However, data-driven decorations is a feature you may not have come across in other graphic tools you've used. This guide will help with the learning curve! In this guide, you'll find: * [Defining "data-driven decorations"](#defining-data-driven-decorations) * [Adding your data](#adding-your-data) * [Decorate in the Basic Editor](#decorate-in-the-basic-editor) * [Size by](#size-by) * [Color by](#color-by) * [Shape by](#shape-by) * [Fine-tune your decorations](#use-decoration-builders-to-create-custom-decorations) * [Decorate in the Advanced Editor](#decorate-in-the-advanced-editor) * [The decorations cascade](#the-decorations-cascade) ## Defining "data-driven decorations" Data-driven decorations are rules that tell Kumu how to style your map. Those rules accomplish two tasks: * Tell Kumu which items (i.e. elements, connections, or loops) the rule should apply to. * Tell Kumu which visual style should be applied to those items. Here are some examples of rules you could create: **All elements should be colored blue.** 1. *Which items?* All elements. 2. *Which visual style?* Change color to blue. **Elements with "Person" in their Type field should have a green shadow.** 1. *Which items?* All elements with "Person" in their Type field. 2. *Which visual style?* Add a green shadow. **Elements with a value of more than 0.6 in their "Betweenness" field should be shaped like a diamond** 1. *Which items?* All elements with a Betweenness of higher than 0.6 2. *Which visual style?* Shape like a diamond **Connections' thickness should vary based on the number in their "Strength" field.** 1. *Which items?* All connections. 2. *Which visual style?* Scale the connection thickness based on its strength. **Loops that have something in their "Type" field should be color coded based on that value** 1. *Which items?* Only the loops that have something in their "Type" field. 2. *Which visual style?* Assign a color automatically, so that each loop's color corresponds with its type. Note that these rules are not tied to specific elements, connections, or loops, but instead are designed to act on groups of items, based on data and information inside of their [profiles](/guides/profiles)—in other words, the rules are all **data-driven**. Whether you have ten, one-hundred, or even one-thousand elements, the first rule from the list above is going to find every single element and color it blue. It gets better! Let's say you add some elements and connections to Kumu and apply a few rules, just so you can build a prototype visualization with the data you have on hand. Then, you decide that the prototype looks good, so you load in your full dataset, adding tens or hundreds more elements and connections to the visualization. Good news: **your data-driven rules will automatically apply to all the new items in real time**. No need to re-create every rule from your prototype after you add new data! All data-driven decorations are completely scaleable—Kumu will apply them to any and all new items you add, whether you're adding new elements, connections, and loops, or just editing the information in existing profiles. ## Adding your data Each element, connection, and loop has a profile that can be used to store additional information in various fields. ![](/files/9h9akZUrdfaoxgFQhz3i) Label, Type, Description, and Tags are all examples of fields. Use these fields to provide additional context for each element and connection, and click **+NEW FIELD** to add a custom field. After you fill out data in the profiles, you can use the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) or the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) to add decorations. ## Decorate in the Basic Editor To open the Basic Editor, open your map and click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map.

Basic Editor

You'll see some of Kumu's most commonly used view settings, and the first three—**Size by,** **Color by,** and **Shape by**—can help you create basic decorations. ### Size by **Size by** allows you to scale the size of your elements based on numbers stored inside them. For example, if you have a map of organizations, you could create a field called "Net Assets" and fill out the numbers for each element. Then you can use the Basic Editor to scale the size the organizations according to their Net Assets, allowing you to quickly compare everyone's resources. {% embed url="" %} Don't like the default sizes? Click the expand icon next to the **Size by** dropdown to fine-tune your sizing options. In this example, we sized people by the number of views they received on their videos of the ALS ice bucket challenge: ![Ice bucket challenge map](/files/Wcq66Rm76MXv4xywJkQR) Note that if you don't have any fields with numbers, the **Size by** dropdown menu won't have any options in it. If you don't have this kind of data available, try using Kumu's [Metrics](/guides/metrics) feature to create some! {% hint style="info" %} Are your fields with numbers not showing up in the Size by dropdown? Try [changing the field type to "Number"](/guides/fields#customize-a-field). {% endhint %} ### Color by **Color by** allows you to color-code your elements based on any field. Select a field from the dropdown, and any elements that have data in that field will be colored! {% embed url="" %} Don't like the default colors? Click the expand icon next to the **Color by** dropdown to fine-tune your coloring options. This example colors by Element Type using the `bujumbra` scale: ![bujumbra color by](/files/00suYM3xaNRp2vWsaqW8) The default color scale, `neon2`, can support seven different colors. If you need more colors (for example if you have 10 or 11 different element types), [check out our color reference](/overview/advanced-editor-hub/color-reference) to find a scale that will work for your data. If you color by a multi-pick field like Tags, Kumu will color code your elements with flags (colored arcs around the outside of your elements). Each flag represents one of the possible values in the multi-pick field. ![Flags example](/files/YAAsQnCrviMSPtUGL86A) To learn more about flags, [read the full guide](/guides/decorate/flags). ### Shape by **Shape by** allows you to shape your elements based on any field that can hold only one value. Select a field from the dropdown, and any elements that have data in that field will get a new shape!
To learn more about shapes, [read the full guide](/guides/shapes). ### Use decoration builders to create custom decorations If you need more precise control over the size and color of your decorations, you can choose either of the last two options on the list. Select **Decorate elements** to bring up the Decoration Builder for elements. ![Element decoration builder](/files/JBxPRVnmJe9ANRd8kiGY) Or, select **Decorate connections** to bring up the Decoration Builder for connections. ![Connection decoration builder](/files/a71EWsYLE5jzOK5KL8LQ) Use the dropdown menus at the top of the builders to choose which elements or connections you are decorating. The options are: * Decorate all elements/connections * Decorate custom selection * Decorate selected elements/connections * Decorate similar elements/connections Note that the last two options won't appear in the dropdown menu unless you selected one or more elements/connections *before* you opened up the Decoration Builder. If you chose to decorate a custom selection, you can use the tools below the first dropdown menu to build your custom selection. For example, you can set the three boxes to `Element Type` `is` `Person` to tell Kumu that you are only decorating elements who have the type "Person" in their [profile](/guides/profiles). After you have built your selection, feel free to play with all the decoration options to find a visual effect that brings insight to your map! ![Element decoration options](/files/aJ8EraaM07Tu60bLom4I) Click the **Done** button to apply your decoration, and if you don't like the way it looks, just find the decoration rule in the [existing decorations](/overview/user-interfaces/view-editors#existing-custom-decorations) section of the Basic Editor, and click the pencil icon to edit it.

Custom decorations

You can also add your decorations to the legend by filling out the **Legend** box at the bottom of the Decoration Builder. For more information on legends, [check out the full legends guide](/guides/legends). ## Decorate in the Advanced Editor If you've seen or used [Cascading Style Sheets (CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS), decorating in the Advanced Editor will look and feel very familiar. ![Advanced Editor](/files/pdYQD3QB363E4EPudl5t) If you haven't seen or used CSS, don't worry! Most Advanced Editor code follows the same straightforward pattern: ```scss selector { property: value; } ``` `selector` can be replaced with any valid [selector](/guides/selectors), and you can read our [property reference](/overview/advanced-editor-hub/property-reference) to find documentation on `properties` and their possible `values`. For example, if you were mapping a network of politicians, you could add a field called "Political Party", fill out the data for each element, then use this code to add a few decorations: ```scss element ["Political Party"] { size: 40; border-width: 2; } element["Political Party"="Democrat"] { border-color: blue; } element["Political Party"="Republican"] { border-color: red; } ``` The first section, starting with `element ["Political Party"]` changes the size and border width of all elements with any value in the "Political Party" field. The section section, which refines the selector to `element["Political Party"="Democrat"]`, gives the Democrats a blue border. The third section changes the selector again to target Republicans, then gives them all a red border. There's much more you can do with the Advanced Editor—it's one of the most powerful tools in Kumu! [Read the full Advanced Editor guide](/overview/user-interfaces/view-editors#advanced-editor) to learn more. ## The decorations cascade Decorations are applied in a cascading order. If you're decorating via the Basic Editor, this means that your most recently created decorations can override your older decorations. For example, if you save a decoration that makes half of the elements blue, then you add another decoration that makes all of the elements green, your end result will be a map full of green elements. The second rule you created will override the first rule. You can click and drag decorations in the [existing decorations](/overview/user-interfaces/view-editors#existing-custom-decorations) section of the Basic Editor to reorder them, changing which rule gets applied in the end. ![Cascading decorations](/files/DewId3ORBBkqHYHnmf5A) If you're decorating via the Advanced Editor, Kumu will read and apply your decoration code from top to bottom. In the example below, all elements will first be colored blue (`#428cba`), but then will be changed to green (`#5cb85c`). ```scss /* Color everything blue */ element { color: #428cba; shadow-color: #428cba; } /* Color everything green */ element { color: #5cb85c; shadow-color: #5cb85c; } ``` If you're using [direct decorations](/guides/decorate/direct-decorations), keep in mind that direct decorations don't follow the rules of the cascade—they always override data-driven decorations. # Flags Flags are a [data-driven decoration](/guides/decorate/data-driven-decorations) created specifically for multi-pick fields (fields like Tags that can hold more than one value). When you decorate elements with flags, Kumu draws colored arcs around the outside of those elements. Each flag represents one of the possible values in the multi-pick field. ![Flags example](/files/YAAsQnCrviMSPtUGL86A) If you're using the **Color by** tool in the Basic Editor, and you select a multi-pick field, Kumu will automatically use flags to color code your elements. {% hint style="info" %} Is the Color by tool applying flags for a field that isn't a multi-pick field? Try [changing the field's limit](/guides/fields#customize-a-field) to "One" instead of "One or more". {% endhint %} In the Advanced Editor, you can use the `flags` property to add flags. Here's the basic syntax: ```scss element { flag: "Field" with colorPalette; } ``` You can replace `element` with any element [selector](/guides/selectors), `Field` with any multi-pick field, and `colorPalette` with any palette from our [color reference](/overview/advanced-editor-hub/color-reference). To further customize the flags' appearance, you can use the `flag-size` property to control the thickness of the flags, and the `flag-offset` property to control the distance between the flags and their element. You can also activate flags using the `@settings` block, like so: ```scss @settings { element-flag: "Leverage Analysis" with neon2; } ``` The advantage of using `@settings` to apply flags is that all of your colors and the corresponding field values will be added to your map's legend. The downside of using `@settings` to apply flags is that the decoration will always be applied to *all* the elements on your map—which might not always be desirable! But, it's easy to turn off flags for certain elements using `flag: none`, like so: ```scss @settings { element-flag: "Leverage Analysis" with neon2; } element["Should I have flags?"="No!"] { flag: none; } ``` This code uses the `@settings` block to add flags to all elements, then, taking advantage of Kumu's [cascade rules](#cascading-decorations), it uses `flag: none` to turn off flags for a smaller selection of elements. You can also manually assign colors to values if you just want to choose specific colors for specific values, or if you don't want to highlight the whole set. ```scss @settings { element-flag: "Leverage Analysis" with yellow "bright spot", #2dc63f "frozen"; } ``` The syntax is `color "value"`. You can replace `color` with a named color or an [HTML hex color code](https://www.w3schools.com/colors/colors_hexadecimal.asp), and you can replace `value` with an actual value from your field. If you're coding more than one `color "value"`, separate them with a comma. ![flag decorations](/files/91T8ljysXWvErHwdsGoU) By default, the [geo template](/guides/templates/geo) limits you to squares and straight lines, but if you want it to support flags as well, add `@settings { renderer: canvas; }` to your Advanced Editor. # Icons Using the Advanced Editor, you can easily bring in any [Font Awesome icon](https://fontawesome.com/v4/icons/) to decorate your elements. ![elements with icons to show element type](/files/3zkXH29JexwGQSIbsWTw) To get started, add a new block of code. You can use any element [selector](/guides/selectors) to open the block, then use the icon property to specify which icon you’d like to bring in, and use the icon-color property to specify its color: ```scss person { icon: user; icon-color: #444; } ``` **Tip**: If you prefer to show just the icon instead of the element itself, set `color` to `transparent`; ```scss organization { icon: building; icon-color: #444; color: transparent; } ``` In the value for the `icon` property, you can also specify `solid` or `regular` to change the icon style: ```scss organization { icon: building regular; icon-color: #444; color: transparent; } ``` Note that, if you add icons to your elements, they will override any images you have added. If you'd like to add icons only for elements that don't have images, you can add this code to the bottom of your Advanced Editor: ```scss // The element[image] selector tells Kumu to only apply these rules for elements with an image element[image] { icon: off; // Setting 'icon' to 'off' will remove any icons you've added further up in the Advanced Editor } ``` # Images In Kumu, there are a number of different places where you can use images to enrich your project. **Skip to section:** * [Adding images to elements](#add-images-to-elements) * [Adding icons to elements](#add-icons-to-elements) * [Adding a background image](#add-a-background-image) {% embed url="" %} ## Add images to elements If you are [building a map by hand](/getting-started/first-steps#build-your-map-by-hand), you can easily upload an image file from your computer directly to Kumu. Just click an item (element, connection, or loop) on your map, click the camera icon in the upper right of the [profile](/guides/profiles), and click "select a file" to upload your image. ![Gif showing how to upload an image to Kumu](/files/OMpjPkHnUFPR2HsvCJRM) You can upload images to descriptions and the map overview as well. To do this, click to edit any text area in the [side panel](/overview/user-interfaces/map-editor#side-panel), and look for "select a file" below the text area. {% hint style="info" %} Note: when you're uploading images, only JPEG, PNG, and GIF files smaller than 5mb are supported at this time. {% endhint %} #### Importing images through Google Sheets If you're [importing data with Google Sheets](/guides/import), then you'll have to include a URL to an image hosted publicly on the web. First, add an "Image" column in the "Elements" sheet of your Google Sheets file, and then add the public URL for the image that you want to add to each element (e.g. each row). {% hint style="info" %} Note that the URL should lead *directly* to the image, so you might need to create such a URL first through an [image hosting platform](https://imgbb.com/). Some images allow you to simply right-click on them and choose "Copy image address". You can then use that link as the image URL. {% endhint %} #### Troubleshooting images Have you uploaded images, but are not seeing images on the map? Here are a few steps you can take to troubleshoot the problem: * Make sure you're not using the SNA template, which doesn't support images. If you are using that template, you can [switch to a different one](/guides/templates#switching-templates). * If you're entering image links directly: * Make sure your link leads directly to the image, rather than a webpage with the image on it. There are many places where you can host your images, but [this website](https://imgbb.com/) is generally a good place to start. Some images also allow you to simply right-click on them and choose "Copy image address". * Make sure your image URL is using a secure connection—that is, the link starts with `https` instead of just `http` * Disable image proxy: click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left of the map editor, then click **Admin** and click **disable it**. #### Using decorations to add images With decorations, you can create rules that add the same image to multiple elements. To do this, [open the element decoration builder](/guides/decorate#refine-your-decorations), select which elements the rule will apply to, and check the box next to "Add image". You'll be prompted to add an image URL or upload an image from your computer, and your image will be added to the selected elements. You can also use [advanced decorations](/guides/decorate#decorate-in-the-advanced-editor) to add images and tweak their appearance on the map. In a decoration in the Advanced Editor, use the `image-url` property to set the image url for your selection, and use the `image-visibility` property to hide images or make them visible on the map. You can also use the `image-size` property to choose whether images on the map will completely cover their parent elements, or be fully contained inside the parent element. ```scss #my-element { image-url: url(https://example.com/my-element-image.png); image-size: contain; image-visibility: visible; } ``` Be sure to check out our [property reference](/overview/advanced-editor-hub/property-reference) for full documentation on properties that can be used in the Advanced Editor. ## Add icons to elements Using the Advanced Editor, you can easily bring in any [Font Awesome icon](https://fontawesome.com/icons) to decorate your elements. ![elements with icons to show element type](/files/3zkXH29JexwGQSIbsWTw) For more guidance, check out [our full guide on icons](/guides/decorate/icons). ## Add a background image To add a background image to a map, you can use a snippet of code in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor). The following instructions will help you add an image of a world map, but they can be adapted to add any background image. 1. Create an element and change its label to `background`. 2. Pin the element (press `P` on your keyboard, or click the pin icon in the left side panel). 3. Copy/paste the following code into your Advanced Editor: ```scss @settings { culling: off; } #background { image-url: url(https://s3.amazonaws.com/cloud.kumu.io/accounts/2057/201677/44522144-b11e-48dd-96b1-aeca8c3592d9.png); layer: background; shape: rectangle; height: 10000; width: 10000; color: transparent; image-size: contain; image-resolution: original; label-visibility: none; } ``` 1. Click **SAVE** at the bottom of the Advanced Editor to save your changes. You can replace the `image-url` in that code with a link to any image online. To get an image URL from any image you see online, you can right-click the image and select "Copy Image Address". When you're pasting your new image url into the Advanced Editor, make sure to put it inside the `url( )` parentheses. Also, if your image isn't big enough, or if it's so tall or wide that it's affecting your zoom fit, you can change the `height` and `width` numbers in the code to adjust the dimensions. {% hint style="info" %} Some images won't be displayed in Kumu, because they are using an insecure connection (the link starts with `http` instead of `https`), or because they are traveling through a proxy server.\ \ If your image isn't displaying in Kumu, you can save the file to your computer and follow the steps below to upload the image directly to your Kumu project. {% endhint %} You can also use the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) to upload an image from your computer to your Kumu project—this will override the `image-url` in your code. Follow these steps: 1. Complete the initial steps above to create your background element, add your Advanced Editor code, and save your changes. 2. Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the Basic Editor. 3. Click **More Options** 4. Select **Decorate elements** 5. In the element decoration builder, set the dropdown at the top to "Decorate custom selection" 6. Set the second row of dropdown menus to `Label` `is` `background` (assuming your background element's label is `background`) 7. Check the box next to "Add image", then click "upload image" 8. Upload your image, and click **Done** at the bottom of the decoration builder 9. Click **SAVE** at the bottom of the Basic Editor {% hint style="info" %} If you need to adjust the position of the image element in the map, you'll need to remove the `layer: background;` line. Click and drag the element to adjust its position, and then add back that line of code when you're done. {% endhint %} **Notes:** * "background" is the label of the element that will contain the background image in this example, but the label can be anything you want. Just make sure you update the `#background` [selector](/guides/selectors) in your code to match your new label. * `image-resolution` can have values of `auto`, `original`, or any number. The number you include (e.g. `1000`) will adapt the resolution for an image of that width (1000px). {% hint style="info" %} If you add a control to your map, you'll see that the background gets filtered out. If you want to keep your background as you filter, follow these steps: 1. Create the control first. Don't forget to save it! 2. Then go into the Advanced Editor and change the line from `target: element;` to `target: :not(#background);` 3. Now the control won't affect the background! {% endhint %} As always, if you have any questions on how this works, email us at for help! # Label templates When you're working with a map that displays labels for elements, connections, or loops, Kumu will only display the text in the Label [field](/guides/fields) by default. If you want to include other fields in the label, **label templates** can help you do that. {% embed url="" %} Label templates are customized through the Advanced Editor, using a simple syntax. ```scss selector { label: "{{Field name}}"; } ``` Replace `selector` with any valid [selector](/guides/selectors), and replace `Field name` with the name of any of your fields. Remember to wrap each field name in double curly brackets `{{}}` and wrap the entire `label` value in double quotes. {% hint style="info" %} Some [field types](/guides/fields#field-type) will give unwanted results when used as label templates. If a field type is set to **text**, **url** or **e-mail**, you'll either get an error or find HTML code being added to your labels on the map. For example, the "Description" field is set to type "text" by default, and can't be changed to another type. In that case, please use a different field for your label template and make sure the Type is set to either **string**, **number**, **currency** or **date**. {% endhint %} For example, below is the code for an **element** label that includes the **label** and **element type**. ```scss element { label: "{{label}} {{element type}}"; } ``` {% hint style="info" %} When using the **Type** field in label templates, you need to specify whether it is **Element** Type, **Connection** Type, or **Loop** Type. For example, use `{{connection type}}` when adding Type to a connection's popover. {% endhint %} # Popovers [Profiles](/guides/profiles) are great for including detailed background information about what you’re mapping. But sometimes they can be a bit overkill, and they do take up a lot of precious screen space. Sometimes you want to share just a little bit more context about an element or connection without having to open the profile. **Popovers** allow you to display fields from the profiles when someone hovers over an element, connection, or loop. {% embed url="" %} When you're editing the map, the [direct decorations toolbar](/guides/decorate/direct-decorations) will hide popovers. However, anyone who has view-only access to the map or is viewing a [presentation](/guides/presentations) or a [shared/embedded map](/guides/share-and-embed) will still see your popovers (the direct decorations toolbar is hidden for them, since they can't make edits to your map). {% hint style="info" %} If you're building popovers and want to see how they look before you publish, you can either follow the instructions in the [direct decorations guide](/guides/decorate/direct-decorations) to turn off the direct decorations toolbar, or simply click the ellipsis icon in the bottom right corner and select "Switch to preview mode". {% endhint %} ## Basic popover syntax Popovers are added through the Advanced Editor, using a simple syntax. ```scss selector { popover: "{{Field name}}"; } ``` Replace `selector` with any valid [selector](/guides/selectors), and replace `Field name` with the name of any of your fields. Remember to wrap each field name in double curly brackets `{{}}` and wrap the entire popover value in double quotes. For example, here is the code for an **element** popover that includes the **label** and **element type**: ```scss element { popover: "{{label}} {{element type}}"; } ``` {% hint style="info" %} When using the **Type** field in popovers, you need to specify whether it is **Element** Type, **Connection** Type, or **Loop** Type. For example, use `{{connection type}}` when adding Type to a connection's popover. {% endhint %} ## Using markdown to style the popover You can use [markdown](/guides/profiles/markdown) to add italics, bold text, videos, and more to your popover. You can also add double spaces to create line breaks. Here's a popover that uses markdown to style the label, add a horizontal rule, and add line breaks in between the fields: ```scss chapter { popover: "### {{label}} --- {{topic sentence}} {{image}}"; } ``` ![](/files/ov9NHe0oDFORV8odsQCB) Note that popovers automatically recognize images, so there's no need to style those with markdown. This works with hyperlinks as well—just use something like `{{website}}` or `{{image}}` in your popover, and the popover will render it properly. Popovers also recognize multi-pick fields (like Tags) and will render them as bulleted lists. ## Resizing the popover Kumu sets default popover sizes based on how much content is in each popover, but you can override these defaults using the `popover-height`, `popover-width`, and `popover-padding` properties. `height` and `width` control the vertical and horizontal size of the popover box, and `padding` controls the space between the edge of the popover and its contents. ```scss chapter { popover: "### {{label}} --- {{topic sentence}} {{image}}"; popover-height: 200; popover-width: 300; popover-padding: 3; } ``` **Good to know:** * `popover-width` is a great tool if you want to set a maximum width for images that you want to include in the popover. Kumu will resize the image to fit your `popover-width` without stretching or distorting the image. * If the height of your content exceeds your `popover-height`, Kumu will add a vertical scroll bar to your popover. ## Use cases Here are just a few cases where we think popovers are useful! ### Show connection labels on demand Sometimes you want to use connection labels to add information (such as role or nature of a relationship) but don’t want those showing up on the map all the time. In that case, just add the following: ```scss connection { label-visibility: hidden; popover: "{{label}}"; } ``` ![](/files/iHZPp1cjyjrsmFO3cxTi) ### Bring the profile into the popover The profile is great when you have a lot of information in the description as well as a number of fields. But when you only have one or two fields, sometimes it is easier to disable the profile and just use popovers instead. Our first step is to disable the profile for everything on the map: ```scss * { profile: false; } ``` We can then activate the popover for all elements and connections: ```scss element, connection { popover: "### {{label}} {{image}} {{description}}"; } ``` ![](/files/dheHmhVaxN834XHSmhcu) ### Highlight key facts and figures Ever sized elements or connections based on a quantitative data, but didn’t want people to have to dig through the profile to find the number? Use popovers to display those values instead: ```scss element { popover: "**Money raised for:** ${{money raised for}} **Money raised against:** ${{money raised against}}" } ``` ![](/files/nTrKPaGpNKsjhqSpl6DD) # Default view settings In Kumu, **default view settings** is your one-stop-shop for adjusting the underlying settings in your [view](/guides/views). Templates, layouts, default element and connection styles, and more can all be changed with default view settings. ## Change default view settings in the Basic Editor You can find the **Default view settings** tool in the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) by clicking the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of your map, and selecting **Customize defaults**.

Customize defaults

The tool has up to six sections, depending on the [template](/guides/templates) and [layout](/guides/layouts) you're using: Template settings, Element defaults, Connection defaults, Font defaults, Layout settings, and General settings. #### Template settings This section, which is only available for the systems, stock and flow, and causal loop templates, allows you to tweak things like same/opposite connection color, connection labels, and more. #### Element, Connection, and Font defaults These three sections allow you to change colors, sizes, widths, and other styles for all your elements and connections. Font defaults will apply to loops, as well. Note that any [decorations](/guides/decorate) you have created will override your default settings. #### Layout settings Layout settings are available when you are using the force-directed layout on your map. For more information on how to use this section, check out our [full guide on the force-directed layout](/guides/layouts/force-directed). #### General settings The General settings section allows you change your theme, template, quality, and layout. **Theme** can be either light or dark. The dark theme is great for big screens in dark rooms! **Template** allows you to choose one of Kumu's pre-built [templates](/guides/templates). **Quality** can be either high or low/fast. High quality gives you full access to Kumu's suite of decorations, but it will run slowly on very large maps. Low/fast, on the other hand, restricts your access to different decorations, but it helps large maps to load and animate much more quickly. **Layout** allows you to choose between the [fixed layout](/guides/layouts/fixed) (select "off" from the dropdown) or [force-directed layout](/guides/layouts/force-directed). ## Change default view settings in the Advanced Editor In the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), you can use the `@settings` at-rule to change default view settings: ```scss @settings { property: value; } ``` Replace `property` with any property from the [settings reference](/overview/advanced-editor-hub/settings-reference), and replace `value` with any valid value for that property, as described in the settings reference. # Export You can quickly export your entire map (or just a portion through selections). This makes it easy to refine your data in Excel (or Google Drive) and share it with others, or even transfer your data into a new project. You'll find the export button in the lower right corner of your project. You'll have four options for exporting: * [Export to PDF](#export-to-pdf-for-high-resolution-images) * [Export to PNG](#export-to-png-create-a-screenshot) * [Export to XLSX](#export-to-excel-for-bulk-editing) * [Export to JSON](#export-to-json-downloading-a-project-blueprint) ## Export to PDF: for high-resolution images If you need a hi-res screenshot that can scale up or down to any size (for example, when you're printing a Kumu map on a large poster), you can create hi-res PDF files. PDFs are free and unlimited for all projects in all workspaces. {% hint style="info" %} Want to make sure your labels are readable on your PDF or screenshot? [Learn how to remove label overlap](/guides/layouts/remove-overlap). {% endhint %} {% hint style="warning" %} PDFs do not render for:\ \- [Geo templates](/guides/templates/geo)\ \- [Presentations](/guides/presentations)\ \- [Grids & Guides](/guides/underlays)\ \- [Background images](/guides/decorate/images#add-a-background-image) {% endhint %} ## Export to PNG: create a screenshot To quickly snap a screenshot of your map, click the download icon in the bottom right corner, and select "Export to PNG". Note that the screenshot will be taken at your current position and scale on the map—if you'd like everything to be centered, click the zoom-fit icon in the zoom toolbar, or press `\` on your keyboard. {% embed url="" %} When Kumu brings up your screenshot, you can right-click the image and select "Save image as..." to save the image to your computer. {% hint style="info" %} Note that geo maps can not be exported to PNG. Also: the default background color of Kumu maps is off-white. If you wish to change the background color to a regular white so that it fits better within the rest of your document, you can add this code to the Advanced Editor: @settings { background-color: white; } {% endhint %} ## Export to Excel: for bulk editing If you choose "Export to XLSX" without anything selected, your entire map will be exported as a spreadsheet in xlsx format. If you only want to export a portion of your map, just select the things you'd like to export before clicking export. You'll now have all of your elements and connections available as two separate sheets in a xlsx file. You can use this to edit and refine your data if you (or your teammates) prefer working in Excel. Simply drag the file back onto the map when you're done to pick up any changes. *Note: If you're working with loops, you'll need to continue to edit them within Kumu as exports don't support loops yet.* ## Export to JSON: downloading a project blueprint If you need to backup your entire project (all maps, views, and underlying data **except presentations**), click the download icon in the lower right corner and choose "Export to JSON". This will create a [JSON blueprint](/guides/import/blueprints) which can be used as a snapshot in time of your project, and can be imported into a blank project to restore it. {% hint style="danger" %} **Note:** A JSON export does not include any [presentations](/guides/presentations) you’ve created in your project. If you import the JSON into another project, you’ll need to recreate any presentation(s). If your goal is simply to transfer your project to another account, [follow this guide](/frequently-asked-questions/how-do-i-transfer-a-project) to transfer the presentation(s) along with your project. {% endhint %} # Fields Fields allow you to save additional data about the elements, connections and loops in your map. Create whatever fields you need and modify the settings to enable things like checklists, prompts, currencies, and much more. **Skip to section:** * [Add a custom field](#add-a-custom-field) * [Customize a field](#customize-a-field) * [Field type](#field-type) * [Field prompt](#field-prompt) * [Field category](#field-category) * [Field relevance or privacy](#field-relevance-or-privacy) * [Field ordering](#field-ordering) * [Deleting a field](#deleting-a-field) * [Deleting field values](#deleting-field-values) *** ## Core fields Kumu comes with a set of core fields. Putting data in *all* of these fields isn't necessary, but they get special visual treatment in [profiles](/guides/profiles) and have special functionality, so it's great to use them when you can!
#### Label The Label field uniquely identifies an element, connection or loop. Look at it as the name for any of these entities. The label shows up all the way at the top of any element or connection profile. Your element, connection and loop labels will appear on the map by default. An element usually requires a label ([unless you're identifying by IDs](/frequently-asked-questions/how-do-i-avoid-duplicating-data#use-ids-to-separate-identical-labels)), but a connection doesn't necessarily need to have a label, unless you like to give it one. Your map shows an element, connection or loop's label by default. #### Type Use the Type field to categorize elements and connections. Common element types include 'person', 'project', or 'company'. Common connection types include the nature of the relationship, e.g. 'personal', 'business', or 'family', or whether a connection has a positive affect (+) or a negative effect (-). What's important to note here is that Type values are *mutually exclusive,* meaning that an element or connection type can only be one single value. For example, an element cannot be a 'person' and an 'organization' at the same time. #### Connection direction In a connection's profile, you'll see whether a connection is directed, undirected, or mutual. Direction determines where/if an arrow is depicted on one or both ends of a connection, and is used in [Metrics](/guides/metrics) calculations to analyze the structure of a network. When you export your map to Excel, you'll also see this field included in the Connections tab of your sheet. To change the connection direction, please visit [this guide](/frequently-asked-questions/how-do-i-add-arrows-to-my-connections). #### Description The description field is designed to hold longer-form content that describes an item. Descriptions can include multiple paragraphs, and even multimedia content. You can use [Markdown](/guides/profiles/markdown) to format your text and [widgets](/guides/widgets) to add multimedia content. #### Tags The tags field is designed to hold multiple values that each describe your item in a different way. This field is ideal for when an element can belong to *one or more* categories that do not need to be mutually exclusive. For example, a connection between a person and a non-profit might have the following tags: "Strong relationship", "Board Member", "Donor", and "Advocate", all stored as separate values in the Tags field, adding rich detail to that person's relationship with the non-profit. In the profile, tags appear under the description, and hovering your cursor over a tag will [showcase](/guides/showcase) other items with that same tag. #### Image Include an image URL or upload an image from your computer, and Kumu will display it on the map and in the profile. Learn more from [our full guide on images](/guides/decorate/images). #### URL Add any link to the URL, and the link will open when the element, connection, or loop is double-clicked. #### Email Add an email and Kumu will automatically include their [gravatar](http://en.gravatar.com/) on the map and in the profile. Gravatars can be a huge time saver when working with social network data! #### ID Add a unique ID to each element and connection when you want to have fine-tuned control over Kumu's decision to create or update items during a [spreadsheet import](/guides/import). To learn more about this, check out [our guide on avoiding duplicate data](/frequently-asked-questions/how-do-i-avoid-duplicating-data). ## Add a custom field To add a custom field, select an element or connection and then click the **+New Field** button in the sidebar. You'll be prompted to name the field and then enter a value for the element or connection you selected. By default, new fields are set to accept only one value and not prompt users with suggested values. While this is an easy way to get started adding values, you may have times where you want people to pick from a list of defined values (level of influence: high, medium or low) or multiple values from a list (skills: project management, web development, leadership, public speaking). In those cases, you can customize your field—keep reading to learn how! {% hint style="info" %} Field's can't be named `YES`, `NO`, `ON`, `OFF`, `TRUE`, or `FALSE`. Uppercase and lowercase versions of these words will cause errors elsewhere in Kumu. {% endhint %} ## Customize a field To customize the settings for a given field, click on an element, and click the field in the element's profile: ![Customizing a field](/files/3J3YJ8xwJmcwRW5l76WC) {% hint style="warning" %} Not able to click on your fields in the profile? It might be that you're [importing your data with Google Sheets](/guides/import#google-sheets) or a [remote JSON link](/guides/import/blueprints#set-a-remote-json-link). In this case, please follow these steps: \ 1\. Navigate to Project Settings in th top-left corner of your project (three stripes)\ 2\. Click on the Fields tab\ 3\. Choose the field you wish to edit by clicking on it\ 4\. Make any changes to your field's settings\ 5\. Make sure to save at the bottom of the page! {% endhint %} A dropdown will appear with the following options: * **Name** - change the name of your field * **Type** - string, text, URL, email, number, currency * **Limit** - one value **OR** none (one or more values) * **Prompt** - none, autocomplete, or list * **Category** - for grouping fields in sections on the profile * **Visibility** - public **OR** private (whether or not viewers can see a given field) * **Clustering** - whether to allow clustering by this field * **More** - access settings, relevance, or delete the field Let's look at a few of these options in more depth: ### Field type Below are the choices for the field format and guidance on when to use each: * **String** - This is the default value and used when entering simple, short pieces of text * **Text** - Used for longer text fields like notes, addresses, and anywhere you want to use [Markdown](/guides/profiles/markdown) formatting * **URL** - Used for website addresses * **Email** - Used for email addresses * **Number** - Used for numerical values that aren't currencies or dates * **Currency** - Used for financial values to be displayed with standard currency format ($) * **Date** - Used for dates, like February 14th (Kumu's birthday!) ### Field prompt Field prompt is managed by clicking "more" and then "settings" in the dropdown. Below are the choices for the field prompt and guidance on when to use each: * **None** - Use when you'd like to turn off any prompts for field values * **Autocomplete** - Use when you'd like a tag-like interface for prompting values that match the current input * **List** - Use when you want to pick from a list of defined values {% embed url="" %} ### Field category By default, all fields are ordered alphabetically based on the name of the field. You can also group fields by assigning them a category. For example, you may want to have all financial information (FY 2012 Investment, FY 2013 Investment and Cumulative Investment) under the category "Financials". You can create multiple categories and each will be ordered alphabetically. We reserve a few category names that we give special treatment to: * **General** - This is the default. Fields in this category will live at the top of the field section and won't have an explicit category label. * **Footnotes** - This category is meant for things like attribution and citing your sources. Fields in this category will always be listed at the bottom of the profile. * **Metrics** - This category holds any of the data you create using Kumu's [Metrics](/guides/metrics) tool. ### Field relevance or privacy **When do I see a field?**\ By default, all fields are shown in the profiles of all elements, connections, and loops while you're editing the map. Even if a field has a blank value, it will still show up in the profile. But, in each profile, Kumu will automatically *hide* all blank fields in the following cases: * When someone is viewing a [presentation](/guides/presentations) * When someone is viewing a [shared/embedded map](/guides/share-and-embed) * When someone is viewing the source project, but they don't have edit access **Hide fields across all profiles**\ If you'd rather hide irrelevant fields while you're editing the map, you can use **field relevance** in your project settings. Click the menu in the top left of your map and then click "fields". Scroll down and you'll see a "relevance" section. To edit which fields should be included for each of the element, connection, and loop types in your project, click edit, uncheck the relevant fields, and click "Done" at the bottom of the field list. ![field relevance](/files/3NRrHTCYBam00tRaLJMc) If you'd like to limit the fields that are shown, simply click edit and then uncheck the field you'd like to hide in the profile for a given type. Label, type, description, and tags are always shown for all types regardless of what you enter. Above is an example of customizing the profile of elements with type of "Company" to only show Image, Website, URL and Attribution. **Hide fields for viewers only**\ You might also want to hide a field from view for anyone who is not a contributor. For example, this is handy when you're working with information that is not relevant to the viewer. In this case, you can make a field "private" and hide it from view for anyone who is not a contributor. {% hint style="warning" %} **Note:** If you're hiding a field from viewers, the data is never completely hidden from your project. When viewing a map, the data is still passed to the browser to enable decorations and other view settings to work for those fields. This means that anyone who has access to view the map can technically get access to the data in hidden fields (even though it is hidden from the profile). If anything is unclear about this, please contact our support through . {% endhint %} To do so, click on any custom field and then check the Privacy checkbox: ![field privacy](/files/ucgWfT2vTus0azRrxwek) **Hide fields in certain "entity" profiles only**\ You can also indicate whether you'd like profile fields to show up in element, connection, or loop profiles (or all of them). The field (and any field values) will then be hidden in any profiles in which you don’t want it to show up, whether it contains any values or not.
{% hint style="info" %} * By default, a field is ‘relevant’ (shows up) in all profiles. * Default fields such as `element type`, `tags`, `description` etc. cannot use field relevance, as they must always be visible to editors in each profile. {% endhint %} ### Field ordering You can also use the field relevance menu to change the order fields are listed in the profile. By default all fields are listed alphabetically (and optionally broken into sections if you've assigned categories). The order of fields is unique to each element or connection type. To change the order, click edit next to the element type that you'd like to adjust: ![Edit field order](/files/aBifg4qOHvmDZagM9BBf) And then simply drag the fields to reorder them: ![Drag field order](/files/a58gZNzFo9Cfr3lQtSUH) When you are finished, click "Done" and you'll see the new order reflected in the profile. ## Deleting a field If you've created a field and want to delete it and all corresponding values, click on the label of the field in any profile and then go to more -> delete. Alternatively, you can use the menu in the upper left corner to go to the field settings page (choose fields). This will delete the field and any values assigned for any content in your project. {% hint style="warning" %} Note: when [importing data from a Google Sheet](/guides/import#google-sheets), you have to add/edit/delete your fields in the Google Sheet directly. You're not able to make these changes within Kumu. {% endhint %} ## Deleting field values Occasionally you may want to delete the prompted choices for a given field, or the options that show up in your legend or in a [control](/guides/controls). To do this, you need to delete the underlying field value. This process is different depending on the field's [prompt](#customize-a-field). For fields that have their prompt set to "Autocomplete" or "None" (this includes the Tags field), you can only delete the field value by removing it from every element, connection, and loop in the project, including the [trash](/overview/kumus-architecture#trash). For all other fields (including Element Type, Connection Type, and Loop Type), follow these steps: 1. Click the menu in the upper left of your map and choose **FIELDS** 2. Click on the field you want to edit 3. Find the value you want to delete. Then, click the delete button next to the value to delete it. 4. Scroll down and click **SAVE** to save your changes 5. Refresh the page After you follow these steps, the field value(s) you deleted will no longer show up in prompted lists, in legends, or in controls. # Computed fields Computed fields are a special type of field that allow you to calculate values automatically based on an expression that you specify. ## Creating a computed field You can create a computed field in one of two ways: 1. Type `= expression` into any field value and it will convert that field to a computed field using the specified expression. 2. Click on the label of any field from the profile and then use the dropdown menu to access the settings. Under "Advanced Settings" you'll see an "expression" input where you can type the expression (no `=` required). ## Supported syntax #### Concatenating text in computed fields To create a new string (a piece of text) using computed fields, just type your expression inside a pair of double quotes. Include a value from another field using double curly brackets `{{}}` with the field name inside, in all lowercase letters. For example, here's the expression for computed field that combines the elements label and type in a simple sentence. ``` // Note the double quotes surrounding the expression, // and the double curly brackets around each field name. = "{{label}} is a {{type}}" ``` You can also bring numbers into your expression: ``` = "Dr. Evil is demanding ${{ridiculous amount of money}}" ``` #### Doing math in computed fields We use [mathjs](https://mathjs.org/docs/expressions/syntax.html) to power computed fields and you have their complete expression syntax to use within Kumu. It's pretty similar to writing an equation in Excel or Google Sheets (with the caveat that we don't support all the functions you'd find in a spreadsheet, like `vlookup`). If the field you are using in your expression is a single word, you can just write it as-is in the expression. If it is more than one word, you'll need to wrap the field name with two mustaches on either end `{{my longer than neccessary field name}}` . For all field names, be sure that they are written in all lowercase letters. Here's some examples: * Add two values `betweenness + eigenvector` * Multiply two values `{{level of influence}} * degree` * Create a more complicated ratio `(indegree + outdegree)/betweenness` * Check for a value and output a number `(archetype == "yes" ? 1 : 0)` * Take the log of a value `log(networth)` That's just the tip of the iceberg. Head over to [mathjs](http://mathjs.org/docs/expressions/syntax.md) if you're interested in what else is possible. ## Things to watch out for When you are building expressions, you need to be careful not to build an expression that may lead to an undefined value or an error. Here's a few common stumbling blocks: ### Dividing by 0 For those of you whose last math class was decades go - remember you can't divide by 0 (or you can, but we'll display the answer as "infinity"). One way you may run into this is when creating an equation for leverage. Leverage is usually defined as "outdegree/indegree". If you have an element with no incoming connections, you're going to get "infinity" as the answer which will throw off your decorations. Instead, try tweaking the expression so that it is: ``` (outdegree + 1)/(indegree + 1) ``` ### Order of operations matters Order of operations applies to expressions so make sure to wrap the portions of your expression that you want to be calculated first in parentheses. For example... ``` indegree + outdegree / betweenness ``` will get a different result from ``` (indegree + outdegree) / betweenness ``` ### Avoid null values If you have a field without a value defined, it can cause errors when running the expression. Make sure each element has at least some value and if you are using yes/no types of fields, make sure to include "no" instead of just leaving it blank. ## Advanced usage Some of you are interested in creating an uber analysis metric based on whether there are qualitative and or quantitative values in other fields. You can create conditional statements that provide different values based on whether the criteria is met. The below example involves two fields, "archetype" and "trend" that each store "yes" or "no" values. We're essentially looking to give a point anytime the answer is "yes" and then add up those points. Here's the expression: ``` (archetype == "yes" ? 1 : 0)+(trend == "yes" ? 1 : 0) ``` Make sure that you're including "no" for the fields that aren't "yes" instead of just leaving them blank as it will throw an error that will prevent the expression from running. ## Limitations Currently you can only create a computed field that pulls values from other standard fields in Kumu. You cannot create a computed field which pulls values from other computed fields. For example, if you created a computed field "total contributions" which was based on the expression `{{amount for}} + {{amount against}}`, you couldn't use "total contributions" in another computed field that was looking at the relative percentage of for vs. against. This **wouldn't** work: ``` {{amount for}} - {{amount against}} / {{total contributions}} ``` But just including the expression again for "total contributions" **would** work: ``` {{amount for}} - {{amount against}} / ({{amount for}} + {{amount against}}) ``` # Filter Filters allow you to show and hide elements, connections or loops based on information stored in their [fields](/guides/fields). This guide will help you master filters, one of the most powerful tools in Kumu! {% hint style="info" %} Before you start: [use fields](/guides/fields) to add additional information to your elements, connections, and loops. {% endhint %} ## Filter in the Basic Editor Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map, then click the icon to the right of **Filter** to open up your filter settings. ![filter](/files/NNNxeotagUmPJbD0pzMO) If you're filtering by element or connection type, simply un-check the types you want to hide. To filter using other fields, use the "also include" and "but ignore" fields. Click the rocket icon ![](/files/hnLxVe0GJLgW3aMjsSeF) to the right of the input of each field to select what you want to hide or make visible. If you've hidden certain elements and connections using the type checkboxes, you can use the **Also include** tool to bring things back into view. But, you first have to un-check some of the boxes above, or this tool will have no effect. Use the **But ignore** tool to hide elements and connections from your map. Anything you add here will override the settings in the checkboxes above and the **Also include** tool. ## Filter in the Advanced Editor If you prefer working in the Advanced Editor, you can use the `include` and `ignore` properties in the `@settings` block to activate filters. Here's the basic syntax: ```scss @settings { include: selector; ignore: selector; } ``` You can replace `selector` with any valid [selector](/guides/selectors). For example, here is the code for a view that includes elements with the element type "Person" but ignores all elements who have no Tags in their profile: ```scss @settings { include: person; ignore: element[!"tags"]; } ``` If you want to include or ignore multiple different selections, you can separate selectors with a comma. Here's the code for a view that includes three different selections: 1. All connections 2. All elements with the element type "Organization" 3. All people with the tag "Board of Directors" ```scss @settings { include: connection, organization, element["tags"*="Board of Directors"]; } ``` #### Ignore orphans You can also use the `ignore-orphans` property in the `@settings` block to automatically filter out any elements that have no connections. Possible values for this property are `true` or `false`. ```scss @settings { ignore-orphans: true; } ``` ## Activate filter using controls If you'd like to make it easy for readers to activate filter on their own with predefined options, check out the [filter](/guides/controls/filter-control)[ control](/guides/controls/filter-control). # Focus Kumu's **focus** feature allows you to focus on one or more elements, connections, and loops, temporarily hiding the rest of the map. It's a great tool for storytelling, allowing you to reduce the complexity of your system or network while you introduce the basic concepts behind your map. Focus is activated in one of two ways, by clicking and holding on any element, connection or loop or by selecting an element, connection or loop and then clicking the focus icon on the right side of your map. Once focus is activated, you can walk in and out by degree using the and buttons. ![focus animation](/files/QYAqxRvpncbK7beCayha) Click the focus icon again to bring the full map back into view. {% hint style="info" %} Keyboard shortcuts: Press `+` and `-` on your keyboard to expand and contract focus, or press a number on your keyboard to specify exactly how many degrees the focus should extend. Press `esc` on your keyboard to bring the full map back into view. {% endhint %} ## Focus in the Advanced Editor You can pre-define a focus within `@settings` in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) of any view. ```scss @settings { focus: #jack out 2; } ``` The above will load the map with Jack and any other elements that are within 2 degrees. You can add multiple hubs by using a comma to separate them: ```scss @settings { focus: #jack out 2, #companyxyz out 1; } ``` This will load the map with Jack and any other elements that are within 2 degrees, as well as Company XYZ and any elements that are directly connected. You can use any [selector](/overview/advanced-editor-hub/selector-reference) to set the focus of the map. For example, you could set the focus to show only influential people, out 2 degrees: ```scss @settings { focus: person["level of influence"="High"] out 2; } ``` ### Focus direction In the Advanced Editor, you can also customize **focus direction** to specify which connections should be shown. ```scss @settings { focus-direction: all; } ``` The options are: * `in`: Only show connections leading into focused elements. * `out`: Only show connections leading out from focused elements. * `all`: Show all connections connected to focused elements. This is the default value. ### Prompted mode Prompted mode builds on the preset focus by allowing users to build a map based on search criteria. When you've enabled prompted mode, users are presented with a search prompt rather than seeing the full map. Users can then type the name of any element and hit enter to add them to the list of elements to be included in the map. By default that element and its direct connections will be included, but you can tweak the "out 1" setting to also include second and third degree connections. ![prompted mode](/files/KhmpGSVklM95S8Ofurjg) Click build map and voila! You can also use "out n" for a search to automatically change the number of degrees out included in the search results. For example, "Bill Gates out 3" will display Bill Gates and all elements within 3 degrees. ![the map](/files/dR6negomDzrFo2kPI0gC) Hit escape on your keyboard to start over, or use the focus menu and choose "back to prompt" to edit the current map. ![focus prompt](/files/pemWZSRpi3Yw89IwVLTr) To enable prompted mode, you'll need to add the following to the advanced tab of any view you'd like it active within: ```scss @settings { focus: prompt; } ``` ## Activate focus using controls If you'd like to make it easy for readers to activate focus on their own with predefined options, check out the [focus control](/guides/controls/focus-control). # Forking A fork is a copy of a project. Forking a project allows you to experiment with changes without affecting the original project. Forks are commonly used to propose changes to someone else's project or to use someone else's project as a starting point for your own. ## Creating a fork To fork a public project, click the menu in the upper left corner of the map and then click fork project (). This will: * Create a copy ("fork") of the entire project, including all views, maps and presentations * The fork will be created under your personal account with the same name as the original project * Only you will have access initially to the fork (but you can add other collaborators as needed) * All presentations in the fork revert to unpublished (even if they were published in the original) * Any links in the project will remain the same (so make sure to use relative links to have a fork-friendly project) While public projects can be forked by anyone, private projects can only be forked by their owners. If you would like to make a fork of a private project you don't own, follow these steps: 1. Have the project owner make their own fork of the project. 2. Have the project owner use the [project admin menu](/guides/project-admin) to transfer the project to your account. ## Intellectual property and forking By giving others access to your project on Kumu, you [agree](https://kumu.io/terms) to let them fork the project. This does not grant any rights beyond creating the initial fork. To make it clear what others are permitted to do with your project, we encourage each project to include a license at the bottom of the default map's description. The license you use is up to you, but we hope many of you choose to share your projects generously with the community. We've released a new license called the [Kokua License](https://medium.com/@rymohr/the-kokua-license-b2f430a03f4a#.razdhigjg) to make that even easier. # Grids & Guides Grids & guides are a great tool when you need to add some structure or context to the background of your map. Kumu supports the following underlays: * [Grids](#add-a-grid) * [Guides](#add-guides) * [Radars](#add-a-radar) * [Background images](#add-a-background-image) *This video below explains how to create Grids & Guides in the advanced editor. Want to know how to use them in the Basic Editor? Please jump to the sections listed above.* {% embed url="" %} ## Add a grid **In the Basic Editor** 1. Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)to open the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) 2. Click "More" and then select "Grids & Guides" to open the menu 3. Check the "Show grid" checkbox to make the grid appear You can use the settings below **Grid** to adjust color, offset and width of your grid.

Add a grid

**In the Advanced Editor** ![grid showcase](/files/g1w8Zhnz1EXfNzajS1wO) You can use the `layout-grid` property of `@settings` in the Advanced Editor to add a grid: ```scss @settings { layout-grid: on; } ``` Once you have the grid turned on, you can customize the distance between gridlines using `layout-grid-offset` and customize the width of lines using `layout-grid-width`. ```scss @settings { layout-grid: on; layout-grid-offset: 20; layout-grid-width: 1.5; } ``` By default, gridlines will extend infinitely. But, you can use the `layout-bounds-xmin`, `layout-bounds-xmax`, `layout-bounds-ymin`, and `layout-bounds-ymax` properties to set a stopping point for the gridlines. ```scss @settings { layout-grid: on; layout-bounds-xmin: 0; layout-bounds-ymin: 0; layout-bounds-ymax: 550; layout-bounds-xmax: 500; } ``` ![grid with bounds](/files/rSgQhgUHUtQOAkMGi5fE) Finally, you can use the `layout-grid-color` property to customize the color of gridlines (replace `color` with any CSS web color or hex color code): ```scss @settings { layout-grid-color: color; } ``` ## Add guides **In the Basic Editor** To add a guide to your map, follow the following steps: 1. Click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH)to open the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) 2. Click "More" and then select "Grids & Guides" to open the menu 3. Adjust the guide settings and click "Add guide" to make the guide show up on your map

Add guides

Guides can be *horizontal*, *vertical*, or even a *circle*. To remove an existing guide, click the "Remove" button. **In the Advanced Editor** You can use the Advanced Editor to add vertical, circular, or horizontal guidelines. Here's the basic syntax for vertical and horizontal lines: ```scss @settings { layout-guides: x(coordinate), y(coordinate); } ``` Replace `coordinate` with any number, indicating the x or y coordinate where you would like the guide to be drawn. `x(coordinate)` draws a vertical line, and `y(coordinate)` draws a horizontal line. To draw circular guidelines, you can choose between two different syntaxes: ```scss @settings { layout-guides: circle(radius), circle(x, y, radius); } ``` If you're using the `circle(radius)` syntax, replace `radius` with any number to draw a circle with that radius. When you're using this syntax, the circle will always be centered at `0, 0`. If you'd like to center your circle somewhere else, for example, an x coordinate of 40 and a y coordinate of 20, you can use the `circle(x, y, radius)` syntax. Replace `x` with the center's x coordinate, `y` with the center's y coordinate, and `radius` with the circle's radius. **Note:** to add more than one guide, just leave a space between the guide declarations. Here's an example that adds two vertical lines, one horizontal line, one circle with radius `100` centered at `0, 0`, and one circle with radius `100` centered at `100, 50`: ```scss @settings { theme: dark; layout-guides: x(0) x(100) y(0) circle(100) circle(100, 50, 100); } ``` ![guides example](/files/b4lPiOqXmNwKPMmUM858) For additional styling, use the `layout-guide-width` and `layout-guide-color` properties to customize the width and color of guides. ## Add a radar You can add a radar of concentric circles to your background to play with positining of your elements. If you want to pin elements in place, visit [this guide here](/frequently-asked-questions/how-do-keep-elements-from-moving). ![default radar](/files/cFS0a9e0VVJ3RcnMMuFn) You can use the `radar` property of `@settings` in the Advanced Editor to add a radar: ```scss @settings { radar: on; } ``` The radar will come with a few default rings and axes, which you can easily override using the `radar-rings` and `radar-axes` properties. Each comma-separated value in those properties will create and label a new ring or axis: ```scss @settings { radar: on; radar-rings: INTENT, DESIGN, FEEDBACKS, PARAMETERS; radar-axes: BEFORE PROBLEM, FIRST CONCERN, PROBLEM, CRISIS, ADAPT OR RESTORE; } ``` ![systems leverage radar](/files/7dsGkPobm3DS2xak0GtR) You can customize your radars extensively, changing the color, font color, the distance between rings, etc. To see a full list of supported properties and learn how they customize the radar, head over to our [@settings reference](/overview/advanced-editor-hub/settings-reference) (type "radar" to filter the list). ## Add a background image For full instructions on adding a background image, see [our full images guide](/guides/decorate/images#add-a-background-image). # Import Kumu's import feature makes it possible to map your existing data, without recreating every bit of it by hand. {% hint style="warning" %} Before you import your data, make sure to [structure it for Kumu to understand](/guides/import/import). {% endhint %} {% embed url="" %} Full video on importing data {% endembed %} ## Three options for importing data Kumu offers three ways to import data. Read about them below! ## **Excel /CSV** An Excel sheet or a Comma Separated Value (CSV) file is one of the most common ways to hold and edit data. **Pros** * Most platforms allow you to export data into an .xlsx or a .csv file. You'll then be able to easily [structure it for Kumu](/guides/import/import) and import it into your project * Great for bulk-editing data by dragging cells and using formulas in your Excel sheet **Cons** * Not great for cases where data requires frequent updating: each edit to your Excel sheet requires a re-import into Kumu * Re-imports into Kumu increase the chances of duplicating data. Read how to prevent this in [this guide](/frequently-asked-questions/how-do-i-avoid-duplicating-data) * As soon as you make changes to your data directly in Kumu, your Excel sheet will be outdated. (Luckily, you can always [export your Kumu map](/guides/export) into an Excel sheet to get the most updated version again) [Visit our guide to import data with Excel/CSV here](/guides/import/excel-csv) ## **Google Sheets** Google Sheets provides online spreadsheets that can be edited by multiple people at the same time. **Pros** * Updates data in your Kumu map after each page refresh * Great for crowdsourcing: allow people to add/edit their data without giving direct access to the Kumu map * Allows for real-time collaboration: multiple people can work on the sheet at the same time * Allows for versioning and activity-tracking: you can always see who made changes and/or restore to an earlier version of your data **Cons** * Data in Kumu is read-only. Any changes to underlying data must be made in the Google Sheet. * Some Kumu features (such as [pinning elements in place](/frequently-asked-questions/how-do-keep-elements-from-moving), [popovers](/guides/decorate/popovers), and [direct decorations](/guides/decorate/direct-decorations)) don’t work for maps connected to a Google Sheet [Visit our guide to import data with Google Sheets here](/guides/import/google-sheets) ## **JSON / Blueprints** You can create our JSON imports—we call them **blueprints**—in any language from any dataset. Kumu can interpret JSON files and JSON remote links. A JSON file simply holds data structures and objects, while a JSON link is commonly used for transmitting data between web applications (e.g., sending some data from an external server to Kumu, so it can be displayed on your map). **Pros** * A remote JSON link is the closest thing Kumu has to a public API * JSON files are great to use as downloadable backups of your project **Cons** * Not easy for bulk-editing data * Requires knowledge of JSON-structured data or a willingness to learn [Visit our guide to import data with JSON here](/guides/import/blueprints) {% hint style="success" %} Want to dive right in? [Find some example data sets here](https://drive.google.com/drive/folders/1_xoIFJ2snCcxta1Fw8AwrxWCe5YlKXCW?usp=sharing). Need some inspiration? [Find some Kumu Projects in the Wild here.](https://kumu.io/kumu/projects-in-the-wild#projects-in-the-wild) Want to add your Kumu project to Projects in the Wild? [Submit it here.](https://form.typeform.com/to/aUUuSLnj) {% endhint %} # Structure your data for Kumu This guide explains how to structure your data in Excel or Google Sheets. Finding it challenging to start from scratch? Do it the other way around! Manually create a few elements, connections, and some profile fields in Kumu, and click the [export](/guides/export) icon in the bottom-right corner of your project. **Skip to section:** * [Common Import Pitfalls](#common-pitfalls) * [Master Imports in 5 Steps](#master-imports-in-5-steps) ## Structure your data Before you can import your data into Kumu, you'll need to structure your spreadsheet so that Kumu can read it. First, make sure your spreadsheet contains the following required column headers: **For elements** * Label (must be in the first cell of Column A) **For connections** * From (must be in the first cell of Column A) * To (must be in the first cell of Column B) After you create the required column headers, you can start filling out the rows to create new elements and connections. You can also optionally add more columns to hold custom data: **For elements** * Type * Description * Tags * Organization * Net worth ...etc. **For connections** * Type * Description * Tags * Label * Strength ...etc. All of these optional columns can be used to add data to [fields](/guides/fields) inside your elements and connections. If you want to store multiple values inside of one cell (for example, tags or keywords), just separate each value with the pipe character `|`. If you put multiple elements in the "To" cell of a connection, separating each element with the pipe character `|`, Kumu will draw a connection from the "From" element to each separate element in the "To" cell. {% hint style="info" %} It's also possible to use ID as the first column header in element and connection sheets. To learn how and why you would do that, [check out our guide on avoiding duplicate data](/frequently-asked-questions/how-do-i-avoid-duplicating-data). {% endhint %} Here's a sample element import spreadsheet: | Label | Type | Description | Tags | | --------- | ------- | ----------------------------------------------------------- | --------------------- | | Jeff Mohr | Person |

Co-Founder and CEO, always
up for learning

| Founder\|Male\|Runner | | Kumu | Company |

A web-based platform
for mapping relationships...

| Mapping\|Technology | And here's a sample connection import spreadsheet: | From | To | Type | Strength | | ---------- | -------- | ---------- | ---------------- | | Barack | Michelle | Personal | Strong | | Ed Snowden | NSA | Contractor | It's complicated | {% hint style="success" %} Get your hands dirty! [Click here for a sample import file](https://docs.google.com/spreadsheets/d/1f0OesdZ32eqKWG77v3fsL7htW5TxeBSX/edit?usp=sharing\&ouid=107261106798466659559\&rtpof=true\&sd=true) for the [PayPal Mafia map](https://kumu.io/jeff/paypal-mafia), or find our [folder of public data samples here](https://drive.google.com/drive/folders/1_xoIFJ2snCcxta1Fw8AwrxWCe5YlKXCW?usp=sharing). You can examine these files to see how imports work with real data before creating your own import file. {% endhint %} {% hint style="info" %} If you need to convert an [adjacency matrix](https://en.wikipedia.org/wiki/Adjacency_matrix) to meet Kumu's format, see our ["How do I restructure my adjacency matrix"](/frequently-asked-questions/how-do-i-restructure-my-adjacency-matrix) FAQ. {% endhint %} #### Ignore unneeded sheets Sometimes, you'll have other sheets in your Excel or Google Sheets workbook that aren't formatted for Kumu and shouldn't be imported, but need to stay in the workbook. If that's the case, just add `(ignore)` to the name of the sheet, and Kumu will ignore it during the upload. ## Common pitfalls Having trouble with your import? If Kumu is giving you an error message, click on the triangular error icon to see what is wrong. If Kumu just loads indefinitely, there's also likely something wrong with the format of your sheet(s). Here are a few common pitfalls... #### Not starting your file with the correct column headers **Label** should be the first column header in your spreadsheet (cell `A1`) for an element import, and for a connection import, you should have **From** and **To** in the first two columns (cells `A1` and `B1`). The only exception to this is when you're using IDs in the first column, please read more about that [here](/frequently-asked-questions/how-do-i-avoid-duplicating-data#use-ids-to-separate-identical-labels). #### Not having column headers in the first row Your column headers (e.g. Label, Type, Description, etc.) should be in row 1 of your spreadsheet. #### Not ignoring unneeded sheets If you have multiple sheets in your file, and you only want to import some, make sure that Kumu ignores the other sheets when importing. To do this, you can add `(ignore)` to sheet names—for example: `Sheet 3 (ignore)`. Also make sure to double-check if you have any hidden sheets in your file! #### Hidden data in unused cells If it seems like your spreadsheet is taking *forever* to load, or it's consistently throwing errors, you might have some data or formatting hiding in your unused cells. To clear all content and formatting from unused cells in Excel, [follow this Excel guide](https://support.office.com/en-us/article/clear-cells-of-contents-or-formats-9ff6b8ff-1afd-495f-8ad8-8c1f6f82a9d6). #### Trying to import .xls files If you run into this error message... {% hint style="danger" %} Sorry, there was an error with your import.\ Error: Import format not recognized: auto {% endhint %} ...you're trying to import an .xls file. Save it as .xlsx and try again! #### Importing an Excel file in Google Drive as a Google Sheet If you add an XLSX file to Google Drive, it will still open as an Excel sheet, only inside Google Drive. Make sure you're file is actually a Google Sheet by clicking on "Open with" at the top of the page and choosing Google Sheets, or by clicking File in the top-left corner and then choose "Save as Google Sheets". You can enter that sheet's link as your Google Sheet link. **Too much data** Kumu can only [handle so much data](/frequently-asked-questions/how-much-data-can-kumu-handle). Perhaps you're trying to add 10,000+ data points? Try importing a sub-set of your data first. If that imports without a problem, then your dataset is likely too large for one Kumu project. #### Funny character issues? If you're running into funny character issues, please make sure your import file is [UTF-8 encoded](https://help.alchemer.com/help/encode-an-excel-file-to-utf-8-or-utf-16). ## Master Imports in 5 Steps Looking to hone your importing skills? These tips will turn you into a master importer: 1. [Separate elements (or element types) and connections into their own sheets](#1-separate-elements-or-element-types-and-connections-into-their-own-sheets) 2. [Take advantage of pre-named fields](#2-take-advantage-of-pre-named-fields) 3. [Use pipes to separate | multiple | values](#3-use-pipes-to-separate-multiple-values) 4. [Try to be selector friendly](#4-try-to-be-selector-friendly) 5. [Ask for help!](#5-ask-for-help) #### 1. Separate elements (or element types) and connections into their own sheets Since elements and connections often have very different sets of fields, we recommend using separate sheets in your workbook for each dataset. Sometimes, you'll have different types of elements (for example, people and organizations) that have very different fields. In that case, you can separate those elements into separate sheets as well. Each separate sheet can have different column headers, and Kumu will still be able to read and understand each sheet. If you prefer keeping everything within a single sheet, you can use two blank rows to tell Kumu that a new section is starting—that is, Kumu should look at the first row of the new section to find column headers. If you are using a .csv file, this tip doesn't work—you'll need to either use the single sheet method or create separate files for elements and connections. #### 2. Take advantage of pre-named fields Our pre-named fields aren't required in your spreadsheet, but they get special visual treatment in [profiles](/guides/profiles), so it's great to use them when you can! TypeUse the type field to categorize elements and connections. Common element types include person, project, and company. Common connection types include personal, business, and family. [Try to be selector friendly](#try-to-be-selector-friendly) with your types, when you can.DescriptionThe description field designed to hold longer-form content that describes an item. Descriptions can include multiple paragraphs, and even images and videos. [You can use Markdown](/guides/profiles/markdown) to format each description's content.TagsThe tags field is designed to hold multiple values that each describe your item in a different way. For example, a connection between a person and a non-profit might have "Strong relationship", "Board Member", "Donor", and "Advocate" all stored as separate values in the Tags field, adding rich detail to that person's relationship with the non-profit.\ \ Make sure to separate multiple tags using a pipe "|" in your spreadsheet cells, and [try to be selector friendly](#try-to-be-selector-friendly) with your tags, when you can.ImageInclude an image URL and Kumu will display it on the map and in the profile.EmailAdd an email and Kumu will automatically include their [gravatar](http://en.gravatar.com/) on the map and in the profile. Gravatars can be a huge time saver when working with social network data! #### 3. Use pipes to separate multiple values For columns with multiple values in a single cell (such as tags, skills, hobbies, etc), you need to separate them using the pipe character `|`. If you're already separating them using commas, just use find-and-replace to swap out the commas for the pipe character `|` before importing. #### 4. Try to be selector friendly [Selectors](/guides/selectors) provide a simple way to slice up your data. By keeping your field names and values selector-friendly, you'll be able to write much shorter queries. Use single words for your element types, connection types, and tags. By doing so you'll be able to use shorthand selectors in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), such as: * `person` To select all elements with type "Person" * `personal-connection` To select all connections with type "Personal" * `project.priority` To select all projects tagged "priority" If you include special characters or multiple words, you'll have to use longer selector code instead (e.g. `["element type"="Government Sector"]`)—and that's just not nearly as much fun! #### 5. Ask for help! Still have questions? Having trouble structuring your data? [Let us know!](/about-kumu/where-can-i-get-help) We've massaged *a lot* of data to get it into Kumu's format, and we're happy to help. # Excel / CSV After you've [structured your data](/guides/import/import), save your spreadsheet file with either the .xlsx or .csv extension (Kumu doesn't support the .xls file extension). Then, you can import that file into Kumu in two different ways: **1)** Simply drag and drop the file onto the map's canvas. OR **2)** Click the green **+** button at the bottom of your map, select **Import**, and click "Select .xslx file" (this button works for .csv files as well). Then click "Import spreadsheet". Either way, you'll have the option to review the import before finalizing to double-check that everything imported correctly. After you review the import, just click save, and you're all set! {% hint style="success" %} Get your hands dirty! Find some example data sets, and their accompanying maps, in our [public data samples folder](https://drive.google.com/drive/folders/1_xoIFJ2snCcxta1Fw8AwrxWCe5YlKXCW?usp=sharing). {% endhint %} {% hint style="info" %} Seeing errors during your Excel import? You can use the [common pitfalls](/guides/import/import#common-pitfalls) section of this guide to help troubleshoot. {% endhint %} # Google Sheets Our Google Sheets integration populates a map using the contents of a spreadsheet hosted on Google Drive. Any data you add, edit, or delete in a Google Sheet connected to a Kumu project will be reflected in Kumu as soon as you refresh the page of your project. There are two versions of the Google Sheets integration, private and public: * **Private** is more secure and uses oAuth to authorize Kumu to access the sheet. It means that your Google Sheet is private to you and anyone you explicitly give permission to view and/or edit your file. * The **Public** integration requires you to make your data publicly viewable on the internet. Anyone with the link to your Google Sheet will be able to view and/or edit and/or comment your data {% hint style="info" %} Pssst! We wrote ["The Ultimate Guide to using Google Sheets with Kumu"](https://blog.kumu.io/the-ultimate-guide-to-using-google-sheets-with-kumu-d46e96fd47a8) to help you unlock all of the Google Sheets superpowers. Have a look if you're interested in external integrations, crowdsourcing, visualizing surveys etc! {% endhint %} ## Connect your Google Sheet to Kumu 1. Create a spreadsheet with Google Sheets 2. [Structure your data](/guides/import#structure-your-data-for-kumu) for Kumu 3. Click on "Share" in the top-right corner of your Google Sheet. Make sure to check below the "General access" section whether your file is *private* (set to "restricted"), or *public* (set to "Anyone with the link"), and make a change if necessary. Then click "Copy link" 4. Open your Kumu project, click the green **+** button at the bottom of the screen, and choose "Import" from the popup 5. Paste the shareable link in the correct box below the text "Link map to public / private Google Sheet" 6. Click “Import spreadsheet” 7. Wait for Kumu to review your data, and then click Save Import 8. Voilà, your data will appear! {% hint style="info" %} Seeing errors during your Google Sheets import? Visit the [common pitfalls](/guides/import/import#common-pitfalls) guide to help troubleshoot. {% endhint %} {% hint style="success" %} Get your hands dirty! Find some example data sets, and their accompanying maps, in our [public data samples folder](https://drive.google.com/drive/folders/1_xoIFJ2snCcxta1Fw8AwrxWCe5YlKXCW?usp=sharing). {% endhint %} ## Caveats for the Google Sheets integration Unlike file-based imports, the Google Sheets integration is an ongoing import. The elements and connections will be fetched from the spreadsheet on the fly each time you refresh the page. None of the data will be saved to your project or Kumu's servers. * Elements and connections are read-only within Kumu—all edits to the underlying data must be made within the spreadsheet. You can’t make edits in [Table](/guides/table) either. * The above also implies that Google Sheets provides a *one-way* synchronization: Kumu pulls data from Google Sheets *into* the Kumu project, but can’t send updated information *back* from Kumu to Google Sheets. * Some Kumu features (such as [pinning elements in place](/frequently-asked-questions/how-do-keep-elements-from-moving) and [direct decorations](/guides/decorate/direct-decorations)) don’t work for maps connected to a Google Sheet. ## Crowdsourcing data through Google Sheets Since Google Sheets can be opened up to the general public for editing, this integration is a great way to crowdsource maps where individuals can add and update their own data, without having to give everyone full edit access to the project on Kumu. This video gives an explanation of how to crowdsource data with Google Sheets:
{% embed url="" %} ## Unlinking a Google Sheet If you wish to unlink a Google Sheet (for example, to switch to an Excel import), please click on the green + button at the bottom of your map and choose "Unlink Map". {% hint style="info" %} Unlinking your Google Sheet will disconnect your data source, which means your Kumu map will appear empty. Not to worry! Your decoration rules are still saved in both the Basic and Advanced editors. Once you import a new data sheet, your visualization will be restored just as before. {% endhint %} # JSON / Blueprints It’s easy to import existing data into Kumu without having to mess with spreadsheets. You can create our JSON imports—we call them **blueprints**—in any language from any dataset. JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax. Kumu can interpret JSON files and JSON remote links. A JSON file simply holds data structures and objects, while a JSON link is commonly used for transmitting data between web applications (e.g., sending some data from an external server to Kumu, so it can be displayed on your map). **Skip to section:** * [Import a JSON file](#import-a-json-file) * [Project backups](#project-backups) * [Set a remote JSON link](#set-a-remote-json-link) ## Create a JSON file To get started, use any text editor to organize your data into elements and connections: ```json { "elements": [ {"label": "A"}, {"label": "B"} ], "connections": [ {"from": "A", "to": "B"} ] } ``` If you've worked with the JSON format before, you'll notice that this Kumu blueprint is organized as an object with two key-value pairs. The `"elements"` and `"connections"` keys are each paired with an array, and the arrays contain your data, formatted as objects. Once you’ve got the basics in place you can add additional key-value pairs to the objects that represent your data—for example, "type", "description" and "tags", along with any custom keys you’d like as well: ```json { "elements": [ { "label": "A", "type": "Letter", "description": "This is A", "tags": ["one", "two"] }, { "label": "B", "type": "Letter", "Favorite Dessert": "shave ice" } ], "connections": [ { "from": "A", "to": "B", "type": "likes" } ] } ``` In your connection objects, you can assign a value to the `"direction"` key to control whether connections are undirected, directed, or mutual: ```json { ... "connections": [ { "from": "A", "to": "B", "direction": "mutual"} ] } ``` If you’re working with multiple elements with the same label, you can assign values to the `"id"` key to differentiate them. Just make sure to use the ids, not the labels, when building the connections: ```json { "elements": [ { "id": "e1", "label": "A" }, { "id": "e2", "label": "A" } ], "connections": [ { "id": "c1", "from": "e1", "to": "e2" } ] } ``` When you're finished creating your blueprint, save the file with a `.json` extension. ## Import a JSON file You can import the JSON file into Kumu in two different ways: **1)** Simply drag and drop the file onto the map's canvas. Make sure to save the import by clicking "Save changes" in the side panel on the left! OR **2)** Click the green **+** button at the bottom of your map, select "Import:, and click "Choose file" under Advanced > Import JSON file. Then click "Import JSON". Again, make sure to save the import by clicking "Save changes" in the side panel on the left. ## Project backups You can create a full backup of your Kumu project at any time, thanks to our JSON blueprint exports. All you need to do is open your project, click the download icon in the lower right corner, and select **Export JSON**. The file that downloads to your computer is a full backup of your project, including all data (elements, connections, loops, and data stored in their fields), element positions, views, maps, map overviews, field relevance settings, etc. The backup will also include anything that is in [your project's Trash](/overview/kumus-architecture#trash), so it can be a helpful tool when you need to restore large groups of deleted elements and connections. To restore this backup in a brand new project, go to your Kumu dashboard and click the New Project button. Name your project, set it to private or public, and advance to the next screen. Click the link at the bottom that says **restore backup**, then select the blueprint from your computer. Kumu will import the blueprint, fully restoring all data and project settings, including the project name. {% hint style="info" %} Not seeing the restore backup link on your screen? Make sure you're importing into a brand new project—it's not possible to import a blueprint into a project with existing maps, views, and other data. {% endhint %} ## Set a remote JSON link If you have a blueprint that is regularly receiving new data (for example, from a social network analysis survey), you can tell Kumu to automatically fetch the most up-to-date version each time the page is refreshed, just like a [Google Sheets import](/guides/import#integrating-with-google-sheets). If your blueprint is already hosted online, click on the green **+** button at the bottom of your map, choose "Import", and paste your JSON's public link into the "Link map to remote JSON" box. For this to work, you first need to host your blueprint publicly online, so that Kumu can find it. One option is to use GitHub: 1. Sign into GitHub (or create an account if you don't have one) 2. Create a new repository, and upload your JSON blueprint 3. Click on your file in GitHub, then click the `Raw` button 4. Copy the URL of the page that opens up, and use that URL in the function above {% hint style="danger" %} Note that remote blueprints do not support the full Kumu project export JSON format. You must structure a blueprint file that just includes elements, connections and loops rather than the full project definition. A remote blueprint acts as the data source for a single map rather than the definition of a full project. {% endhint %} # Imported views ### Imported views When you're working on projects that have several different [views](/guides/views), you'll often find yourself rebuilding certain settings in every single view. For example, you might want all views to have a base element size of 20, or you might want all views to have a [filter control](/guides/controls) across the top to filter by element type. But let's say you decide later on that you want the base element size to be 25, or you want to filter by tags instead of element type—if you had to update those settings across a big group of views, it would get tedious and complicated. **Imported views** solve that problem! Instead of rebuilding your base settings in every view, you can simply define them in one view, then instruct your other views to import those base settings. When you make any change to your first view, Kumu will automatically update all other views that are importing those base settings. ### Import views with the Advanced Editor You can use the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) to import views. Here's the basic syntax: ```scss @import "my-view"; ``` Replace `my-view` with the [slug](/guides/slugs) of your original view's name, and you'll be ready to go! # Layouts There are a number of layout options available in Kumu, from [fixed layouts](/guides/layouts/fixed) where you position things yourself, to [force-directed (floating) layouts](/guides/layouts/force-directed) where positions are based on relationships, to scatter plots where positions are driven by underlying field values. {% embed url="" %} This guide will cover the basics you need for whichever layout you choose. # Fixed With the fixed layout, you position everything manually. Just click and drag an element to change its location, or click and drag a connection to change its curvature. If you want to change the starting point of a connection (to make it start from another element), click on the starting point of the connection and drag it over to another element. The same steps can be used to change the ending point of a connection. If you're building a fixed map with [Sketch Mode](/getting-started/first-steps#sketch-mode), you can hold the `Alt` key on your keyboard, then click and drag elements and connections to move them. **Good to know:** The [system templates](/guides/templates#system-template) are set to a fixed layout by default. ## Changing from force-directed to fixed layout: 1. Click on the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map 2. Select **Customize defaults** 3. Scroll down to the **General settings** section to change the "Layout" to "off" 4. In the same section, change "Default element behavior" to "fixed" If you would rather do this in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), here is the code you can use to switch to a fixed layout: ```scss @settings { layout: static; } ``` If you were previously using a force-directed layout, you may need to pin all the existing elements in place. You can do this by pressing `A` on your keyboard to select all, and then by clicking the pin button in the lower right of the element profile or pressing `P` on your keyboard. # Force-directed With the force-directed layout, Kumu positions everything automatically based primarily on three forces: 1. A **gravity** force that pulls all items toward the true center of the map 2. A **particle charge** force that pushes elements away from each other, as if all elements were the same pole of a magnet 3. A **connection** force that pulls connected elements back together The force-directed layout also allows you to override any element's position by pinning it in place. After you pin an element, it will stay where you left it and won't be affected by any of the usual forces. {% hint style="info" %} The [stakeholder template](/guides/templates#stakeholder-template) and [SNA template](/guides/templates#sna-social-network-analysis-template) use the force-directed layout by default. {% endhint %} We've picked default strengths for each of these forces in order to create comfortable layouts for most maps, but if things are looking a little off, you can customize the layout forces in two different ways. ## Change the layout preset The easiest way to change how gravity, particle charge, and connections affect the layout is to change your **layout preset**. To do that, click the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) to open the Basic Editor, then click **MORE OPTIONS** and select **Customize view defaults**. Scroll down to the **Layout settings** section and use the "Preset" dropdown to switch between three default settings: * auto * dense * hairball ## Change the forces' underlying strengths If none of the layout presets look good for your map, you can use the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) to fine-tune the forces' underlying strengths. Here's some sample code to get you started: ```scss @settings { layout-gravity: 0.0001; layout-particle-charge: 300; connection-length: 500; connection-strength: 0.1; } ``` ## Changing from fixed to force-directed layout: 1. Click on the settings icon ![](/files/4Lc5bqaUm5VeFBw2pPDH) on the right side of the map 2. Select **Customize defaults** 3. Scroll down to the **General settings** section to change the "Layout" to "force-directed" 4. Then right-click your mouse on your map to open the quick-access menu. Choose Maps > Default Element Behavor > change it to "floating" 5. If you were previously using a fixed layout, you may need to un-pin all the existing elements. You can do this by pressing `Shift`+`E` on your keyboard to select all elements, then click the pin icon in the lower right of the element profile **or** press `Alt`+`P` on your keyboard. If you would rather do steps 1-4 in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), here is the code you can use to switch to a force-directed layout: ```scss @settings { layout: force; } ``` After you complete all five steps, you just need to move one element, and they will all start to float into the force-directed layout. # Remove overlap If you add a fair amount of data to a Kumu map that is using a [force-directed layout](/guides/layouts/force-directed), you'll soon find out that elements and their labels tend to overlap. As a result, your map can become less readable. But don't worry, there's a solution! Kumu has a built-in tool that will automatically re-position your elements and labels to make sure none of them overlap. To use this tool, open up the [quick actions menu](/overview/user-interfaces/quick-actions) and search for "overlap". You'll see two options: "Remove element overlap" and "Remove label overlap". Select one option or the other, based on the effect you want to see on your map. Kumu will move your elements to new positions, then tell you how to save the new positions. If you save the positions, your elements will be pinned in place and won't float anymore. If you'd rather discard the new positions, just press `spacebar` or `B` on your keyboard to bump the map back into a floating position. {% hint style="info" %} Keyboard shortcuts: press `o` to remove both element and label overlap, and press `Alt` + `o` to remove just the label overlap. {% endhint %} {% hint style="info" %} Maps that source their data from [Google Sheets](/guides/import#import-from-google-sheets) or a [remote JSON blueprint](/guides/import/blueprints#set-a-remote-blueprint) can't save positions for elements, so you won't be able to permanently remove overlap on those maps.\ \ However, you can still remove overlap before [taking a screenshot or creating a hi-res PDF](/overview/collaboration#create-a-screenshot). {% endhint %} # Scatter With the scatter layout, elements are positioned in an XY plot using element fields. You can choose any quantitative field for each axis -- or even use mathematical expressions if you're up for it! ![scatter plot with labels](/files/3Ufbeb4abCeUI7UrXDAG) Want to see a finished scatter plot before you get started? Check out our [scatter plots blog post](https://blog.kumu.io/introducing-scatter-plots-b5fb1e2040e3). ## Set up your scatter plot To apply the scatter layout to your map, the first step is to open the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor) add `layout: scatter` to your `@settings`. ```scss @settings { layout: scatter; } ``` Then, use `layout-x` and `layout-y` to tell Kumu which element fields contain the x and y coordinates. ```scss @settings { layout-x: "field1"; layout-y: "field2"; } ``` Replace `field1` and `field2` with the appropriate fields in your map, but don't forget to keep the quotation marks. After you set up your fields, you will probably need to multiply them by a constant value in order to improve the map's zoom-in and zoom-out interaction. ```scss @settings { layout-x-multiplier: 100; layout-y-multiplier: 100; } ``` We've found that `100` is a sensible default multiplier, but depending on your data, you may want to raise or lower it to make the zoom feel right. In general we've had success with layouts that are roughly 1000 x 1000, but there are no hard limits, if you want to get creative. ### Expressions The values for `layout-x` and `layout-y` can be simple field expressions such as `layout-x: "degree"`. But that's not all they can be. You can also use complex mathematical expressions to build your scatter plots. ```scss @settings { layout: scatter; layout-x: "1000 * betweenness"; layout-y: "500 * max(1, log(outdegree / indegree))"; } ``` **Note:** Since spaces aren't allowed in variable names, you need to use the camelcased version of the field name. For example, `"levelOfInfluence * 100"` instead of `"level of influence * 100"`. Notice there's no need to use the `-multiplier` settings if you're comfortable writing expressions instead. The rest of the scatter plot settings still apply. We're using the [mathjs](http://mathjs.org) library under the hood so if you want to learn more we recommend checking out the following links: * * ## Put it all together In this guide, we broke down the code into pieces for clarity, but in an actual Kumu view, you'll put it all into one `@settings` block. ```scss @settings { layout: scatter; layout-x: "field1"; layout-y: "field2"; layout-x-multiplier: 100; layout-y-multiplier: 100; } ``` ## Add grids, bounds, and guides You can have the scatter plot cover your entire Kumu map, or you can give it bounds, so that it knows where it begins and ends. Similarly, you can also add a guide to your scatter plot, in order for it to have a clearly defined Y and X axis. This is the code that allows you to do that: ``` @settings { layout-bounds-xmin: -1000; layout-bounds-ymin: 0; layout-bounds-xmax: 1000; layout-bounds-ymax: 1500; layout-guides: x(-1000) x(0) x(1000) y(500); } ``` Have a play with the numbers to adjust what your scatter plot looks like! ## Add X and Y-axis labels You might encounter some maps with scatter plots that have labels on the X and Y axes for easier interpretation. Note that these are not a function of the scatter layout, but rather 'hacky' workarounds explained here: **Hacky workaround number 1** This method is simply creating transparent elements, so that only the label remains, and placing them where you'd like them to be on the map: 1. Create two elements, one for each label 2. [Make the elements transparent](/frequently-asked-questions/how-do-i-make-elements-transparent) 3. Place the elements on the scatter plot (either through their X and Y coordinates, or by simply dragging & [pinning](/frequently-asked-questions/how-do-keep-elements-from-moving) them in place)
**Hacky workaround 2** This method involves creating two controls that are stylized. Note that with this method the scatter labels always exist at the edges of your Kumu map, so this method is not optimal when your scatter has bounds. Use this code to create the controls (just update the labels 'Betweenness' and 'Degree' with your own preferred labels): ``` @controls { top-left { search {} text { value: "

↑

Betweenness

↓

"; margin-top: 110px; } } bottom { text { value: "#### Degree"; margin-bottom: -42.5; } text { value: "

←               →

"; } } } ```
# Snap-to Snap-to makes it easy to arrange a group of elements as a circle or a line. This can be useful for creating rings of stakeholders based on whether they are core vs. periphery, positioning elements along a linear timeline, or just bringing more order to a complex map. It also brings additional grouping and sorting functionality to support analysis of complex data. There's two ways to use Snap-to: 1. [Set Snap-to manually](#set-snap-to-manually) 2. [Set Snap-to automatically](#set-snap-to-automatically) ![snap to line](/files/VMNwLx3HxX9W34SO6iIX) ## Set Snap-to manually **1. Pick a selection** To get started using snap-to, select one or more elements. You can do this by holding `shift` on your keyboard and dragging your mouse to draw a selection box over part of the map, or by clicking the search bar at the top of the map and then using the rocket icon ![](/files/hnLxVe0GJLgW3aMjsSeF) to build a [selector](/guides/selectors). **2. Arrange as a circle or line** After you've selected multiple elements, right click the map and choose "snap to" from the menu. Then, you can choose whether you want to arrange the elements as a circle ("snap to circle") or a line ("snap to line"). **3. Adjust the spacing and angle of elements** * **Spacing.** Once you've chosen whether you are using a circle or a line, scroll on your mouse or trackpad to adjust the spacing of elements on the circle (creating a larger or smaller circle) or the line (creating a longer or shorter line). * **Angle (snap to line only).** By default, lines will be drawn horizontally. If you'd like to change the line to be vertical or any angle in between, hold `shift` and then scroll on your mouse or trackpad. * **Snap to center.** After you've snapped your elements to a certain shape, right-click on the blank canvas again and choose "Snap to center" to bring the shape to the center of your Kumu map. This is especially useful when you're creating concentric circles. **4. Group and sort** You can tweak the ordering of elements in the circle or line by using the "group by" and "sort by" options. "Group by" allows you to group elements from matching categories together while "sort by" allows you to order elements from low to high based on numerical values. You can combine both to achieve sorted groups where the elements in each group are ordered from low to high. To group or sort, right click on the map again before hitting `enter` to save. You'll see an option for both "group by" and "sort by". It doesn't matter whether you choose to "group by" or "sort by" first. Simply pick one and then choose the relevant field from the menu. **5. Save your work** Once you're happy with how all the elements are positioned, hit `enter` to pin each element in place. If you'd like to start over, hit `esc`. If you've already saved the positions by hitting `enter`, you can always change the positions later by repeating these steps or unpinning the elements. If you don't like what it did to your map, simply hit the `escape` (esc) button on your keyboard, and your map will be back to normal. ## Summary Cheat sheet ### Snap to circle To snap to circle, follow these steps: 1. Select multiple elements by building a [selector](/guides/selectors) using the search or by holding down `shift` and dragging a box over the elements 2. Right click anywhere on the map and click "snap to" and then "snap to circle" 3. Adjust the size of the circle by scrolling on your mouse or trackpad (optional) 4. Group or sort the elements in the circle by right-clicking again on the map (optional) 5. Press `enter` to save or `esc` to exit without saving. ### Snap to line To snap to line, follow these steps: 1. Select multiple elements by building a [selector](/guides/selectors) using the search or by holding down `shift` and dragging a box over the elements 2. Right click anywhere on the map and click "snap to" and then "snap to line" 3. Adjust the spacing of the line by scrolling on your mouse or trackpad (optional) 4. Group or sort the elements in the circle by right-clicking again on the map (optional) 5. Press `enter` to save or `esc` to exit without saving. ## Set Snap-to automatically You can also have a map snap to a certain shape automatically. This option is great when you're [importing through a Google Sheet](/guides/import#google-sheets), which doesn't allow you to pin elements in place. {% hint style="danger" %} **Note:** You need at least 4 elements to snap to a circle. If your selection contains less than 4 elements, Kumu will not be able to render your data and hide your data. Fear not! Your data has not disappeared. Simply remove the automatic snap-to rule, save your changes and refresh your project. {% endhint %} \ \ **1. Pick a selection** Open the Basic Editor by clicking on Settings ![](/files/CRQ1FXnEuQ9G6zpnUNhO) on the right. Then choose "More" > "Snap To" > "Add a snap-to rule". This will automatically apply the snap to all the elements on your map. If you want to create a more specific selection, click on the little pencil icon to add a [selector](/guides/selectors). **2. Adjust the settings** Once you have the selection set, adjust the settings for the snap-to by using the `shape`, `x-coordinate`, `y-coordinate`, `size`, `angle` and `space`. Once you're done, click Save on the yellow bar at the bottom. {% hint style="warning" %} **Note:** the connections don't adjust their position until you have saved your snap-to rule. This might look a bit wonky as you're creating the rule, but it will adjust once you have saved the settings. if it hasn't, please refresh the page and the connections should be updated. {% endhint %} **3. Check the Advanced Editor** Once you've saved the settings, click "Switch to Advanced Editor" at the bottom. You'll now be able to locate a code looking something like this: `selector {` \ `position: circle(0, 0, 100, auto);` \ `}` You can use that code to make any adjustments to your shape, in case you want to do a quick edit. Of course you can also make edits in the Basic Editor still, in the Snap-to menu! # Legends Adding a legend to your map is an important step to make sure your readers can easily understand your decorations. There are a number of different ways to add and remove legend entries—this guide will explain all of them! Note that you can only create a legend through [data-driven decorations](/guides/decorate/data-driven-decorations). If you're using [direct decorations](/guides/decorate/direct-decorations) (the toolbar) to color, then you won't have a legend. **Skip to section:** * [Use the Color by tool to create a legend](#use-the-color-by-tool-to-create-a-legend) * [Use the decoration builder to add custom legend entries](#use-the-decoration-builders-to-add-legend-entries) * [Removing legend entries](#removing-legend-entries) * [Reordering legend entries](#reordering-legend-entries) * [Add legend entries through the Advanced Editor](#add-legend-entries-through-the-advanced-editor) * [Change the legend title](#change-the-legend-title) * [Hide the legend](#hide-the-legend) * [Legend code reference](#hide-the-legend) *** ## Add legend entries through the Basic Editor There are two ways to create your legend from the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor): 1. Using the **Color by,** or **Shape by** options 2. Using the [decoration builders](/guides/decorate#refine-your-decorations) (Decorate Elements & Decorate Connections) **Color by** is a great way to get a legend up and running quickly, while the decoration builders are useful when your legend needs to be a bit more customized. Read on to learn more about both options. #### Use the Color by tool to create a legend When you use the [Color by](/guides/decorate#color-by) tool in the Basic Editor, Kumu will automatically create your color legend, adding an item for each possible value in the field you're coloring by. For example, this map is colored by Element Type using the `bujumbra` scale: ![bujumbra color by](/files/EwMILvY1TzRhWb3vQa7w) This automatic legend feature also works when you're using **Color by** to add [flags](/guides/decorate/flags). Note that the **Color by** tool will stop adding legend entries after it runs out of colors in its default color palette (seven colors). To make sure all your field values get included in the legend, you might need to click the expand icon and choose a [larger color palette](/overview/advanced-editor-hub/color-reference). If the **Color by** tool is including some unwanted field values in your legend, try [deleting the unwanted values](/guides/fields#deleting-field-values). One more caveat about **Color by**: when you're using this tool, it's not possible to remove, replace, or edit individual colors from the color palette. To fully customize the colors in the palette, you can follow the guide to [define your own palette](/overview/advanced-editor-hub/color-reference#defining-your-own-color-palette). Alternatively, you can read through [the section below](#use-the-decoration-builders-to-add-legend-entries) to learn how to create a custom legend without using the **Color by** tool. **Only color by the values being used** In some projects, you might have a long list of field values, but only use *some* of them on a given map. If that is the case, your **Color by** legend will include *all* of the possible field values, not just the values being used on your map. Using Kumu's [computed fields](/guides/fields/computed-fields) feature, you can quickly solve this problem and create a legend with only the used values: 1. Open your [project settings](/overview/user-interfaces/settings#project-settings) and click "Fields" 2. Add a new field—this new field can have any name, but something like "Color coding field" might be clear and easy to remember. 3. Scroll down to the fields "Advanced settings" section. 4. In the **Expression** box, paste in `{{Field Name}}`, replacing `Field Name` with the name of the field you originally wanted to color by. For example, if you want to color by the element type field, paste in `{{element type}}`. 5. Click "Save" to save the field With that done, you can return to the map, and use the **Color by** tool to color by your new computed field. Regardless of how many possible values you have in the original field, the legend will now only include the values being used on the current map. For bonus points, use [field relevance settings](/guides/fields#field-relevance) to hide your computed field from all profiles. #### Use the decoration builders to add legend entries To add custom colors and icons to your legend, use the [element and connection decoration builders](/guides/decorate#refine-your-decorations). Once you build out your decoration rule, fill in the "Label for Legend" box at the bottom of the decoration builder, and Kumu will add your decoration to the legend. ![label for legend box](/files/z9BGUJ9siZlEANOMbLh9) You can use the decoration builders to add many different kinds of items to your legend—for example, icons to indicate that elements or connections are being scaled in size: ![Network map with cool legend entries](/files/nANDRMCr3nVpXfYHPDaK) For a full list of legend icons you can add, [jump to the legend reference](#legend-reference). The legend entries added from the decoration builder will be listed in the Basic Editor among other [existing decorations](/overview/user-interfaces/view-editors#existing-custom-decorations). If you hover over a custom decoration, you can click the pencil icon next to it to edit that entry, or you can click the trash can to delete that decoration.
#### Removing legend entries Legend entries added using the **Color by** tool can only be removed by [defining your own color palette](/overview/advanced-editor-hub/color-reference#defining-your-own-color-palette) or [deleting the field values](/guides/fields#deleting-field-values) that you don't want to see. To do this, you need to delete the underlying field value. This process is different depending on the field's [prompt](#customize-a-field). For fields that have their prompt set to "Autocomplete" or "None" (this includes the Tags field), you can only delete the field value by removing it from every element, connection, and loop in the project, including the [trash](/overview/kumus-architecture#trash). For all other fields (including Element Type, Connection Type, and Loop Type), follow these steps: 1. Click the menu in the upper left of your map and choose **FIELDS** 2. Click on the field you want to edit 3. Find the value you want to delete. Then, click the delete button next to the value to delete it. 4. Scroll down and click **SAVE** to save your changes 5. Refresh the page After you follow these steps, the field value(s) you deleted will no longer show up in prompted lists, in legends, or in controls. If you used the decoration builder to add a legend entry, you can go to the existing decorations section, click the pencil icon next to the decoration, and clear out the Label for Legend box. This will remove the legend item, but keep the decoration—if you'd rather delete both, you can click the delete icon in the existing decorations section. Some legend entries get added automatically when you apply different [templates](/guides/templates). Here's how to delete those entries: * For **Person** and **Organization** entries (stakeholder template), and **Stock**, **Flow**, **Variable**, **Source**, and **Sink** entries (stock and flow template), follow the guide to [delete field values](/guides/fields#deleting-field-values). Delete these values from the Element Type field. * For **Adds to / same direction** and **Subtracts from / opposite direction** entries (causal loop template), follow the guide to [delete field values](/guides/fields#deleting-field-values). Delete these values from the Connection Type field. * **Opposite** entry (system template): Open your [default settings](/guides/default-view-settings), and, in the **Template settings** section, clear out the "Opposite connection label" box and click **SAVE** at the bottom. #### Reordering legend entries There are two ways to re-order legend entries, depending on how they were added. If you added legend entries using the **Color by** tool, follow these steps to change the order: 1. Click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) to bring up the [project settings](/overview/user-interfaces/settings#project-settings) 2. Select **Fields** from the sidebar on the left 3. Select the same field you selected in the **Color by** tool—it's settings panel will open up 4. Drag and drop field values to change their order 5. Click **Save** at the bottom of the field settings to save your changes, then reload the page If you added legend entries using the decoration builder return to the Advanced Editor and locate the codes generated by Kumu for your custom decorations, cut and past the codes to re-arrange the legend entries the way you want them to appear on your map. ![re-arranging legend entries via advanced editor](/files/0W4ZWwTtDEb0kFd7RlJf) ## Add legend entries through the Advanced Editor If you're working on decorations in the [Advanced Editor](/overview/user-interfaces/view-editors#advanced-editor), you can add a comment above a decoration to tell Kumu that it should be included in the legend. The syntax is: ```scss /* entry-type: Entry Label */ ``` Replace `entry-type` with either `elements` or `connections` to tell Kumu what your decoration rule applies to. Replace `Entry Label` with the text that will appear in the legend. Your decoration rule should start on the next line down in the Advanced Editor. Here's a working example from a decoration in one of the screenshots above: ```scss /* elements: Authors, sized by number of articles written */ author { color: #918dc2; scale: scale("total articles", 0.5, 3); border-width: 1; border-color: #fcfcfa; } ``` Note that you can combine multiple decoration rules into one block of code, and Kumu's legend will combine many of your rules into one legend icon. The code above will create the following entry in the legend, complete with color, border color, and scale: ![fancy legend combo](/files/UrOc7ippaqcXuXLfo8dF) For a full list of legend icons and how to use them from the Advanced Editor, [jump to the legend reference](#legend-reference). ## Change the legend title If you'd like to change the title of your legend from "Legend" to something more descriptive, you can use the following code: ```scss @controls { bottom-left { legend { title: 'My custom legend title'; } } } ``` This is what it'll look like: ![custom legend title](/files/KIXBqMs1EZvh82ksOyxH) ## Hide the legend If you want to completely hide the legend, you can use the Advanced Editor to do so. Here's some sample code to get you started: ```scss @controls { bottom-left {} } ``` For more info on why and how this works, check out [our full guide on built-in controls](/guides/controls#built-in-controls). ## Legend reference Below is a list of all the icons you can add to your legend, as well as instructions on how to access the icons from the Basic and Advanced Editors.
Legend iconBasic EditorAdvanced Editor
element color iconDecorate elements >
Change color >
Set a fixed element color
element {
    color: #34b3eb;
}
element shadow color iconDecorate elements >
Add shadow >
color
element {
    shadow-color: #34b3eb;
}
element bullseye color iconDecorate elements >
Add bullseye >
color
element {
    bullseye-color: #34b3eb;
}
element border color icon
element {
    border-color: #34b3eb;
}
connection scale iconDecorate connections >
Change size >
Scale connection widths by field
connection {
    scale: scale("strength", 0.5, 3);
}
connection color iconDecorate connections >
Change color >
Set a fixed connection color
connection {
    color: #34b3eb;
}
connection dashed iconDecorate connections >
Change style >
dashed
connection {
    style: dashed;
}
# Licensing It's easy to get wrapped up in the creation of your projects, but if you're sharing them with others it's important to tell them what they can do with your content. We encourage each project to include a license to make that clear, and we've made it incredibly easy to add one: From your project, click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the top left of the screen to open your [Project Settings](/overview/user-interfaces/settings#project-settings). In the **Overview** section, you can add a license. ![Kokua License in a project](/files/Dc7EfkpN5zmHIo3GUHqb) The hard part is deciding which license to use! There are a number of existing licenses available: * [Creative Commons](http://creativecommons.org/) * [Open Data Commons](http://opendatacommons.org/) Kumu projects are unique in the sense that they include general content (map descriptions, presentations, etc), data (fields, metrics, etc), and code (views). Most existing open source licenses only cover a single type of content. Creative Commons licenses are the most comprehensive, but they also carry legal burdens we aren't comfortable with for most of our projects. After reviewing existing options, we ended up developing our own license we call [The Kokua License](https://medium.com/@rymohr/the-kokua-license-b2f430a03f4a#.razdhigjg). The license you use is up to you, but we hope many of you choose to share your projects generously with the community. Remember, by giving others access to your project on Kumu you [agree to let them fork](/guides/forking) the project. This does not grant any rights beyond creating the initial fork, so it's important to tell people what they can do with the content. ## The Kokua License ``` The Kokua License Copyright (c) Permission is hereby granted to freely exploit this content in any way by anyone for any purpose, without warranty of any kind. Attribution is appreciated, but not required. ``` *Kokua is a Hawaiian word, that translates into "extending help to others for their own benefit, without expectation for personal gain."* ## Legal burdens of Creative Commons licenses The [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/legalcode) license is one of the most permissive Creative Commons licenses. Even it requires derived works to include attribution in the form of: > the name of the creator and attribution parties, a copyright notice, a license notice, a disclaimer notice, and a link to the material. And if you make any changes you must: > indicate if you modified the material and retain an indication of previous modifications # Lightbox In Kumu, you can embed content from external providers into a **lightbox**. ![Lightbox showing a YouTube video in Kumu](/files/yKLWPo1XeaST7TMHyhyE) To show content in a lightbox, start by finding a link to the embeddable version of the external content. Once you have the link, just add add `?lightbox` to the end for the default lightbox, or add `?lightbox=full` for a nearly-fullscreen lightbox. Add the completed link into one of the following places in your map: * The Map Overview located in the [side panel](/overview/user-interfaces/map-editor#side-panel) * The text for any [presentation](/guides/presentations) slide * The Description field in any [profile](/guides/profiles) * Any custom field with its [field type](/guides/fields#customize-a-field) set to Text or URL {% hint style="info" %} Tip: Add the lightbox to a custom field named `URL` with its type set to URL, and the lightbox will open when your element, connection, or loop is double-clicked. {% endhint %} {% hint style="info" %} **Note:** If you're looking to put a Youtube video in a lightbox, make sure to use the full URL. More info [here](/guides/widgets#youtube). {% endhint %} # Loops In Kumu, the three basic items you can create are **elements**, **connections**, and **loops**. Visually speaking, elements are circles, connections are lines between the elements, and loops are groups of two or more connections. ![Elements, connections, and loops](/files/QRXjpkHEyjo6mX1KuR0Q) Loops show up on the map as a text label, and the default position of that label is in the middle of all the connections that are part of the group. You can use these visual tools in all kinds of different ways, but here are some common uses that we see: | Elements | Connections | Loops | | ----------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | | Factors in a system (causes and effects) | Cause-and-effect relationships | Causal loops | | Stocks | Flows | Sub-systems | | Decisions, chances, and ends in a decision tree | Paths along the decision tree | Multi-part decisions | | Steps in a process | Paths from one step to the next | Sub-processes | | People | Interpersonal relationships | Sub-networks or communities | | People & organizations | Connect people to the organizations they're affiliated with | Sub-networks or communities | | Authors & books/articles they've co-authored | Connect authors to their books/articles | Sub-networks or communities | | Stakeholders & areas of interest | Connect stakeholders to the areas they're interested in | Sub-networks or communities | | Funders, non-profits, and population groups | Connect funders to non-proftis, and connect non-profits to the populations they serve | Sub-networks or communities | | Companies and sectors/industries | Connect companies to their sectors/industries | Sub-networks or communities | ## Creating a loop To create a loop, you can click the green button at the bottom of your map and select "Add loop". Then, click on the connections you want to include in the loop, then add a descriptive loop label below and press `enter` on your keyboard. If you want to edit a loop, click on the loop's label to open its [profile](/guides/profiles) in the left side panel. In the bottom right corner of the profile, click the pencil icon to select and de-select connections that are a part of the loop. Click & drag the loop label to move it, or hold down `Option` on your keyboard (`Alt` on Windows) and click & drag to move the entire loop, including all its elements and connections, while maintaining their structure. ## Identifying loops in systems Colloquially, you can use the word “loop” to describe any kind of line that curves around in a circle or an oval. When you’re mapping systems in Kumu, you’ll find many groups of connections that meet that definition, but they aren’t necessarily the loops that a system mapper is looking for. In a system map, a great litmus test for discovering loops is to ask the question, “If I follow the arrows in this group of connections, can I get trapped?” If the answer is yes, you’ve found a loop! If not, the structure is not a loop, but might still be complex enough to deserve some further study. Here’s an example of a structure that looks like a loop, but is not, because no matter which arrow you follow, you always end up at the same factor, escaping the trap: ![not a loop](https://miro.medium.com/max/4992/1*noatmnqxsIbLdQx3FtM-BA.png) On the other hand, if you reverse just one of the arrows in the structure, you inevitably get trapped going around and around in a circle: ![this is a system loop](https://miro.medium.com/max/5020/1*KtuXkBbRz3KVUD9zPePAwQ.png) *This* is the kind of loop you’re looking for in a system map. It’s rarely so simple—in many cases, your loops will contain more than three connections, and they likely won’t be laid out in such a nice, circular shape. You'll also have the rest of the elements and connections in the map contending for your attention. This is where loop detection comes in handy! ## Loop detection **Automatic loop detection** We finally added the much-awaited feature that allows you to detect loops automatically! To detect loops, follow these steps: 1. Create your map with some elements and connections, as you would normally. 2. Click on the green plus icon at the bottom of your map, and choose "Add loop". 3. Click "detect loops automatically". 4. A menu will pop up on the left side of your map with the detected loops. {% embed url="" %} **Some things to know:** * Loops are ranked from shortest (least amount of elements) to longest (most elements). * You can hover over any loop name to showcase it on the map and see which elements/connections are a part of it. * Click on any loop number to give it a name and save it. Unnamed loops are not saved in your dataset! * Adding a name to a loop will add that label to your map in the center of the loop. * Loops can only be [exported with JSON](/guides/export). You can't export loops to Excel. {% hint style="info" %} Automatic loop detection is not (yet) available for maps imported with Google Sheets. If you'd like to use loop detection, please [import your map with Excel](/guides/import#import-from-excel-or-csv). {% endhint %} **NOTE:** Some maps are simply too large for Kumu to automatically detect loops, as the number of loops on a highly inter-connected system map can quickly run into the thousands. If you notice that loop detection is not giving you any results, you can try one of two things: * Try simplifying your map by [deleting](/frequently-asked-questions/how-do-i-delete-data-from-my-project) unnecessary elements and/or connections. * [Filter](/guides/filter) out one part of your map and run loop detection again. Make sure to save your loops before you filter another part of the map! ## Decorating loops Once you've identified your loops, you might want to customize how they look! One common thing to change is your loops' font size. This can be done in the Advanced Editor, like so: ```scss loop { font-size: 40; // Replace with any number } ``` This code will change the font size for all loops. If you just want to change the size for a specific loop, you can use a [selector](/guides/selectors). Here's an example that selects by label to decorate one loop: ```scss // replace My Specific Loop with the label of your loop loop[Label = "My Specific Loop"] { font-size: 40; } ``` Less common, but still useful, is to categorize loops with types like Vicious, Virtuous, Stagnating, and Stabilizing, then color-code by those loop types. If you add those types to the Loop Type field (under the Label in the profile), you can use this code to color code automatically: ```scss loop { font-color: categorize("Loop Type", olympic) } ``` You can replace `olympic` with the name of any of our [color palettes](/overview/advanced-editor-hub/color-reference). # Metrics Kumu has a powerful metrics engine which includes a number of popular social network analysis (SNA) metrics as well as community detection and other helpful calculations. ![metrics tool](/files/FjtQQc5TX37en1iMYbJR) ## How to run basic metrics 1. Click on the Metrics icon in the bottom right corner of the map 2. Select "Social Network Analysis" 3. Choose a metric from the dropdown list 4. Click the large button "Discover ..." (e.g. "Discover the connectors/hubs" for the "degree" metric) **Good to know:** * To rerun metrics (for example, if you added new elements and connections), just follow the same steps again. * Metrics will not be calculated for elements that are filtered out of the map. {% embed url="" %} ## SNA metrics You can run the following metrics in Kumu: | Metric | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Degree | Degree centrality is the simplest of the centrality metrics, counting the number of connections an element has. In general, elements with high degree are the local connectors / hubs, but aren't necessarily the best connected to the wider network. | | Closeness centrality | Closeness measures the distance each element is from all other elements. In general, elements with high closeness can spread information to the rest of the network most easily and usually have high visibility into what is happening across the network. | | Betweenness centrality | Betweenness centrality measures how many times an element lies on the shortest path between two other elements. In general, elements with high betweenness have more control over the flow of information and act as key bridges within the network. They can also be potential single points of failure. | | Size | Size measures the number of neighbors an elements has (plus the element itself). It's similar to degree, but counts the number of elements instead of connections. | | Indegree | Indegree measures the number of incoming connections for an element. In general, elements with high indegree are the leaders, looked to by others as a source of advice, expertise, or information. | | Outdegree | Outdegree measures the number of outgoing connections for an element. In general, elements with high outdegree can reach a high number of elements and spark the flow of information across a network (but may not be the most efficient at spreading the information). | | Eigenvector | Eigenvector centrality measures how well connected an element is to other well connected elements. In general, elements with high eigenvector centrality are the leaders of the network, though they may not have the strongest local influence. | | Reach (two-step out) | Reach measures the portion of the network within two steps of an element. In general, elements with high reach can spread information through the network through close friend-of-a-friend contacts. | | Reach efficiency | Reach efficiency normalizes reach by dividing it by size (number of neighbors). In general, elements with high reach efficiency are less connected but gain more exposure through each direct relationship. | | MICMAC | MICMAC is a system analysis that explores element exposure (how much a given element is affected by other elements) and influence (how much a given element affects other elements). When plotted on an XY axis, these scores help you identify potential leverage points within the overall system. | {% hint style="info" %} Looking for group metrics that describe your entire network? Check out the [SNA Dashboard control](/guides/controls/sna-dashboard-control). {% endhint %} ### Weighted metrics Certain fields also support weighting so you can include fields like strength and frequency in the calculations. Betweenness, closeness and degree use connection fields for weighting while size and reach use element fields for weighting. For the metrics that allow weighting, you'll see an Advanced Options link once you select the metric: ![Weighted metrics](/files/wWdVeuMoP0dkXtN5xCDt) You can choose any numerical field for the weighting, but make sure you have values saved for the elements or connections based on which is used for the weighting. If you don't see the field you want to use listed, make sure the type for that field is set to numeric. ### Saving multiple versions of a single metric By default, all metrics are saved to a field with the name of the metric (betweenness calculations are saved to the "betweenness" field). Each time you run the metric the previous values are overwritten. If you'd like to keep the previous values, rename the field (maybe it's "2014 betweeness" or "betweeness before") so that future saves don't overwrite the values. {% embed url="" %} {% hint style="warning" %} **Note:** If you're importing data through Google Sheets, the profile fields will not allow you to edit the field name by clicking on them (as demonstrated in the video above). In that case, please navigate to the Projects Settings in the top-left corner of your project (three stripes) > choose the Fields tab > click on the field of the metric for which you want to change the name and update the value in the Name textbox. Don't forget to click Save at the bottom of the page! You can then return to your Kumu project and run the SNA metrics again. {% endhint %} **Using metrics for a social network analysis?** Don't miss our [SNA / Network Mapping guide](/disciplines/sna-network-mapping). ### Other cool things you can do with metrics Once you have Metrics calculated, you can use those numbers to decorate your map. For example, you can [size your elements by the number of connections they have](/frequently-asked-questions/how-do-i-size-elements-by-number-of-connections) or you can use [data-driven decorations](/guides/decorate/data-driven-decorations) to decorate your elements based on Metrics. Here's how to highlight the outliers in your network by coloring all elements with a Betweenness metric *above* 0.6 blue: ``` element["betweenness">"0.6"] { color: blue; } ``` ## Community detection Kumu includes support for community detection based on the [SLPA algorithm](https://scholar.google.com/scholar?q=slpa+community+detection). With the SLPA algorithm, communities are identified based on communication flows and, unlike older algorithms (such as the Louvain method used by Gephi), the algorithm can detect overlapping communities (which is helpful since community membership is rarely black and white). ### Detecting communities Click the Metrics icon in the lower right corner of your map and choose "community detection". If you haven't run community detection before, clicking this will automatically detect communities. If you're already run community detection, clicking the icon will bring you to a window showing you the previous results. ![](/files/JdPlZ4LIfN3VrlFIM78C) {% hint style="info" %} Good to know: Connection direction *does* influence community detection. {% endhint %} ### Reviewing community breakdowns After running the algorithm, we present the results to you in a table that allows you to browse each of the communities, ordered by popularity (defined as the size of the community). Within each community, elements are listed in order of their strength of association to that community. Think of this value as the probability of that element belonging to the given community. Elements in grey are ones that had ties to the community but ultimately had stronger ties somewhere else. When analyzing the communities, you may notice that a common theme runs across all members of that community. Maybe they all went to the same graduate school, or worked at the same law firm (maybe they even went to the same high school). If you notice a theme like this, we provide an easy way to override the community name and replace it with a descriptive one. Don't forget to click save once you're done! {% hint style="info" %} Note: Some community detection algorithms treat communities as black and white—you're either in, or you're out. While this helps simplify the analysis, it throws away a lot of useful information about the overlapping community structures within the network.\ \ The SLPA algorithm preserves this data, and we believe the breakdown is even more valuable than simply knowing the primary community an element belongs to. {% endhint %} ### Color by communities First, make sure to save the community results. This will save the best match for each element to the "Community" field so you can use the community values to decorate your maps. ![Les Miserables](/files/RwtqQZEHHkQgyscCpqUe) To quickly color-code elements by community, you can use the [Color by](/guides/decorate#color-by) tool in the Basic Editor. ### Rerun from scratch (optional) When you rerun community detection, we'll use the existing communities to seed the algorithm by default. This keeps the communities more stable, but occasionally you may want to throw away the previous communities and start fresh. For instance, if you've made a number of changes to the map the previous communities will unfairly dominate the new network. Just click "throw away the current communities" and we'll dump the existing communities and rerun the algorithm from scratch. Remember, not all networks have meaningful community structure! Use the default settings and try to avoid fiddling too much just to get a pretty picture. Also remember that the science of community detection is still evolving. Use the results from the algorithm to ask better questions about your maps, but don't take them as fact. # Two-factor authentication Two-factor authentication (2FA) helps secure your account and prevent unauthorized access to your data. Once enabled, to sign into Kumu, you'll need to enter your password *and* an authentication code from an authenticator app like [Authy](https://authy.com/) or [Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2\&hl=en). We strongly recommend managing your authentication with [Authy](https://authy.com/) which supports backups across multiple devices. {% hint style="info" %} If you lose your device and do not have backups enabled for your 2FA information, we will not be able to restore access to your account. {% endhint %} To enable two-factor authentication on your account, go to the [2FA section of your settings page](https://kumu.io/settings#2fa) and follow the instructions. *Note: As of April 28, 2023 we no longer support SMS-based 2FA.* # Pro workspaces **Pro workspaces** are shared workspaces that allow multiple Kumu users to collaborate seamlessly, with fine-tuned permissions (view, edit, and admin) for each of the workspace's projects. This makes Pro workspaces a great fit for teams of people that have several active Kumu users. In addition to flexible user management, Pro workspaces also have access to these exclusive features: * [**Private project archiving**](/guides/pro-workspaces/archiving-projects)**.** Have private projects you want to continue to share through Kumu but don’t need to edit? Simply archive the project and you’ll no longer need to pay for it. * [**Project-wide activity feed**](/guides/activity-feed)**.** Collaborating with a large team to build out your map? Use the activity feed to keep tabs on who’s making each change across your project. * [**Real-time, embedded comments**](/guides/pro-workspaces/discussions)**.** You’ve done the work of building your map, let us do the heavy lifting to collect the feedback. Engage in Discussions and link them to specific elements, connections, and loops. Use comments to brainstorm ideas and make it easy for others to give feedback while you’re building out your map. * **Hourly backups, retained for six months.** Map freely, knowing you have backups of your project data in case you make a mistake. * **Customized branding.** Replace Kumu's logos with your own to align your projects with your brand. ## Pricing Pro workspaces are $10 per month for unlimited *public* projects. \ Private projects on the Pro workspace plan are $20 per private project per month. **Example**: if you have a Pro workspace with 2 private projects, then your monthly invoice would be $10 + (2 \* $20) = $50. For more information about billing, downgrading your subscription, and/or annual plans, visit our [Billing guide here](/overview/billing). Find an overview of all of Kumu's pricing plans [here](/frequently-asked-questions/what-pricing-plans-does-kumu-have). ## Create a Pro workspace **To upgrade your existing workspace to a Pro workspace:** Click on the Workspaces tab in your dashboard. Then click on the title of your workspace to open its settings. Under the Billing section click on the button "Upgrade to Pro workspace". **To create a new Pro workspace, next to your existing workspace:** Go to your [account dashboard](https://kumu.io/dashboard), then navigate to the **Workspaces** tab and click the green **New Workspace** button. Give your new workspace a name, and Kumu will send you through to the workspace's Settings page. Your workspace will be a Basic workspace by default. In the Billing section of your workspace's settings page, click the button to upgrade to a Pro workspace. After that, you're all set! {% hint style="info" %} Note: You need to create an account in order to create and own a Pro workspace. Even if you think a Pro workspace is the right option for you, be sure to [sign up for your Kumu account](https://kumu.io/join) first. {% endhint %} ## Add users to a Pro workspace After you create your Pro workspace, you can start inviting other Kumu users to join. Scroll down to the **Collaboration** header on the Pro Workspace Settings page to add or edit the users of a Pro Workspace. (If you're not already on your Pro Workspace page, click on the Workspaces tab in your Kumu Dashboard > and then on the title of the Pro Workspace to get there) Users can be invited to be owners or members: * **Owners** can add new members, and they have full access to everything within the Pro workspace. The creator of the Pro workspace is an Owner by default. Owners also have admin access to update billing and profile information. * **Members** can see a list of all projects owned by the Pro workspace, and they can create new projects, but they can only open projects they've been [given access to](#grant-direct-access-to-projects). ## Create a project Next, you'll want to create a project for your Pro workspace. This works just like it does for Basic workspaces—simply click the **New Project** button, fill out the required information, and you'll be ready to go. ## Grant direct access to projects Once you have a project, you can start granting access to other users. If you have the project open, you can go into the [project settings](/overview/user-interfaces/settings#project-settings) menu and click **Members** to search for and add other users to the project. ![project add users](https://github.com/kumu/docs/blob/main/images/pro-workspace-project-users.png) These users can be existing members of your Pro workspace, but you can also add any personal Kumu account. This is useful when, for example, you're creating a project for a client, and you want them to view that project, but you don't want to add them to your Kumu Pro workspace. You can grant users one of three project access roles: * **Observers** can only view the project—they can't make any changes * **Contributors** can view and edit the project * **Managers** can view and edit the project, and they can also rename or delete the project and add or remove other users Of course, if you have a lot of projects or a lot of users, it would be tedious to add the same users with the same permissions to every single project! To solve that problem, you can use team-based access. #### Team-based access Teams are very useful when you want to assign project permissions quickly, without opening up each project. You can add your Pro workspace's owners and members to teams, then grant a specific project permission to the team itself—each user inside the team will instantly be given that same permission for the project. If you have a lot of projects and/or a lot of Kumu users in your Pro workspace, this will be much faster than assigning project permissions to every single individual, for every single project! To create a team, go to your Pro workspace dashboard and click the **New Team** button. Then, use the modal that pops up to add users to the team. You can also decide whether you want those users to be "members" or "maintainers". Maintainers can add and remove users to and from the team:
When your team is all set up, click on one of your Pro workspace's projects to bring up the project access modal. Choose whether the team has no access, view-only access, edit access, or admin access (includes the ability to add users to the project, rename the project, and delete the project):
Now that you've mastered the basics of adding users, check out the next sections to learn how to use other features exclusive to Pro workspaces. ## Branding When you sign up for a Pro workspace, you can tweak Kumu's branding to be more aligned with your brand. Currently, you can: * Upload a logo to use on the project loading screen * Upload a logo to use as a watermark on [embedded maps](/guides/share-and-embed) To manage your branding settings, go to your [Pro workspace's dashboard](/overview/user-interfaces/dashboard#pro-workspace-dashboard) and scroll down to the **Branding** section. # Archiving projects Archiving projects (an exclusive feature for [Pro workspaces](/guides/pro-workspaces)) is a great way to keep your finished work private *without* having to increase your bill. An archived private project will stay private, and you can view the project, its [presentations](/guides/presentations), and its [shared/embedded versions](/guides/share-and-embed) at any time. Archived projects don't count toward your total private projects—for monthly plans, this means that your next charge will be pro-rated based on when you archived the project and removed it from your bill. For annual plans, archived projects won't count toward your private project limit, however, to make sure that change is pro-rated on your next bill, you'll need to decrease your private project limit on your Pro workspace's settings page. Note, however, that you won't be able to edit the archived project, create new presentations or shared/embedded versions of it, or leave comments, unless you **unarchive** the project first. To unarchive a project, send an email to with a link to the project, and our team will take the next steps. A $20 unarchiving fee will be billed to the account owner when we unarchive the project, and unarchiving may take a few days. To archive one of your projects: open the project, then click the menu icon ![](/files/cyfoqu9S7QZXJBIOfxCA) in the upper left corner to open the [project settings](/overview/user-interfaces/settings#project-settings). Select **Admin**, and click **Archive project**. ![Admin settings](/files/DH1r6VcxC4QNNmnYCcVP) {% hint style="info" %} Project archiving is an exclusive feature for [Pro workspaces](/guides/pro-workspaces). {% endhint %} # Discussions With Discussions (an exclusive feature for [Pro workspaces](/guides/pro-workspaces)) you can chat with your team and attach comments to items in your map—all within Kumu, all in real time! To access, click the Discussions tab in the left-hand side panel, or click the Discussions icon in the bottom-right corner of your project.
To create a discussion topic, click the **New discussion** button, and to join an existing discussion, simply select it from the list. When you're commenting on a discussion topic, you can use [Markdown](/guides/profiles/markdown) to add basic formatting, as well as links, images, and even videos. To tag team members, you can use `@username`. You can reference elements and labelled connections & loops on the map with `[[label]]`. Or, just type `[[`, and the comment box will prompt you with a list of available labels. You can also attach a discussion topic directly to an element, connection, or loop on the map. To do that, select your item(s), and click the comment icon in the left-hand [side panel](/overview/user-interfaces/map-editor#side-panel). An asterisk will appear next to that element. If you click on the asterisk it should open that element's specific discussion, even if you have another discussion open. f you click on an asterisk for an element that has been tagged in multiple discussions, it will take you to a page showing all of those discussions. To close the Discussions tab, navigate back to the Overview tab, or click on any blank space in your map to collapse the side panel entirely. ## Email notifications When a new discussion top is created, every Kumu user that is a member of the project will be notified by email, in addition to all the owners of the Pro Workspace that the project lives in. From the email, they can open the discussion thread in Kumu and respond, or they can simply reply to the email to add their new comment. You can also subscribe to a certain discussion thread if you want to stay updated on any new comments. To do so, you can open a discussion topic and click on the notification icon "follow this discussion" in the top-right corner. ## Open, close, and search discussions Once you've been working in a project for a while, your list of discussions might get a bit lengthy. To clean up the list, and to let your team members know which conversations are finished, you can close out old discussions. From the list of open discussions, click on an discussion topic you'd like to close, then use the button in the upper right corner to close it. You can use this same button if you need to re-open the discussion in the future. Closed discussions will be removed from the open discussion list, but stored in their own list, in case you need to reference them later. When you open up the discussion tab, you can use the buttons at the top to toggle between open and closed discussions. If you're ever having trouble finding a conversation, just use the search bar at the top of the discussion tab—it searches not only titles but also contents of all your discussions. {% hint style="info" %} Discussion are an exclusive feature for [Pro workspaces](/guides/pro-workspaces). {% endhint %} # Partial views [Views](/guides/views) offer a lot of powerful features—[decorations](/guides/decorate) for sizing and coloring your data, [filters](/guides/filter) for showing/hiding different items, [controls](/guides/controls) for adding rich interactivity to your maps, and much more. Different views [can also be layered on top of one another via the `@import` syntax](/guides/imported-views). For most maps, you'll probably curate one view that highlights your data in the best way possible, but more complex data demands a more complex visual. Different color-coding and sizing rules, levels of focus, cluster connections...in short, to get the most value out of a more complex dataset, you'll need to create several different visual variations. That's where partial views come in handy! {% embed url="" %} A **partial view** is almost exactly like a normal view—in the Advanced Editor, it's a block of code defining all the rules that affect the visual appearance of your map. But there's one major difference: you can use the [view toggle control](#add-the-view-toggle-control) to allow your readers to switch between your partial views at will, with just the click of a button: ![](/files/0qSlJpPecEv0zHjJihi8) {% hint style="success" %} Looking for some examples of partial views? Check out our [Projects in the Wild](https://embed.kumu.io/1e76eed07febdc8b962f86c9d0d3af6b) and set the Kumu Features dropdown to "partial views". {% endhint %} ## Recommended workflow for partial views If you want to build partial views, some Advanced Editor work will be required, but you definitely don't need to code everything by hand if you don't want to. For an alternative, potentially easier workflow, create a new view in your project and use the [Basic Editor](/overview/user-interfaces/view-editors#basic-editor) to build out your desired view there, isolated from everything else. When you're satisfied with your view, open the Advanced Editor and copy all of its code to your clipboard. Return to the original view, and follow the rest of this guide to make sure your copied code ends up in the correct place. You can also watch the quick tip above to see a real-world example of how this works. ## Define partial views in the Advanced Editor Use an `@view` block to define a partial view: ```scss @view "name" { // any view code can go in here, including @settings, @controls, @imports, and anything you have copied from other views in your project } ``` Replace `name` with the name of your partial view (keep the double quotes). This `name` should be unique to the partial view—you'll use it in [`@import`](/guides/imported-views) rules and in the view toggle control to refer to your partial view. Here's how you use a partial view's `name` to `@import` it into other partial views: ```scss // Here's where the base settings are defined @view "base-settings" { element { size: 40; } } // Partial One imports the base and adds its own settings @view "partial-one" { @import "base-settings"; element { color: green; } } // Partial Two also imports the base, but adds different settings than Partial One @view "partial-two" { @import "base-settings"; element { color: blue; } } ``` If you just need to define some base settings that will apply to all your partial views, you can also simply do that at the top of the Advanced Editor, outside of any `@view` block, like so: ```scss // Here's where the base settings are defined element { size: 40; } // Partial One adds its own settings @view "partial-one" { element { color: green; } } // Partial Two adds different settings than Partial One @view "partial-two" { element { color: blue; } } ``` ## Add the view toggle control To allow readers to switch between your partial views, you can add a view toggle control. Here's the syntax for adding the view toggle control in the Advanced Editor: ```scss @controls { top { view-toggle {} } } ``` You can use the `options` property inside the control to list exactly which partial views should be included as options: ```scss @controls { top { view-toggle { options: "one-partial", "another-partial", "a-third-partial"; } } } ``` You can also use the `option {}` syntax if you'd like to customize the list of options *and* how they're labelled on the map: ```scss @controls { top { view-toggle { option { value: "one-partial"; label: "Toggle first view"; } option { value: "another-partial"; label: "Toggle second view"; } option { value: "a-third-partial"; label: "Toggle third view"; } } } } ``` [Check out our controls reference](/overview/advanced-editor-hub/controls-reference) to see the full list of properties and values recognized by the view toggle control. ## The partial view cascade Kumu's advanced editor applies decorations in a cascading order. This means that your most recently created decorations *can* override your older decorations. Read more about this basic rule [here](/guides/decorate/data-driven-decorations#the-decorations-cascade). When using partial views, you might sometimes notice that your partial view isn't overriding the decorations of your default view. Read on below to learn how that works, and how you can work around it. **Basic rule:** A separate element block of code will always override an @settings block, even when dealing with partial views. **Rule for partial views:** This means that the simplified loading order with a "default view" and an "active partial" view becomes like this (first to last, meaning last decoration "wins" and is applied to your map): 1. @settings for current view 2. @settings for active partial view 3. other advanced editor code for current view 4. other advanced editor code for active partial view **Example:** In the following code, you can see that the default view is using an element block to color the elements "orange", while the partial view is set up to color the elements either red, green, or blue based on the value in their Tags field. ```scss @view "My Partial View" { @settings{ element-color: categorize("Tags", red, green, blue); } } @controls { top { view-toggle { as: labels; } } } @settings { template: stakeholder; } element { color: orange; } ``` As a result, activating the partial view will *not* change the color of your elements, in accordance with the cascading rule. To work around that, use the following code: ```scss @view "My Partial View" { @settings{ element-color: categorize("Tags", red, green, blue); } } @controls { top { view-toggle { as: labels; } } } @settings { template: stakeholder; element-color: orange; } ``` Moving the element color within an @settings block allows your partial view to override the default view. If you're encountering any issues with this, don't hesitate to reach out to . # Presentations Presentations combine the best of PowerPoint, Prezi, and Kumu into one easy-to-use tool. Combine text, video, images and maps into a single, engaging presentation that anyone can access via URL. {% hint style="success" %} Want to see some examples? Visit our [Projects in the Wild](https://embed.kumu.io/1e76eed07febdc8b962f86c9d0d3af6b#projects-in-the-wild) map and use the toggle in the bottom-right corner to only show Presentations. {% endhint %} ## Create a presentation To create a presentation, navigate to Project Settings in the top-left corner of your project and choose the Presentations tab. When you create a new presentation, you'll land on a title slide, to which you can add a title, subtitle, and background image. ![presentations interface](/files/Fn26izuPNnfUfWM3Cpyn) Use the plus button in the upper left corner to add a slide. After the title slide, your added slides can be one of several types: * Title * Map * Text * Image * Embed ### Title slides Title slides are useful when you want to signal the start of a new section in your presentation. They let you add a nice splash image with some overlayed text: ![title slide](/files/S9mGOm1X8hDICFCRUbBy) ### Map slides A map slide is any combination of a map and a view. You can choose to have the slide zoom fit by checking the corresponding box, or you can create just the zoom you'd like but zooming in or out. On a map slide, you can use the dropdown menus above the slide to choose which map and view will be applied. You can pick any map or view in your project. ![change presentation view](/files/jm6Y4cvaNGNW0TaSUimx) You can also activate focus or filter for a given map slide, and Kumu will remember those settings. This is a great way to unfold a map step-by-step for your readers. ### Text slides Text slides can include both a title and content. The content section supports markdown so you can also include images and other basic formatting (widgets aren't supported though). ![text slide](/files/PKpcyy40nxgBC5q0rc44) ### Image slides As you might expect, image slides allow you to upload an image to be displayed full screen on a slide. They're particularly useful for bringing in images of graphs or charts created outside of Kumu. You can also choose to include a title. ![image slide](/files/nKStXu3bLxRESIGaZhOR) ### Embed slides Embed slides are for interactive web content and support embeds from over [300 different providers](http://embed.ly/providers). Just add the URL of the content you'd like to embed. ## Publish a presentation Once you're finished creating your presentation, click Save and Exit the presentation builder. Click "Publish" to publish the presentation and choose whether you'd like to make the presentation public or if you'd like to make it even more secure by adding a password. After you publish, Kumu will give you a link that you and your audience can use to view your presentation. {% hint style="info" %} **Note:** If you've already published your presentation but make updates to your Kumu map afterward, be sure to click 'Publish' again, and then select 'Update presentation' to reflect the changes. {% endhint %} Want to skip your title slide when you view the presentation? Just add `/embed` to the end of the presentation's link (only supported for public presentations, not private ones). {% hint style="warning" %} Changing the [privacy of your project](https://docs.kumu.io/guides/pages/TeJrEKNvMD9ZnqbP2SNT#public-vs.-private-projects) does not automatically change the privacy of your presentation. To change the presentation's privacy, first "Unpublish the presentation" and then "Publish" again with the right settings. Changing the privacy settings of a presentation will generate a new URL. If you've already shared the original link, be sure to provide your audience with the updated URL to ensure continued access. {% endhint %} ## Embed a presentation Presentations can also be embedded just like any other Kumu embed: as an `iframe` on a web page. To get your `iframe` embed code, just publish your presentation, and Kumu will generate the code for you automatically: ![presentation embed code](/files/05eTmoGQkzkbWo96632J) Copy/paste the code onto your website, and you're visitors will see a fully interactive Kumu presentation! ## Autoplay a presentation If you want your presentation to automatically advance to the next slide, add an `autoplay` parameter to the URL. This parameter specifies the number of seconds to wait before advancing to the next slide. For example, if your presentation URL is `https://you.kumu.io/presentation` and you want it to automatically advance each 10 seconds, then you would use `https://you.kumu.io/presentation?autoplay=10`. If your presentation is private and has a URL like `https://you.kumu.io/presentation?token=123` and you want it to advance each 10 seconds, then use `https://you.kumu.io?token=123&autoplay=10.` ## Deleting a presentation To delete your presentation, navigate to the Presentations menu again (Project Settings in the top-left corner of your project) and click the Delete button next to the presentation you wish to delete:
{% hint style="danger" %} **Note:** Deleting a Kumu project does *not* automatically delete the presentation connected to it. If you want to make sure that your Kumu presentation is no longer accessible after you delete the project, please delete the presentation first and *then* delete the project. Do you have a presentation you wish to delete that no longer belongs to a project? Please send the URL to your presentation, together with your request to delete, to . {% endhint %} # Profiles Every element, connection and loop has a **profile** that you can use to add narrative and any data that is important for you to track. {% embed url="" %} By using [views](/guides/views) you can bring any of the information in the profile to life through [decorations](/guides/decorate), [filters](/guides/filter), [geo maps](/guides/templates/geo), and more. We'll look at each of the parts of the profile one by one:
## Default fields Every profile shows a set of default fields at the top. Those fields are: * Label * Type * Description * Tags * Image To learn more about each of those fields and their purposes, check ouot [our full guide on fields](/guides/fields). ## Custom fields The default fields are enough to get you started on most projects, but if you have other pieces of information like sector, net worth, or anything else, you can use the bottom section of the profile to create custom fields and fill them in with values. Custom fields can also be grouped together using their "Category" setting. Assigning a category to a a field will make sure it is listed in that category in the profile. The most common example of this is [metrics](/guides/metrics) fields, which are assigned to the "Metrics" category by default: ![Screenshot of field category in the profile](/files/gUQrK2il0F2Ce2R6DJAU) ## Disabling the profile You can choose to disable the profile entirely or only for specific elements and connections. To disable the profile for all elements and connections, use the `profile` property within `@settings`: ```scss @settings { profile: false; } ``` To enable the profile only for elements and connections that have a description field, you could use the following: ```scss @settings { profile: false; } [description] { profile: true; } ``` You can swap out `[description]` for any selector. Values for the `profile` property can be either `true` or `false`. # Markdown ## Markdown Markdown is an easy and powerful way to format your descriptions and long text fields using simple, natural syntax. ### The basics ```md *italic* and **bold** ``` -> Creates *italic* and **bold** ```md An inline link: [Kumu](http://launch.kumupowered.com) ``` -> Creates an inline link: [Kumu](http://kumu.io) {% hint style="info" %} Note that inline links always open the website in the same tab and direct your viewer away from your Kumu map. If you wish to open the link in a separate tab, you can use the following HTML syntax: `Kumu website` Replace the URL with your own and swap the word "Kumu website" for any word(s) you'd like your viewers to click. Make sure that target= stays the same. {% endhint %} ```md An auto-generated link: http://kumu.io ``` -> Creates an auto-generated link: ### Lists ```md * Milk * Cookies * Marshmallows ``` Looks like: * Milk * Cookies * Marshmallows ```md 1. California 2. Texas 3. New York ``` Looks like: 1. California 2. Texas 3. New York ### Links within your account We also support linking to elements, connections and loops (even other maps in your account). You can use the following syntax: **Selectors** ```md [link text](= selector) ``` Replace `link text` with the text for your link, and replace `selector` with any valid [selector](/guides/selectors). **Maps** ```md [link text](#map-slug) ``` Replace `link text` with the text for your link, and replace `map-slug` with the [slug](/guides/slugs) of your map. **Views** ```md [link text](#map-slug/view-slug) ``` Replace `link text` with the text for your link, replace `map-slug` with the [slug](/guides/slugs) of your map, and replace `view-slug` .with the [slug](/guides/slugs) of your view. ### Images ```md ![alt text](image-url) ``` Replace `alt text` with an image caption that screen readers can read, and replace `image-url` with a link to your image. #### Widgets See our guide to [widgets](/guides/widgets) to learn more about embedding videos, podcasts, slideshows, and other interactive content inside markdown. ### Headings ```md # Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6 ``` Looks like: ## Heading 1 ### Heading 2 #### Heading 3 **Heading 4** **Heading 5** **Heading 6** {% hint style="info" %} Learn how to create anchors that skip to certain sections of your map description [with this guide](/frequently-asked-questions/how-do-i-add-anchors-to-my-map-description). {% endhint %} ### Code Simply indent lines with four spaces or wrap the code with three backticks: ```` ```md
© 2013 Kumu Systems LLC
``` ```` Looks like: ```md
© 2013 Kumu Systems LLC
``` ### Blockquotes ``` > Add quote text here ``` Looks like: > Add quote text here ### Tables ```md One | Two | Three --- | --- | --- Blue | White | Gray Green | Yellow | Red ``` If you are using Markdown in the Description column of an [import](/guides/import), you will have to use the [HTML table tag](https://www.w3schools.com/tags/tag_table.asp) rather than the usual Markdown syntax. Make sure to remove all line breaks from your HTML, or your table will render with a large white space above it. ```md | One | Two | Three | | ----- | ------ | ----- | | Blue | White | Gray | | Green | Yellow | Red | ``` | One | Two | Three | | ----- | ------ | ----- | | Blue | White | Gray | | Green | Yellow | Red | ### Horizontal Rules ``` Three or more dashes or asterisks --- *** ``` \ Now you know the basics of formatting with markdown! For more information, visit [Daring Fireball's markdown syntax documentation](http://daringfireball.net/projects/markdown/syntax#precode). ### Inline HTML Kumu's markdown editor also recognizes a limited amount of inline HTML. {% hint style="info" %} More HTML fun: * Learn how to create anchors that skip to certain sections of your map description [with this guide](/frequently-asked-questions/how-do-i-add-anchors-to-my-map-description). * Learn how to add text dropdowns that show/hide additional text upon click [with this guide](/frequently-asked-questions/how-do-i-add-text-dropdowns-to-my-map-overview). {% endhint %} Here are the tags you can use in Kumu, anywhere that accepts markdown: ```md