User:Mrtorrent

Gallery 2/Zen Cart Integration

Summary

The primary purpose of this project is to allow the sale of Gallery items through a more powerful e-commerce application (Zen Cart). Users will be able to provide and configure a variety of product options, shipment options, and payment options, while having their Gallery items automagically connected to Zen Cart's product management and shopping cart.

Schedule

A detailed implementation schedule is available at http://themikecam.com/downloads/zcg2schedule.html

Original Proposal

Synopsis

An integration of the Gallery 2 web-based media management software with the Zen Cart e-commerce application to provide both a powerful media storage back-end for any e-commerce site and to enable the easy sale of Gallery images via a powerful e-commerce engine.

Community Benefits

While all integrations hold the possibility of bringing more users and contributors to Gallery from other communities (and vice versa), this integration has the unique possibility of appealing to and drawing in the business users of e-commerce applications. As can be seen by past examples, including the Internet itself, capturing the imagination and resources of the business community can help vault a project to even greater heights, by virtue of added time and money. Although Gallery does have a small business user base in the number of professional or semi-professional photographers using Gallery to sell their photos, the built-in shopping cart is relatively simple and demand is high for advanced features, from payment processors to shipping modules to sale options. Integrating Gallery with a full-fledged e-commerce application that fulfills their needs would draw in much more of this strong demographic. Perhaps even more importantly, however, an integrated Gallery installation could be the powerful media-management solution that all open source e-commerce applications are lacking. By filling this gap, Gallery would become instantly useful and interesting to every e-commerce site. The potential influx of business users could mean an incredible growth in the popularity and support of Gallery.

Deliverables

A release-quality integration of Gallery 2 and Zen Cart, including user/group synchronization, integrated configuration, uploading, selecting, and displaying product images within Zen Cart using the GalleryEmbed API, and the ability to insert single images or entire albums from Gallery as actual products.

Project Details

The first consideration in this integration is, of course, what e-commerce application to integrate with. Unfortunately, there are a limited number of complete open source e-commerce solutions. The de facto choice for some time has been osCommerce, but it has been experiencing team and community trouble and has not seen a new release in over two years. In my research, I have come across a fork known as "Zen Cart" that seems to be under more active development, already having completed several point releases over the past year. Further, Zen Cart has made important steps towards implementing a more flexible architecture, including preliminary separation of logic from presentation, and preliminary plug-in work by way of template overrides and auto-loading directories. These considerations indicate to me, then, that Zen Cart would make the best choice. It will require a little further familiarization on my part, because although I have used and hacked osCommerce previously, Zen Cart is a fork that has made progress from the osCommerce base. Depending upon what I learn from my in-depth look at Zen Cart, the actual implementation can go in either of two ways. Ideally, Zen Cart's framework can be used and Gallery will be plugged in where necessary, hopefully utilizing Zen Cart's template override and auto-loading directory systems. From my knowledge of osCommerce, however, I know that there is no plug-in system in place to easily add new features and, while Zen Cart has taken some steps in the right direction, it may still very well not be enough. If this proves to be the case, a sort of "wrapper" entry point, whereby Zen Cart functions are called but fed preprocessed Gallery data as necessary, may be possible. The first step in the actual integration will be to provide for automatic synchronization of users and groups between Gallery 2 and Zen Cart, as well as synchronizing appropriate configuration options, such as product thumbnail sizes, etcetera by reading the Zen Cart variables. The next step will be to seek out and replace or override all instances of the built-in media manager with calls to Gallery upload, insertion, and view functions. Finally, images or albums must be made easy to add as actual products, preferably with options for download and/or prints of varying sizes. This will be accomplished by implementing a wrapper function that calls the appropriate Zen Cart routines to insert the selected Gallery images as products. Ideally, this will be available both as a point-and-click interface as well as an automated procedure called in response to a GalleryEntity::Save event on a STORAGE_FLAG_NEWLY_CREATED item in a designated album.

Project Schedule

As I am on my summer break from university, I am available to immediately begin execution of my proposal. My projected time line, spanning the two months allotted, is as follows:

• Further familiarization with Zen Cart: 1 week
• Integrate Zen Cart's configuration and users/groups with Gallery: 1 week
• Replace Zen Cart's media back-end with Gallery 2: 4 weeks
• Make Gallery albums and images addable as products: 3 weeks

Bio

