Last Updated: 2018-02-01
SetupTools started off large and will only get larger. This document outlines all the methods and keys found in SetupTools in an effort to make understanding it easier on future development and new devs.
For the method reference, arguments contained in brackets [...] are optional.
Muledump Accounts Configuration
These are keys which report state information about SetupTools current runtime. All values are boolean.
Various assistant states.
Whether or not the control key is being pressed.
Whether or not SetupTools has entered an error state.
Whether or not the user has been detected as having or not having the Muledump CORS Adapter.
Whether or not the user is detected as being a first time user.
Whether or not the user is running local or hosted Muledump
Whether or not SetupTools has successfully loaded client configuration.
Whether or not any notifier is running.
Whether or not the system has detected we're in preview mode.
[default: string|jcmd]
An identifier placed in certain local storage keys to identify the specific Muledump fork generating the data.
[default: string|empty]
Used for forcing redirection within code. For example, setuptools.storage.test() listens for devForcePoint='storage-test' and will always force a test failure if present.
Basically, if you want to test alternative paths such as errors and fallbacks, this will let you simulate those events.
[default: string|#ae0000]
Hex color used for error texts outside of css
[default: string|empty]
The Google Analytics site ID.
[default: string|analytics]
The function name to assign Google Analytics.
[default: number|300000]
The analytics background ping rate in milliseconds.
[default: string|jakcodex.github.io]
Hostname for Muledump Online
[default: string|muledump:setuptools:]
Prefix used for all local storage objects accessed in SetupTools
[default: number|1000]
Time in milliseconds to run the background task.
[default: number|5000]
Time in milliseconds to run the background task health checker.
[default: object|{action: 'query', ignore_cache: false, cache_only: false]
The base config object to use when creating MuleQueue requests.
[default: number|300000]
Time in milliseconds that a rate limit lasts for.
[default: number|86400000]
Time in milliseconds after which mulequeue cache data is considered stale.
[default: object]
An object for storing Muledump-specific feature server configuration data.
This currently consists of a single key. setuptools.config.muledump.corsAttempts
which determines how many failed preflight requests may occur before triggering CORS Assistant.
[default: number|60]
The number of seconds the notices monitor will run before exiting.
[default: string|https://github.com/jakcodex/muledump/wiki/One-Click-Login]
URL to the One-click login wiki page.
[default: number|3000]
Time in milliseconds after which to consider load time a performance issue.
[default: number|4]
Minimum number of recommended CPU cores.
[default: string|https://github.com/jakcodex/muledump/wiki/Rate-Limiting]
URL to the Rate Limiting information wiki page.
A list of RegExp objects used throughout the program
[default: number|3]
How many seconds to wait before triggering automatic window reloads
[default: number|0]
Width of each item in the totals block.
[default: number|600000]
The length of time in milliseconds to cache Github Tags API response data.
[default: string|https://api.github.com/repos/jakcodex/muledump/tags]
The Github API URL for accessing Muledump repo tags.
[default: string|https://jakcodex.github.io/muledump]
URL for Muledump Online
[default: number|1]
Whether or not the account assistant is enabled.
[default: number|0]
How many seconds to delay between account loads with Deca. Supports two automatic modes which set a time based on number of accounts:
Seconds set to 0 - Targets 25 requests per 10 minutes on the high end.
Seconds set to -1 - Targets 35 requests per 10 minutes on the high end.
[default: number|5]
How many accounts to display per page during pagination.
[default: number|1]
Whether or not to alert on new versions (0=off, 1=releases, 2=all versions).
[default: number|1]
Whether or not to show full (1), reduced (0), or minimal (-1) animations where applicable.
[default: boolean|true]
Enable creation of an automatic backup if more than 24 hours has past since the last backup by any method.
[default: number|0]
How old cache data can be before it is considered stale (only applies to accounts with autoReload=true).
[default: number|14]
How many days between backup assistant alerts.
[default: number|1]
Whether or not the CORS assistant is enabled.
[default: boolean|false]
Whether or not to log debugging information to the browser console
[default: boolean|false]
Whether or not SetupTools is enabled
[default: boolean|false]
Whether or not Usage Analytics is enabled (Muledump Online only). If disabled, all enabled GA settings are disabled at runtime.
[default: boolean|true]
Whether or not to participate in Usage Analytics error reporting.
[default: boolean|true]
Whether or not to participate in Usage Analytics background ping.
[default: boolean|true]
Whether or not to participate in Usage Analytics feature usage reporting.
[default: boolean|true]
Whether or not to participate in Usage Analytics totals usage reporting.
[default: number|1]
How to merge accounts configured in the groups manager (0=off, 1=parallel, 2=serial).
[default: number|1000]
How long a long left click must last to register as a longpress.
[default: number|10]
Number of non-protected backups to keep in local storage before automatically removing old backups
[default: number|2]
Position of the menu between left, center, and right.
[default: number|180]
Maximum amount of time in seconds the background task can run without pinging before being considered stale (presently not user changeable).
[default: number|1]
Maximum number of concurrent requests to run in MuleQueue (presently not user changeable).
[default: number|100]
Maximum number of MuleQueue history records to keep.
[default: number|0]
Whether or not one-click login is enabled
[default: number|0]
Whether or not to disable Masonry page layout
[default: number|2]
Whether or not to display the full Page Search bar (2), expanding bar (1), or no bar (0).
[default: boolean|true]
Whether or not to prevent browser automatic, no-confirm downloads (dangerous given our usage; sensitive files don't belong in Downloads)
[default: number|7]
Number of items to display in a single row in Muledump (combo of chars+accounts)
[default: number|0]
Whether to use the testing server instead of production
[default: number|500]
Time to wait in milliseconds before displaying a tooltip on hover.
[default: number|0]
Number of items to display per row in totals. A value of 0 will default to whole screen usable width.
SetupTools replaces the need for an accounts.js file by importing that data and restructuring it. Muledump is still provided the original structure for the accounts
variable by means of setuptools.app.config.convert()
.
var accounts = {
'email@test.com': 'pass',
'email2@test2.com': 'pass2'
}
setuptools.data.accounts = {
meta: {
created: <timestamp>,
modified: <timestamp>,
format: 1,
version: <modifiycount>
},
accounts: {
'email@test.com': {
password: 'pass',
enabled: true,
loginOnly: false,
cacheEnabled: true,
autoReload: false
},
'email2@test2.com': {
password: 'pass2',
enabled: true,
loginOnly: false,
cacheEnabled: true,
autoReload: false
}
}
}
[default: boolean|true]
Whether or not the specified account is enabled.
[default: boolean|false]
Accounts marked as login only will connect to Deca to reload account data but will not display in Muledump.
[default: boolean|true]
Disabling the data cache forces an account to reload its account data every time Muledump is ran.
[default: boolean|false]
Accounts marked as auto reload will reload account data whose cache is determined to be too old.
Converting from format 0 to format 1 should only occur during an accounts.js import when creating a fresh format 1 configuration.
Going the other direction happens a lot as it's the format in use by Muledump.
setuptools.data.accounts = setuptools.app.config.convert(accounts, 1);
var accounts = setuptools.app.config.convert(setuptools.data.accounts, 0);
Reference to window.options
A clone of setuptools.data.config default values and used in restoring default settings
Begins initialization of SetupTools by determining eligibility to run.
- Checks for existence of accounts.js file
- Tests for local storage support
- Checks new user state
- When no config is found and accounts.js is present, SetupTools bypasses and Muledump runs like normal
- When no config is found and accounts.js is missing, SetupTools enters first run state by calling setuptools.app.index()
- When no config is found and the storage test fails, an error message is displayed
- When a configuration is found it is loaded on top of the default configuration and setuptools.app.upgrade.seek() scans for any necessary data upgrades
If SetupTools is enabled and loaded, this updates the accounts variable with currently enabled accounts; otherwise, it loads from accounts.js.
Mules are then loaded into the mule variable if they don't already exist. Disabled accounts are deleted from the variable.
Stores the value to local storage using setuptools.config.keyPrefix+key for the key name.
If skipPrefix=true then just key is used for the key name.
Reads the value from local storage using setuptools.config.keyPrefix+key for the key name.
If skipPrefix=true then just key is used for the key name.
Deletes the key from local storage using setuptools.config.keyPrefix
+key
for the key name.
Tests whether or not local storage works on the browser.
This utility uses Featherlight to create the lightboxes in use within SetupTools.
setuptools.lightbox.create(html data [, object config, string title='Muledump Setup'])
Creates a Featherlight lightbox with the supplied HTML data with the specified title and optional configuration.
Configuration object options can be seen in the Featherlight configuration documentation.
setuptools.lightbox.override(string targetPage, string targetAction [, function callback, object data])
Overrides the targetAction of other pages by changing the callback and/or data object.
For example, say you're sending a user to setuptools.app.accounts.manager() from setuptools.app.myspace.method(). By default, setuptools.app.accounts.manager() will include a goback link to setuptools.app.index(). You can override this behavior with:
setuptools.lightbox.build('myspace-method', ' \
Hello! This is my page. \
Go to <a href="#" class="setuptools link accountsmanager">Accounts Manager</a> \
');
setuptools.lightbox.settitle('myspace-method', 'My Method Title');
setuptools.lightbox.display('myspace-method');
setuptools.lightbox.override('accounts-manager', 'goback', setuptools.app.myspace.method);
$('.setuptools.link.accountsmanager').click(setuptools.app.accounts.manager);
The above example creates a sample page with a link to another page and an override for the other page.
Adds the provided html to the page being built. Build data is stored in an array and is joined on display after being processed.
Processes and removes all special build data for the specified page (settitle, goback, etc), builds the HTML response data, and sends it to setuptools.lightbox.create().
This method is intended to be bound to a link to the Github Pages hostname. It is primarily bound thru the drawhelp button, but it can be used on custom links as well.
Makes an ajax call to the link href and builds a lightbox with the response data. Example:
setuptools.lightbox.build('myspace-method', ' \
Hello! This is my page. \
Go to <a href="https://jakcodex.github.io/muledump/docs/some/doc" \
class="setuptools link somehelpdoc noclose">Help Docs</a> for more info \
');
setuptools.lightbox.settitle('myspace-method', 'My Method Title');
setuptools.lightbox.display('myspace-method');
$('.setuptools.link.somehelpdoc').click(function(e) { setuptools.lightbox.ajax(e, {title: 'My help title'}, this); });
This creates a lightbox with a link in its message. When the link is clicked the Ajax response data is processed for links and displayed in a lightbox. The class noclose prevents SetupTools from erasing the previous page so when the user closes the help doc they are returned to the original page.
Erases the build data for the specified page.
Manually closes a lightbox for the specified page.
Adds to the page build data a drawhelp object with the format:
var object = {
iam: 'drawhelp',
link: link,
title: title
}
Changes the default page title for the specified page build
Adds to the page build data a goBack object with the format:
var object = {
iam: 'goback',
callback: callback,
text1: text1,
text2: text2
}
Creates and displays an error page with the specified information. Terminates program execution by throwing a new error.
setuptools.lightbox.menu.context.create(string title, object position, object options[, jQuery self])
Creates and displays a context menu at the specified position (pos.left, pos.top).
The following example is taken from Groups Manager group menu controller:
// selection menu
$('.setuptools.div.groupControls div.groupSelect').click(function (e) {
var self = this;
// deselect other menu options
$('.setuptools.div.groupControls div:not(.groupSelect)').each(function(index, element) {
$(element).removeClass('selected');
});
// display the menu
if ( $('.setuptools.div.groupControls div.groupSelect').hasClass('selected') === false ) {
// base info
$(self).addClass('selected');
var position = $('.setuptools.div.groupList div.dragbox div.cell:first-child').offset();
var options = [
{
class: 'selectAll',
name: 'Select All',
callback: SelectAll
},
{
class: 'selectNone',
name: 'Deselect All',
callback: SelectNone
},
{
class: 'selectEnabled',
name: 'Select Enabled Groups',
callback: SelectAllEnabled
},
{
class: 'selectDisabled',
name: 'Select Disabled Groups',
callback: SelectAllDisabled
}
];
setuptools.lightbox.menu.context.create('Select Menu', position, options, self);
} else {
setuptools.lightbox.menu.context.close(self);
}
});
Clicks to the specified div are captured to toggle the menu on and off. If the menu is presently disabled, setuptools.lightbox.menu.context.create() will be called to create it.
For this context menu, it is supposed to line up with the first div underneath the menu. That position is sent directly to the method.
The options object defines the menu options and what their clicks do. The callback can be a literal callback with no arguments, or you can use function() { ... }
to use local variables in the callback.
Providing the jQuery self argument will deselect the menu icon when the menu is closed.
Binds up and down arrows for menu navigation and enter for menu selection.
Returns true or false for the status of the specified context menu.
Closes any open context menu and will removed selected class from any provided jQuery object.
If keep is true, it will close all menus except the specified menu.
setuptools.lightbox.menu.paginate.create(array PageList, string ActionItem, string ActionContainer, string ActionSelector, function ActionCallback, function ActionContext[, object Modifiers])
Creates and managed a paginated display (think accounts manager or either column in the group editor).
Format A:
var PageList = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 100"];
Format B:
var PageList = [{item: 1}, {item: 2}, {item: 3}, {item: 4}, {item: 5}];
Any constant that might be used in this pagination system (e.g. groupName). This argument belongs in the optional section.
Use "undefined" if none.
Pagination assumes you are attaching to a div with this class (e.g. div.ActionContainer).
Full selector value for the location page updates are stored.
Action to perform when the page needs to be updated. Received arguments: ActionItem, currentPage.
Action to perform after the page HTML has been updated (JQuery bindings, etc).
Modifies aspects of the pagination system.
You can add extra buttons next to the 'Next Page' button:
var Modifiers = {
'pageButtons': ' \
<div \
class="editor control massSwitch noselect" \
title="Mass Switch" \
style="font-weight: normal; font-size: 12px; padding-top: 3px !important;">\
≡\
</div>\
'};
If you PageList is a Format B (see above) you can attach the search feature to specified keys:
var PageList = [
{user: 'blah', someoption: true},
{user: 'ick', someoption: true},
{user: 'oof', someoption: true},
{user: 'doh', someoption: true}
];
var Modifiers = {search: {key: 'user'}};
Locates the specified searchTerm and updates state.currentPage to reflect it. If skip=true it will skip automatically updating the page.
setuptools.lightbox.menu.search.bind(object state[, boolean skip, string altContainer, JQuery altPosition, object altAdjustments, function altBinding, boolean keepName])
Binds the search menu to the state and can be modified in a variety of ways.
Overrides the ActionContainer setting for the page.
Overrides the JQuery selector used to position the menu.
Overrides the bindings to execute after search execution.
Name of the search menu to keep when taking focus.
Resets all or specified pagination data back to a clear state. If reset=true, ActionContainer is reset to page 0.
Locates page of specified searchIndex and updates state.currentPage.
setuptools.lightbox.menu.paginate.pageUpdate(boolean close, function ActionContext, object ActionContextOptions)
Refreshes page bindings after the page has been updated.
If true, any open context menus are closed.
Function or array of functions to execute.
Object passed to ActionContext functions.
Displays a tooltip above the parent element.
var Modifiers = {
classes: 'string', // classes to insert into the tooltip div
heightFrom: 'string' // where to get height data from; options are: tooltip, parent (default: parent)
}
Replaces provided self with supplied string for the specified duration before resetting the label.
Display the introduction page for new users
Display the application index page (or first time user page for new users)
Determine if the user is completely new or not
Reads the location.hash to direct users to specified pages on request.
- about
- accounts
- accounts-export
- accounts-mass
- accounts-massSwitch
- accountsjs
- backups
- backups-create
- backups-restore
- backups-upload
- groups
- groups-create
- groups-select-all
- groups-select-disabled
- groups-select-enabled
- groups-disableAll
- groups-enableAll
- help-cors
- settings
- settings-
- settings-assistants
- settings-setuptools
- settings-system
setuptools.app.ga(string command[, mixed action, mixed value1, mixed value2, mixed value3, mixed value4, mixed value5])
Handles all commands for Usage Analytics. Blocks commands when Usage Analytics is disabled. If command!==init then action is required.
The first value is checked against a list of approved values to sort them into categories that users can enable/disable.
This is a wrapper for the Universal Analytics function.
Provided to users new to Usage Analytics to explain to them what it is and offer them the option to opt-out.
An early prototype for the first time user walk through. A relic of old.
Displays the Accounts Manager page and facilitates all modifications.
Displays a download link for the specified GUID's account data if any exists.
A save confirmation screen shown to first-time users upon finishing setup.
Generates an accounts.js file using setuptools.app.accounts.AccountsJSExport() and provide a download link.
Display a page offering users the choices available for importing an Accounts.js file.
Facilitates importing from an accounts.js detected in the Muledump installation.
Facilitates importing by uploading an accounts.js file to SetupTools.
Displays the Groups Manager page. A string or array of groups provided will be automatically selected. If open=true, the first group is opened in the group editor.
Displays a confirmation page to delete the specified list og groups.
Accepts a JQuery selector of selected groups from the groups list or a comma-separated string of groups.
Displays a page to facilitate copying a group to a new group. Calling with newGroupName will alert the user that the name is a duplicate.
Displays a page to facilitate the renaming of a group. Calling with newGroupName will alert the user that the name is a duplicate.
Displays a page to facilitate the merging of two or more selected groups. Calling with newGroupName will alert the user that the name is a duplicate.
Displays a page to facilitate creating a new group.
Returns a sorted list of group accounts based on the provided list of available accounts.
Display and manage Settings Manager page
Creates and returns a backup that can be optionally protected at creation.
Intended to be bound to links, it will attempt to get the user's attention when they left click on a link they're supposed to right click on.
Converts the supplied accountConfig data between formats 0 or 1. If specified, only accounts of a specific group or all accounts can be returned.
See Muledump Accounts for more information.
Determine of the supplied accountConfig format matches the specified format. Returns true or false.
Determine the format of the supplied accountConfig. Returns 0 or 1. Throws an error if invalid.
Lists all users in the configuration and optionally filters on id (group or guid) and enabled status.
Checks if the supplied user exists in the accounts variable. Returns true or false.
Checks if the supplied user is enabled in the accounts variable. Returns true always for format 0. Returns true or false for format 1.
setuptools.app.config.createUser(string username, string password, boolean enabled, number group, boolean autoReload, string action, number format)
Creates a user user with the supplied username, password, enabled status, group, and autoReload status. Action can either set or return the new user object. Format 0 implies the action is set.
Takes a format 0 accountConfig and creates a format 1 accountConfig from it.
Generates a new accounts.js file from the supplied accountConfig object and SetupTools client configuration data.
Generates and displays an error when the SetupTools client configuration fails to save to local storage.
Saves the current SetupTools client configuration to local storage and increments setuptools.data.accounts.meta.version.
Display the Backup Manager page
Perform the automatic backup policy
Display the backup upload page and optionally specify if it's operating in manual upload mode
setuptools.app.backups.restore(string RestoreMethod, string BackupID, string BackupName [, boolean SaveExisting=false, boolean BadEntriesForce=false, boolean BadSaveForce=false])
Restores a backup to the current configuration.
If RestoreMethod=local then BackupID should be the ID of a backup in local storage.
If RestoreMethod=upload then BackupID is the file contents of the upload.
Display a page to confirm if a user wants to restore a local backup.
Delete the specified backup and display a page showing the results of this task.
Change the protection state of the specified backup.
Display a page with a download link for the specified backup.
Display a page providing the user a form to change a backup's name.
setuptools.app.backups.renameHtml(string page, string BackupID, string BackupDataJSON[, function callback, boolean noclose])
Inserts a backup custom name input to the provided page and returns a context binding. When the form is executed, it will update the backup and any download link filename on display.
Create a backup and display a page with a download link for the new backup.
Returns an array listing all backup metadata found in local storage.
Enforces the maximum backup count by finding all non-protected backups and deleting any whose position is larger than the maximum allowed limit.
Captures clicks on #setup button
Checks if a new Muledump version has been loaded and applies it to the client configuration. Also notifies Muledump Online users of changes.
Performs all SetupTools client configuration upgrades necessary to bring the user up to current configuration format.
If an accounts.js file was successfully loaded into Muledump then the accounts var is cloned here; otherwise, its value is false.
Process a CustomList and validate its char ids against the Mule's char id list.
Displays a page for management custom character sorting lists.