InkTank

Project Info | Installation Guide | Object Diagram

Introduction to InkTank's Architecture

In designing InkTank, I tried to write PHP in a Cocoa, object-oriented style. The result is an architecture that makes InkTank clean, well-defined, and easy to understand—at least, I like to think so. Here's a system object hierarchy diagram.

Object hierarchy... just download this one

To create a page, three main objects are involved. First is an ARPage subclass instance, which generates the body HTML. Second is an ARInfoPanelCollection instance, which contains a set of ARInfoPanel subclass instances which generate the information boxes down the right hand of the page. Bringing it all together is an ARContainer instance, which prints the header, footer, and puts the HTML generated by the ARPage and ARInfoPanelCollection in the appropriate places An ARGhost instance helps violate a strict adherance to the object hierarchy by storing messages (objects) set by the ARPage and later used by ARInfoPanel subclass instances. For example, to save an extra SQL query, the ARInfoPanel that displays information about a story re-uses the ARAuthor object that the ARPage that displays the story used to print the author's name and e-mail.

One level deeper, on the right there is an object hierarchy diagram beneath the author list page, an ARPage subclass. Beneath it is an ARStoryCollection, which contains ARStory objects, which have even more objects underneath them. This particular ARPage uses an ARAuthor instance to display the number of stories an author has written, along with his/her e-mail address. It uses an ARStoryCollection to display the list of the author's stories. The ARStoryCollection contains ARStory instances for each story displayed. Essentially, the ARStoryCollection prints the skeleton list, the ARStory instances print the cells displaying information about each story, and the ARPageAuthor coordinates all that.

Read all that? Excellent, you now have a better grasp of how I thought while designing InkTank. Now, here's a list of all the objects of each type InkTank uses. Happy contributing!

Master Objects

InkTank's core objects are listed here. In general, they have the ability to track the identification numbers (unique keys) of the rows of item information they store as separate from the data themselves. This is perhaps best illustrated with the search results page. If a user's search results contain a hundred items, an ARStoryCollection is populated with only the story IDs. Then, the story descriptions and metadata are only downloaded for the particular page of results the user is looking at. This helps with efficiency.

Here is a list of the master objects and what they do:

ARAuthor Contains information about a single author—name, author description, e-mail. Can look up the author story count and a list of genres the author writes.
ARAuthorCollection Manages a set of ARAuthor objects, and used on the author list pages. Contains and manages a set of ARAuthor objects. Can initialize multiple ARAuthor objects from a single query.
ARAward Describes a single award—a row from the awards table. Will in the future be able to save its data back to the datastore.
ARAwardCollection Manages a set of ARAward objects, as displayed in the Awards InfoPanel.
ARCharacterCollection Manages a set of characters. There's no associated ARCharacter object. An ARCharacterCollection can download a list for a specific story, or from a provided query result. It discriminates between pairings and character rows and can return a string representation of either.
ARColor An ARColor object can calculate tints and shades of n-bit colorsby additive and mean methods. It returns hexadecimal for 24-bit web colors and HTML colorboxes for genre tint legends.
ARContainer An ARContainer coordinates an ARPage and ARInfoPanelCollection—it draws a single InkTank page using both.
ARGenreCollection ARGenreCollection objects simply store a list of genres. They return HTML and text descriptions, highlighting a story's primary genre.
ARGhost The ARGhost spares us functions polluting the global namespace. It performs various tasks, including acting as a message postbox, and various string beautification functions.
ARInfoPanel ARInfoPanels are the boxes you see on the right of InkTank pages. Ths master ARInfoPanel is their superclass, defining their protocol.
ARInfoPanelCollection ARInfoPanelCollections contain a set of ARInfoPanel objects, and they coordinate printing them out for an ARContainer.
ARPage ARPages are the left side of InkTank pages. They display all important content. The master ARPage is a skeleton protocol.
ARRatingManager The ARRatingManager manages story ratings. It can be used to limit certain copies of InkTank to only displaying certain ranges of stories from a single database. ARRatingManager rules are global and hard-coded.
ARStory ARStory objects represent a single story or work. Each instance contains an ARAwardCollection, ARGenreCollection, and ARCharacter collection. They can download data individually, and are often contained in an ARStoryCollection.
ARStoryCollection ARStoryCollection objects contain a list of story IDs and populate their array of ARStory objects as required for certain sections of their sets. ARStoryCollections can save their results to a file to preserve the list of story IDs, say, from a specific advanced search.

