Quantcast
Download
(26 Kb)
Download
Updated: 05/27/19 02:14 PM
Pictures
File Info
Compatibility:
Elsweyr (5.0.5)
Updated:05/27/19 02:14 PM
Created:10/03/18 10:28 PM
Monthly downloads:17,449
Total downloads:37,814
Favorites:74
MD5:
5.0.5
LibSavedVars  Popular! (More than 5000 hits)
Version: 4.2.2
by: silvereyes [More]
A library to manage and migrate to addon settings that support scopes per server, per account and per character, and to allow toggling between scopes on-the-fly.

Should I Use LibSavedVars?

If you answer "yes" to all the below, then LibSavedVars is definitely for you.
  • I am an addon developer
  • I want to add the ability to toggle between server-wide and character-specific saved variables at runtime, without reloading
  • I want to store different settings per megaserver (NA, EU)
  • I want my character-specific settings to survive character name changes.
  • I want to be able to version / upgrade saved vars structure without resetting all existing data while incrementing the standard "version" saved var.
  • I want to do this all in a standardized way without inventing my own custom logic

How Easy Is LibSavedVars to Use?

LibSavedVars is just as easy to use as ZO_SavedVars, just with some additional functionality.

It will be easiest to implement for the following kinds of addons:
  • Addons that don't yet have any saved vars
  • Addons that only have a single saved var table for player settings
  • Addons that have a single saved var for character settings and a single saved var for account-wide settings, and the state for which one is active for a player is stored within the character settings table.

If your addon falls into one of those two categories, migrating to LibSavedVars should only take a few lines of code beyond including the library.

What LibSavedVars Is NOT For
  • Server-Agnostic Saved Vars

    If you don't need to separate out data between NA and EU because the data you are tracking doesn't change (e.g. furniture lists, item links, coordinate positions, etc), then LibSavedVars isn't going to really provide you with much advantage over the normal "Default" account wide ZO_SavedVars functionality.

  • Addons with complex custom logic for managing saved variable scope between servers

    You are certainly free to rework your addon to use LibSavedVars instead, but it's most likely not going to do everything your custom implementation does.

  • Addons with a saved var for character settings and one for account settings, but the state for which one is active is stored within the account settings table.

    I'll probably add a function in the future to enable account-wide settings on all characters with a simple function call, but it will always retain the ability to disable account-wide settings for an individual character while having them enabled for others.

    LibSavedVars is designed with the idea that account-wide settings represent a player's global default preferences, and character-specific settings act as overrides to those defaults.

    Forcing a player to choose between whether they want global defaults -OR- per-character customization runs counter to the purpose of LibSavedVars.

Planned Features
  • Adding a function and a LibAddonMenu-2.0 button to enable account-wide settings on all characters
  • Utilities and LibAddonMenu-2.0 controls for copying settings between characters, accounts and servers.

Installation
  • Include the unzipped LibSavedVars and LibStub anywhere inside your addon's folder.
  • Add a DependsOn: clause to your addon manifest with LibSavedVars in the list

Setup
  • Create a SavedVariables entry in your addon manifest txt file. If you have any existing SavedVariables entry (e.g. MyAddon_Data) leave it in place.

    MyAddon.txt
    Code:
    ## Title: My Cool Addon
    ## Author: |c99CCEFsilvereyes|r
    ## Description: Example of LibSavedVars usage.
    ## Version: 1.2.0
    ## APIVersion: 100024 100025
    ## DependsOn: LibStub LibSavedVars LibAddonMenu-2.0
    ## SavedVariables: MyAddon_Data
  • Inside an event handler for EVENT_ADD_ON_LOADED in your addon lua code, do one of the following:

    If you want account-wide settings to be the default:

    Lua Code:
    1. MyAddon.settings = LibSavedVars
    2.     :NewAccountWide( "MyAddon_Data", "Account", MyAddon.defaults )
    3.     :AddCharacterSettingsToggle( "MyAddon_Data", "Characters" )
    4.     # Optional, if you have existing data
    5.     :MigrateFromAccountWide( { name = "MyAddon_Data" } )

    If you want character-specific settings to be the default. Note, if you have an old saved var created with ZO_SavedVars:NewCharacterIdSettings(), then you will want to use :MigrateFromCharacterId() instead of :MigrateFromCharacterName().

    Lua Code:
    1. MyAddon.settings = LibSavedVars
    2.     :NewCharacterSettings( "MyAddon_Data", "Characters", MyAddon.defaults )
    3.     :AddAccountWideToggle( "MyAddon_Data", "Account" )
    4.     # Optional, if you have existing data.
    5.     :MigrateFromCharacterName( { name = "MyAddon_Data" } )

