Guide to Variables

Guild Exclusive

This is a Master+ feature. To get access, Join the Worldbuilder's Guild!

Variables are a powerful tool to simplify a number of tasks. This guide gives some technical details, presents many potential use cases and proposes a number of best practices on how to create them. Using variables correctly can make your life much easier in the future.  
All changes in the text-areas within the Variables interface are automatically saved. There is no save button.

Creating Variables

The creation of variables is simple. However, before starting to create variables it makes sense to think about how they will be used. This helps in creating consistent variables that you can use and keep organized as their numbers grow. Keep in mind that you want to avoid having to change variable keys down the line as that requires you to find each use and change it. There is currently no tool to support this process.

Collections

The collection is currently a purely organizational tool. The idea is to keep similar variables in the same collection. Don't be afraid to make many collections even if they will only contain a few variables in the end.  
  • Name. The name of the collection. Use something clear and descriptive. You can change this later on without problems.
  • Description. Use the description to expand on what the variables in this collection are for. You can later change this without problems.
  • Prefix. The prefix is added to the variable name and replaces the username suffix. This is useful if you expect there to be many collections and if there is are additional authors creating variables. Otherwise, it might be hard to determine which collection a used variable is from. Make this short, but clear.
    • The prefix can be used to find the variables within the collection with the auto-complete dropdown.
 

Variables

The variables are created inside of a collection. Make sure the variable you want to create fits the description of the collection. Each variable has four fields.  
  • Key. The key needs to be a unique value that can easily be connected to the purpose of these variables. Any additional variables with the same key will be ignored. You cannot change the key on a created variable.
  • Type. Select the type of variable you wish to create. Check below what each type can be used for.
 

Term, Simple

Creates some displayed text with or without a simple tooltip.
  • Title. The title is displayed as text in the article where you place the variable. You can use BBCode here.
  • Value. (Optional) The value generates a plain tooltip for the title. You cannot use any BBCode here.
example-tooltip.webp
Example Tooltip

Term, Advanced

Creates some displayed text with a fancy BBCode tooltip.
  • Title. The title is displayed as text in the article where you place the variable. You can use BBCode here.
  • Value. (Optional) The value generates a rendered tooltip for the title. You can use any BBCode here.
example-advanced-tooltip.webp
Advanced Tooltip

Rendered Fragment

Creates a piece of re-usable BBCode text.
  • Title. (Leave Empty) The title can be left empty. It is not used and cannot be changed or seen after creation.
  • Value. The value generates a rendered tooltip for the title. You can use any BBCode here.
example-rendred-fragment.webp
This text can contain any BBCode such as italics, a tooltip or even a secret.

Link

Creates a link to a specific URL.
  • Title. The display text of the link. You can use BBCode here.
  • Value. The URL that should be linked. You cannot use any BBCode here.
 

Number

The number can be used to write an integer number anywhere. Currently very limited in use and can always be replaced by a simple term. Future updates will expand its utility.  

JSON Array

This has currently no use. Ignore it. It will become important in future updates.

Best Practices

As more and more collections and variables are created within the world it becomes harder and harder to keep things organized. A good organization is key to keep using variables in a productive and efficient manner. They lose much of their value when you can find them quickly. And always think that you should continue to find them in a year or maybe ten!  
  • Collections. Make sure that your variables are sorted into collections that make sense to you! It is the only way to keep them organized in an efficient manner. When in doubt, create one collection too many than too few. All the variables inside of a collection should either match thematically or share a similar function.
  • Memorable Prefixes. Your collections should have prefixes that you can remember easily, but are unique enough that the dropdown doesn't bring up your entire collection of images and categories! The better you do this, the less scrolling you will be doing.
  • Descriptive Keys. Make the keys of your variables describe what they do. The key is all you will see in the article once you use that variable. You can of course always check the view or the variable menu, but it should be apparent just from the key. Future you who has to edit an old article will thank you!
  • Consistent Naming. The keys should be named in a consistent manner. This helps not only with the organization but makes it easier to remember them when you want to use them. It makes sense to invest some time to come up with a scheme that works for you. You absolutely do not want to change this later on as it requires you to manually update all the variables!

Using Variables

