Support - Whited00r Custom iOS for iPhone 2G, 3G & iPod Touch 1G & 2G > Tutorials - Whited00r - iOS 3.1.3 - iOS 4.2.1

Modules Documentation and Creation - Expand the Whited00r Settings

(1/3) > >>

Bruan:
Updated 14/04/2014

Introduction

Modules, as I so like to call them, provide simple expansion for the Whited00r Settings. 
This means anyone can make a toggle or option in the Whited00r Settings, and take pretty much near full advantage of all that it provides.
There are already a couple of modules in WD7.1, used to put in options for certain features.
iTechy has created a module, and hopefully will start making even more - you can find it here: iTechy21's Whited00r module - Retina Remover -DOWNLOADS AVALABLE-

There could be many advantages to this, ranging from when making a new tweak if you want to put an option in for it (or several), to something a little more creative, like say an adblock tool with a kill switch, or even something to add hosts to the adblock file.
Really, it is up to you what to do with it.  Simple to use, and very powerful in the right hands, it is our little gift to the Whited00r creative community out there :)



Features

Localizable
You can localize your module very easily, so it blends in with everything else settings wise.

Script Support
You can include a script to be executed in the module. You don't need to even have any options in the whited00r settings and it will just run every time the settings are applied.
You can also have many different options, and the Configurator will pass along arguments to the script too, so you know which option was set with what value. (more on how to use that later)
There is even an option to run a script without even applying the settings, if you need that.

Styling
Unlike the stock settings app (well, for the most part), the Whited00r Settings allows you to make your cells stand out more, with colouring and more!

Intelligent
With features like the popup text, which displays information on the tap of a cell, the requiredCapabilities/reverseCapabilities options for hiding and displaying the cell when needed, as well as the grouping and paging options, the Whited00r Settings are very easy to expand upon in a clean and organized manner.



Documentation
The different options and supported cell types, with mini examples of the use.  This will be updated as time goes on. Required keys/arguments will be in maroon.

Cell
Obviously, this is required to even begin with anything. You can choose from:

* PSGroupCell
* PSButtonCell
* PSSwitchCell
* PSLinkListCellfor the accompanying value. The value is a string.

--- Code: ---<key>cell</key>
<string>PSSwitchCell</string>

--- End code ---


label
Sets the label for the cell. The value is a string.

--- Code: ---<key>label</key>
<string>Test1</string>

--- End code ---

defaults
Sets the identifier for the cell, if it is a button or switch cell this is quite useful (mostly for the switch or list cells).  Whatever you set this to, you will find the appropriate file created in /var/mobile/Library/Preferences/my.bundle.id.plist. The value is a string.
If you have a switch or list cell, this key is required for it to be of any use.

--- Code: ---<key>defaults</key>
<string>com.bruan.test1</string>

--- End code ---

default
For switches mainly, this sets the default value of the switch for the first time around. It will change of course after it is written to a preference state. This is a boolean value when used with a switch, otherwise it is a string. If none is specified, it will default to "false" or just blank..
Not to be confused with "defaults".

--- Code: ---<key>default</key>
<true/>

--- End code ---


--- Code: ---<key>default</key>
<string>option1</key>

--- End code ---

cellBackgroundColor
Used for setting the color of the cell background. If none is specified, it will default to white.
You can use any of the UIColor types, although only the color names such as "redColor, greenColor, grayColor" and so on. clearColor works as well, if needed.
This is a string value.

--- Code: ---<key>cellBackgroundColor</key>
<string>greyColor</string>

--- End code ---

textColor
Used for setting the color of the cell text, it uses the same style as the cellBackgroundColor option. It is preferred if your cell is an advanced config option, that you use "blueColor" as the value to differentiate it is an advanced option.
This is a string value.

--- Code: ---<key>textColor</key>
<string>redColor</string>

--- End code ---

script
When specified, when this cell is toggled or pressed, it will execute the file path specified. It is run with root privileges, although no arguments are passed to it. If this requires arguments, you will have to manually retrieve values inside the script. This can be at any location on the file system, and does not get executed when the changes are applied in the whited00r settings (unless it is in the module folder and named "configurator"). The value is a string.


