{"id":3785,"date":"2011-12-08T21:48:38","date_gmt":"2011-12-09T05:48:38","guid":{"rendered":"http:\/\/blog.mozilla.org\/addons\/?p=3785"},"modified":"2011-12-08T21:49:05","modified_gmt":"2011-12-09T05:49:05","slug":"just-landed-simple-prefs-api","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/","title":{"rendered":"Just Landed: Simple Prefs API"},"content":{"rendered":"<p>On November 28, Myk Melez closed <a href=\"https:\/\/github.com\/mozilla\/addon-sdk\/pull\/270\" target=\"_blank\">pull request 270<\/a>, which added the new &#8216;simple-prefs&#8217; module to the Addon SDK. This addition to the SDK&#8217;s addon-kit apis is special for a couple of reasons:<\/p>\n<ul>\n<li>The ability to add a simple preferences panel to an SDK-based add-on has been a major gap in functionality in the SDK. We&#8217;re very happy to be moving forward adding features like this.<\/li>\n<li>This code was contributed entirely from the community, in particular community contributors <a href=\"https:\/\/github.com\/peregrinogris\" target=\"_blank\">Hern\u00e1n Colmeiro<\/a> and <a href=\"https:\/\/github.com\/erikvold\/\" target=\"_blank\">Erik Vold<\/a>.<\/li>\n<\/ul>\n<p><!--more--><\/p>\n<h3>How to get it<\/h3>\n<p>As this API has not been included in an SDK release, it is not yet available in the online builder, so the only way you can try this out currently is by installing the SDK locally. The simple-prefs api is currently available by checking out the &#8216;master&#8217; branch of the addon-sdk repository:<\/p>\n<pre lang=\"bash\">git clone git:\/\/github.com\/mozilla\/addon-sdk.git<\/pre>\n<p>By default you should have the &#8216;master&#8217; branch. Alternatively you can just download a zip archive of the current master: <\/p>\n<p><a href=\"https:\/\/github.com\/mozilla\/addon-sdk\/zipball\/master\">https:\/\/github.com\/mozilla\/addon-sdk\/zipball\/master<\/a><\/p>\n<p>If you are not familar with how to work with the SDK, please see the <a href=\"https:\/\/addons.mozilla.org\/en-US\/developers\/docs\/sdk\/1.3\/dev-guide\/addon-development\/installation.html\" target=\"_blank\">installation documentation<\/a>.<\/p>\n<h3>How to use it<\/h3>\n<p>Preference fields are defined in an add-on&#8217;s package.json file as an array called &#8216;preferences&#8217; that contains objects that contain four allowed values: type, name, value and title. The api currently only supports three types: integer, bool and string. Here is an example package.json file that defines three prefrence fields, one for each type supported by the SDK:<\/p>\n<pre lang=\"javascript\">{\r\n    \"name\": \"pref-example\",\r\n    \"license\": \"MPL 1.1\/GPL 2.0\/LGPL 2.1\",\r\n    \"author\": \"Jeff Griffiths ( jeff@canuckistani.ca )\",\r\n    \"version\": \"0.1\",\r\n    \"fullName\": \"pref-example\",\r\n    \"id\": \"jid1-NYHGYVhOiA8sWA\",\r\n    \"description\": \"a basic add-on\",\r\n    \"preferences\": [\r\n        {\r\n            \"type\": \"string\",\r\n            \"name\": \"stringPreference\",\r\n            \"value\": \"this is the default string value\",\r\n            \"title\": \"String Preference\"\r\n        },\r\n        {\r\n            \"type\": \"bool\",\r\n            \"name\": \"boolPreference\",\r\n            \"value\": true,\r\n            \"title\": \"Boolean Pref\" \r\n        },\r\n        {\r\n            \"type\": \"integer\",\r\n            \"name\": \"intPreference\",\r\n            \"value\": 42,\r\n            \"title\": \"Integer Pref\" \r\n        }\r\n    ]\r\n}<\/pre>\n<p>In your JavaScript code, simply require simple-prefs as you would any other api-kit module:<\/p>\n<pre lang=\"javascript\">\r\nvar prefSet = require(\"simple-prefs\");\r\n<\/pre>\n<p>You can access any of your preferences as a property of prefSet.prefs by name:<\/p>\n<pre lang=\"javascript\">\r\nvar strPref = prefSet.prefs.stringPreference;\r\n<\/pre>\n<p>You can also assign handlers to run whenever a preference is changed:<\/p>\n<pre lang=\"javascript\">\r\n\/\/ define a generic prefs change callback\r\nfunction onPrefChange(prefName) {\r\n    console.log(\"The \" + prefName + \r\n        \" preference changed, current value is: \" + \r\n        prefSet.prefs[prefName]\r\n    );\r\n}\r\n\r\nprefSet.on(\"stringPreference\", onPrefChange);\r\n<\/pre>\n<p>The preferences are exposed to the user via the about:addons page by clicking the &#8216;preferences&#8217; button on the Addons page:<\/p>\n<p><img decoding=\"async\" loading=\"lazy\" src=\"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg\" alt=\"\" title=\"prefbutton\" width=\"585\" height=\"62\" class=\"alignnone size-full wp-image-3803\" srcset=\"https:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg 585w, https:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton-300x31.jpg 300w\" sizes=\"(max-width: 585px) 100vw, 585px\" \/><\/p>\n<p>Your preference settings are each displayed on the preferences panel for your add-on with type-sensitive entry fields:<\/p>\n<p><img decoding=\"async\" loading=\"lazy\" src=\"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefpanel.png\" alt=\"\" title=\"prefpanel\" width=\"556\" height=\"410\" class=\"alignnone size-full wp-image-3804\" srcset=\"https:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefpanel.png 556w, https:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefpanel-300x221.png 300w\" sizes=\"(max-width: 556px) 100vw, 556px\" \/><\/p>\n<p>I&#8217;ve provided a <em>very<\/em> simple working example on github:<\/p>\n<p><a href=\"https:\/\/github.com\/canuckistani\/sdk-simple-prefs\" target=\"_blank\">https:\/\/github.com\/canuckistani\/sdk-simple-prefs<\/a><\/p>\n<p>Remember, you can only use this code with the current master branch of the SDK! Make sure you&#8217;ve installed this version before you start hacking!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>On November 28, Myk Melez closed pull request 270, which added the new &#8216;simple-prefs&#8217; module to the Addon SDK. This addition to the SDK&#8217;s addon-kit apis is special for a &hellip; <a class=\"go\" href=\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/\">Read more<\/a><\/p>\n","protected":false},"author":316,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[44,588,742],"tags":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v22.5 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Just Landed: Simple Prefs API - Mozilla Add-ons Community Blog<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Jeff Griffiths\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"2 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/\",\"url\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/\",\"name\":\"Just Landed: Simple Prefs API - Mozilla Add-ons Community Blog\",\"isPartOf\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage\"},\"thumbnailUrl\":\"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg\",\"datePublished\":\"2011-12-09T05:48:38+00:00\",\"dateModified\":\"2011-12-09T05:49:05+00:00\",\"author\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/e2f4c71eb45392ea29162432c3f1d433\"},\"breadcrumb\":{\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage\",\"url\":\"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg\",\"contentUrl\":\"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/blog.mozilla.org\/addons\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Just Landed: Simple Prefs API\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#website\",\"url\":\"https:\/\/blog.mozilla.org\/addons\/\",\"name\":\"Mozilla Add-ons Community Blog\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/blog.mozilla.org\/addons\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/e2f4c71eb45392ea29162432c3f1d433\",\"name\":\"Jeff Griffiths\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/b07ae75dd1a5414bf30d7f773ccfc894?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/b07ae75dd1a5414bf30d7f773ccfc894?s=96&d=mm&r=g\",\"caption\":\"Jeff Griffiths\"},\"description\":\"Jeff is Product Manager for the Firefox Developer Tools and occasional Open Web hacker, based in Vancouver, BC.\",\"sameAs\":[\"http:\/\/canuckistani.ca\/\",\"https:\/\/x.com\/canuckistani\"],\"url\":\"https:\/\/blog.mozilla.org\/addons\/author\/jgriffithsmozilla-com\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Just Landed: Simple Prefs API - Mozilla Add-ons Community Blog","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/","twitter_misc":{"Written by":"Jeff Griffiths","Est. reading time":"2 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/","url":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/","name":"Just Landed: Simple Prefs API - Mozilla Add-ons Community Blog","isPartOf":{"@id":"https:\/\/blog.mozilla.org\/addons\/#website"},"primaryImageOfPage":{"@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage"},"image":{"@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage"},"thumbnailUrl":"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg","datePublished":"2011-12-09T05:48:38+00:00","dateModified":"2011-12-09T05:49:05+00:00","author":{"@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/e2f4c71eb45392ea29162432c3f1d433"},"breadcrumb":{"@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#primaryimage","url":"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg","contentUrl":"http:\/\/blog.mozilla.org\/addons\/files\/2011\/12\/prefbutton.jpg"},{"@type":"BreadcrumbList","@id":"https:\/\/blog.mozilla.org\/addons\/2011\/12\/08\/just-landed-simple-prefs-api\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/blog.mozilla.org\/addons\/"},{"@type":"ListItem","position":2,"name":"Just Landed: Simple Prefs API"}]},{"@type":"WebSite","@id":"https:\/\/blog.mozilla.org\/addons\/#website","url":"https:\/\/blog.mozilla.org\/addons\/","name":"Mozilla Add-ons Community Blog","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/blog.mozilla.org\/addons\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/e2f4c71eb45392ea29162432c3f1d433","name":"Jeff Griffiths","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.mozilla.org\/addons\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/b07ae75dd1a5414bf30d7f773ccfc894?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/b07ae75dd1a5414bf30d7f773ccfc894?s=96&d=mm&r=g","caption":"Jeff Griffiths"},"description":"Jeff is Product Manager for the Firefox Developer Tools and occasional Open Web hacker, based in Vancouver, BC.","sameAs":["http:\/\/canuckistani.ca\/","https:\/\/x.com\/canuckistani"],"url":"https:\/\/blog.mozilla.org\/addons\/author\/jgriffithsmozilla-com\/"}]}},"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts\/3785"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/users\/316"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/comments?post=3785"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/posts\/3785\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/media?parent=3785"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/categories?post=3785"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/addons\/wp-json\/wp\/v2\/tags?post=3785"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}