A variable can be used anywhere where BBCode can be used. You can get the BBCode for the variable in one of two ways:  
Gray Copy to Clipboard Button
The created variable displays a small, grey clipboard button. Click it and paste the variable into the place where you want it to appear.  
Summon Suggester
Type a [ and then three letters of the title or key of the variable. Then select the variable from the list. Variables are always sorted in after images and categories.
Add Variable to Article
 
Remember that you can use variables within fragment variables. The embedded variable may not contain a variable itself and it does not work with other variable types. What you do with the variables from here is up to you! The possibilities are endless.

Example Use Cases

This section will touch on a number of potential use cases you might want to use variables for. However, this collection only covers the basic and most obvious use cases. There are many other ways that they can be used.

Placeholder Names

Use a simple term variable to place placeholder names. Once you come up with the proper name you simply need to replace the variable text and it will be updated everywhere. The limitation here is of course that you can only have one variant of the name per variable. So if a character is addressed differently in a different context you need to use multiple variables. You can add a tooltip to explain that this is a placeholder name!

Things That Need an Explanation but Not An Article

Sometimes you mention something within your world, but you don't really want to write a full article about it. Create a variable and you can still mention this thing in all the places and you can update it in just one place!

Reusable Tooltips

When you find yourself write out a tooltip more than once, be it to explain an abbreviation or translate a conlang word, use a simple term! This way you can always summon the tooltip and can change it in one single place when something needs changing!

Fancy BBCode Tooltips

Unlike the normal BBCode tooltip, the Advanced Term tooltips can render BBCode within them. This can be used to create previews, nice teasers or tooltips with images. This is the only way to achieve this outside of article mouse-over snippets.

Useful Icons

Create a collection of all the Fontawesome & RPG Awesome Icons you use frequently. This way you can just start typing the collection name and the code is inserted for you. No more remembering or looking it up!

Frequently Updated Information

Anything data or content you wish to update frequently you can put into a variable. Even if this variable is only used in one place you can quickly find the data and change it in one place. This can save you a lot of time if you have many of these bits of data or content that might be distributed across many articles.   This is especially useful in World for RPG Campaigns as small changes can make these worlds seem alive! Use it to update the dates of upcoming and recurring events such as festivals, markets, wandering troupes, auctions and more. Update the current locations of travellers in one place as they move through your world. Or update the wealth and number of members of an organization.

Technical & Repeated Announcement Containers

These are more useful for documentation worlds, RPG system, WIP warnings and similar banners and containers. This way you can manage these containers and banners in one central place and keep them up to date.

External Links

Keeping external links up to date can be a nuisance when they appear in many parts of your world. With this, you can just create on the link and place the variable everywhere. If you need alternative display texts depending on where you use them create an extra collection or name them similarly. This way when something changes you just need to update these variables and the new link is displayed everywhere in your world.  
NOTE: You might not always want to use the Link type for this. When you use a simple term you can write the URL using BBCode as in the example below (add this to the title field):  
[url:https://worldanvil.com/dashboard|tab]World Anvil[/url]
  This way you can add the tab modifier which forces the browser to open the link in a new tab and you can add a tooltip to add some context to the link!

Content

Variable Privacy

All variables are public and can be seen by anyone if they have a direct link to them. However, finding your variables is practically impossible without knowing this direct link. This will be changed in a future iteration of the feature when collections can be set to private and added to subscriber groups.  

Advanced Options

The open advanced options text uncovers all the advanced tools for variables.  

CSV Import

The CSV Import can be used to quickly create a large collection of variables. Each row creates a new variable and requires four columns: key, title, type, value. Separate each column with a comma. If you want to use a comma inside of one of cells then put " (double-quotes) around the cell value.   The type column accepts the following values:
  • string (Term, Simple)
  • text (Term, Advanced)
  • fragment (Rendered Fragment)
  • link (Link)
  • number (Number)
  • json (JSON array)
 
Example CSV Import
You can copy and paste this example into the CSV Import field and it will create four example variables within that collection.
example-tooltip,Example Tooltip,string,"This is an example tooltip, with a bad comma."
example-advanced-tooltip,Advanced Tooltip,text,"[b]A bold tooltip[/b] with an image [img:386957]"
example-rendered-fragment,title,fragment,"This text can contain any BBCode such as [i]italics[/i], a [tooltip: This is a tooltip text]tooltip[/tooltip] or even a secret."
example-link,World Anvil,link,https://worldanvil.com/dashboard
 

JSON URL

The JSON URL gives direct access to the values of the variables via the private API of World Anvil. This URL is currently accessible by anyone so do not give them to anyone else if you wish to protect your content.  

Collection Settings

Here you can change the title, description and prefix of the collection. Title & description can and should be updated to reflect the variables within the collection.   Changing the prefix does not affect existing variables. However, all future variables are created with the new prefix. This means that this change does NOT break existing variables.  

Danger Zone

Delete all the variables and the collection you have currently selected. It asks for confirmation, but with any deletions on World Anvil this is irreversible. So make sure you are in the right collection!

Comments

Author's Notes

Any questions? Any ideas on how to use these variables? Comment on this article or come to our Discord community.


Please Login in order to comment!
18 Mar, 2021 14:49

I love this new feature and am making extensive use of it (mainly for characters, locations and items that do not warrant a full article). It would be really great if, in the future, you could add the ability to move variables from one category to another. Some of my categories are pretty big now!

18 Mar, 2021 19:15

It is a great feature, yes! You would need to make a feature request for that :)   In the meantime, there is a reason I wrote to better have too many collections than too few! ;)

