Hook me up

I'm all done with classes for the week, got some time before the evening activities, sitting in the 34th & Walnut Starbucks... goals for the session are: to connect via PHP with the test database I set up on my server space - at the least to pull info from it and spit it out onto the page, if not to insert new records to the one table - and to get a few calls to the Facebook API working via the Facebook PHP client library.

First I'm checking to make sure PHP works in the first place.  I made my test.html page into test.php and threw in a call to phpinfo().  It works, so it looks like I'm good to go.  Now to figure out database access.  I created a new database user and gave the user access to the app database (which currently only has the one test table).  I'm not sure yet exactly what functionality the app will need to have in accessing the database, so I somewhat arbitrarily gave the following permissions for now: select, insert, update, delete, drop, and lock tables.

In search of a refresher on integrating a MySQL database, I came upon this more general tutorial on building various parts of a Facebook app.  (For now I am only referencing the MySQL example section.)  For organization's sake, I created a file called db_connect.php just to encapsulate the connection code.  Following the example, I inputted "localhost" as the host (following this Support Center answer) along with the user and password I just created.  I also looked up the PHP documentation for the mysql_connect function and based on the example there I added a test for whether the connection attempt was successful.  Since no error message appeared, I assume the connection worked.  The last step is selecting the particular database to use.  I added a call to mysql_select_db and a test for success.  This worked as well.

Redux: So I think I might be documenting my every action a little too carefully, because this took more time than it should for only a bit of code.  I didn't make it to actually pulling from or inserting into the database, and nowhere close to trying out Facebook API calls.  But I figured out the right parameters to connect and it worked, so I did make it that far.

Setting up the Facebook application

Luckily this task does not seem nearly as daunting to me as it might, since I have worked through the process before when I took the User Interfaces and the Web course (which was CIS 399.006 prior to the renaming of all the 399s) and my partner and I were creating a Facebook app for our project.  However, since things may have changed since then, I've decided to figure out the process again with the help of instructions and documentation, and consult my code from the prior app only if I get stuck.

Some of the basic information was easy: what to name the app (Trace Race), an email address for Facebook to use to contact me, and an email address for app users to contact the developer (which I set to the email I created while setting up my web hosting service).  There are also spaces to fill in a few callback URLs, but as I haven't created any of the pages yet, I'm leaving those blank for a moment.

The first major choice to be made was whether to build the app as an iframe or with FBML.  I found an article on the developers' wiki explaining the differences and pros/cons of both structures.  After reading this over, I decided to go with the iframe-based structure for a few reasons: it reduces the overhead for AJAX calls (which I do expect to use), it avoids the slowdown caused by reloading Facebook Chat (this happens in FBML apps because page reloads must reload the whole page, whereas iframe reloads only reload the frame), and XFBML provides a faster way to use Facebook elements or access Facebook data than making individual API calls (and I don't expect to be making many of those anyhow).

The next question was whether to use the resizable iframe option.  This allows some control over the size of the iframe as opposed to having to fit the app into a fixed-size frame.  Although I am not sure yet how large the Flash gameboard area will be, I imagine that the pages without the gameboard and the pages with the board will probably have a different-sized content area, so I will try out turning on the resizing option.  Maybe I will turn it off later once I see how the pages are coming together.

Finally (though the app isn't totally set up--have to connect the database and hook in Facebook API code), I ran the simplest of tests.  On my web hosting space I created a directory for the pages for this app and entered it as the canvas callback URL in the app settings.  I chose a canvas URL, which is the direct link to the app in the form of "http://apps.facebook.com/[name]": http://apps.facebook.com/tracerace/.  So now if you access the canvas URL, you'll see the directory index (being pulled via an iframe from my server space) and can click to the test.html page.  Sweet!

p.s. I have added a screenshot showing the test page on my server space being pulled into the app's iframe, BUT, since the app is indeed live and publicly accessible--albeit in a primitive bare-bones fashion--you can actually go to the URL and see it yourself.  (At least, I believe so--a Facebook account may be required.  I haven't tested that.)

Database planning - ER diagram and query thoughts

ER Diagram
So, with some refreshing to help out my memory of CIS 330 material, I have constructed a first-draft entity-relationship (ER) diagram for the database.  I'm the slightest bit iffy on whether I've indicated the participation and many-to-one constraints via the correct notation; see the legend (added mainly for my own reference) for my understanding of it.  I also can't remember if foreign keys should be indicated--I seem to recall that they should be given a dashed underline, but I left that out because I'm not sure.  At any rate, I've unconventionally included a bunch of extra notes (including mentions of the foreign keys) to provide further explanation and clarification.

Additional iterations and modifications of this setup are of course likely to occur.  I will try to post updated diagrams as they do.  (Maybe I'll make this into an Illustrator file, but for now, it was easiest for me to work it out in my head and put it directly onto paper.)

Please please click on the image to see it in full size... it's quite difficult to read at the embedded size.

Queries
While I'm thinking about it, here's a very preliminary and unfinished list of SQL queries I'll need to figure out...  (Capitalized terms are entity names; terms in single quotes are attribute names.  I don't know if that's correct syntax, but it's simple notation for myself and readers.)