I am an honors student studying at Arizona State University and a National Merit Scholar with junior (third year) class standing after one year of university. I have been using computers all my life, from MS-DOS and Windows 3.1 to the present, as well as running and administering Linux machines for the past five years. I have been designing web pages for nine years, including five years professionally. My first foray into programming was with Visual Basic seven years ago and since then I have studied and utilized Perl, PHP, and C++. For two years, I was active in the the Perl-based YaBB and the PHP-based YaBB SE open source forum software communities, contributing new feature hacks, providing support, and helping lead development on YaBB 2. For two years after that, I practiced web design and development professionally, including several integrations of Gallery 1 into client sites. Last fall, I contributed code to the saa7134 Linux kernel module to add support for a new TV tuner card. Most recently, I have added functionality to and rewritten much of the script to import data from a b2evolution-based blog to WordPress, as well as contributed some code to the wp-gallery2 plug-in for WordPress and Gallery 2. Outside of the technical, I have excellent communication skills honed by theatre acting work and two years as an independent web designer pitching proposals to businesses. While I have an array of skills that will be useful in implementing my proposal, I also hope to learn a great deal, particularly about development methodologies and organization, as it is an area that I have had limited long-term experience in, but in which the Gallery project excels. For the past week, I have been visiting the Gallery IRC channel, talking with the developers, and exploring the Gallery 2 API to bring me up-to-date from Gallery 1. They have already begun teaching me the value of test-based development and have been happy to educate. I believe this is a team I can work well with, learn from, and to whom I can deliver a quality contribution.

User Stories and Scenarios

These are two user scenarios, one from an admin perspective and one from a visitor perspective, broken up by user stories.

Alice the Admin

Alice is a semi-professional photographer who has a working Gallery 2 that she uses to display her photos. She would like to make money from her photos, videos, and other G2 items by selling them online. She wants to set her own prices, provide a variety of payment and shipping options, and designate purchase options for the products, such as print sizes, print finishes, downloads, and CD-ROMs.

"Alice uses the ZCG2 module's site admin page to enter the path to Zen Cart."

• Alice clicks "configure" after installing the ZCG2 module, which loads a page with a text field where she enters the path to Zen Cart and then clicks "Verify."

"Alice uses the ZCG2 module's site admin page to select a ZC category where G2 items will be inserted as products"

• Once the Zen Cart directory has been located, Alice is presented with a drop-down list of the categories in her Zen Cart. She selects one called "Photos" where she would like her Gallery products to be added.

"Alice uses the ZCG2 module's site admin page to view current product options."

• Next, she decides she wants to configure the pricing, so she clicks on "ZCG2" in the "Admin Options" column, then the "Product Options" tab at the top of the config area, which is next to the "Settings" tab. She is presented with the list of product options for G2 items, which consists of several defaults that were preloaded upon activation. Alice sees a three-column table. The first column lists the names of current product options for G2 items, such as "Size" and "Finish." The second column lists option type (drop-down, text, radio, checkbox, file, read-only), and the final column has "delete" links for every option.

"Alice uses the ZCG2 module's site admin page to add a product option."

• Below all the current G2 product options is a small horizontal form to add options, with one text box for the option name, a drop-down list for the option type, and an "add" button. Alice types in "Frame" as the option name, selects "drop-down" as the option type, and clicks add. The page reloads with a message from the system at the top saying "The option was successfully added." Below it is the Product Options table with her new option at the end.

"Alice uses the ZCG2 module's site admin page to delete a product option."

• Alice decides she won't be offering a choice in finishes, so she clicks the "delete" link in the "Finish" row. The page reloads with with the text "The option was successfully deleted" at the top of the config area. Below it is the updated Product Options table.

"Alice uses the ZCG2 module's site admin page to view current option values."

• Alice needs to add some choices for her new "Frame" option, so she clicks on the "Option Values" tab at the top of the config area, which is next to the "Product Options" tab. She sees the four-column table of option values, preloaded with some defaults. The first column lists the parent option name (Size, Finish, etc.), while the second column lists the option values, such as "8x10" and "Glossy," and the third column lists the price associated with the value, and the fourth lists the weight if any.

"Alice uses the ZCG2 module's site admin page to add an option value."

• Below the last row of the values table is a four-part form with a drop-down list to select the option name, a text box to enter an option value, a text box to enter a price, a text box to enter a weight, and an "add" button. Alice selects the "Frame" option, decides she wants to keep it simple, and enters a value of "Yes," a price of "5," a weight of ".1" and clicks the "add" button. The page reloads with the text "The value was successfully added" at the top and the updated Option Values table below.

"Alice uses the ZCG2 module's site admin page to delete an option value."

• Alice won't be offering 4x6" prints, so she clicks "delete" in that row on the Option Values table. The page reloads with the system text "The value was successfully deleted" at the top.

