How to use Wagn



Creating and editing cards

Note: on most Wagns, you'll need to have an accounts and be signed in to create cards.  Wagneers can change this by editing the *create permission.


There are a several ways to add new cards in Wagn:

  1. via the navbox. Most wagns include a navbox at the top of every page. Click in it and type the name of the card you want to create. Wait a moment, and a menu will drop down.  When the card's name is unknown and you have permission to create it, an option to "Add" that card will appear.
  2. via links.
    • make a link to a card that doesn't exist yet by editing some other card.  In most Wagns the link's color will indicate whether the card already exists (in, links to unknown cards are red).  Clicking on such a link — for example, one that says name of unknown card — will get you the same offer to create a card as above.
    • A link to /new/Image will prompt you to create a new Image card.
    • /card/new will prompt you to create a card.  You'll see fields to add the name and choose the type.
  3. via inclusions.  Whenever you include another card that doesn't exist, you're prompted to add it.
  4. via the url bar.  Many old school folks like to type their card names directly into the browser.  Feel free!

At the top right of every cards you'll typically see a card menus.  To edit a card, click on "edit" in the menu, or double-click anywhere in the content of the card.


This is one of the best acronyms in all of geekdom: "What You See Is What You Get". Most cards have a "wysiwyg" editor, which basically looks something like this (learn about using the wysiwyg editor):

editing bar

Some types, like Image, File, Pointer and Date, have different editors. If you edit an image or file, for example, you'll see a "Browse" button that lets you select a file on your computer.

Saving/cancelling and deleting cards

Underneath the editing area, you'll see "Save" and "Cancel" buttons. Click "Save" to save your edits, or "Cancel" if you want to leave the card as it was. If you have permissions, you'll also see a button for deleting the card.

Linking and Inclusion

See links and nesting to learn how to insert them when you are editing cards.

Tickets relevant to editing cards


Relating cards to each other


Cards can relate to each other in several different ways. In the text of any card you can easily make links to other cards (as with any wiki). You can also plus one card to another — to add an attribute, create a section, etc. (this is part of how Wagn is like a Database). You can even include the entire content of one card in another, and create formatting that applies to different cardtypes.

How to create and edit links of various kinds as you are editing cards in Wagn:


Regular web & e-mail addresses


Web addresses such as will automatically be made into links, with or without the http:// at the front - so also works. E-mail addresses also become automatically clickable, such as .


Links within Wagn


To link to another card, type its name in double square brackets, so when you type [[Community]] and save it becomes community. Feel free to link to cards that don't exist yet! Such a link will show up red rather than green, and anyone who clicks on it will be invited to add the new card.


Naming Wagn links and regular web/e-mail links

Sometimes you want the name of the link to be different from the actual name of the card. For example, a card may have a full name like International Business Machines, but in the sentence you're writing you want to use an acronym, IBM. To do this, use double square brackets around the name of the card, and the text that you would like to appear, separated by a vertical bar (|). So if you enter & save: [[International Business Machines|IBM]] it will look like: IBM.

This also works for regular web & e-mail addresses:


[[|Grass Commons]] will look like: Grass Commons


[[|email us]] it will look like:


Link to card tabs, custom layouts and views, etc.


You can link directly to card tabs (changes, options, related, edit), apply custom layouts and views on the fly, and more by using special URLs. They will render as external links, but you can make them render as internal links by dropping the initial part, e.g. /card/edit/Documentation rather than, and you can even name it with something like edit the Sandbox — which renders as edit the Sandbox.


To learn about all of these special URLs, see web address for everything.





Development Tickets (by status)




Documentation Tickets


Support Tickets


a way to link to files or images in named links

cards can include other cards inside them.  nesting helps you:

  • edit chunks of content in place - faster and easier than editing whole pages.
  • keep data current - a card's updates (e.g., an address or event info) appear everywhere it's included.
  • display the same information in different ways using views.  Eg, closed view let you use space more efficiently.
  • specify content patterns with inclusion-based formats.

The following (relevant) video is in a card named +howto video and is included here with the following syntax:

{{_l+howto video}}





Including cards is achieved through a simple syntax, which consists of the name of the card inside double braces, with a couple of optional modifiers. 

{{ cardname | key1:value; key2:value }}

 The complete Nest Syntax is documented here:

{{ cardname | view }}

{{ cardname | key: value }}

{{ cardname | key1: value1 ; key2 value2 }}

{{ cardname | key1: value1 ; key2 value2 | itemkey1:itemvalue1; itemkey2:itemvalue2}}


Keys and Values




"view" key is optional; if no key is given, value will be treated as view

Learn more about views



replaces card name in view


applicable view names

e.g. title_link on any view that shows a title. use commas for multiple views 


applicable view names

e.g. paging on searches or menu wherever it's shown by default. use commas for multiple views


any card name

overrides content and structure rule.


any valid view name

may be deprecated?; set via multiple-pipe syntax above Eg: {{some card | key1: value1 | view: open}}


