Difference between revisions of "WTF Backend"

Revision as of 02:51, 7 February 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.

Remove from Watch/Trust Lists

Removing is even easier. No options. You just tell the system which list you want to remove the user from. Again, let's have $u stop watching $other_u:

$u->remove_edge( $other_u, 'watch' );

That's it. To remove both at once, try one of these:

$u->remove_edge( $other_u, 'watch', 'trust' );
$u->remove_edge( $other_u, qw/ watch trust / );

I prefer the latter, but it's personal preference.

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;

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;

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.