Application:Tweaks

Overview
Tweaks is a webOS application that can be used to "tweak" the operation of patches. In this way, a single configurable patch can implement a number of different options, and the user can use the Tweaks app to choose between these options.

Installation
The following information will help you with installing the Tweaks application.

Overview
The Tweaks application requires webOS 2.0.0 or later. The initial set of patches that have tweaks available are only released for webOS 2.1.0 at this time.

In order for Tweaks to properly work, you will need to install it along with at least one patch that has tweaks support. Patches that have Tweaks support will be displayed in Preware with a new category icon, a distinctive green plus sign.

Method
The following method can be used to install Tweaks.

Preware

 * 1) Open Preware
 * 2) Start typing “Tweaks” (no quotes)
 * 3) Tap the Tweaks from the list
 * 4) Tap the Install button

Or


 * 1) Open Preware
 * 2) Tap Available Packages
 * 3) Tap Application > System Utilities > Tweaks
 * 4) Tap the Install button

Usage
The information listed below will help you understand how to use the Tweaks app. The Usage section is broken down into to parts: One section for the End Users on how to access and use the the Tweaks app and the other section is for Patch Developers on how to include Tweaks support into their patches.

End Users
Accessing the Tweaks
 * Open Tweaks by starting it from the Launcher.

Configuring the Tweaks Upon opening Tweaks, the Tweaks service will scan for tweaks that were added, modified and/or removed since the last time the app was accessed.