Versioning / Upgrading

You can chain the following methods after the :New***Settings(), :Add***Toggle() and:MigrateFrom***() method calls to add versioning. Multiple methods can be called per version.

Lua Code:
  1. --[[
  2.      Upgrades all saved vars tracked by this data instance of a given scope to the given version number.  
  3.      Has no effect on saved vars at or above the given version.
  4.      
  5.      version:         Settings are only upgraded on saved vars below this version number.
  6.      
  7.      scope:           (optional) LIBSAVEDVARS_SCOPE_CHARACTER, LIBSAVEDVARS_SCOPE_ACCOUNT or '*' for all scopes.
  8.                                  Defaults to '*'.
  9.      
  10.      onVersionUpdate: Upgrade script function with the signature function(rawDataTable) end to be run before updating
  11.                       saved vars version.  You can run any settings transforms in here.
  12.   ]]--
  13. function LSV_Data:Version( version, scope, onVersionUpdate )

Lua Code:
  1. --[[
  2.      Removes a list of settings from all saved vars tracked by this data instance of a given scope
  3.      when upgrading to the given version number.  Has no effect on saved vars at or above the given version.
  4.      
  5.      version:          Settings are only removed from saved vars below this version number.
  6.      
  7.      scope:            (optional) LIBSAVEDVARS_SCOPE_CHARACTER, LIBSAVEDVARS_SCOPE_ACCOUNT or '*' for all scopes.
  8.                                   Defaults to '*'.
  9.      
  10.      settingsToRemove: Either a table containing a list of string setting names to remove, or a single string
  11.                        setting name.  If a string is given, then additional strings can be provided as extra parameters.
  12.   ]]--
  13. function LSV_Data:RemoveSettings(version, scope, settingsToRemove, ...)

Lua Code:
  1. --[[
  2.      Changes the names of a list of settings in all saved vars tracked by this data instance of a given scope
  3.      when upgrading to the given version number.  Has no effect on saved vars at or above the given version.
  4.      
  5.      version:   Settings are only renamed on saved vars below this version number.
  6.      
  7.      scope:     (optional) LIBSAVEDVARS_SCOPE_CHARACTER, LIBSAVEDVARS_SCOPE_ACCOUNT or '*' for all scopes.
  8.                            Defaults to '*'.
  9.      
  10.      renameMap: A key-value table containing a mapping of old setting names (keys) to new setting names (values).
  11.      
  12.      callback:   (optional) A function to be called on saved vars values right before they are renamed.
  13.                            Used by RenameSettingsAndInvert().
  14.   ]]--
  15. function LSV_Data:RenameSettings(version, scope, renameMap, callback)

Lua Code:
  1. --[[
  2.      Changes the names of a list of boolean settings and inverts them in all saved vars tracked by this data instance of
  3.      a given scope when upgrading to the given version number.  Has no effect on saved vars at or above the given version.
  4.      
  5.      version:   Settings are only renamed on saved vars below this version number.
  6.      
  7.      scope:     (optional) LIBSAVEDVARS_SCOPE_CHARACTER, LIBSAVEDVARS_SCOPE_ACCOUNT or '*' for all scopes.
  8.                            Defaults to '*'.
  9.      
  10.      renameMap: A key-value table containing a mapping of old setting names (keys) to new setting names (values).
  11.   ]]--
  12. function LSV_Data:RenameSettingsAndInvert(version, scope, renameMap)


Saved Variable Reading and Writing

