Editing WoW:Creating defaults

This is a basic HOWTO to help you create defaults for your addon. First, I'm going to assume you are at least familiar with how to start an addon, and make it save variables. If not, please check out [[AddOns|this page on how to start an addon]] and [[Saving variables between game sessions]]. This is required knowledge for our defaults.

== The Basics ==

Let's begin. At the top of the page, before any functions, add this:

 local ThisAddon_Defaults = {
   ["Options"] = {
     ["MasterOnOff"] = "On",
     ["version"] = "1.0",
     ["debug"] = false,
     ["More Random Variables"] = Value,
   },
 };

Now for an explanation...

* local ThisAddon_Defaults - This one is easy enough. First, we declare that our defaults are local to this LUA file only. If you choose not to use local, then any addon can use your defaults. Removing the "local" may be needed if you expand your addon's need for defaults beyond a single file. Second, we give the library of defaults a name. In this case, I choose to use the Addon's Name, then _Defaults. This naming convention is a good idea even if you keep the "local". 
** ["Options"] - The name of the table our Options defaults are in. I recommend this in case you need to add more defaults and don't want them intermingling. For example, a list of defaults for items should be separate from your options.
*** Your variables - These are how your variables should be set when installing a fresh copy of your addon.
** End our list of option variables.
* End the list of defaults.

There we go. This is a quick and easy way to set up defaults.

== The Next Step ==

Now let's add a bit more complexity. I mean, we have the list of defaults... Now what can we do with them?

=== Initialization ===

Let's make it so when the addon starts, if the settings aren't there, the defaults will be set! So, for this, let's assume we have a options variable being saved, by the name of "ThisAddon_Options". All of our options settings are saved to that, and this is saved from session to session. So let's save our options!

==== The XML ====

First off, we need to make a function that we call when our addon has finished loading... To do that, first we need to add a line to the OnLoad section of our XML file.

 <Scripts>
   <OnLoad>
     this:RegisterEvent("VARIABLES_LOADED");
   </OnLoad>
 </Scripts>

This gives our addon something to look for to see if it has finished loading. If our addon was a LoadOnDemand type of addon (not loaded until it is needed), we would want to use "ADDON_LOADED".

Also, while we're here, let's add a bit of code we'll need later. After </OnLoad>, add the following:

   <OnEvent>
     if (event == "VARIABLES_LOADED") then
       ThisAddon_Loaded();
     end
   </OnEvent>

This will tell our addon to run the ThisAddon_Loaded() function as soon as the addon has been fully loaded.

Okay! We're done here! Let's jump back to our main code!

==== The Main Code ====

Now we can write our post-load function... This will run after the addon has been fully loaded. We do it this way, because if we call things that haven't been loaded yet, then our addon will fail, and output an error message. This way, everything will have already been loaded.

 function ThisAddon_Loaded()
   if (not ThisAddon_Options) then
     ThisAddon_Options = ThisAddon_Defaults["Options"];
     DEFAULT_CHAT_FRAME:AddMessage("ThisAddon Options database not found. Generating...");
   end
 end

* Start the function we run 
** Check to see if our options ("ThisAddon_Options") are already set.
*** If not, then copy the default options to ThisAddon_Options.
*** Output a message saying we're generating the options database
** End the check

See? We're done. Fairly simple. And if we end up changing our defaults, then we don't have to type them in again.

== The Future... ==

=== The Possibilities ===

There's even more we can do with Defaults. You'll noticed that I added ["version"] to the list of defaults at the top. There is an excellent reason for this.

Let's say that I did some more work, and created a new version of the addon, Version 1.2, and I changed, removed, and added a lot of options to the defaults. Rather than tell people to delete the existing settings they have, let's write a code that will automatically update their options upon finding the version difference!

But first, let's add a global at the top of the page:

 ThisAddon_Version = "1.0";

This will make it easy for us to check and update the internal version number. In fact, in the Defaults, we can set 
 ["version"] = ThisAddon_Version;
which will make it even easier to check and change versions.

=== Back to the Loaded Code! ===