--- Code: ---<key>script</key>
<string>/var/mobile/someScript.sh</string>

--- End code ---

popupText
Localizable, this is what is shown when tapping on a cell. If nothing is specified for this, nothing will be shown. It uses the label of the cell as the title.
This is a string value.

--- Code: ---<key>popupText</key>
<string>This is just a test popup, nothing to see here</string>

--- End code ---

bold
Makes the cell text bold. If not present, the cell will not be bold. This is a boolean value.

--- Code: ---<key>bold</key>
<true/>

--- End code ---

localize
This tells the module if you want that cell to be localized or not for both label and popupText. This requires the defaults to be set, and the defaults to be the same as the module folder name, and the localization folders to be in the module folder. It is a boolean value.

--- Code: ---<key>localize</key>
<true/>

--- End code ---


section
This allows for some form of keeping cells of the same time together. No real organizational abilities within the cells themselves of the section, but it will keep the cells grouped together in a category page though. Fiddle around with the cell placement in the Cells.plist to get the right order for what you want. This is a string value.

--- Code: ---<key>section</key>
<string>testSection</string>

--- End code ---

category
This dictates what page the cell falls under. You don't need to use the same category for all the sections, it is up to you. You could even create a new category if you want, and have all your cells show up on a new page. This is a string value.

--- Code: ---<key>category</key>
<string>Features</string>

--- End code ---

requiredCapabilities
This is a little trickier to handle. There are a couple pre-built options here, pretty much anything the system uses, and a couple others like "iPhone", "backgrounder", "advancedConfig", "multitasking" (not exactly sure of that, take a look at the Configurator.plist to see what the cells use there as options for this and the reverseCapabilities).
If any of the conditions for requiredCapabilities are not met, it will hide the cell.
This is an array of strings.

--- Code: ---<key>requiredCapabilities</key>
<array>
    <string>iPhone</string>
    <string>advancedConfig</string>
</array>

--- End code ---

reverseCapabilities
Like required capabilities, but rather, if an option is not found, it will show the cell. So say you want to hide it on the iPhone but show it on iPods, you would put that in this. It can mix with requiredCapabilities, but any conflicting options will give unusual results and is not recommended. (such as putting iPhone in both required and reverse).
This is an array of strings.

--- Code: ---<key>reverseCapabilities</key>
<array>
    <string>multitasking</string>
</array>

--- End code ---





Creation of a Module
Creating a module is simple enough, although the above may look daunting. I'm going to hope you understand the basics of XML formatting, otherwise your cells won't work and will likely break the configurator/not show up until you fix it. Basically, make sure the syntax is correct.
Also going to presume you know how to make a basic .deb file, and get correct permissions for it as well. (google is your friend! :) )

Folder/File Layout
So, the layout of the files is pretty standard stuff, and easy enough to understand I hope. You have pretty much 3 things you need.

1. Module folder
This is the folder that contains all the module-related things. Name it like you would name a bundle identifier of a package. This should match up to any "defaults" keys you want to use for toggles for the module. So, say I have a defaults key set to "com.bruan.testmodule", I would name the module folder that too.
This folder will reside in /var/mobile/Library/Configurator

2. Cells.plist
This is the graphic side of things, used for making the cells themselves. You will configure them like above. The start and end of the Cells.plist are always the same, it is just the standard formatting for something like this.
Before any of the cells, you will put this at the top of the file:

--- Code: ---<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>items</key>
<array>

--- End code ---

Between that and this, which goes at the very end of the file, you will put your cells.

--- Code: --- </array>
<key>title</key>
<string>Test Module</string>
</dict>
</plist>

--- End code ---

The basic structure of a cell goes like this, between the <dict> and </dict>.

--- Code: --- <dict>
<key>cell</key>
<string>PSSwitchCell</string>
<key>default</key>
<false/>
<key>defaults</key>
<string>com.bruan.testmodule</string>
<key>key</key>
<string>switch1</string>
<key>textColor</key>
<string>blueColor</string>
<key>label</key>
<string>TESTSWITCH1_LABEL</string>
<key>popupText</key>
<string>TESTSWITCH1_POPUP</string>
<key>category</key>
<string>Visual</string>
<key>section</key>
<string>IconOptions</string>
<key>requiredCapabilities</key>
<array>
<string>advancedConfig</string>
</array>
<key>localize</key>
<true/>
</dict>

