Restructuring the CodexWe are currently moving articles around and changing the general structure of the Codex. Please come back later if you get lost!
Variables can be found under Advanced Tools from the global sidebar.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 VariablesThe 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.
CollectionsThe 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.
VariablesThe 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, SimpleCreates 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.
Term, AdvancedCreates 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.
Rendered FragmentCreates 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.
LinkCreates 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.
NumberThe 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 ArrayThis has currently no use. Ignore it. It will become important in future updates.
Best PracticesAs 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 VariablesA 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 ButtonThe created variable displays a small, grey clipboard button. Click it and paste the variable into the place where you want it to appear.
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 CasesThis 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 NamesUse 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 ArticleSometimes 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 TooltipsWhen 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 TooltipsUnlike 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 IconsCreate 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 InformationAnything 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 ContainersThese 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 LinksKeeping 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!
Variable PrivacyAll 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 OptionsThe open advanced options text uncovers all the advanced tools for variables.
CSV ImportThe 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 ImportYou 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 URLThe 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 SettingsHere 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.
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!