In our function ThisAddon_Loaded() code, at the very end of it, let's add the following code:

 if (ThisAddon_Options["version"] < ThisAddon_Version) then
   ThisAddon_Options_temp = ThisAddon_Defaults["Options"];
   for k,v in ThisAddon_Options do
     if (ThisAddon_Defaults["Options"][k]) then
       ThisAddon_Options_temp[k] = v;
     end
   end
   ThisAddon_Options_temp["version"] = ThisAddon_Version;
   ThisAddon_Options = ThisAddon_Options_temp;
 end

* If the options version we loaded is lower that the version this code is running... (So if I change ThisAddon_Version to "1.2", and the user used "1.0" before this, this code will activate!)
** This creates a temp version of our options, based on the new defaults. All of the user's current settings have not been touched.
** This says, for all the options we loaded at the start... (The user's current settings...)
*** If the same option is in the default options...
**** Then copy that setting to the temporary options.
*** End what to do if the same options exist
** End going through all of the default options.
** Update the temp option's version number to the latest version.
** Finally, copy the temp options, into the options in memory.
* End this action.

== Advanced Default Setting Updating ==
Having worked with this for so long now, I've developed even more advanced methods for using these defaults.

The first thing I've done is seperated the update code from the loading code, so it is it's own function. Another change I've made is that it can now work with tables within tables. The following can work with up to 3 levels of tables within your defaults. (Main level, 1 subtable, and a subtable within that.)

You will also notice that if the version you are upgrading from is below or equal to version 1.2, then an error message will be displayed using a custom message display function. (Which I won't get into here.) This is useful if you've made major database changes and don't feel like making an adaptor for the settings. A common use of this would be if you had a lot of settings, but decided to move them into a subtable. This would ensure the old settings were erased. This functionality should be used sparingly.

 function ThisAddon_OptionUpdate()
  local temp = ThisAddon_Defaults["Options"];
  if (ThisAddon_Settings["Version"]) and (ThisAddon_Settings["Version"] <= "1.2") then
   ThisAddon_Error_Msg("Your Database is Severely out of date. Some settings may not have carried over.");
  else
   for k,v in pairs(ThisAddon_Settings) do
    if (type(ThisAddon_Settings[k]) == "table") then
     for k2,v2 in pairs(ThisAddon_Settings[k]) do
      if (type(ThisAddon_Settings[k][k2]) == "table") then
       for k3,v3 in pairs(ThisAddon_Settings[k][k2]) do
        if (ThisAddon_Settings[k][k2][k3]) then
         temp[k][k2][k3] = v3;
        end
       end
      else
       if (ThisAddon_Settings[k][k2]) then
        temp[k][k2] = v2;
       end
      end
     end
    else
     if (ThisAddon_Settings[k]) then
      temp[k] = v;
     end
    end
   end
  end
  temp["Version"] = ThisAddon_Version;
  ThisAddon_Settings = {};
  ThisAddon_Settings = temp;
 end

Now let's go through this;

*The function's name.
** Copy the new defaults into a temp variable.
** Here is the detection of an out-of-date database that can't be updated like normal. Will only fire if it detects an old version.
*** What to do if it's out of date. (Send an error message so they know!)
** Otherwise...
*** For every variable in your current settings...
**** If it's a table...
***** Now we run through the subtable.
****** If it's a table...
******* You get the idea. (This function is repeated for the 2nd subtable.)
****** If it's not a table...
******* If the setting exists...
******** Update it!
***** End subtable.
**** If it's not a table...
***** If the setting exists...
****** Update it!
** Update the temp var's Version number.
** Delete all the old settings. Technically, we shouldn't have to do with our next command, but this ensures that the old settings are deleted first.
** Copy the temp variable into our settings.
* End function

That's the basics of this new setting. The best thing is, now in our Post-Load function, instead of writing all that out, we just call:
 if (not ThisAddon_Settings["Version"]) or (ThisAddon_Settings["Version"] < ThisAddon_Version) then
  ThisAddon_OptionUpdate();
 end

Now you can do even more with defaults! If you come up with something new and original, put it on this HowTo's Discussion page! I'd love to see how people use this!

[[Category:HOWTOs|Create Defaults]]