• Get all Users currently logged in but not playing a game
• Get all default Tracks
• Get all Tracks created by a User
• Get all Tracks... [should I allow access to tracks created by other users?]
• Create a new Track - store the 'filepath', associate with a 'creator' = User.fb_id
• Create a new Game - associate a Track, a User.fb_id as organizer, and 'in_play' = false
• Add Users (unconfirmed) to a game - 'joined' = false
• Confirm a User's participation in a game - set 'joined' = true
• Set (update) a player's position on the game board grid - change 'xpos' and 'ypos' for given User.fb_id
• Get the player whose turn it is now/next
• Delete a Game when it's finished - this will include removal from Game table and all entries with that Game.id in player_group

Implementation Breakdown...

Pardon the rambling nature I expect this post will assume...  I just want to try to really break this grand plan in my head down into rather small, manageable chunks so that I can actually get them done.  Some brainstorming ideas will also be here.  Post is subject to later editing. :)

Note: items listed within brackets, [ ], are things I am considering but not sure whether I will ultimately implement.

Database
What it needs to include:

• all currently logged-in users (so you can see who's available to start a game with)
• [all users ever? - only if I want to include saved information on a user's past activity]
•  [location pointers to stored screenshots of past games]
• location pointers to stored game board (track) files - both the default/provided ones and the user-created ones
• games currently in progress: the group of users who are playing together; whose turn it is; locations on the board of each player.  note: include some kind of tag for games not yet started, players invited vs. accepted, and user who started game (becomes 'organizer')

Steps:

• draw out the schema
• create db, add tables and relationships
• add some test data
• write out the queries for the above functionality
• code queries in PHP, test

Interface
Elements/pages:

• navigation...
• introduction, maybe combined with help/about page
• list of users currently online (split to show your friends and non-friends)
• list of games not yet started and open to players joining (as opposed to closed/invite-only games)
• sequence of pages or steps on a page to set up a new game: selecting a premade track or [a saved track of yours] or design a new track, decide whether to open your game to any users or invite certain users, choose symbol markers
• main gameplay page - the Flash gameboard, list of the players, their symbols, whose turn it is
• post-game display... [stats? save this game screenshot?]

 Steps:

• diagram of navigational flow through pages / solidify pages
• and similarly, decide what to put in main navigation
• sketches of interfaces
• mockups of interfaces (html etc.)

Flash game board area
Functionality:

• display pre-made static image (blank grid on which to draw a new track; pre-made tracks on grid)
• user drawing a new track [check for invalid tracks - e.g. unclosed loops or lack of inside and outside boundary...?]
• detect user clicks and localize them onto gridpoints (for players to take their turns)
• display new overlaid graphics (player symbols on gridpoints, showing possible locations for next move)
• determine whether a move would be out of bounds - for each potential new position, I'm thinking of drawing a line (possibly invisibly within the code?) from current player position to new position, and seeing if that line intersects with the track boundary; perhaps store some key information regarding the track boundaries when it's created, and use start and endpoints of these lines to compare...
• output/save entire game board as a static image (for saving new tracks and/or completed games)

Facebook integration
Steps:

• Set up a new Facebook application
• Connect outside hosting/database
• Run some tests to make sure FB API hooks up
• After or as mockups are being built, convert into FBML, FBJS, etc.

Long-awaited story boards!

[EDIT: Ah, crap, the images are far too wide for this skinny column.  Click them to see the full image, so that the explanations make sense.]

The aim of these diagrams - which are not necessarily intended to represent proposed visual design - is to show the progression of a sample game at various points.  So here we go:

Initialization
Set up requires choosing a provided closed-loop racetrack (of relatively consistent width) on grid paper, or drawing one yourself.  A start/finish line and direction of travel (see the arrow beside the start line) are decided upon, and each player chooses a symbol and selects a position on the start line.
The possible first moves are shown (for the blue-circle player) as filled blue circles.  Since clearly they have not started moving - a speed of (0,0) - their next move can have a speed of -1, 0, or 1 along each axis.  All possible moves are shown here for completeness, but obviously, you would never move backwards behind the starting line.

Getting going: how to move
At this point, each player has taken 3 moves, and the options for the fourth move are shown for each.  (Dual-color circles indicate that that point is an option for both of those players.)  The basic rule is that for any move, a player can hold constant or change by 1 the number of points to move along each (horizontal and vertical) axis.
For example, if in the prior turn, a player moved (3,2) in (horizontal, vertical) movement, their next move could be any of these options (within bounds): (2,1) (2,2) (2,3) (3,1) (3,2) (3,3) (4,1) (4,2) (4,3)
Note a couple things:

• Players cannot occupy the same grid point at the exact same time.  (BUT, any player can occupy a point that was occupied in a past move by another player.)  Taking a grid point that would be ideal for another player's move could be a strategy.
• Players are not allowed to move to grid points outside the track (obviously).  Clearly, here, the green and blue players have a decreased set of options.  Grid points exactly on the border of the track are considered in-bounds.

Stuck
Now each player has taken 6 moves.  The red player did not think ahead enough and has created a situation in which all possible next moves are located out of bounds.  At this point I have not decided how to handle this situation, but I do not think cutting the player out of the game from then on is ideal.  That's no fun.  I may decide to require some sort of backtracking to a prior position.

The end: finishing/winning
Here, the completion of the game is shown (except the blue-circle player, left out to make the example easier).  Assuming that the red and green players were taking the same turn at the bottom-right of this quadrant of the diagram, notice that 14 moves for each are shown here.  Since the red player reached the start/finish line (and the green player has not yet), the red player wins.
Notice this diagram includes an example of players occupying the same grid point at different times in the game: the green player's 10th move on this diagram is the red player's 8th move.