settings.js API

Using Node.js Modules in settings.js

From within the settings.js script you can require any Node.js module that is a dependency in Somiibo.

Visit somiibo://developer and go to the "Using Node.js Modules" tab to see the currently supported modules.

settings.html Skeleton File

        
          let settings;
async function main(mod) {
  settings = mod;

  // Build your settings logic here

}

module.exports = main;

        
      

The settings library is the first argument passed to the exported function, so as seen here, the variable settings is used to access the settings.js API.

API

Discover the settings.js API

Methods

Flow controls the initialization and looping of the module.

somiibo.getAll()

• returns <Object> The current settings as an object

Get the user's current settings as an object where each key is the setting name and the value is the setting value.

        
          console.log('The current settings are', settings.getAll());
        
      

somiibo.getUser()

• returns <Object> The current user as an object with the following keys
• auth <Object>
• uid <string> The user's UID, a unique identifier for each user
• plan <Object>
• id <string> The plan id which can be either basic or premium
• roles <Object>
• betaTester <boolean> true if the user is a beta tester
• developer <boolean> true if the user is a developer
• admin <boolean> true if the user is an administrator

Get the user's current settings as an object where each key is the setting name and the value is the setting value.

        
          console.log('The current user is', settings.getUser());
        
      

somiibo.getTab()

• returns <Object> The current tab as an object with the following keys
• proxy <boolean> Whether or not the tab has a proxy
• session <string> The ID of the current Session
• userAgent <string> The user agent of the tab

Get information about the current tab such as its proxy, session ID, and the userAgent

        
          console.log('The current tab is', settings.getTab());
        
      

Events

event: 'change'

• event <Event> The generic event
• name <string> The name of the changed setting
• value <any> The value of the changed setting
• target <ElementHandle> The element that the edit occurred on

Emitted when the module.js script encounters a fatal change. The default behavior is to stop the module and display an change to the user but this can be prevented with event.preventDefault(). Usually (but not always), navigation changes can be recovered from and calling event.preventDefault() is advised.

        
          settings.on('change', function (event, name, value, target) {
            console.log('change event:', event, name, value, target);
          })
        
      

event: 'submit'

• event <Event> The generic event
• data <Object> The settings as an object

Emitted when the settings are saved by the user. Any changes made to the data object will overwrite the user's settings.

        
          settings.on('submit', function (event, data) {
            // Here it is possible to modify the data before it is saved
            data.mySetting = 'new value';
            console.log('submit event:', event, data);
          })
        
      

The default behavior of the submit event is to continue with the save but you can prevent this behavior by returning a custom object like so:

        
          settings.on('submit', function (event, data) {
            // Block the default behavior of saving the settings and will instead show an error to the user
            return {
              error: new Error('This field has an error!'),
              input: 'fieldName' // Supplying the name of a setting will automatically highlight it for the user
            }
          })