Author Topic: Modules Documentation and Creation - Expand the Whited00r Settings  (Read 3410 times)

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
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
  • PSLinkListCell
for the accompanying value. The value is a string.
Code: [Select]
<key>cell</key>
<string>PSSwitchCell</string>


label
Sets the label for the cell. The value is a string.
Code: [Select]
<key>label</key>
<string>Test1</string>

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: [Select]
<key>defaults</key>
<string>com.bruan.test1</string>

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: [Select]
<key>default</key>
<true/>

Code: [Select]
<key>default</key>
<string>option1</key>

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: [Select]
<key>cellBackgroundColor</key>
<string>greyColor</string>

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: [Select]
<key>textColor</key>
<string>redColor</string>

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: [Select]
<key>script</key>
<string>/var/mobile/someScript.sh</string>

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: [Select]
<key>popupText</key>
<string>This is just a test popup, nothing to see here</string>

bold
Makes the cell text bold. If not present, the cell will not be bold. This is a boolean value.
Code: [Select]
<key>bold</key>
<true/>

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: [Select]
<key>localize</key>
<true/>


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: [Select]
<key>section</key>
<string>testSection</string>

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: [Select]
<key>category</key>
<string>Features</string>

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: [Select]
<key>requiredCapabilities</key>
<array>
    <string>iPhone</string>
    <string>advancedConfig</string>
</array>

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: [Select]
<key>reverseCapabilities</key>
<array>
    <string>multitasking</string>
</array>





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: [Select]
<?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>

Between that and this, which goes at the very end of the file, you will put your cells.
Code: [Select]
</array>
<key>title</key>
<string>Test Module</string>
</dict>
</plist>

The basic structure of a cell goes like this, between the <dict> and </dict>.
Code: [Select]
<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>

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: [Select]
#!/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

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: [Select]
<?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>

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  :'(

Offline iTechy21

  • Bashing the shell
  • Global Moderator
  • SuperHero Member
  • *****
  • Posts: 1675
  • Country: gb
  • Well errr... Stuff :3
    • View Profile
    • My Blog
  • Device: iPod Touch 1G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #1 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...
« Last Edit: April 14, 2014, 08:49:17 PM by itechy21 »
Follow me on twitter! | Subscribe to my YouTube Channel! | Follow my blog!
Please Read all the stickies if you're new. And follow the rules, please :)

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #2 on: April 14, 2014, 10:43: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...

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 :)

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #3 on: April 15, 2014, 04:14:40 AM »
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 :)

Offline AnimateDread

  • SuperHero Member
  • *****
  • Posts: 741
  • Country: ca
  • Learning developer
    • View Profile
  • Device: iPod Touch 1G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #4 on: April 15, 2014, 05:34:21 PM »
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
Soutient en Francais ici

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #5 on: April 16, 2014, 04:30:27 AM »
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

Ah yes, you can indeed! :)  You understand shell and all this well enough to walk newer developers through the basics of this too.

Took long enough to get around to writing it, but only an hour or so to actually organize and track down everything I put in. I'm very glad I did make it as dynamic as it is, really makes it stand out in terms of future proofing as well as ease to make a quick little extra option if needed (like spotlight override).  I wrote the handling for everything ;)  None of that uses the system methods for anything, I just used the names that were used by the system so users can adapt to this easier ;)  A basic switch cell, which most people would know, will just work out the box now because I named things the same.  It's all the extra stuff that was more tricky (although the required/reverse capabilities were a pain)

Offline iTechy21

  • Bashing the shell
  • Global Moderator
  • SuperHero Member
  • *****
  • Posts: 1675
  • Country: gb
  • Well errr... Stuff :3
    • View Profile
    • My Blog
  • Device: iPod Touch 1G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #6 on: May 09, 2014, 08:59:51 PM »
This is a question but can you add more cells in one module package? Or would you need to create more module packages?
Follow me on twitter! | Subscribe to my YouTube Channel! | Follow my blog!
Please Read all the stickies if you're new. And follow the rules, please :)

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #7 on: May 10, 2014, 03:19:59 AM »
This is a question but can you add more cells in one module package? Or would you need to create more module packages?


You can add as many cells as you want into the Cells.plist, and it will be loaded up and categorized and all :)  You only get one configurator script though, but seeing you get arguments on what key it is giving the value for, you can do logic checks inside the configurator script and handle the different options (or read them manually if you need them in advance)

Offline abbeygiles1

  • Member
  • **
  • Posts: 24
  • Country: au
  • WE ARE THE NIGHT
    • View Profile
  • Device: iPod Touch 2G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #8 on: September 15, 2014, 11:30:53 PM »
This is really helpful, thanks.

If i wanted to add a description underneath the cell, you would use a statictext cell, right?
PEOPLE WHO PUT PINEAPPLE ON PIZZA ARE BARBARIANS

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #9 on: September 16, 2014, 06:02:21 AM »
This is really helpful, thanks.

If i wanted to add a description underneath the cell, you would use a statictext cell, right?

Welcome to the forums :)

yes, you would use one of those for that.  Unless it is better suited by having a popup for what it does, and a label for just general information to distinguish what it does.

Offline abbeygiles1

  • Member
  • **
  • Posts: 24
  • Country: au
  • WE ARE THE NIGHT
    • View Profile
  • Device: iPod Touch 2G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #10 on: September 16, 2014, 08:48:09 AM »
Cool, thanks for the welcome.
Also, what type of cell would i use if i wanted to align said text cell
PEOPLE WHO PUT PINEAPPLE ON PIZZA ARE BARBARIANS

Offline iTechy21

  • Bashing the shell
  • Global Moderator
  • SuperHero Member
  • *****
  • Posts: 1675
  • Country: gb
  • Well errr... Stuff :3
    • View Profile
    • My Blog
  • Device: iPod Touch 1G
  • My Computer: Windows
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #11 on: September 16, 2014, 11:03:44 PM »
How would I make a label appear above a button with just text... As Google isn't giving me straight awsners.
Follow me on twitter! | Subscribe to my YouTube Channel! | Follow my blog!
Please Read all the stickies if you're new. And follow the rules, please :)

Offline Bruan

  • Feature Developer
  • Administrator
  • SuperHero Member
  • *****
  • Posts: 13082
  • Country: 00
  • Methuselah
    • View Profile
    • Bruan_WD Twitter
  • Device: iPhone 3G
  • My Computer: Linux
Re: Modules Documentation and Creation - Expand the Whited00r Settings
« Reply #12 on: September 17, 2014, 05:55:09 AM »
Cool, thanks for the welcome.
Also, what type of cell would i use if i wanted to align said text cell

Aye, I do that for everyone I notice is new ;)  Muscle memory and all that  ;D

I'm not sure if I actually added in support for alignment...
From the code of the .plist it looks like I did though, using something like this:
Code: [Select]
<key>alignment</key>
<integer>1</integer>

I would think changing that number to 0, 1, or 2 (or maybe -1, 0, 1) would change the alignment...

How would I make a label appear above a button with just text... As Google isn't giving me straight awsners.

Huh?  Just put a text cell above the button cell in the file itself, and don't have a spacing cell in-between.