Difference between revisions of "WTF Backend"

Latest revision as of 06:08, 7 March 2009

This page is a brief introduction to how to use the WTF backend to do things related to watching/trusting. First thing to know is that the backend uses the term "watch" for what we're calling "read" and the term "trust" to mean "access." We chose to keep the backend a little frontend-agnostic, so some other site based on the DW code might choose completely different verbs, and it won't matter to the backend.

The second thing to note is that we've implemented the backend in terms of edges. Most of the actual API you are going to be interacting with is the DW::User::Edges API, a fairly straightforward system. (In the future, more things such as community memberships, banning, etc will be implemented as Edges. But not yet.)

Add to Watch List

Add $other_u to $u's watch list:

$u->add_edge( $other_u, watch => {} );

That's the simplest way. There are a host of options you can set. Here's a full list of options example:

$u->add_edge( $other_u, watch =>
    {
        fgcolor  => 16777215, # foreground white
        bgcolor  => 0,        # background black
        nonotify => 1,        # do not notify $other_u
    }
);

The colors are specified as integers in the range 0..16777215 (2^24). There are some LJ functions to make this easier (i.e., look at LJ::color_todb). The "nonotify" argument suppresses the notification "$u added you to their watch list" that would otherwise be sent.

Add to Trust List

This is very similar to the above. The options are the only thing different, so I will show the full breakdown of options.

$u->add_edge( $other_u, trust =>
    {
        mask     => 6,        # add to groups with id 1 and 2
        nonotify => 0,        # do notify $other_u (default)
    }
);

Add to Both Lists

You can combine options fairly easily. Example:

$u->add_edge( $other_u, watch => {}, trust => {} );

That's it. Yes, you can put the same options in there if you want.

Determining Eligible Actions

If you ever need to know if someone is allowed to watch or trust, it's fairly easy to do so with these methods:

# see if $u is allowed to watch anything
if ( $u->can_watch ) { ... }

# see if they're allowed to watch/trust $other_u
if ( $u->can_trust( $other_u ) ) { ... }

These checks are done by the add_edge call, so you don't have to do them yourself. Use these methods to alter the UI of the page you're displaying as well as for showing/hiding/enabling/disabling buttons, widgets, etc.

Remove from Watch/Trust Lists

Removing only has one option: nonotify. Otherwise, the syntax is basically the same as adding. Again, let's have $u stop watching $other_u:

$u->remove_edge( $other_u, watch => {} );

To pass the nonotify option:

$u->remove_edge( $other_u, watch => { nonotify => 1 } );

That's it. To remove both at once:

$u->remove_edge( $other_u, watch => {}, trust => {} );

Simple Questions

Here are some examples, in code form. Read and be enlightened.

# see if $u trusts $other_u
if ( $u->trusts( $other_u ) ) {
    ...
}

# see if $u watches $other_u
if ( $u->watches( $other_u ) ) {
    ...
}

# trust can be mutual
if ( $u->mutually_trusts( $other_u ) ) {
    ...
}

# get the exact trust mask (all groups)
my $mask = $u->trustmask( $other_u );

Get Watch/Trust Lists

All of the methods are on the $u object and are pretty easy to access. Here's some more code to amble through:

# get all userids that you watch, trust, etc
my @userids = $u->watched_userids;
my @userids = $u->trusted_userids;

# now go the other way, who watches $u? or trusts?
my @userids = $u->watched_by_userids;
my @userids = $u->trusted_by_userids;

# mutual is easy
my @userids = $u->mutually_watched_userids;
my @userids = $u->mutually_trusted_userids;

These methods can all be used in scalar context to return how many people are on the list. For example:

my $watched_count = $u->watched_userids;

Get Full Watch/Trust Lists

If you need more data, i.e., if you need to know exactly what groups everybody is in or you need to know all of the colors for the entire list, you can use these methods.

# everybody I watch in a hashref
my $watched = $u->watch_list;

# everybody I trust
my $trusted = $u->trust_list;

# everybody I trust in a group
my $group = $u->trust_group_list( id => 5 );
my $group = $u->trust_group_list( name => 'Foo Group' );

All of these methods return a hashref that looks like this:

# print out $group from above
{
  35 => { groupmask => NNN,
          fgcolor => '#xxx',
          bgcolor => '#xxx',
          showbydefault => NNN },
  42 => { groupmask => NNN,
          fgcolor => '#xxx',
          bgcolor => '#xxx',
          showbydefault => NNN },
 }

The above indicates that the two users (id 35, id 42) are members of Foo Group. (As that was the last group called.) Note that this is the approved way of getting access to everybody: do not call $u->trustmask() on 500 people!

Manage Trust Groups

Trust groups are what we call what used to be "custom friend groups". These groups are security groups and are only used for posting, NOT for filtering/reading your reading page.

Getting the list of groups a user has is very easy:

# get groups
my $grps = $u->trust_groups || {};
foreach my $id ( keys %$grps ) {
    print "group name = $grps->{$id}->{groupname}\n";
}

Other columns that you will want to use are sortorder (0..255 byte) and is_public (1/0 boolean).

You can create a trust group easily:

# create a group when you don't care what ID it gets
my $id = $u->create_trust_group( groupname => "Some Name", sortorder => 50, is_public => 0 );

Note that sortorder and is_public are optional. Also, another method of creating a group, if you know what ID you want to use:

# create by id
my $id = $u->create_trust_group( id => 35, groupname => "Another Name" );

The returned value should be the same as the id you provided. If not, something went horribly wrong and you can blame Mark.  :)

Editing groups is similar:

# edit the group
$u->edit_trust_group( id => 35, groupname => "New Name!", sortorder => 35, is_public => 1 );

All of the columns are optional except for id, which is required so we know which group you are trying to edit.

Deleting a group is also easy:

# delete group 4
$u->delete_trust_group( id => 4 );

# delete group "Awesome People"
$u->delete_trust_group( name => 'Awesome People' );

Manage Trust Group Membership

Determining if a user is a member of a trust group is straightforward. If you're doing a simple check (i.e. for security purposes) then you can use this method:

# see if $other_u is in group 13
return 0 unless $u->trust_group_contains( $other_u, 13 );

If you wish to edit a user's membership in a group, you can do that:

# edit $other_u's groups by adding them to group 5
$u->edit_trustmask( $other_u, add => 5 );

# or add to multiple
$u->edit_trustmask( $other_u, add => [ 1, 3, 15, 26 ] );

# or delete them from one or more
$u->edit_trustmask( $other_u, remove => [ 3, 15 ] );

# or forget everything they have now and set a new view
$u->edit_trustmask( $other_u, set => [ 1, 2, 3 ] );

# or just call the whole thing off (remove from all groups)
$u->edit_trustmask( $other_u, set => [] );

Note that these functions are not going to be particularly fast if you have to do a mass-edit situation. Will have to write something for that.