Custom Options

Introduction

WeakAuras version 2.10 and later supports custom option panels. This allows authors of complex auras with lots of code to let users modify the behavior of those auras, without having to worry about the user editing code. Please note that WeakAuras only provides a space for you to build this panel of options, and does not assist you in designing your GUI to look presentable, or be easy to understand for your users. For assistance in designing a decent UI, see Tips & Tricks, or visit our discord server for advice from a human.

Table of Contents

• Author Mode
• Common Option Fields
• Option Types
• Option Groups
• User Mode
• aura_env.config
• Tips & Tricks

---

Author Mode

To begin making your own options, open WeakAuras Options to the aura you wish to add custom options, click on the Custom Options tab, and then click on Enter Author Mode to enter Author Mode. In Author Mode, you will be presented with a list of options which you can edit to suit your needs. At first, you will only have the ability to Enter User Mode, or Add Option. Enter User Mode toggles back into User Mode, while Add Option ... adds an option. The first option you add will look something like this in Author Mode:

Option Controls

Each of these controls will change how the option is rendered and behaves while in User Mode. Since a comprehensive User Mode option panel generally takes a lot of options to create, there are some basic Quality of Life style controls in the header, which you can see at the top of the above image:

• The chevron on the left of the Title is a toggle button, which will collapse the option entry for ease of navigation. While collapsed, only the option header is visible.
• The up and down arrows will move the option up and down, respectively. The order of the options in Author Mode determines the order in which they are shown in User Mode, so you can use this to fine tune the design of your options panel.
• The icon which looks like 2 stylized pages with an arrow will duplicate the option, and insert the duplicate directly below.
• Finally, the red X will delete the option. Note that currently, this cannot be undone, so take care to not accidentally click that button!

---

Common Option Fields

Below the option header are several inputs which control the behavior and appearance of the option in User Mode. Some of these are common to all option types:

• Display Name - The title that the user will see for this option in User Mode.
• Option Key - The key by which you can access the user's choice for this option in custom code. See aura_env.config for details. This is always interpreted as a string valued key.
  • NOTE: It is illegal to have multiple options on the same aura with duplicate keys. Attempting to do so will cause the new key you are writing to be rejected. This is done for the sake of your sanity. ;)
• Option Type - The type of widget which the user will see. This also determines any additional controls which appear in Author Mode. See Option Types for details on what each option type supports and expects.
• Width - The width of the option.
  • A width of 1 represents half of the width of the panel, and a width of 2 represents the whole width. Think of it as 2 columns, side by side.
  • If the remaining width in one row is insufficient for an option, then it will be rendered on the next row.
• Default - The default value. In User Mode, once the user has begun to modify the controls, a button labeled Reset To Default will appear. Clicking it will reset all of the values to the default that you choose here.
• Tooltip - These two options (the toggle and the text input) determine what tooltip will be shown when the user mouses over the option in User Mode. Toggling the tooltip checkbox off will disable the tooltip; while toggled on, you can edit the text which will be shown. This is best used for explaining what an option does when the Display Name is insufficient to explain on its own.

---

Option Types

Each option type adds its own controls to Author Mode, representing the special values which it requires in order to function properly. They are listed here:

Description

This option type will place a non-interactive chunk of text of your choice into User Mode. Since it is non-interactive, the Option Key, Option Name, Default, and Tooltip controls are irrelevant and not shown.

Description Fields

• Description Text - The text to be shown. This can support multiple lines of text, so you are given a large editbox to write your text into.
• Font Size - The font size to be used. Currently, only Small, Medium, and Large are supported.

Space

This option type will create a space in the UI. This renders in User Mode to a description element with no text, but is helpful to provide here as an easy shortcut to create space quickly.

Space Fields

• Width - If the toggle box is unchecked, then the space will fill the remainder of the line that it falls on. Otherwise, it will have a width as set by the slider.
• Height - If the toggle box is unchecked, then the space will occupy only the line that it falls on. Otherwise, it will span across the number of lines set in the slider.

Separator

This option type creates a horizontal line to separate sections, with optional text to accompany it.

Separator Fields