--- End code ---

After you make the Cells.plist, put it in the module folder, and it should show up after installed :)

3. Configurator script
Now, onto the fun stuff. If you don't actually use this, and are just toggling an option for some other preference file for another tweak, don't worry about this ;)  You also could have just this run on the settings apply without using any Cells.plist.
This is a shell script, with no .sh extension!  If you put a .sh at the end it won't run.
The file name is literally configurator, nothing extra. Just plop it in the module folder, and you are good to go.

This script is passed 2 arguments on execution, if there was anything with the bundle identifier found in the preferences folder.

--- Code: ---#!/bin/bash

#the key for whatever it found a value for is passed as the first positional parameter.
key="$1"

#the value is passed second. If it is a switch, it will pass enable or disable. Otherwise, it will return whatever string it found for the key's value.
value="$2"

if [[  "$key" == "testSwitch1" && "$value" == "enable" ]];
then
sbalert -t "Test Switch 1" -m "Enabled."
elif [[ "$key" == "testSwitch1" && "$value" == "disable" ]];
then
sbalert -t  "Test Switch 1" -m "Disabled."
else
sbalert -t "$key" -m "$value";
fi

--- End code ---

That little script above displays certain messages based upon what is toggled for the key of "testSwitch1" in a switch. If it is not a switch, or is not testSwitch1, it will display an alert for the key and the value for that key.  It is just a simple example showing how to perform certain things based on what is passed to the script.

4. Localization
This requires a bit of effort, but pays off in the long run for making users feel a more native experience.  You will have to provide the localizations, but, if you ask nicely and explain how to do it, I'm sure users will help you :)  You can see an example of how to do this at: Whited00r Settings Localizations - Help Translate Whited00r!

So, once you have the system identifier for your language, you can then make a folder like that with .lproj at the end of it in the module folder. Inside there, make a file called Cells.strings.
It should look like this on principle (note the different start and end from the Cells.plist):

--- Code: ---<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>TESTSWITCH1_LABEL</key>
<string>Switch 1</string>
<key>TESTSWITCH1_POPUP</key>
<string>Some text describing what this switch does</string>
</dict>
</plist>

--- End code ---

There you go, you have just made a localization for your module!  Just remember, whatever you put for the label value or the popupText value, you have to copy that exactly and use it as a key in the localization, and then assign the real value to it. (confusing, but also makes sense!)


5. Finishing up
Well, after all that is done above how you want, you can then just package it up as a .deb and share it with the world! Just make sure you have read permissions for the module folder and the contents in it, as well as the owner and group being mobile:mobile. Otherwise, it won't show up  :'(

iTechy21:
Ohhh :o (btw thanks for the mention of my module :) ) I am slowly working on another one which uses your debug.sh and logs info which users can upload to a thread which could help us diagnose a problem if that is ok with you...

Bruan:

--- Quote from: itechy21 on April 14, 2014, 08:46:36 PM ---Ohhh :o (btw thanks for the mention of my module :) ) I am slowly working on another one which uses your debug.sh and logs info which users can upload to a thread which could help us diagnose a problem if that is ok with you...

--- End quote ---

No worries, that would be helpful indeed :) I was actually thinking it may be better done in an app though, but if you could have it as a "Diagnostic button" or something, that displays text in an alert that the user can then copy and email to themselves, that would be brilliant :)

Bruan:
There we go, all finished up for what I remember and had up code wise. I think maybe there are a couple other things, but they aren't as important. I just give the basic premise of how to make a module, and the complete documentation.  It is up to you to make things out with it (not just you, but anyone really).  If you have questions, I can answer :)

AnimateDread:
I can also help aswell :)

nice documentation there, and dang good work on making the configurator THAT dynamic! :O
I know you wrote handling for most things yourself though and that is nice :3

Navigation

[0] Message Index

[#] Next page

Go to full version