27 Mar, 2021 15:06

A helpful addition to this guide would be information on the containers used by variables for those of us that have specific CSS for popups such as tooltips, mouseovers.

29 Mar, 2021 11:49

Hi, not that would be something added to the CSS guides and then linked. I can see if we get someone to write something up.

2 Apr, 2021 16:53

I don't suppose this is the kind of thing that could ever go in titles? If they could, this would be the one thing I have always wanted as a guy with a world with too many conlangs, but never had. (Though, I understand there might be technical reasons why not)

2 Apr, 2021 18:13

Putting them into a title is very unlikely as the titles are used to create the URL. As a workaround you can for example add a small footnote (question mark icon) to the article links in the form of a variable (this of course means you have to always insert to values, but its a lot faster than repeating tooltips :))

3 Apr, 2021 10:33

I figured there might be technical reasons like that :P A shame, but not a huge one, I suppose!

Sage Horonor
Marc Betbeder-Matibet
13 Apr, 2021 05:46

These variables are great! They solve one of my biggest issues using WA, needing to explain something small without dedicating an entire article to it. I'm hoping to use them all throughout my world, for small things and for common shorthand.   However, I'm having an issue getting variables to nest properly. This isn't a deal-breaker, but would be handy to have, especially to be able to include shorthand in my other variables. An example of this not working is in this article (Emberstone), where I have placed the 'Garnet' variable, and my nested variables to not show up. They are meant to be in the value column ('gp' should show up after '10'), and the heading of the 4th column ('CC'). Is this because I am embedding them within a BBCode table, or am I doing something else wrong?

25 Apr, 2021 05:18

Hi! Unfortunately, variable nesting support was removed from Advanced Terms, but the documentation has not been updated yet. I made a report to have this changed.

19 Apr, 2021 10:17

First of all: I love the feature so, so much! It makes so many things so much easier, so thank you!   But, from the sidebar of the Variables-page   "Term, Advanced All form fields required When embeded into an article, the value will appear as a tooltip of the title. The value can include BBCode tags and other variables (one additional level), which will be rendered in the tooltip"   According to the Codex , nesting only works with fragments (which also seems to be the current version). I am however 100% certain that when the feature launched the advanded terms could be used to embed another variable, so I would ask to either change the description on the sidebar or (which I'd prefer if possible) reenable nesting in advanced terms.

We share this world - so make it a better place both for people and the environment. <3
25 Apr, 2021 05:17

Thank you! I submitted a report to change the documentation.

27 Apr, 2021 02:12

Are there barriers to using simple variables within stat blocks? I've been unable to get them to work!

27 Apr, 2021 04:53

Hi. Statblocks do not support variables as those are defined for a World while statblocks are not and can be used in many places.