• Separator Text - If the toggle box is checked, then the text provided in the input field will be inserted into the center of the separator. Otherwise, a continuous line will be rendered.

Toggle

A simple checkbox. There are no additional fields for this option. Values can be the boolean values of true (checked) or false (unchecked).

Toggle List

A collection of checkboxes. There are no additional fields for this option. This is useful for if you have a lot of toggle options which are similar to each other in purpose. NOTE: The user's choices for each checkbox will be found at aura_env.config[optionKey][index], where index is a positive integer. So in the screenshot above, the user choice for val1 would be found at aura_env.config[optionKey][1], since it is the first checkbox in this toggle list.

Color

A simple color picker the user can click on to open the Color Picker Widget. There are no additional fields for this option. The value in custom code will a table of the form {r, g, b, a}, which represents normalized RGBA. So, a value of {1, 0.5, 0, 1} represents orange, and {1, 1, 1, 1} is white.

Note: the remainder of the option types described will omit the common option fields in their preview images, as they do not change for any other option type.

String

A simple string input.

String Fields

• Max Length - If the checkbox is checked, then the string the user inputs will be trimmed if it is too long. The slider goes up to 20, but you can enter a larger number if you wish by typing into the small input field below the slider.

Number

A simple number input. In User Mode, this is identical in appearance to the string option type, but it will only accept inputs which can be evaluated into a number.

Number Fields

Note that all of these values can be unset if you do not wish to restrict the user's choice in User Mode.

• Min - The minimum acceptable input. Inputs below this minimum are adjusted to the minimum. Defaults to 0.
• Max - The maximum acceptable input. Works the same as Min, but on values larger than what is deemed acceptable. Defaults to 1.
• Step Size - The minimum acceptable step size. If set, then the user input will be adjusted down, until is is equal to min + n * stepSize, for some non-negative integer n (if min is not set, then it is interpreted as 0 for the purposes of stepification). Defaults to 0.05.

Slider

A simple slider. This is an alternative method to get a number value in your configuration.

Slider Fields

Note that all of the following fields are optional, just like in the Number Option Type.

• Min - Identical to Min in the Number Option Type. Defaults to 0.
• Max - Identical to Max in the Number Option Type. Defaults to 1.
• Step Size - Identical to Step Size in the Number Option type. Defaults to 0.05.
• Soft Min - Similar to Min, but affects only the slider. Has no default value. This value must be greater than or equal to Min to have any effect.
• Soft Max - Similar to Max, but affects only the slider. Has no default value. This value must be less than or equal to Max to have any effect.
• Slider Step Size - Similar to Step Size, but affects only the slider. Has no default value. This value must be greater than or equal to Step Size to have any effect.

Dropdown Menu

A Dropdown Menu. This option type is more complex than the other basic option types, so it will take up more space.

• Default - The default value control here is a dropdown menu, whose options are determined by the values you enter into the controls below. Note: in custom code, the value you get will be an integer (starting at 1) which represents the user choice. So, if you have {'val1', 'val2', 'val3'} as choices in a dropdown menu option, and the user picks 'val2', then you will see 2 as the value chosen in custom code.
• Value controls - Each existing value in the dropdown menu will be on its own row. You can edit the string which the user will see, or delete the entry by clicking the red X, or by entering an empty string into the input field.
• New Value - Enter a value here to add a new option to the dropdown menu. The controls in Author Mode will extend to accomodate it.

Option Groups

WeakAuras 2.13 and later supports the formation of Option Groups, which are designed to allow authors to create complex option UIs, with better organization. An option group is, at its core, an option with other options nested inside. The value of the option group in aura_env.config is always a table, and the group type determines how the table is arranged.

NOTE: WeakAuras supports arbitrary nesting of option groups, and it is ultimately up to you how far you wish to nest things. However, deep nesting of groups does not always make sense from a UI/UX perspective, so some degree of caution is recommended, so that you do not accidentally make a horrifically complicated UI.

Option Group Fields

• Display Name
  • The title of the option group. This is displayed in the collapseible header.
• Group Key
  • The location within the config table where this option group exists. The behavior of this field is identical to that of non-group options, and duplicate keys are still forbidden.
