Difference between revisions of "Userprops"

Revision as of 02:17, 4 August 2009

Userprops are defined in bin/upgrading/proplists.dat. They're a quick way to store preferences, settings, and information about the user, such as the values of choices they've made in the past. If you're looking for a quick way to store any data about the user, without having to create a whole new database table, your first thought should be "userprop".

(There are other things in proplists.dat along the same lines -- talkprops, which apply to comment objects, and logprops, which apply to entries -- but for the purpose of this walkthrough, we'll assume that you're dealing with userprops.)

When to use userprops

• Are you trying to store a yes/no for the user, like whether or not they have a specific feature on or off? If so, you should make a new userprop.

• Are you trying to store a trinary or multiple-value option, like the option for what email address to show on the profile for paid users? (none, system email address, user-specified email address, local (@dreamwidth.org) email address, system + local, user + local) If so, you should make a new userprop.

• Are you trying to store a small amount of text as a preference, like the customized crosspost footer text or the username of the person who invited the user? If so, you should make a new userprop.

• Are you trying to store something that's greater than 255 characters? If so, a userprop won't help you -- they have to be 255 characters or less.

• Are you trying to store multiple things that all depend on each other, or things that have the possibility to get really long, or things that there can be a lot of (like tags or memories or vgifts received/sent)? If so, a userprop won't help you -- that's getting into "new database table" territory.

Seeing userprops

On your development environment, give your working user the priv canview:userprops or canview:* and go to /admin/propedit.bml. That lets you see all of the userprops defined on your dev environment, and manipulate them as necessary. It's a good idea to keep this page handy, because while you develop, you'll want to refer to it as you go.

Creating userprops

To create a new userprop, add it into bin/upgrading/proplists.dat. It's okay to copy an existing userprop definition and just change what you want to change.

The lines you want to change are 'des' and 'prettyname'. Prettyname should be a short, explanatory, human-understandable title for the userprop, and 'des' should be a description of what it does and what the possible values are (and what they mean). Documenting the possible values and what they do here will save you and others a hell of a lot of time code-diving later, so be sure you do it!

"Datatype" is something else you can change if you want to. The two you'll most usually use are 'char' (characters) and 'num' (for numbers), although there's also 'bool' for boolean (on/off). It's usually a better idea to go with 'char' as a type for greatest flexibility -- if you set something up as boolean and later on discover that you need another option, it's annoying to re-do them, while if you set it up as 'char' you can treat it as boolean in the code and still have the ability to expand later.

Once you have your new userprop created, save the file and tell the database to reload the file:

$LJHOME/bin/upgrading/update-db.pl -r -p --innodb

Then go to /admin/propedit and verify that your new userprop exists.