Settings

Settings packages live in cgi-bin/LJ/Setting or cgi-bin/DW/Setting. Entirely new settings packages -- things created for Dreamwidth -- should go into cgi-bin/DW/Setting, while settings packages that manipulate or extend things that we inherited from LJ code should go into cgi-bin/LJ/Setting. (This is a very rough guide, and exceptions exist. Use your best judgement.)

Settings packages basically exist to manipulate and work with |userprops. They appear on the Manage Settings page, but only if they're defined at the beginning of manage/settings.index.bml.

Step one: do you really need a setting?
Resist the urge to add new settings for everything! They can be really powerful and good to have, but we are trying to keep the number of options and settings down to a minimum. Usability guidelines say that you should include as few options and settings as possible, because it can really turn someone away to look at the settings page and see eight thousand things they have to play with.

Only add a setting if you genuinely believe that more than a small portion of the userbase is going to want to change the default.

Creating a new setting
To add a new settings package, first create a file for your setting. Let's say that you want to create a setting that will let the user decide whether or not to turn on AwesomeNewFeature. You'd create a file cgi-bin/DW/Setting/AwesomeNewFeature.pm and tell your Mercurial installation about it:

Contents of the setting package
New settings packages have to include, at minimum, four functions in the file. Those four functions are:

The first few lines of the file (after the standard header that all Dreamwidth files should contain) define and set up the file. They should be:

Once you do that, you should add the four necessary functions. The generalized settings setup mean that each function is called with the following arguments, so these should be the first lines of each function:

You can then look around the other files in cgi-bin/DW/Setting to see how the other settings manipulate things.

English-stripping your setting
Your text strings for English-stripping your setting package should go in bin/upgrading/en.dat, with the text string starting as setting.settingname. Assuming we're dealing with AwesomeNewFeature, the strings would likely be:

Or, if AwesomeNewFeature has multiple options that will be used to create a drop-down menu:

Adding your setting to the Manage Settings page
To get your setting to appear on the Manage Settings page, you have to include it in http://hg.dwscoalition.org/dw-free/file/tip/htdocs/manage/settings/index.bml htdocs/manage/settings/index.bml]. The categories appear under this line:

Categories there correspond with the tabs of the Manage Settings page (for the most part; the Notifications tab is a bit of a special case). To add your setting, you need to determine:


 * What tab the setting should appear under
 * Where on the page it should appear

Once you've figured that out, add your setting package name in the appropriate line. For instance, if we want the AwesomeNewFeature setting to appear first on the Privacy page, we'd change this section:

To read like this:

The settings appear in the order they're loaded there, so all you have to do to determine order is to rearrange that list.

Testing your setting
Once you've added your setting to the Manage Settings page, you can test it by playing around with changing the setting around a bit. If your setting is manipulating a |userprop, which most of them are, you can verify that the setting is setting and clearing the appropraite userprops properly by giving your user account the canview: or canview:userprops priv and going to admin/propedit.bml to check the contents.

(You should also test that the values of the setting also make AwesomeNewFeature behave properly based on the settings you've chosen, of course!)