How to use Wagn
Browsing
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:
- 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.
- 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 wagn.org, 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.
- via inclusions. Whenever you include another card that doesn't exist, you're prompted to add it.
- 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.
Wysiwyg
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):
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.
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 http://grasscommons.org/ will automatically be made into links, with or without the http:// at the front - so grasscommons.org also works. E-mail addresses also become automatically clickable, such as info@grasscommons.org.
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:
[[http://grasscommons.org/|Grass Commons]] will look like: Grass Commons
[[mailto:info@grasscommons.org|email us]] it will look like: email us
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 http://wagn.org/card/edit/Documentation, 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)
Ideas
Documentation Tickets
Support Tickets
Recognize odd characters at end of URLslinkify local file linksremove link from image inclusionsenable images to be used as linksVery long URLs and pages breakinterpret Wagn links in PlainTextstrip html from toc linkshandle long URLs in named linkshandle brackets in named linkslabel context-named inclusions correctlyadd reference syntax for main card of pagerespect spaces in inclusions in linksinclusion confusion in linksGUI for adding links and inclusions
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.
Example
The following (relevant) video is in a card named +howto video and is included here with the following syntax:
{{_l+howto video}}
How To
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
Key Values Notes view
"view" key is optional; if no key is given, value will be treated as view
title
text
replaces card name in view
show
applicable view names
e.g. title_link on any view that shows a title. use commas for multiple views
hide
applicable view names
e.g. paging on searches or menu wherever it's shown by default. use commas for multiple views
structure
any card name
overrides content and structure rule.
item
any valid view name
may be deprecated?; set via multiple-pipe syntax above Eg: {{some card | key1: value1 | view: open}} size
Image cards only
type
any valid Cardtype name
may be deprecated?; set type via rules with *default setting
other
any valid CSS value
may be deprecated?; will be treated as CSS
Notes
- whitespace is optional
- inclusions can use contextual names
- see nesting and views cards for examples.
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:
{{nymph}}
Tips
- 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}}
Discussion
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.
Example
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.
How To
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.
Tips
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
Discussion
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
Example
Open these two Recipe cards, and you'll see they have the same structure:
Chilaquiles+preparation time30 minutesChilaquiles+servesChilaquiles+DietChilaquiles+tagChilaquiles+ingredients
Tortilla
Tomatos
Chile
Chicken (optional)
Cheese
CreamChilaquiles+preparation
- 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)
Chilaquiles+discussion
Testing out discussion
Carnitas+preparation time10 minutesCarnitas+servesCarnitas+DietCarnitas+ingredients
Pork
Water
Salt
Lime
+preparation
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.+discussion
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.)
How To
*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
Tips
Discussion
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.
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).
To sign into Decko, you must have an accounts.
Like everything else on Decko, accounts are represented in cards. People with accounts can be given both permissions to contribute and credit for their contributions. When someone is signed in, a link to their card will show up on comments they make, in Recent Changes next to cards they've edited, etc.
Example
If Johnny Carson signs up for an account on a standard Decko deck, the user experience of the signup process should seem pretty familiar: you enter your name, email, and password, you get a confirmation email, you click the verification link...
Everything that happens behind the scenes is tracked in cards. The following cards will get created along the way:
- Johnny Carson
- Johnny Carson+*account
- Johnny Carson+*account+*email
- Johnny Carson+*account+*password
- ...and a few more
How To
Basics
Signing up
Most Decks feature a "Sign Up" link near the top right corner of every page. Clicking on that link will take you to a Sign up form (which is actually the "new" views of the card named "Sign up"). When you Sign up for a Decko site, you are creating a Sign up cards, along with cards for your email, encrypted password, etc. By default Anyone can create a Sign up.
If you also have permissions to create User cards, then after you Sign up you will receive a verification email. Clicking on that email will confirm your email address and then change your Sign up into a User (by changing the card's types) and activate your account.
If you don't have permissions to create User cards, then someone who does will need to approve the account.
Signing In / Resetting Passwords / Inviting
When you sign in with an email and password, you will typically see a link to your card (the card with your name) at the top of the page. If you navigate to that card, you will be able to access account details and roles settings via the card's menus. This is the easiest way to update your email or password.
If you ever lose your password, just click on "Sign In", and then "RESET PASSWORD". This will prompt you to give your email address, to which Decko will send a verification email with a new token that will allow you to reset your password. If you lose access to your email address, or forget which one was used when you got the account, you'll have to contact an Administrator to sort things out.
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).
Administration
Permissions
As with any card, permissions rules for Sign up and User can be edited via the advanced item on the menus. Some important permissions to consider.
- who can create Sign ups? If this is set to "Anyone", sign-ups are turned on. Otherwise they are effectively off.
- who can create Users? If this is set to "Anyone", then users can verify their own accounts. Otherwise someone with this permission will need to approve them
- is captcha on? This can reduce spammy sign-ups.
- what Role does the user have? This will heavily influence what the user can do once signed in and can be set via the "account" item on the menus of a User's card.
Emails
There are three account-related Email template you may wish to customize:
- The verification email is sent to users when all that remains for their account to be finalized is for them to click a verification link.
- The signup alert email is sent when a new signup is created (typically to administrators)
- The password reset email is sent when... you can probably guess that one.
Formatting
Because both Sign up and User are normal cards, each can be formatted like any other card. So, for example, you can add an nesting like to the *structure of a Sign up card, and this will add a newsletter field to the sign up form.
If your User card shares the same field with the sign up card, then the value of this field will, of course, persist and be displayed even after the card's type is changed. All Sign up fields will persist upon approval, in fact, but you can independently decide whether and how to display these fields on the User card.
Tips
- The account links are included in layouts with {{*account links}}
- An account — that is, an email and a password allowing sign-in — can be added to any card that is in a Set that has the *accountable rule turned on. This enables you to, for example, create cards for people now who may join later, or have an Organization cardtype that can have an account.
- Currently, users with existing edits cannot be deleted.
Discussion
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.
Example
Permission to update a given cards is based on its *update rules. A new Wagn comes with several update rules, including these two:
- All cards can be updated by Anyone Signed In.
- Layout cards can be updated only by Administrator.
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.
How To
Basics
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.
Inheritance
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.
Tips
- 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).
Discussion