"Alice simultaneously adds items to her Gallery and products to her Zen Cart."

• Alice adds some items to her Gallery completely as usual. When she visits her Zen Cart, she is delighted see that they have magically appeared there as well!

"Alice edits an item's properties."

• Alice, being the editorial type, tidies up the description copy on one of her best-seller photos in Gallery just as she normally would. When she checks on the item in Zen Cart, the description matches the one she entered in Gallery.

Bob the Buyer

Bob is looking to buy a couple photos of himself dancing with a hot bridesmaid at a wedding that Alice photographed and is directed to her online gallery of photos. He wants to buy a few wallet photos to show off to the guys and a big 8x10" that he wants to overnight through Fedex so he can put it on the wall in time for his parents to come over for dinner and see that he's not a loser. (okay, I had a little fun with this one... -Mike)

"Bob browses an album view to see Gallery items, starting prices for each, and the choice to buy each."

• Bob clicks on the album for the wedding he attended. He sees the first page of photos arranged on his screen with links entitled "Buy ($2.99 & up)" under each.

"Bob visits the Zen Cart product page for a Gallery item to view product options and pricing."

• Bob clicks the "buy" link under a photo he likes and a Zen Cart product page for the photo loads. He sees the photo title, thumbnail with link to "larger image," starting price, and textual description. Next to "Please choose:" he also sees a couple drop-down lists with product options such as "Print Size" and "Print Finish," a text box to enter quantity, an "add to cart" button, and a "Return to album" link.

"Bob looks at a Gallery item view to see a better preview, the starting price, and the choice to buy it."

• Bob decides he wants a better look at the photo, so he clicks on "larger image." Bob finds himself back in Gallery viewing a larger version of the photo he's interested in. Below it is a link entitled "Buy this, starting at $2.99." He decides he does want this photo, so he clicks the link, which brings him back to the ZC product page.

"Bob chooses his product options for a Gallery item and adds it to his cart."

• Bob makes his choices from the drop-down options list and clicks the "add to cart" button. A new page loads and he sees the contents of his shopping cart with various options to manipulate it, such as changing quantities, estimating shipping, and checking out.

"Bob moves from a Gallery page to checkout."

• After looking over the rest of the thumbnails, Bob decides there's nothing else he'd like to buy, so he clicks "checkout" in the Gallery menu on the left and is brought to page beginning the checkout process, which is handled by Zen Cart.

Use Cases

These are some stripped-down use cases, without all of the preconditions, postconditions, and various other sections. My purpose is to document and plan the basics of what the system has to do in the background in order to make this module work.

Configure Zen Cart path

• Precondition: Module is installed
• Trigger: User clicks "configure" on the modules page
• Trigger: User clicks "ZCG2" on the site admin menu
• Main path:

1) The user enters the path to his Zen Cart installation.

2) The system verifies that the directory exists, the Zen Cart portion of the module's files have been uploaded, and the config file exists.

3) The system stores the module setting, returns success, and moves to the next step.

• Exception path:

3) The system returns failure and reports what cannot be found.

4) Go to step 1 (Main path)

Select Zen Cart category

• Precondition: Configure Zen Cart path success
• Trigger: Configure Zen Cart path
• Trigger: User clicks "ZCG2" on the site admin menu
• Main path:

1) The system lists all ZC categories.

2) The user selects a ZC category.

3) The system checks if this is a category change or the first-time selection.

4) If it is a change, update the parent ID of all direct children of the category to the new ID.

5) The system stores the module settings and returns success.

• Alternate path:

3) The user has not chosen a different category.

4) The system returns the user.

Activate module

• Precondition: Configure Zen Cart path success, Select Zen Cart category success
• Trigger: User clicks "activate" on the modules page

1) The system adds "product_gallery" as a product type to the Zen Cart database and adds some default product options and values.

2) The system recursively adds albums as categories and items as products under the selected ZC category.

3) The system returns success.

View product options

• Trigger: User clicks "Product Options" tab in the ZCG2 site admin view
• Main Path:

1) The system displays all product options with a "[G2]" prefix.

Add product option

• Main Path:

1) The user enters an option name and selects an option type.

2) The system stores the option in the ZC database with "[g2]" as the products_options_comment to act as an identifier.

3) The system returns success.

Delete product option

• Trigger: The user clicks "delete" next to a product option
• Main Path:

1) The system deletes all option values associated with the option.

2) The system deletes the option.

3) The system returns success.

View option values

• Trigger: User clicks "Option Values" tab in the ZCG2 site admin view
• Main Path:

1) The system displays all option values whose parent option has a "[G2]" prefix.

Add option value

• Main Path:

1) The user enters an option value, and selects a parent product option, and enters a price.

2) The system stores the option value in the ZC database.

3) The system adds the option value to all current Gallery products in ZC.

4) The system returns success.

Delete option value

• Trigger: User clicks "delete" next to an option value
• Main Path:

1) The system deletes the option value.

2) The system returns success.

Add Gallery AlbumItem

• Trigger: User creates new AlbumItem in Gallery
• Main Path:

1) The system detects the event.

2) The system adds the album to Zen Cart as a category, using the Gallery title, description, and thumbnail.

Add Gallery DataItem

• Trigger: User adds a new DataItem to Gallery
• Main Path:

1) The system detects the event.

2) The system adds the DataItem to Zen Cart as a product, using the Gallery title, description, thumbnail, item view URL as product URL, and Gallery item ID as model number.

3) The system adds the G2 product options, values, and prices to the Gallery product.

Update Gallery item

• Trigger: User edits Gallery item title, description, or thumbnail
• Main Path:

1) The system detects the event.

2) The system synchronizes the title, description, and thumbnail of the Gallery product (if DataItem) or category (if AlbumItem) in Zen Cart with those in Gallery.

Delete Gallery item

• Trigger: User deletes a Gallery item
• Main Path:

1) The system detects the event.

2) The system removes the deleted item from Zen Cart and any sub items (<-- is this necessary or are multiple events posted?).

View AlbumItem in Gallery

• Trigger: User browses to an AlbumItem or DataItem (Gallery generates item links with getItemLinks)
• Main Path:

1) The system gets the default starting price for a DataItem.

2) The system displays the default starting price at the top of the page.

3) The system generates "buy" links for each DataItem displayed.

View DataItem in Gallery

• Trigger: User browses to a DataItem
• Main Path:

1) The system gets the starting price for this specific DataItem.

2) The system generates a "buy" link for the DataItem including the starting price.

• Alternate Path:

1) The system cannot find the corresponding ZC product for this DataItem.

2) The system does not generate or display a "buy" link.

Navigate to Zen Cart product page

• Trigger: User clicks "buy" link in album view or item view
• Main Path:

1) The system controller for redirecting to a ZC product is invoked.

2) The system looks up the product ID by model number (== Gallery item ID).

3) The system generates a Zen Cart URL and redirects to the ZC product page.

View Gallery item Zen Cart product page

• Trigger: User has navigated to a Gallery item ZC product page

1) The system retrieves and renders title, description, thumbnail with link to Gallery item view, and link back to album.

2) The system strips the "[G2]" prefix from all options and renders them, as well as an "add to cart" button.

/dev/random

Extended

1. More G2 module features
   1. Display different options depending upon the type of Gallery item
   2. Re-order product options and values
   3. Select specific albums for sale
      1. "Alice uses the ZCG2 module's site admin page to select under which Gallery album items will be automatically synchronized as products."
      2. Beneath the list of ZC categories is a drop-down list of G2 albums. Alice leaves the default "All" selected, so that all items in her Gallery will be synchronized as products, and clicks "Save." After saving her settings, Alice clicks "activate" next to ZCG2 on the modules page to enable the module.
   4. Choose quantity in Gallery?
   5. Choice of displaying options in album view or product/item view
   6. If no options in album view, choice to display "Buy this!" link
   7. If "Buy this!" link, choose whether to point to product page or item view
   8. Widget (link?) to return user from a product page to viewing the album he came from.
   9. Replace strings with variables for localization.
   10. If moving from a product page to a Gallery item view, change "buy this" link to "return to purchase"?
   11. Remove all Gallery items from Zen Cart.
   12. Change pricing per-album or per-item from Gallery.
   13. Automatically assign different options/pricing to an item based on its type.
2. Replace Zen Cart image manager with GalleryEmbed

UI Design Decisions

1. References
   1. http://printbutton.photobox.co.uk/printbutton.html?v_id=120875&product_id=display_popup&buy=15-78-19%26t%3D2
   2. http://www.dpcprints.com/print.php?IMAGE_ID=129695
   3. http://www.torrentphoto.com/gallery/WassermanFire
   4. G2 paypal module
   5. http://www.highpulse.com/G2/main.php
   6. http://www.mrx.no/Canada-West-Coast-June-2005/Time_to_land.html
2. Choices
   1. Direct buy links to ZC product page and display product options there.
   2. Display only "Buy" and price on album and item views.