Firefox Extensions - Working with Settings

Today I would like to talk about how you can implement a configuration system for your extension. Starting from defining options and ending with the addition to your expansion of the ability to change settings using the dialog boxes you created.

The first article, I hope from the future cycle of my articles, can be found here .


The system settings extensions in Firefox has a very simple structure. Type in the address bar about: config, and you will see all the settings not only of the browser itself, but of all installed extensions. Here you can change them to fit your needs.
')
In order for your extension to have its own set of settings, you need to create a directory defaults/preferences (if it has not been previously created) and place there a .js-file with settings. Here is an example of such a file.

1. pref ( "extensions.sample.username" , "Joe" );
2. pref ( "extensions.sample.sort" , 2);
3. pref ( "extensions.sample.showAdvanced" , true );

* This source code was highlighted with Source Code Highlighter .

Thus, we have created a set of default settings. Restart Firefox. Now you can view and change the values ​​of these parameters on the about:config page.

Read settings

The following code snippet shows how to access the settings:

1. init: function ()
2. {
3. this .prefs = Components.classes [ "@ mozilla.org / preferences-service; 1" ]
4. .getService (Components.interfaces.nsIPrefService)
5. .getBranch ( "extensions.sample." );
6. this .prefs.QueryInterface (Components.interfaces.nsIPrefBranch2);
7. this .prefs.addObserver ( "" , this , false );
8. }

* This source code was highlighted with Source Code Highlighter .

The last line of the init function indicates that all events related to changing settings should be sent to our object.

So now the variable this.prefs refers to an object with the nsIPrefBranch interface. Read the values ​​of any option as follows:

1. this .prefs.getCharPref ( "username" );

* This source code was highlighted with Source Code Highlighter .

Because When initializing the settings object, we specified extensions.sample. as the namespace extensions.sample. , then the option extensions.sample.username we created earlier will be read.

In addition, the methods provided by the nsIPrefBranch interface can be found here .

Change settings

To change the settings for your extension, you can create a dialog box in which you can display the options you need, and the user can change their values ​​to the ones he needs.


Create an options.xul file in the chrome/content directory and add the following content to it:

1. <? xml version = "1.0" ? >
2. <? xml-stylesheet href = "chrome: // global / skin /" type = "text / css" ? >
3. < prefwindow id = "test-prefs"
4. title = "Test options"
5. xmlns = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" >
6. < prefpane id = "test-pane" label = "Test Settings" >
7. < preferences >
8. < preference id = "pref_username" name = "extensions.sample.username" type = "string" />
9. </ preferences >
10. < hbox align = "center" >
11. < label control = "username" value = "Username:" />
12. < textbox preference = "pref_username" id = "username" maxlength = "24" />
13. </ hbox >
14. </ prefpane >
15. </ prefwindow >

* This source code was highlighted with Source Code Highlighter .

Now in order:

• <prefpane> is a container for dialog box controls, also this element contains links to component settings.
  
• <preferences> - contains links to options of your component.
  
• <preference> - link to the option. The name parameter specifies the name of the option, the type parameter specifies the type of this option ( string , int or boolean ), the id parameter specifies the setting identifier inside the dialog box, by which the controls themselves will read and write the setting values ​​(look at the textbox preference attribute)
  
• This is followed by the dialog box controls with which you can change the options for your extension.
  

If you created this file for an already installed extension, then you need to delete and reinstall this extension in order for the "Settings" button to become available.


And the last thing I wanted to talk about is the reaction of the extension to any changes in its settings. At the very beginning, we indicated that we want to process all messages related to changing settings. Here is an example of a function that can handle it:

1. observe: function (subject, topic, data)
2. {
3. if (topic! = "nsPref: changed" )
4. {
5. return ;
6. }
8. switch (data)
9. {
10. case "username" :
11. alert ( this .getUserName ());
12. break ;
13. }
14. }

* This source code was highlighted with Source Code Highlighter .

Briefly about the input parameters:

1. subject - a link to the changed object or event (more details here )
   
2. topic - indicates the type of event, in this case we are interested in "nsPref: changed"
   
3. data is the data transmitted along with the event, in our case it will be the name of the option that was changed
   

This is a necessary minimum for working with extensions settings. You can find out more about this in the links I provided or on the developer.mozilla.org website.

Sample sources can be found here .