• Collapsible Group
  • if this option is checked, then the group will be rendered in User Mode with a text button which toggles visibility of its children when pressed, similar to Author Mode.
• Start Collapsed
  • Determines if the group is collapsed in its default state. Has no effect if the group is not collapsible.
• Group Type
  • Currently, Simple and Array are supported as option group types:
    1. Simple groups have their sub options' values located directly in the group's table. So, if you have an simple group with a key foo, and that group has a option toggle with a key bar, then you can find the value of bar at aura_env.config.foo.bar.
    2. Array groups have copies of their sub options' values in an array of 0 or more subtables of the group's table. This allows the user to make multiple similar entries with similar data (quite handy for e.g. setting up an interrupt rotation). If you have an array with key foo, and a sub option in that array with key bar, then you may find the values of bar at aura_env.config.foo[index].bar, where index is an integer which represents the...index of the entry you are searching. Entries into an array always constitute a contiguous range from 1 to #aura_env.config[key], where key is the key of an array group.
• Number of Entries
  • Dropdown menu, with 3 options. Controls how the entries in an array are limited. Has no effect on simple groups:
    • Unlimited - array has no limit on # of entries, and the user may create and delete entries at willl.
    • Limited - array may not have more than the # of entries specified in the Entry Limit slider. The user will be blocked from adding entries which exceed this limit.
    • Fixed Size - like Limited, but array may not have fewer than the # of specified entries, either. The user will be blocked from creating or deleting entries for this array.
• Entry Limit
  • Slider, which specifies the size of the array. Has no effect if the array is unlimited.

User Mode

In User Mode, you get to see all the fruits of your labor. Here is an example for you to play with:

!vE1AVTTnu0FlRddOfOjq(TZ(wAQZAlCvYcDB(MQPLOK5MePkfPtsXG)TVZLus2oTaRlPnMpV3Z9CFrNmizvcRkHLr)dd1oBPujsy38PvlFF8IewUwzzYVjsIhmmH1ikZVvlv2e2BUz1QB(yc7XBYZBe2KRpB(0jtgnz0O5thn9IOrJsYpB8eiyztDj)PvIhXT(T0ewQRXQRcZZDQuRuRE5R2)H9Rd)AewNrTF9lFXsTruTFTSUXHpY0LAZ(1ns7(18kH917xNQvnIulDbSwMSw2Kkvf7xlkL2Z3V(kdVbtC7xxjBLdw9ZYD8kh2a4kvy4qE5ctLqz9QrYRGO)QtItuPlfnwPy)6YawsDMg6Qos8VxzfMm6sciJkooRJNXH4a(WH4P4)4m9MqTrwrIvQOZ4sLBCneGiDSXv6pI2yHe2rwqhkSIYssPaUsLKd0PePpZ61zsnihhiGAVTFPqj4ksNcR0DGgD2aBSvOYmcJK4rATDUYANLtOTIxO4ejkK54uqy)jWXxDyRgDgzMyaVwkG4Bez9UgRuLkZCkBp)DeV2zevCRvsw9TgUObBcRbrbW6eACpRrcYWRlrbrRbIGgJDZnW9kll5ExtjPcUj1bPf78R65KV6iFQvuv7DvgYy2jTCitJZA8bbFki0glfHy2QvP0z5LKQj6lMxDGbic3dPD6sNTM3dRCHRqstLTHc4MmIrcMFqBbd88x8QFVXT5LdE9WieTts9dF)VjSN6sOgpDWSlMI0PlIgpEgsLc5tCv6wTPnl8QfXRwChYP0QCzbLcB1ffWbHHXdsEtcoJUMYWMNeh1nEaTx7yiXX4NUPtdxmo68HjXdtUEYWHZMfnBE0WztgmDmLupzCs8i)Hgt)TxddH6Ahod3nI25qU(NQZqSvcZ1(j3Hn4wz69Ym72e2Lyow1xnGqpdEgJfdOQeiQVzBymggwfJrSsrHW0ASR6xGgMj24YZx9un017wS82R)0sSVFk3z4uXSAer((SMGCHRrSdrJmCl5JjSVC1LSvFHT6Y7GWCKszuzmi8(JERr4pk72flHW9RbLj4LKbPOAaDif5e9qZVazO7eRcl(rDgkWE2apLbIb(3BQ7iIwlZJCu)fj8KXHQhLwVBK0tc7TgDDM(bKq(rHYLW2XlDDrb0KbK3KgmK0XFlE6qSa7bVhW7kXH6vwMOj1i9hQtlbuTF9Vo6ezGzwF58vB9v3Oejuu4W99zsuHaKctzlnOwzjYE0u2FdAVq1jrwZwEz((1E8C(r9Ey(Z3d0OZNqqD0phuhFcuh3b1lj9z)VWlbg7w)2LCtH4ym)6wqNPDBkf)iy7VspSjMhPmu4uJiMa5B6W)wbpJIScq7FsVg)mFEu07egrp(Ae1C0SsB(Ltf5Kd8qi5VJcw5NTF9nTeZr0WWdXqV50aGPhKwf2w2fYDsavP224dO05KFOBtyDi)KqetJxrazXAq9AGO4z(AuwJUKI)ofFlrf)d4PTWfK(gs2BiPUHK5gsGBirTPpgURA3jMWSdMGuHEAEc)TW7EIT2RW26FhXotcruu8SVB4JuZjvbfiqXghIAgd3DyhVThmlQkKQWR0LH9OYWXZpGQuQDz3XVk078h4KM(ms5)xr5JzKl8fu152p26Ec4WWvu85rSdSviHiQ6RO2ZsDIb5CSk629LCyLse0sVcYZXEXtxFu0b6JijDBk1dAxjsx2akTqRZOujdL1HgNqW(NTvy0U6q215NqfZoQMNVZsmkw2ZNkx1gk955gYGo7i68Ojh769gsuNHCBjNEqwSxkh8ebBiw7F)gkl9KgVJuq959PJkT6mv7v2I8u6Tlu4IpKleEilu4vJzNAkZpYuIcnd8pEqXl)m6LrQoEaW4FHwNYCCTLlUgw6dAt29gEDc7((rs8U9)apZZiXZNUsxvxkqO6v(EU4bGOnNpRlt21lH6LAGnJquUL7PIWZjUMwn0SKD1DlwetBiP(Zaoh1mMLbHsl(LUgsK8B6DeuAVLyFP6N)09T3)5opLptw(frtkF1DOzBJlu0nHDTr(n6XQ8mY(2VE1QUKTqcKVli93ttvqxCr29TLuJIO6BC)3hcpri1)vKOkHDTUtl5nnF3Qum7ZxelBefWEcmRV6oDu0UwSdvnH6hpKqqY)o

It will look like this:

---

aura_env.config

In order to read the values which your user chose, you must index aura_env.config in custom code. This is a table which WeakAuras provides to you. For each option you built in Author Mode (except Description and Space elements), there will be a corresponding value at aura_env.config[optionKey], where optionKey is the value that you wrote in the Option Key input field. So, if you had a toggle option which looked like this:

Then you could check if the user wanted to "Show All Debuffs" by checking the value of aura_env.config["showAllDebuffs"].

WeakAuras guarantees that any change in aura_env.config will be visible to the custom init action. Custom code that runs after init (so, all of it) is not granted the same guarantee for performance reasons, though in practice you will never encounter a scenario where aura_env.config is not the same in a later script, unless you write something to the table or replace it.

---

Tips and Tricks

Here guidelines for creating intuitive and easy to read custom option panels:

• Name your options well. If you have a toggle option named Show All Debuffs, then users will expect that this will somehow translate to the aura showing all debuffs. Try not to be vague, and pay special attention to any time that you change the behavior of an option in your code. Make sure that the Display Name, tooltips, and any description texts are updated to reflect this change in behavior!
• Make some room. Don't be afraid to add description texts which don't have any text in them, to make spacers. This can turn a crowded UI into a comfortable UI. Don't just do this blindly, however. Ask friends for feedback on if your design seems crowded.
• Keep it simple. This might seem counterintuitive, given how complex much of WeakAurasOptions can be, and how this feature gets such prime real estate (as it's in its own special tab), but it's really true. The fewer options you can get away with, while still providing the full functionality you need, the better.