Image cards only


any valid Cardtype name

may be deprecated?; set type via rules with *default setting 


any valid CSS value

may be deprecated?; will be treated as CSS





To demonstrate, here's a simple sample card:

Well, hello.  I'm the content of simple sample card.


We included the card above using this syntax: {{simple sample | view:open }}.  The "view:open" part means we want to see the whole card, with its green header and everything.  There are many other views: closed, content, titled, link, name, change, core, etc


The default view is "content", which means you only see the content of the card -- no header or footer.  So if you don't specify a view, and just type {{simple sample}}, you'll just get the card's content:


Well, hello.  I'm the content of simple sample card.


You would get the very same thing with {{simple sample | view:content}}, which is just a bit more explicit.  Actually, because "view" is such a common key, you can just leave it out, like so: {{simple sample | closed}}, which gives us this:


Well, hello.  I'm the content of simple sample card.


set item views

When you include Search and Pointer cards, you can also specify the views of each card in the returned list by adding another pipe. For example, {{sample user search | open | link}} will yield:

That syntax basically means "show me the search card in open view and each of its items in link view".


escape inclusions


If you want to use double curly brackets without creating an inclusion (for example in documentation), put a backslash just before the brackets. For example, \{{nymph}} appears as:



  • Nest Syntax describes more, such as showing & hiding individual elements such as a card's menu, or customizing its title.
  • You can edit included cards by double-clicking anywhere in them, or by clicking "edit" in the menus in the card's header.
  • Inclusions are not inline, but you can make them inline by using "display:inline" (and if the enclosing card is Basic, editing it's HTML so that instead of having a p tag around the inclusion it has a div tag), so for example "Ethan McCutchen's favorite fruit is {{Ethan McCutchen+favorite fruit|display:inline}}." will render as:

    Ethan McCutchen's favorite fruit is .
  • When you're including a card that doesn't exist yet, you can specify what type it should be with something like {{Phoebe Owens+favorite fruit|type:Phrase}}. Try clicking on this and you'll see it in action:

  • You can put comments in Wagn cards by making an inclusion and beginning with a hash symbol (#). Use two to make a comment that's completely invisible to web browsers:

    {{## completely invisible comment}}

    And one to have it show up as an HTML comment (i.e. <!-- # only visible in HTML -->):

    {{# only visible in HTML}}




Compound names are simply cards names with a "+" in them.

Some important principles:

  • If a card named A+B exists, then cards named A and B also exist.
  • Renaming A to C will automatically rename A+B to C+B.

Suppose we create a card named Joe's Coffee+hours.  It's name contains a "+", therefore it has a compound name

When we have a card with this name, we know that we have two other cards: one named Joe's Coffee, and another named hours.  If you went to create Joe's Coffee+hours but there was no card named hours, then it would be created automatically.

If we were to create a new card named Joe's Coffee+menu, it would share the same left part (Joe's Coffee) with our original card, Joe's Coffee+hours. Similarly, if we created The Bumpy Grind+hours, it would share its right part (hours).

This means that we can use naming patterns alone to start creating networks of information.  With the above examples, Joe's Coffee  is "plussed" to three other cards, and hours  is "plussed" to two.

By following naming patterns like these, we can begin to organize card information in highly flexible ways.

Note that if we were to rename either part (Joe's Coffee or hours), the name of the compound card would be changed to use the new part name. If, however, we were to rename the compound card, the part cards would be unaffected. For example, renaming Joe's Coffee+hours to Joe's Coffee+menu would mean the compound card is no longer related to the hours card and is now connected to the menus card; the hours card would otherwise be unaffacted.


There is very little "howto" involved in compound names themselves.  All you have to do is use a "+" in the name, and you're using compound names.

In general, we do not recommend requiring butterflies (casual site visitors) or Eagle (content editors) to understand the core concepts of compound names.  Most visitors shouldn't have to know what a "card" is, much less how to structure its name.  

Compound names become powerful when you start using them in patterned ways.  To do so, you will need to learn about structure.


More than one plus

  • a compound name can have more than one "+".  E.g. Joe's Coffee+menu+specials.
  • the right name must always be simple. So in our example the left would be Joe's Coffee+menu and the right would be specials.
  • therefore any card used as a right name cannot be renamed into a compound card




Forms are content patterns. Every day we encounter lots of formatted information: weather forecasts, sports cards, restaurant menus, user profile pages, tax documents and nutrition labels each have their own pattern of what information is included, and how it is laid out. These patterns help you compare and contrast information visually, and to notice missing information.

Decko lets you create forms and apply them to Set of cards, so they contain the same kinds of information with the same structure.  It does so using two Setting: *structure and *default


Open these two Recipe cards, and you'll see they have the same structure:

Chilaquiles+preparation time


Chicken (optional)


  • Place the tortillas in a pan with oil until they are really crunchy
  • Prepare the salsa (placing tomato in a pan with oil, onion and chile)


Testing out discussion

Carnitas+preparation time







Put the pork in a pan and cover (barely) with water.  Sprinkle liberally with salt.  Cook on medium flame until the liquid is reduced to a small amount that barely covers the bottom of the pan.  Be sure to turn the pieces of pork halfway through.

Pull the pork out and shred/pull.  Return to the pan and squeeze in the juice of two limes.

Cook until the pork starts to crisp.


You'll also see the same pattern when you create a new Recipe card.

Here's the structure rule that is used to template Recipes:

You'll notice the structure nests cards with recipe information like preparation and cook time, number served, ingredients, etc.  When someone edits a recipe, they can edit those nested cards. (See sample recipe edit form.)


*structure rules control cards' type and content. Like all rules, structure rules apply to a specific Set of cards.  Changing a *structure rule will impact every card in the Set.  Structure rules can be seen and edited in a card's dashboard (or "cardboard"), which is accessed via the ellipses icon (space_dashboard ) in a card's menu.

Nests in structures

Consider again our example of the recipe form card:

Looking at that card, you'll notice lots of nesting, like {{+ingredients|titled}}.  Here's how this works:

  • The double curly brackets ({{) represent a nest, meaning that the recipe card nests the ingredient card inside it.
  • The "+" before "ingredients" indicates that this is a contextual names. meaning the name of the nested card depends on the context of the nesting card.  For example, if I make a recipe called "Lobster Bisque", then its ingredient list will be named "Lobster Bisque+ingredients".
  • The "titled" refers to the views of the nested card.  When you see the ingredients card inside the recipe, it will be in titled view.

The important pattern to understand is that these structured nests establish naming patterns. All the cards that contain information about ingredients will have names that begin with the recipe name and end with "+ingredients".  

See also


  • Checkboxes, radio buttons, and other form elements can be added using Pointer.
  • You can add help text that shows up when nested cards are created or edited.





Users and permissions

Anyone can browse around in and read a Wagn, but by default only users who are logged in to their account can make changes and create new content. Wagn's permissions system lets administrators define roles with additional abilities beyond basic editing and creating relationships, and assign one or more roles to each account.

User cards can support accounts, profile pages, and more. more

Add User

If you are signed in and have permission to create User, then you can invite someone to Wagn via /new/:signup (typically reachable via an "Invite " link at the top of a page).

Wagn's powerful permissions system lets you set CRUD (create, read, update, and delete) permissions on any Set of cards.  


These permissions are checked when a card is included.  That means, for example, that if a public page includes a private card, that private card won't be shown to folks without permission.  Permissions are also checked wherever cards are queried, so that search results will never turn up a card that a user doesn't not have permission to see.


Wagn also supports true file permissions, meaning that permissions are checked whenever a file is requested.  


Permission to update a given cards is based on its *update rules.   A new Wagn comes with several update rules, including these two:

By "Layout cards", we mean cards that have the type "Layout".   Since the set of "Layout cards" is narrower than the set of "all cards", the second rule overrides the first, and only Administrators are permitted to edit Layout cards.






Wagn's permissions system is both powerful and simple.  It uses just 4 main kinds of rules: *create, *read, *update, and *delete.    (It currently also supports *comment rules, but that will soon be handled differently.)


All Wagn permissions can be assigned to any combination of User and Role (user group).   For example, a "Conference Call" card could be restricted so that it could be updated only by persons with the Staff role or the Board role or by Justin Blauchen (the CEO's husband).


Editing card permissions is just like editing any other rules; just go to "advanced" or "advanced > rules" on the card menus





A card with the compound name A+B can inherit its permissions from A.


Suppose we have a card named "Jin's Dossier" and another named "Jin's Dossier+overview".  The common use for such compound names is as fields.  Which is to say that the +overview card is used as a field of Jin's Dossier.  Often we want our field cards (+overview) to have the same permission as their subject (Jin's Dossier).


We call this pattern "inheriting" permissions,  and every Wagn comes with default create, read, update, and delete rules that make all plus cards (all cards withcompound names) inherit from their parents.  These rule can, of course be changed or overridden like any other rules.



File permissions


When serving files and images, many systems rely on "security through obscurity": the hope that hard-to-guess urls will prevent users from stumbling upon their files.  But as soon as the url becomes known to search engines, that approach flops.  Wagn checks for file permissions (which are no different from any other card permission) on every request, so clicking a link to a restricted file will only work for permitted users.


  • in general, an attempt to update a card that doesn't exist will fall back to the create action and use the create permission.
  • changing a card type requires permission to delete the old card and create the new
  • one special case in inheritance is adding new children to an existing parent.  In the example above, this would be like editing an Audition later to add some missing information, like, say, the timeslot.  Since, in this case, creating the child is akin to updating the parent, then whenever the child is set to inherit update permissions, it inherits them from the parent's create permissions.
  • the commenting overhaul blueprint proposes to get rid of the *comment setting, so that this will no longer be considered a separate permission.  (instead comments will have full CRUD permissions based on a +*comment card).