(Note: If none of the patch categories have a number next to them or are greyed out, that means that there are no patches installed on your device that have support for Tweaks.

Tapping a patch category will display all of the tweaks available to you that fall under that particular category. In each grouping of tweaks, you can modify the settings to your liking. To learn more about what a particular tweak does, tap the blue question mark button in the header of each patch category, then tap on the corresponding tweak to get a brief description of what the tweak does.

Depending on the type of tweak that was changed, you may be prompted by Tweaks to restart Luna for the settings to apply. For other tweaks that didn't prompt for a Luna restart, a simple closing of the affected app (if already open) will make the changes available for the next use of that app.

Overview
The Tweaks app has a node.js service that keeps a db8 database of all these configuration options and generates the Tweaks app user interface automatically based on the info all the currently installed patches provide.

In this way patches can easily add configuration, yet not to clutter the standard webOS system user interface with all the configuration stuff (since usually you want to set it once and then forget about it). If the Tweaks app is not installed then the patches can just use their default values and they will still work.

Sample JSON File
The JSON file to be submitted with your patch needs to contain the configuration options and their default settings and the patch owner id for the patch. The JSON file provides the configuration options and their default values to the Tweaks app for rendering the configuration options GUI.

When submitting your patch to the Patches Portal, you will need to submit the JSON file as well. The JSON file you submit to the Patches Portal will be renamed automatically to .json. The name used for the JSON file is what is used as the owner information during the service call to Tweaks. If no owner information is provided in the json file, the patch id will be used as the owner info. (Note: It is preferred that you put the owner info in the json file.)

Currently the json file supports the following four (5) widgets: Text Field, Toggle Button, List Selector, Integer Picker and File Picker for generating the interface within Tweaks.

For testing purposes, copy the JSON file into (if necessary, create the preferences directory): /media/cryptofs/apps/usr/palm/services/org.webosinternals.tweaks.prefs/preferences

Here is an example JSON file.

[	{		"category": "system", "owner": "patch-owner-id", "prefs": [ { "group": "behavior", "restart": "app", "label": "Label for this item", "help": "Help text for this item", "key": "someUniqueKey", "type": "IntegerPicker", "value": 50, "min": 0, "max": 100 }, {			"group": "behavior", "restart": "luna", "label": "Label for this item", "help": "Help text for this item", "key": "someOtherUniqueKey", "type": "ListSelector", "value": "default", "choices": [ { "label": "Test label 1", "value": "default" }, {				"label": "Test label 2", "value": "other" } ]		} ]	}, {		"category": "messaging", "owner": "patch-owner-id", "prefs": [ { "group": "misc", "restart": "none", "label": "Label for this item", "help": "Help text for this item", "key": "someYetAnotherUniqueKey", "type": "ToggleButton", "value": false }, {			"group": "misc", "restart": "none", "label": "Label for the numeric item", "help": "Help text for this item", "key": "againYetAnotherUniqueKey", "type": "TextField", "value": "", "input": "numeric" }, {			"group": "misc", "restart": "none", "label": "Label for the numeric item", "help": "Help text for this item", "key": "againYetSomeAnotherUniqueKey", "type": "TextField", "value": "", "input": "text" } ]	}, {		"category": "misc", "prefs": [ { "group": "fonts", "restart": "none", "label": "Label for the picker dialog", "help": "Help text for this item", "key": "againYetAnotherUniqueKey", "type": "FilePicker", "path": "/media/internal/downloads", "filter": "files", "select": "single", "value": ["/media/internal/downloads/test.txt"] } ]	} ]

Sample Service Call
The following is an example of a Mojo-style service call that can be used in the code to query the current value of any of the keys provided in the json file.

(Note: Remember that the owner is the appid of the patch and keys is a list of wanted keys that was provided in the json file.)

this.controller.serviceRequest("palm://org.webosinternals.tweaks.prefs/", {method: "get", parameters: { owner: "patch-id", keys: ["someUniqueKey"]}, onSuccess: this.successCallback.bind(this)});

successCallback(response) { if((response) && (response.someUniqueKey)) { // Do something with the config value } }

The following is an example of an Enyo-style service call.

// define the service call kind in the components {kind:"PalmService", name:"getTweaks", service:"palm://org.webosinternals.tweaks.prefs/", method:"get", onSuccess:"successCallback", onFailure:"failureCallback"}, ...   // make the call to the Tweaks service this.$.getTweaks.call({owner: "patch-id", keys: ["someUniqueKey"]}); ... successCallback:function(inSender, inResponse){ if((inResponse) && (inResponse.someUniqueKey)) { // Do something with the config value }; },  // although this is separately defined in the example below, this can also be an existing function in the original code failureCallback:function(inSender, inResponse){ // Do your patch's default behavior }, ... }

Troubleshooting/FAQs
Q: What version of webOS is Tweaks available for?

A: webOS 2.0.0 or later.

Q: How can I tell what patches have Tweaks support?

A: Patches that include support for Tweaks are shown in Preware with a distinctive green plus sign.

'''Q: I am getting a "connecting to service" error after installing Tweaks through Preware. What should I do?'''

A: For some people, the service does not get installed properly. For those with that error, uninstall Tweaks, then reinstall using WebOS Quick Install (WOSQI). If that does not help you can try installing the service configuration files manually by using the following command in a terminal (over novacom/ssh or from an terminal app in the phone): sh /media/cryptofs/apps/usr/lib/ipkg/info/org.webosinternals.tweaks.postinst

ls-control scan-services

Official Forum

 * Official PreCentral Forum Thread

Changelog

 * 1.8.5 - Current Public Release - (Released Oct. 26th, 2011)
 * Polished the Enyo UI when used on phones and fixed the luna restart action in the app menu


 * 1.8.1 - (Released Oct. 24th, 2011)
 * Fixed the mojo/enyo UI detection/selection


 * 1.8.0
 * Added support for file picker widget and made enyo interface work on phones as well


 * 1.6.5
 * Installation fixes to cover problems with 3.0.4


 * 1.6.0
 * First public release of tweaks with enyo UI


 * 1.5.2
 * Small update for the tablet user interface


 * 1.5.1
 * Small bug fix for the tablet user interface


 * 1.5.0
 * Added enyo based user interface for the tablet


 * 1.3.3
 * Added more characters to be allowed for the text fields


 * 1.3.2
 * Promotional release to support sconix, no new features


 * 1.3.1
 * Fixed text field tweaks not count as new tweaks bug


 * 1.3.0
 * Added support for basic text field widget


 * 1.2.0
 * Work around the fatal webOS 2.x db permissions bug


 * 1.1.0
 * Allow for the tweaks json file to override the owner value


 * 1.0.0
 * Initial public release