Gaia/Settings/docs

Settings

Architecture

Settings app comprises panels for configuring various settings of a device. In general the panels responsible for different settings can work independently. Certain settings may require a group of panels, for example, keyboard settings. The architecture was designed to allow new panels to be created easily without worrying about affecting other panels in the app.

Settings app uses requirejs for module definition and management. All scripts should be defined as AMD modules except for ones that we would like them to be executed upon the starting up where requirejs has not been loaded yet.

A panel can be associated with an AMD module implementing a specified interface. In the module we can then require other necessary modules that are used in the panel.

Start Up Path

To present the visuals as soon as possible, we determine the first panel to be displayed and then append the HTML elements to the DOM tree. At this time the panel is visible but not interactive because the associated modules of the panel are not loaded yet.

There can be a short gap between the panel being presented and all fundamental modules loaded. The time results from loading and initializing requirejs. InitialPanelHandler was introduced to provide basic interactions until the associated modules get loaded. One can provide their own panel handler if the required interactions are beyond what InitialPanelHandler can provide.

window.LaunchContext is constructed during the starting up. The object has a property called pendingTargetPanel that specifies the panel that a user would like to navigate. When the fundamental modules are loaded, the user is brought to the specific panel.

Panel

A panel comprises HTML elements and an optional associated module. This document shows how to create a new panel.

All panels are delay loaded. HTML elements of a panel are created and appended to the DOM tree only when users navigate to the panel. Settings app then loads the associated module of the panel and execute it.

The associated module is usually deriving from SettingsPanel or Panel. Panel provides the basic functionality that allows settings app to control the visibility and life cycle. In addition to that, SettingsPanel further creates bindings between the UI elements and the settings database when the module is being initialized. Details of creating an associated module please refer to here.

Panel Navigation

navigate#SettingsService can be used to navigate to any panel by providing the panel id and the options. During the navigation the following functions on the panel are called in sequence: init, beforeShow, and show. When the panel is being navigated out, beforeHide and hide are called. Note that init is only called once.

Dialog Service

Gaia/Settings/docs/Dialog Service

Dialog Manager

Gaia/Settings/docs/Dialog Manager

Common Patterns

The basic principals are view/logic separation and creating modules that have clear roles and responsibilities. There are two typical roles: view and model.

A view connects the UI elements to a model. It updates the content of the UI elements based on the values of the properties provided by the model. Meanwhile, when users interact with the UI elements, the view is responsible for calling to the corresponding methods of the model.

A model is designed to support views. It is not a passive model that only stores static data but provides methods for manipulating the data and actively reports the changes of the model. A model is not allowed to touch the UI elements directly and should not hold any reference of a view.

This pattern is especially helpful when encountering subtle UX requirements changes because we can change the view easily without modifying the model. Writing unit tests becomes simple when models do not touch the UI elements and it is no longer required to mock the UI elements.

The key is to make a model actively report the status in terms of events and property changes. The following modules can be useful when designing models.

Modules in Settings

Define Modules

Settings modules are AMD modules. In addition to following the syntax of AMD modules, settings app also requires the returning object not to be a constructor function. The reason is that we are then able to expect that all returning functions can be used without the "new" keyword. The other advantage is that the returning functions can be seen as factory methods. A factory method can return different type of objects based on the parameters, which provides more flexibility in some use cases.

Panels

Airplane Mode

Gaia/Settings/docs/airplane mode

Wifi

Gaia/Settings/docs/Wifi

Sim Security

Gaia/Settings/docs/Sim Security

Sim Manager

Gaia/Settings/docs/Sim Manager

Call Settings

Gaia/Settings/docs/Call Settings