Datastructure Subclasses

Master objects only contain barebones presentation code, if any. To provide for prettier pages, many of them are subclassed as –IK objects. These subclasses contain load more presentation code.

ARAuthorIK Prints source for Author List entries.
ARAuthorCollectionIK Prints source for Author List lists.
ARAwardIK Prints graphical badges, banners, and award list table entries.
ARCharacterCollectionIK Prints character lists in a less technical manner with " and "
ARContainerIK Prints page headers and footers along with content.
ARGenreCollectionIK Prints genre lists plus the tinted primary genre boxes.
ARGhostIK Prints tint legends and contains site-specific variables.
ARInfoPanelCollectionIK An ARInfoPanelCollection that can print headers in site theme style and is populated with a default set of site-appropriate ARInfoPanels.
ARRatingManagerIK Handles "all but ratings in manager" blocking style.
ARStoryIK Prints story boxes as appearing on author and search result pages.
ARStoryCollectionIK Multi– and single-column lists of ARStory (or a subclass) objects.

ARPage Subclasses

The main display pagesin InkTank are all subclasses of ARPage. The .php files lying around the root of the site simply invoke ARContainers and fill them with specific ARPages.

ARPageAuthor Author pages, giving a list of an author's works.
ARPageAward Award pages, displaying award banners and lists of recipients.
ARPageBrowseAuthors Browse author pages, either for a letter of author's name or a listing of every story in the database.
ARPageLinecount Prints the number of lines in every InkTank object.
ARPageManageAwards Provides web support for delegating awards—so awarders don't need to have the database password through Archangel.
ARPagePairing Lists all stories with a specific character pairing.
ARPageSearchResults The code to execute a search and display its results.
ARPageStaff A flat staff listing page.
ARPageStory The page for a single story. Displays the story and adds appropriate boxes to the container ARInfoPanelCollection.
ARPageSubmissions A flat submission guidelines page.
ARPageTesting Free space for development testing use.
ARPageWelcome The welcome page, including a list of new stories in the last n days.

ARInfoPanel Subclasses

ARInfoPanel subclasses are the boxes you see down the right-hand side of InkTank pages. They are managed by an ARInfoPanelCollection or its subclass.

ARInfoPanelAboutStory Author name, storycount, link to index page,story metadata.Gets its author information from the ARGhost.
ARInfoPanelAuthor Author name and story count. (Merged into ARInfoPanelAboutStory)
ARInfoPanelBrowseauthors Alphabet array for browsing authors.
ARInfoPanelBrowseAwards List of awards with links to award recipient pages.
ARInfoPanelBrowseNC17 Alternative ARInfoPanelBrowseauthors for sites with few authors. Links to a list of every author on one page.
ARInfoPanelQuicksearch Search box for author/title/summary whether slash or no, link to advanced search.
ARInfoPanelStory Story metadata. (Merged into ARInfoPanelAboutStory)
ARInfoPanelWelcome Site logo and welcome message displayed on every page.

Libraries and Non-OO Fun

What the ARGhost can't handle (or what I needed before I had a ghost) is in libraries, all located in /libs.

dbabs-mysql.php Database abstraction routines against MySQL.
dbabs-pgsql.php Database abstraction routines against PostgreSQL (which I much prefer.)
init.php Initialization code. include()s every object. Sets a few global variables.
misc.php Encodes/decodes story names (spaces <> underscores), sanitizes for the database SQL, and converts integers to pretty, capitalized strings.