The following examples assume your saved vars data object is accessable via addon.settings...

Reading a saved var value:
Lua Code:
  1. local setting1 = addon.settings.setting1
  2. -- OR --
  3. local setting1 = addon.settings["setting1"]

Writing a saved var value:
Lua Code:
  1. addon.settings.setting1 = value
  2. -- OR ---
  3. addon.settings["setting1"] = value

Saved Variable Looping

The following examples assume your saved vars data object is accessable via addon.settings...

Looping with pairs:

Note: an additional key called __dataSource is included as the last key with pairs() and next() iterations. This allows you to access the internal dataSource property in Zgoo, but it is something to keep in mind when looping.
Lua Code:
  1. for key, value in pairs(addon.settings) do
  2.     if key ~= "__dataSource" then
  3.         -- do something
  4.         d("key: "..tostring(key)..", value: "..tostring(value))
  5.     end
  6. end

If you don't want to worry about __dataSource, you can loop the raw saved vars table directly:
Lua Code:
  1. local savedVars = addon.settings:GetActiveSavedVars()
  2. local rawSavedVars = LibSavedVars:GetRawDataTable(savedVars)
  3. for key, value in pairs(rawSavedVars) do
  4.     -- do something
  5.     d("key: "..tostring(key)..", value: "..tostring(value))
  6. end

Looping with next:

Lua Code:
  1. local key, value = next(addon.settings, nil)
  2. while key ~= "__dataSource" then
  3.     -- do something
  4.     d("key: "..tostring(key)..", value: "..tostring(value))
  5.     key, value = next(addon.settings, key)
  6. end

Looping with ipairs:

Lua Code:
  1. for index, value in ipairs(addon.settings) do
  2.     -- do something
  3.     d("index: "..tostring(index)..", value: "..tostring(value))
  4. end

Looping with a counter variable:

Note the use of addon.settings:GetLength() instead of #addon.settings. The # operator is not supported, because it cannot be overloaded on tables in Lua 5.1, which is what ESO uses.
Lua Code:
  1. for index, 1, addon.settings:GetLength() do
  2.     -- do something
  3.     d("index: "..tostring(index)..", value: "..tostring(value))
  4. end

LibAddonMenu-2 Integration
LibSavedVars has a helper method to create the "Account-wide Settings" checkbox in your LibAddonMenu-2 panel, localized for English, French, German, Japanese and Russian.

The following example assumes your saved vars data object is accessable via addon.settings...

Lua Code:
  1. -- Setup options panel
  2.     local LAM2 = LibStub("LibAddonMenu-2.0")
  3.  
  4.     local panelData = {
  5.         type = "panel",
  6.         name = addon.title,
  7.         displayName = addon.title,
  8.         author = addon.author,
  9.         version = addon.version,
  10.         slashCommand = "/myaddon",
  11.         registerForRefresh = true,
  12.         registerForDefaults = true,
  13.     }
  14.     LAM2:RegisterAddonPanel(addon.name .. "Options", panelData)
  15.    
  16.     local optionsTable = {
  17.    
  18.         -- Account-wide settings
  19.         addon.settings:GetLibAddonMenuAccountCheckbox(),
  20.        
  21.         -- other LAM2 setting options....
  22.        
  23.     }
  24.  
  25.     LAM2:RegisterOptionControls(addon.name .. "Options", optionsTable)
Version 4.2.2
- Fix for character-scope settings not receiving new default saved vars values when they are only specified at the account-level.

Version 4.2.1
- Fix for error being thrown when LibStub is not installed

Version 4.2.0
- Remove LibStub dependency
- Add new global LibSavedVars for addon authors to use instead of LibStub
- Add ESO - Japanese Localization addon compatibility

Version 4.1.0
- API bump for Update 22 Elsweyr
- Marked as library in manifest with new ## IsLibrary flag.

Version 4.0.1
- Fix load order problem with older versions

Version 4.0.0

- Added saved vars version support that does not wipe all settings during upgrade. See classes/LSV_Data.lua:
* RemoveSettings()
* RenameSettings()
* RenameSettingsAndInvert()
* Version()

