Overview

This describes the mechanism used to sync preferences across devices/surfaces.

It it currently leveraged by the builder to sync the list of search libraries across devices (if you defined your search libraries on remix-dev, you will get the same list on the desktop, etc…)

Structure / Terminology

• a pref: a simple name/value pair (the name could be namespaced if needed)
  • ex: "name": "john", "address.mailing.city": "san francisco"
• prefs: a set of prefs. Prefs will be kept as a hashmap, for instance:

{
	"name": "john", 
	"address.mailing.city": "san francisco",
}

• the prefs for a user are assembled as a combination of 3 prefs (assembled in this exact order):

  • system prefs (defined as constants at compile time). This simply has a the default remix_labs catalog.

    {
    	"builder.search.libs": "# the main remix library\\nhttps://agt.remixlabs.com/ws/remix_labs",
    	"builder.plugins.show_system_plugins": true
    } 
    

  • default prefs (defined as a record for the workspace). An administrator can change this (dynamically).

  • user prefs (define as a record for a given user). A user can change his own prefs (dynamically)

  Each pref takes precedences over the previous value. This means that if the default prefs redefine a value defined in the system prefs, the value from the default prefs is returned. And the same goes for the user prefs.

Builder Prefs

The builder leverages synced prefs by using 2 fields:

• builder.search.libs: catalog list used by L1/L2 search. It is stored as a single string, with one catalog entry per line.
• builder.plugins.show_system_plugins: if true, the system plugins are shown in the builder (L0/L1/L2)

If you want to change the default catalogs for all users in the org, simply set builder.search.libs in the default prefs (with the agent set_default_prefs). Each user will get these by default instead of the system one. And a given user might also want to override this and define its own builder.search.libs.

Agents

Interacting with the prefs is done via agents of the _rmx_prefs app, deployed in the main workspace of a user (the workpace of the user org)

• get_prefs : retrieves the prefs for the current user (a union of system + default + user prefs)
  • input: <nothing>
  • output:
    • prefs: hashmap: the prefs for the user
    • user: string, the user email
• set_prefs: set the prefs for the current user
  • input:
    • prefs: hashmap: the prefs to merged with the existing user prefs
      • the prefs are merged, meaning you don’t need to pass the entire set of existing prefs every time you want to set one or two prefs (so if there was already 2 prefs name and address.mailing.city, passing an object with 2 new prefs address.mailing.zipcode and address.mailing.street will result in 4 prefs)
      • you can delete an existing pref by passing a value of null
  • output:
    • prefs: hashmap: the prefs for the current user after the changes (a union of system + default + user prefs)
    • user: string, the user email