+++ /dev/null
-=head1 Flox: A Free Social Networking Site
-
-Friendster, Tribe, and now Google's Orkut - it seems like in early 2004,
-everyone wanted to be a social networking site. At the time, I was too
-busy to be a social networking site, as I was working on my own project
-at the time - Maypole. However, I realised that if I could implement a
-social networking system using Maypole, then Maypole could probably do
-anything.
-
-I'd already decided there was room for a free, open-source networking
-site, and then Peter Sergeant came up with the hook - localizing it to
-universities and societies, and tying in meet-ups with restaurant
-bookings. I called it Flox, partially because it flocks people together
-and partially because it's localised for my home town of Oxford and its
-university student population.
-
-Flox is still in, uh, flux, but it does the essentials. We're going to
-see how it was put together, and how the techniques shown in the
-L<Request.pod> chapter can help to create a sophisticated web
-application. Of course, I didn't have this manual available at the time,
-so it took a bit longer than it should have done...
-
-=head2 Mapping the concepts
-
-Any Maypole application should start with two things: a database schema,
-and some idea of what the pages involved are going to look like.
-Usually, these pages will be tying to displaying or editing some element
-of the database, so these two concepts should come hand in hand.
-
-When I started looking at social networking sites, I began by
-identifying the concepts which were going to make up the tables of the
-application. At its most basic, a site like Orkut or Flox has two
-distinct concepts: a user, and a connection between two users.
-Additionally, there's the idea of an invitation to a new user, which can
-be extended, accepted, declined or ignored. These three will make up the
-key tables; there are an extra two tables in Flox, but they're
-essentially enumerations that are a bit easier to edit: each user has an
-affiliation to a particular college or department, and a status in the
-university. (Undergraduate, graduate, and so on.)
-
-For this first run-through, we're going to ignore the ideas of societies
-and communities, and end up with a schema like so:
-
- CREATE TABLE user (
- id int not null auto_increment primary key,
- first_name varchar(50),
- last_name varchar(50),
- email varchar(255),
- profile text,
- password varchar(255),
- affiliation int,
- unistatus int,
- status ENUM("real", "invitee"),
- photo blob,
- photo_type varchar(30)
- );
-
- CREATE TABLE connection (
- id int not null auto_increment primary key,
- from_user int,
- to_user int,
- status ENUM("offered", "confirmed")
- );
-
- CREATE TABLE invitation (
- id char(32) not null primary key,
- issuer int,
- recipient int,
- expires date
- );
-
-Plus the definition of our two auxilliary tables:
-
- CREATE TABLE affiliation (
- id int not null auto_increment primary key,
- name varchar(255)
- );
-
- CREATE TABLE unistatus (
- id int not null auto_increment primary key,
- name varchar(255)
- );
-
-Notice that, for simplicity, invitations and friendship connections are
-quite similar: they are extended from one user to another. This means
-that people who haven't accepted an invite yet still have a place in the
-user table, with a different C<status>. Similarly, a connection between
-users can be offered, and when it is accepted, its status is changed to
-"confirmed" and a reciprocal relationship put in place.
-
-We also have some idea, based on what we want to happen, of what pages
-and actions we're going to define. Leaving the user aside for the
-moment, we want an action which extends an invitation from the current
-user to a new user. We want a page the new user can go to in order to
-accept that invitation. Similarly, we want an action which offers a
-friendship connection to an existing user, and a page the user can go to
-to accept or reject it. This gives us five pages so far:
-
- invitation/issue
- invitation/accept
-
- user/befriend
- connection/accept
- connection/reject
-
-Notice that the C<befriend> action is performed on a user, not a
-connection. This is distinct from C<invitation/issue> because when
-befriending, we have a real user on the system that we want to do
-something to. This makes sense if you think of it in terms of object
-oriented programming - we could say
-
- Flox::Connection->create(to => $user)
-
-but it's clearer to say
-
- $user->befriend
-
-Similarly, we could say
-
- Flox::User->create({ ... })->issue_invitation_to
-
-but it's clearer to say
-
- Flox::Invitation->issue( to => Flox::User->create({ ... }) )
-
-because it more accurately reflects the principal subject and object of
-these actions.
-
-Returning to look at the user class, we want to be able to view a user's
-profile, edit one's own profile, set up the profile for the first
-time, upload pictures and display pictures. We also need to handle the
-concepts of logging in and logging out.
-
-As usual, though, we'll start with a handler class which sets up the
-database:
-
- package Flox;
- use base qw(Apache::MVC);
- Flox->setup("dbi:mysql:flox");
- Flox->config->{display_tables} = [qw[user invitation connection]];
- 1;
-
-Very simple, as these things are meant to be. Now let's build on it.
-
-=head2 Authentication
-
-The concept of a current user is absolutely critical in a site like
-Flox; it represents "me", the viewer of the page, as the site explores
-the connections in my world. We've described the authentication hacks
-briefly in the L<Request.pod> chapter, but now it's time to go into a
-little more detail about how user handling is done.
-
-XXX
-
-We also want to be able to refer to the current user from the templates,
-so we use the overridable C<additional_data> method to give us a C<my>
-template variable:
-
- sub additional_data {
- my $r = shift; $r->{template_args}{my} = $r->{user};
- }
-
-I've called it C<my> rather than C<me> because we it lets us check
-C<[% my.name %]>, and so on.
-
-=head2 Viewing a user
-
-The first page that a user will see after logging in will be their own
-profile, so in order to speed development, we'll start by getting a
-C<user/view> page up.
-
-The only difference from a programming point of view between this action
-and the default C<view> action is that, if no user ID is given, then we
-want to view "me", the current user. Remembering that the default view
-action does nothing, our C<Flox::User::view> action only needs to do
-nothing plus ensure it has a user in the C<objects> slot, putting
-C<$r-E<gt>{user}> in there if not:
-
- sub view :Exported {
- my ($class, $r) = @_;
- $r->{objects} = [ $r->{user} ] unless @{$r->{objects}||[]};
- }
-
-Maypole, unfortunately, is very good at making programming boring. The
-downside of having to write very little code at all is that we now have
-to spend most of our time writing nice HTML for the templates.
-
-XXX
-
-The next stage is viewing the user's photo. Assuming we've got the photo
-stored in the database already (which is a reasonable assumption for the
-moment since we don't have a way to upload a photo quite yet) then we
-can use the a variation of the "Displaying pictures" hack from the
-Requests chapter:
-
- sub view_picture :Exported {
- my ($self, $r) = @_;
- my $user = $r->{objects}->[0] || $r->{user};
- if ($r->{content_type} = $user->photo_type) {
- $r->{output} = $user->photo;
- } else {
- # Read no-photo photo
- $r->{content_type} = "image/png";
- $r->{output} = slurp_file("images/no-photo.png");
- }
- }
-
-We begin by getting a user object, just like in the C<view> action: either
-the user whose ID was passed in on the URL, or the current user. Then
-we check if a C<photo_type> has been set in this user's record. If so,
-then we'll use that as the content type for this request, and the data
-in the C<photo> attribute as the data to send out. The trick here is
-that setting C<$r-E<gt>{output}> overrides the whole view class processing
-and allows us to write the content out directly.
-
-In our template, we can now say
-
- <IMG SRC="/user/view_picture/[% user.id %]">
-
-and the appropriate user's mugshot will appear.
-
-However, if we're throwing big chunks of data around like C<photo>, it's
-now worth optimizing the C<User> class to ensure that only pertitent
-data is fetched by default, and C<photo> and friends are only fetched on
-demand. The "lazy population" section of C<Class::DBI>'s man page
-explains how to group the columns by usage so that we can optimize
-fetches:
-
- Flox::User->columns(Primary => qw/id/);
- Flox::User->columns(Essential => qw/status/);
- Flox::User->columns(Helpful => qw/ first_name last_name email password/)
- Flox::User->columns(Display => qw/ profile affiliation unistatus /);
- Flox::User->columns(Photo => qw/ photo photo_type /);
-
-This means that the status and ID columns will always be retrieved when
-we deal with a user; next, any one of the name, email or password
-columns will cause that group of data to be retrieved; if we go on to
-display more information about a user, we also load up the profile,
-affiliation and university status; finally, if we're throwing around
-photos, then we load in the photo type and photo data.
-
-These groupings are somewhat arbitrary, and there needs to be a lot of
-profiling to determine the most efficient groupings of columns to load,
-but they demonstrate one principle about working in Maypole: this is the
-first time in dealing with Maypole that we've had to explicitly list the
-columns of a table, but Maypole has so far Just Worked. There's a
-difference, though, between Maypole just working and Maypole working
-well, and if you want to optimize your application, then you need to
-start putting in the code to do that. The beauty of Maypole is that you
-can do as much or as little of such optimization as you want or need.
-
-So now we can view users and their photos. It's time to allow the users
-to edit their profiles and upload a new photo.
-
-=head2 Editing users
-
-XXX Editing a profile
-
-I introduced Flox to a bunch of friends and told them to be as ruthless
-as possible in finding bugs and trying to break it. And break it they
-did; within an hour the screens were thoroughly messed up as users had
-nasty HTML tags in their profiles, names, email addresses and so on.
-This spawned another hack in the request cookbook: "Limiting data for
-display". I changed the untaint columns to use C<html> untainting, and
-all was better:
-
- Flox::User->untaint_columns(
- html => [qw/first_name last_name profile/],
- printable => [qw/password/],
- integer => [qw/affiliation unistatus /],
- email => [qw/email/]
- );
-
-The next stage was the ability to upload a photo. We unleash the "Uploading
-files" recipe, with an additional check to make sure the photo is of a
-sensible size:
-
- use constant MAX_IMAGE_SIZE => 512 * 1024;
- sub do_upload :Exported {
- my ($class, $r) = @_;
- my $user = $r->{user};
- my $upload = $r->{ar}->upload("picture");
- if ($upload) {
- my $ct = $upload->info("Content-type");
- return $r->error("Unknown image file type $ct")
- if $ct !~ m{image/(jpeg|gif|png)};
- return $r->error("File too big! Maximum size is ".MAX_IMAGE_SIZE)
- if $upload->size > MAX_IMAGE_SIZE;
-
- my $fh = $upload->fh;
- my $image = do { local $/; <$fh> };
-
- use Image::Size;
- my ($x, $y) = imgsize(\$image);
- return $r->error("Image too big! ($x, $y) Maximum size is 350x350")
- if $y > 350 or $x > 350;
- $r->{user}->photo_type($ct);
- $r->{user}->photo($image);
- }
-
- $r->objects([ $user ]);
- $r->{template} = "view";
- }
-
-Now we've gone as far as we want to go about user editing at the moment.
-Let's have a look at the real meat of a social networking site: getting
-other people involved, and registering connections between users.
-
-=head2 Invitations
-
-We need to do two things to invitations working: first provide a way to
-issue an invitation, and then provide a way to accept it. Since what
-we're doing in issuing an invitation is essentially creating a new
-one, we'll use our usual practice of having a page to display the form
-to offer an invitation, and then use a C<do_edit> method to actually do
-the work. So our C<issue> method is just an empty action:
-
- sub issue :Exported {}
-
-and the template proceeds as normal:
-
- [% PROCESS header %]
- <h2> Invite a friend </h2>
-
- <FORM ACTION="[%base%]/invitation/do_edit/" METHOD="post">
- <TABLE>
-
-Now we use the "Catching errors in a form" recipe from L<Request.pod> and
-write our form template:
-
- <TR><TD>
- First name: <INPUT TYPE="text" NAME="forename"
- VALUE="[%request.params.forename%]">
- </TD>
- <TD>
- Last name: <INPUT TYPE="text" NAME="surname"
- VALUE="[%request.params.surname%]">
- </TD></TR>
- [% IF errors.forename OR errors.surname %]
- <TR>
- <TD><SPAN class="error">[% errors.forename %]</SPAN> </TD>
- <TD><SPAN class="error">[% errors.surname %]</SPAN> </TD>
- </TR>
- [% END %]
- <TR>
- ...
-
-Now we need to work on the C<do_edit> action. This has to validate the
-form parameters, create the invited user, create the row in the C<invitation>
-table, and send an email to the new user asking them to join.
-
-We'd normally use C<create_from_cgi> to do the first two stages, but this time
-we handle the untainting manually, because there are a surprising number of
-things we need to check before we actually do the create. So here's the
-untainting of the parameters:
-
- my ($self, $r) = @_;
- my $h = CGI::Untaint->new(%{$r->{params}});
- my (%errors, %ex);
- for (qw( email forename surname )) {
- $ex{$_} = $h->extract(
- "-as_".($_ eq "email" ? "email" : "printable") => $_
- ) or $errors{$_} = $h->error;
- }
-
-Next, we do the usual dance of throwing the user back at the form in case
-of errors:
-
- if (keys %errors) {
- $r->{template_args}{message} = "There was something wrong with that...";
- $r->{template_args}{errors} = \%errors;
- $r->{template} = "issue";
- return;
- }
-
-We've introduced a new template variable here, C<message>, which we'll use
-to display any important messages to the user.
-
-The first check we need to do is whether or not we already have a user
-with that email address. If we have, and they're a real user, then we
-abort the invite progress and instead redirect them to viewing that user's
-profile.
-
- my ($user) = Flox::User->search({ email => $ex{email} });
- if ($user) {
- if ($user->status eq "real") {
- $r->{template_args}{message} =
- "That user already seems to exist on Flox. ".
- "Is this the one you meant?";
-
- $self->redirect_to_user($r,$user);
- }
-
-Where C<redirect_to_user> looks like this:
-
- sub redirect_to_user {
- my ($self, $r, $user) = @_;
- $r->{objects} = [ $user ];
- $r->{template} = "view";
- $r->{model_class} = "Flox::User"; # Naughty.
- }
-
-This is, as the comment quite rightly points out, naughty. We're currently
-doing a C</invitation/do_edit/> and we want to turn this into a
-C</user/view/xxx>, changing the table, template and arguments all at once.
-To do this, we have to change the Maypole request object's idea of the model
-class, since this determines where to look for the template: if we didn't,
-we'd end up with C<invitation/view> instead of C<user/view>.
-
-Ideally, we'd do this with a Apache redirect, but we want to get that
-C<message> in there as well, so this will have to do. This isn't good practice;
-we put it into a subroutine so that we can fix it up if we find a better way
-to do it.
-
-Anyway, this is what we should do if a user already exists on the system
-and has accepted an invite already. What if we're trying to invite a user but
-someone else has invited them first and they haven't replied yet?
-
- } else {
- # Put it back to the form
- $r->{template_args}{message} =
- "That user has already been invited; ".
- "please wait for them to accept";
- $r->{template} = "issue";
- }
- return;
- }
-
-Race conditions suck.
-
-Okay. Now we know that the user doesn't exist, and so can create the new
-one:
-
- my $new_user = Flox::User->create({
- email => $ex{email},
- first_name => $ex{forename},
- last_name => $ex{surname},
- status => "invitee"
- });
-
-We want to give the invitee a URL that they can go to in order to
-accept the invite. Now we don't just want the IDs of our invites to
-be sequential, since someone could get one invite, and then guess the
-rest of the invite codes. We provide a relatively secure MD5 hash as
-the invite ID:
-
- my $random = md5_hex(time.(0+{}).$$.rand);
-
-For additional security, we're going to have the URL in the form
-C</invitation/accept/I<id>/I<from_id>/I<to_id>>, encoding the user ids
-of the two users. Now we can send email to the invitee to ask them to
-visit that URL:
-
- my $newid = $new_user->id;
- my $myid = $r->{user}->id;
- _send_mail(to => $ex{email}, url => "$random/$myid/$newid",
- user => $r->{user});
-
-I'm not going to show the C<_send_mail> routine, since it's boring.
-We haven't actually created the C<Invitation> object yet, so let's
-do that now.
-
- Flox::Invitation->create({
- id => $random,
- issuer => $r->{user},
- recipient => $new_user,
- expires => Time::Piece->new(time + LIFETIME)->datetime
- });
-
-You can also imagine a daily cron job that cleans up the C<Invitation>
-table looking for invitations that ever got replied to within their
-lifetime:
-
- ($_->expires > localtime && $_->delete)
- for Flox::Invitation->retrieve_all;
-
-Notice that we don't check whether the ID is already used. We could, but,
-you know, if MD5 sums start colliding, we have much bigger problems on
-our hands.
-
-Anyway, now we've got the invitation created, we can go back to whence we
-came: viewing the original user:
-
- $self->redirect_to_user($r, $r->{user});
-
-Now our invitee has an email, and goes B<click> on the URL. What happens?
-
-XXX
-
-=head2 Friendship Connections
-
-=head2
projects / maypole.git / blobdiff