- Changed constructor method names and parameters to match ZO_SavedVars exactly. See LibSavedVars.lua:
* NewAccountWide()
* NewCharacterSettings() / NewCharacterIdSettings()

- Added new chainable methods for adding account or character-specific saved vars toggle. See classes/LSV_Data.lua:
* AddAccountWideToggle()
* AddCharacterSettingsToggle()

- Added several new helper methods:
* GetAccountsAndProfiles(savedVarName): Gets a list of tables of the form { account = "@displayName", profile = "NA Megaserver" } for all accounts within the given saved var table.
* GetInfo(savedVars): Gets table containing information about the given saved vars, such as addon name, constructor parameters, raw saved vars table, etc.

- Migration no longer requires creating a ZO_SavedVars instance or leaves any data behind in the legacy saved vars tables. See LibSavedVars.lua:
* MigrateAccountWide()
* MigrateCharacterId()
* MigrateCharacterName()
* MigrateCharacterNameToId()
* MigrateToMegaserverProfiles()

- Deprecated the following methods in LibSavedVars.lua:
* New(). See NewAccountWide() and NewCharacterSettings()
* GetClass(). You can now access classes directly by name (e.g. LSV_Data, LSV_SavedVarsManager)

- Deprecated the following methods in classes\LSV_Data.lua (formerly just Data.lua):
* New(). See NewAccountWide and NewCharacterSettings().
* Migrate(). See MigrateFrom().

- Moved Lua 5.2 pairs(), ipairs() and next() overrides into a separate library, LibLua5.2, to avoid the performance penalty for non-developers or anyone else who doesn't care about iterating saved vars.

- API bump for Update 21 Wrathstone

Version 3.0

- New methods New(), NewAccountWide() and NewCharacterIdSettings() return a data object that can be used as a 1:1 replacement for ZO_SavedVars instances
- New helper method GetRawDataTable() returns the underlying data table for a ZO_SavedVars instance, since ZO_SavedVars:New() just returns an interface, not the data itself.
- Added usage documentation / comments to all public methods in code.

- Data class features:
* data["key"] and data.key operator support
* data["key"] = value and data.key = value operator support
* next(), pairs() and ipairs() support for iterating saved vars
* GetAccountSavedVarsActive() and SetAccountSavedVarsActive(value) methods for toggling the active scope between account and character-specific settings
* Migrate(legacySavedVars, beforeCallback, addon, ...) method to call directly and control when migration is executed.
* GetActiveSavedVars() method to return a reference to the active ZO_SavedVars instance for the currently logged-in character
* GetLength() returns the # length of the data for the active ZO_SavedVars instance for the currently logged-in character
* GetLibAddonMenuAccountCheckbox() replaces the old library-wide method that took an "addon" parameter.

- DEPRECATED METHODS:
* Get() Use data["key"] or data.key of the new data class instead.
* Set(value) Use data["key"] = value or data.key = value of the new data class instead.
* Init() Legacy var migration moved to data class. Use data:Migrate() of the new data class and New(), NewAccountWide() and NewCharacterIdSettings() instead.
* GetLibAddonMenuSetting(addon) Use data:GetLibAddonMenuSetting() of the new data class instead.


Version 2
- Fix bug where account wide settings overwrite character settings when toggling in LAM2

Version 1
- Initial release
Optional Files (0)


Archived Files (8)
File Name
Version
Size
Uploader
Date
4.2.1
26kB
silvereyes
05/25/19 09:35 AM
4.2.0
26kB
silvereyes
05/17/19 08:33 PM
4.1.0
25kB
silvereyes
04/15/19 09:50 PM
4.0.1
25kB
silvereyes
01/28/19 12:59 PM
4.0.0
25kB
silvereyes
01/27/19 02:07 AM
3.0
10kB
silvereyes
10/07/18 11:28 PM
2
5kB
silvereyes
10/04/18 10:27 AM
0.1.0
5kB
silvereyes
10/03/18 10:28 PM


There have been no comments posted to this file.
Be the first to add one.



Category Jump: