Treasure Bag Design Document

 

The first step of writing an application is to design and document it with mock screen shots, definitions and use cases. Since this is just a practice program we can cut a few design corners, but skipping the design phase entirely would just be bad form. Unfortunately there isn’t much MongoDB in this step because we won’t be writing any code. You’ll just have to wait until next time. And be warned! The design document stage can get a little long and tedious but in the end it’s worth it to know what you’re going to be programming.

 

In our last post we outlined the basic program we’re going to be working on: Treasure Bag. Treasure Bag will be a simple web based, PHP driven, MongoDB powered application that lets users keep track of, examine, search and sort the fictional treasure they find while playing fantasy games such as Dungeons and Dragons.

 

Data Definition

 

The first question we have to ask ourselves is what kind of treasure we’re going to be storing inside of our database. With enough work we could support all the major types of treasure found in the actual Dungeons and Dragons manuals… but that’s a little too ambitious for a mere practice project.

 

Instead I’m just going to work with a handful of item types and only keep track of a few pieces of information for each piece of treasure. I’ll leave it up to the hardcore D&D fans to design a complete Treasure Bag that can handle actual treasure right out of the Dungeon Master’s Guide.

 

My four simple treasure types are: Weapons, Rings, Wands and Staffs. Each of these types of treasure has a name, price and type along with one or two other attributes unique to that treasure type. Here’s the list:

 

Weapon Attributes

Name: Name of the weapon

Price: Price of the weapon

Type: Weapon

Bonus: A number representing how strong the weapon is

Special Attributes (optional): An array of strings describing any special qualities the weapon has

 

Ring Attributes

Name: Name of the ring

Price: Price of the ring

Type: Ring

Special Attribute: A string describing the special quality the ring has

 

Wand Attributes

Name: Name of the wand

Price: Price of the wand

Type: Wand

Spell: The spell the wand casts

Charges: How many times the wand can cast it’s spell

 

Staff Attributes

Name: Name of the staff

Price: Price of the staff

Type: Staff

Charges: How many times the staff can be used to cast spells

Spells: An array of string listing the spells the staff can cast

 

Use Cases

 

It’s not enough to know what kind of data we’re storing. We also need to know how our users plan to interact with the program. Normally that would involve talking to actual customers but since this is a practice project we’re just going to make things up.

 

Sample User

Danny “The Dice” Mathews

 

Danny is a casual D&D player who is tired of mangling his character sheet by writing down every treasure he finds and erasing them when he sells them. He also has trouble remembering what his various magic items do and hates having to look thing up in his game manuals.

 

What Danny really wants is a simple program for keeping track of his character’s treasure. Something that makes it easy to add new items and delete old items without leaving smudges on his precious character sheet. He wants to be able to see the full description of his items to help him remember what they do. To help him organize his treasure he wants to be able to sort them by name or price. Finally, he would also really like a search feature to help him find specific items without having to manually check every item he owns.

 

Use Case 1: Viewing Inventory

 

When Danny visits the Treasure Bag main page he sees a complete list of all the treasure he has inserted into the program so far. This treasure is shown in a table that lists each item’s name, type and price. Danny will also have access to two buttons: “Sort By Name” and “Sort By Price”. Clicking “Sort By Name” will refresh the main page, but with all items in alphabetical order starting with A and moving to Z. Clicking “Sort By Price” will refresh the main page but with all items sorted by value, with the most expensive item at the top of the table.

 

Use Case 2: Viewing Specific Items

 

Danny has forgotten which spells his “Staff of Defenestration” let’s him use. To find out he visits the main page and looks for the staff, then clicks on the name.

 

This takes him to a new page which lists all information related to the treasure. In the case of the Staff of Defenestration it would look like this:

 

Name: Staff of Defenestration

Price: 10,000

Type: Staff

Charges: 23

Spells:

• Telekinesis
• Feather Fall

 

Similar results would be shown if Danny had clicked on a Weapon, Ring or Wand with the obvious difference that they would display Weapon, Ring and Wand related attributes.

 

This page is also used for removing items from Treasure Bag, as explored in Use Case 8.

 

Use Case 3: Inserting New Inventory

 

Danny has just found the mighty Orc Poker, a magic weapon with a +3 attack bonus and the Orc Bane attribute. It is worth 8000 gold. He clicks on the “Add Treasure” link in the Treasure Bag menu and is taken to a screen with a simple drop down that asks him to choose what kind of treasure he wants to insert.

 

Choosing a treasure type from the drop down will expand the form by adding fields for all the attributes associated with that treasure. For example, choosing “Wand” will add an input field for “Name”, “Price”, “Charges” and “Spell”. Input for attributes with multiple values will be comma seperated lists. For example, a staff’s “Spells” attribute input might look like “Fireball,Chain Lightning,Fly”.

 

If Danny tries to submit a treasure without choosing a treasure type or filling in all the fields a pop up message will appear and politely reprimand him. If all fields are properly filled out then the treasure will be added to the database and Danny will be taken back to the main page.

 

Use Case 4: Search By Numeric Value

 

Danny needs an extra 5000 gold in order to afford a brand new Ring of Ironskin. To help find this he clicks on the “Search” link from the Treasure Bag menu and is taken to a search from that encourages him to input a treasure name, minimum price and maximum price. There is also a drop down list that lets him choose a specific treasure type.

 

Danny leaves the treasure name and maximum price blank. He also ignore the treasure type drop down. He fills in minimum price with 5000 and hits search.

 

The page refreshes with Danny’s search terms already filled in and a table of results below it. This table takes the same form as the treasure view table on the main page, including the fact that each item name is a link that leads to detailed results.

 

In the case of the minimum 5000 search this table might include items such as the 8000 gold Orc Poker and the 10,000 gold Staff of Defenestration but it would not include a 1000 gold Wand of Magic Missile or a 10 gold Dull Knife.

 

Use Case 5: Search By Treasure Type

 

Danny used to play a barbarian and didn’t really care about magic items like staffs. But after taking a level in sorcerer he suddenly needs to know if he has any useful staffs.

 

Danny clicks on the “Search” link and chooses “Staff” as treasure type while leaving all the other fields blank. Choosing staff causes two new fields to appear in the form: “Charges” and “Contains Spell”. Danny ignores both of these as well and hits the search button.

 

Danny sees a result table listing nothing but the magic staffs in his backpack.

 

Use Case 6: Search By Text Value

 

Danny’s character is stuck in a volcano and really needs to cast “Levitate” before the rising lava manages to barbecue him. Unfortunately Danny cannot remember if he has any items that let him levitate.

 

Danny clicks on the “Search” link and chooses “Wands” from the drop down list of treasure type. This adds two new fields to his search form: charges and spell. Danny types “Levitate” into the spell field and hits search.

 

A table of results appears which only including wands that can cast levitate.

 

Use Case 7: Search With No Results or No Criteria

 

It turns out that Danny doesn’t have any wands that can cast levitate. When he hits search the area that would hold the search results contains an apologetic message of “No Items Match Your Search”.

 

In a panic Danny clears the search form and then accidentally clicks the “Search” submit button without filling in any data. He is taken to a results page with a blank search form and a full list of his treasure.

 

Danny’s character eventually gets destroyed by the lava. The character is later raised from the dead but loses one level. Danny also loses most of his treasure due to it melting.

 

Use Case 8: Deleting An Item

 

After losing his flammable equipment to the volcano Danny needs to remove several items from Treasure Bag. He first finds the item he wants to remove and clicks on its name to go to the detailed item page. At the bottom is a link labeled “Delete”. This deletes the item and then returns Danny to the main page.

 

Non-Use Case: Improvements We’re Ignoring

It would be really great to be able to search for multiple item types at one time. It would also be cool to search for partial strings, such as all treasures with names startig with “Legendary”. Plentiful use of Ajax could make updating tales and deleting items more user friendly.

 

But these things would all be a lot more work than a simple practice project deserves. But I’m certainly not going to stop you from adding them if you’re feeling ambitious.

 

Mockup Screen Shots

 

Wow! Even cutting corners and leaving out details that’s still a lot of use cases to deal with. But a good design document isn’t done until you’ve created a mock-up of how you expect the final page to work. Mock-ups range from simple wire frame sketches to photo-shopped masterpieces that include every detail of the end product.

 

Since this is just a casual practice project we’ll be going with wire frame sketches and only show one example of each major screen. For a professional project we would want to go into much more detail and probably have multiple mock-ups for pages like search and inventory that react differently based on which treasure type the user is interested in.

Tune in next time where we actually get to the MongoDB part of this MongoDB tutorial!

 

BONUS!

 

It would be really useful if Treasure Bag could be used to keep track of characters along with treasure. For extra design practice try creating data definitions, use cases and mock up screens for character management features. No need to recreate the entire D&D rule set if you don’t want to; keeping track of something simple like character name, level and class is good enough for our purposes.