Difference between revisions of "Settings"

Revision as of 03:17, 4 August 2009

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:

touch $LJHOME/cvs/dw-free/cgi-bin/DW/Setting/AwesomeNewFeature.pm && 
hg add $LJHOME/cvs/dw-free/cgi-bin/DW/Setting/AwesomeNewFeature.pm

Contents of the setting package

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

should_render
# Tells the site when to show the setting on the Manage Settings page
 
label
# Tells the site what label to show the user for the setting on the Manage Settings page
 
option
# Tells the site how to construct the setting on the Manage Settings page 
# (drop-down menu, text input box, checkbox, etc
 
save
# Tells the site what to do when you save the setting.

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:

package DW::Setting::AwesomeNewFeature;
use base 'LJ::Setting';
use strict;
use warnings;

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:

sub should_render {
    my ( $class, $u ) = @_;
}
 
sub label {
    my $class = shift;
}
 
sub option {
    my ( $class, $u, $errs, $args ) = @_;
}
 
sub save {
    my ( $class, $u, $args ) = @_;
}

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:

setting.awesomenewfeature.label=Awesome New Feature
setting.awesomenewfeature.option=Enable Awesome New Feature

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

setting.awesomenewfeature.label=Awesome New Feature
setting.awesomenewfeature.option=Use AwesomeNewFeature:
setting.awesomenewfeature.option.always=Always
setting.awesomenewfeature.option.mondays=On Mondays
setting.awesomenewfeature.option.weekends=On weekends
setting.awesomenewfeature.option.never=Never

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 htdocs/manage/settings/index.bml. The categories appear under this line:

# the different navigation categories and their settings

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:

privacy => {
            name => $ML{'.cat.privacy'},
            visible => 1,
            disabled => !$u ? 1 : 0,
            form => 1,
            desc => $ML{'.cat.privacy.desc'},
            settings => [qw(
                DW::Setting::EmailAlias
                LJ::Setting::MinSecurity
                DW::Setting::SynLevel
                LJ::Setting::SearchInclusion
                LJ::Setting::NotifyWeblogs
                LJ::Setting::FacebookBeacon
                LJ::Setting::EnableComments
                LJ::Setting::CommentScreening
                LJ::Setting::CommentCaptcha
                LJ::Setting::CommentIP
                LJ::Setting::Display::BanUsers
                DW::Setting::ProfileEmail
            )],
        },

To read like this:

privacy => {
            name => $ML{'.cat.privacy'},
            visible => 1,
            disabled => !$u ? 1 : 0,
            form => 1,
            desc => $ML{'.cat.privacy.desc'},
            settings => [qw(
                DW::Setting::AwesomeNewFeature
                DW::Setting::EmailAlias
                LJ::Setting::MinSecurity
                DW::Setting::SynLevel
                LJ::Setting::SearchInclusion
                LJ::Setting::NotifyWeblogs
                LJ::Setting::FacebookBeacon
                LJ::Setting::EnableComments
                LJ::Setting::CommentScreening
                LJ::Setting::CommentCaptcha
                LJ::Setting::CommentIP
                LJ::Setting::Display::BanUsers
                DW::Setting::ProfileEmail
            )],
        },

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