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.
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!
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. |
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. |
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 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. |
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. |
