Shopping Cart for Director

May 19, 1999
by Jim Rudnick

For those of us who surf the web daily, it's been hard lately not to notice the vast number of websites that are selling something to visitors and using what's become known as a Shopping Cart to help that task along. The procedure of collecting a list of items for the visitor to view before proceeding is something that we Director developers also have needs for, hence this article which will attempt to show the conceptualization of the Shopping Cart function and the actual code used too! Bear with me a little upfront, as we work through the ideology, and then move on to the code -- though for those of you who want to go off on your own, a complete movie that shows all functionality is at the bottom of this page.

To begin with, a Shopping Cart is a basic method to show the website visitor or the CD-ROM user just what selections they've made so far. It should allow the user to see a list, however formatted, that bears a direct correlation to the items previously selected....a 'vetting' of that list is what occurs at that time. It should also allow the user to change a selection, and finally to 'okay' the list and complete the transaction -- which for us CD developers means the user is now ready to download the list of files to their own hard drive as in our example here.

This whole article and the resulting movie you can download below are taken from recent projects I've just completed for SAAB US and Mercedes-Benz. Both companies wanted to produce CD-ROMs for distribution that would allow their targeted user to make selections of files (installed on the CD) for download to the user's hard drive. While both projects had relatively small numbers of files, this Shopping Cart methodology could very easily be re-worked to handle hundreds and hundreds of files (CD-ROM space permitting) of all types as the code is basically straightforward in its operations. All one has to do is to expand the viewing of the associated onstage information to allow the user to a make a choice, and expand the final download screen to hold scrolling fields to show all of the user's choices, simple and neat!

This Shopping Cart task then is the putting together of a list of files for downloads that many of us have faced before, and while there are many opportunities to do just that, the method we'll discuss here will entail creating a simple linear list, having the user 'vet' that list, then download same.

Our first job, entails the creation of our linear list with a cautionary note...that the list must be exact when it comes to the names of the files that are to be included on the CD for downloading. Director will attempt to do as it's asked when it comes to downloads, so our code also checks for the correct files when asked to. But failing that, the simple creation of the linear list is the first step.

Here are the pertinent parts of the movieScript that I created for the movie below...let's look at the part that details the creation of the linear list by going over the first item to be shown to the user...

Item Name: "Company Logo"
Item Description: "Black Logo Against Gray"
File Name: "LOGO1.pct"
File Format: "Mac File"

As you can see, the data is relatively simple, all one has to do is to put that data into what I call a 'compartmentalized' linear list format as below...


[["Company Logo", "Black Logo Against Gray","LOGO1.pct", ¬
  "Mac File"]]

Now, I'll have to set a global value to that list....and here I used my standard global naming custom...


set gFileList = [["Company Logo", "Black Logo Against ¬
  Gray","LOGO1.pct", "Mac File"]]

And once that's done, all I have to do is to add in the 4 other items using the SAME standard linear list tags...


set gFileList = [["Company Logo", "Black Logo Against Gray",¬
  "LOGO1.pct", "Mac File"], ["TV Logo", "Black Logo Against ¬
  Pale Salmon", "LOGO2.bmp", "PC File"], ["Black 3D Logo", ¬
  "Black 3D Logo Against White", "LOGO3.pct", "Mac File"], ¬
  ["CD-ROM Logo", "Gray Ghosted Logo", "LOGO4.bmp", "PC ¬
  File"], ["Advert Logo", "Lo Res Logo for Adverts", ¬
  "LOGO5.pct", "Mac File"]]

As you can see, what I've finished above is to create a global (called gFileList) and equated it to a linear list, that is composed of 5 seperate entities...each one broken down into 4 component parts. Take for instance my first item, called "Company Logo." Note, that it is described as being a "Black Logo against a Gray background", that the name of the file is "LOGO1.pct", and that it is a "Mac file" format-wise. This is important, as each of the items that the user may look over to decided if they want to download same to their hard drive, must be shown in this similar format...hence that format was used to describe each of the items in that simple linear list. The fact that I'm only using 5 items here, is of no importance. You can create a linear list that holds 5 or 50 or 500 items...the total number of items is not important, only that everything uses the same 'compartmentalized' format.

Once our list is created in our movieScript, then our next task is score work, the layout of the items on stage to allow the user to make choices. In the movie below, you'll note from this screen shot, that I simply put the five logos in a column along the lefthand side of the stage. Note that this is relatively easy, you can choose any way at all to let the user see the items (or thumbnails if you prefer) to enable a wise choice...

Next, I had to decide for this little movie just HOW the user would be able to signify that they'd made a choice. While I picked the simple text sprite that says "Click here to select the 3D logo" you could have also made the little thumbnail logo a 'clickable' sprite...or used a scrolling text field that tracks the mouseLine to make a selection. The opportunities here are many; while I chose the one that was most explanatory, you may use your own creative here to show off your own choice! As well, the lingo used is quite simple, yet it works just fine! Let's take a look at the lingo used to add the first item, the Company Logo to the download list...

SpriteScript: for Click here to select the 3D logo button...
on mouseUp
  global gLine, gFileList
  -- two variables to track the user choices..
  
  set gLine = getAt(gFileList, 1)
  -- run to the list, and get the data on 
  -- the first item (Company Logo) described...
 
  set numFiles = the number of lines in field "itemFile"
  -- determine how long the file list is so far...
  repeat with x = 1 to numFiles
  
    -- how many items are already in the shopcart list...
    -- they must all be checked to see that this 
    --item is NOT already there...
    
    if gFileList[1][3] = line x of field "itemFile" then
      -- track by filename only, as they are 
      -- all different for sure!
      set okay = FALSE
      exit repeat
    else
      set okay = TRUE
    end if
  end repeat
  
  
  if okay = TRUE then
  
    -- okay to add this item to the list...
    put (gFileList[1][1] & RETURN) after member "itemName"
    put (gFileList[1][2] & RETURN) after member "itemDesc"
    put (gFileList[1][3] & RETURN) after member "itemFile"
    put (gFileList[1][4] & RETURN) after member "itemFormat"
    -- set the onstage fields to show the 4 items so picked...
    
  end if
  
  set the memberNum of sprite 36 = member "Logo1.psd.S"
  
  -- switch the castmember so it now shows 
  -- that this item has been selected via the 
  -- selected word appearing on logo
  
end

As well, when the user has determined that they've made a mistake, and wish to delete an item from their download listing, all they have to do is again, click on the text sprite that says Click here to select the 3D logo from the download list...let's look over the lingo used to delete an item next....

SpriteScript: for Click here to select the 3D logo button...
on mouseUp
  global gFileList
  
  set the blend of sprite 17 = 40
  -- reset the sprite to look 'grayed' out as 
  -- it will now not have been selected...
  set numFiles = the number of lines in field "itemFile"
  -- again, find the number of items selected so far...
  repeat with x = 1 to numFiles
    -- how many items are already in the shopcart 
    -- list...they must all be checked...
    
    if gFileList[1][3] = line x of field "itemFile" then
    
      -- track by filename only, as they are all different 
      -- for sure! once I find the item to be deleted, I 
      -- ask Director to delete the same line from all the 
      -- fields holding data...and erase an item completely!
      delete line x of field "itemName"
      delete line x of field "itemDesc"
      delete line x of field "itemFile"
      delete line x of field "itemFormat"
      
    end if
    
  end repeat
  
  set the memberNum of sprite 36 = member "Logo1.psd"
  -- put the unselected castmember back on screen 
  -- for the user to confirm it's been deleted...
end

Nothing is worse, than underestimating the amount of feedback you deliver in a project, and for this Shopping Cart, I decided that the user should see something that would indicate that yes, they have picked this item to download -- over and above -- the simple listing in the Shopping Cart screen. So what I did was to add the word selected to the logo's in PhotoShop, then puppet those channels and switch castmembers when the user made a selection. Of course, you must remember to move those selected sprites off stage once you go somewhere else in the movie as I had to add that code to the view button and the quit button, and then put those sprites back into their on stage place once the user clicked on the back button. This visual feedback for users is very important and can often make or break a project, so my counsel is to always add in feedback wherever necessary!

Once the user has made their choices, or just wants to check on the list 'so far,' the movie offers up a view button, that takes the user to the Shopping Cart screen. Here, they can again, 'vet' their list and when satisfied, either go back to make more selections, or finish the transaction by clicking on the download button up in the top right corner.

While it might be easier to just use one field here, I chose instead to use 4 fields, each one for a different facet of each item, and then laid them out so that they look correct when the user clicks on the view button. This will allow the user to be able to link the names of the items with their choices made...and if everything is still correct, then they can go to the download process last.

Clicking on Download, the user is faced with a dialog box that will allow them to choose where on their own hard drive the files will be downloaded to, via a handler again put in the movieScript and called from the script attached to the download button. Let's look at that code now...

CastMemberScript: for Download button...(calls writeFiles...)
on writeFiles
  global gCDDrive, gSep, gFolderList, goAhead
  
  -- where gCDDrive is the drive name, gSep is the 
  -- itemDelimiter and gFolderList will hold all file names....
  
  
  -- sets up the folder list for error checking...
  
  set gFolderList = []
  
  -- create a list of all items found in 
  -- the file folder on the CD...
  
  set goAhead = FALSE
  
  -- flag used to track any missing files 
  -- in the images folder...
  
  repeat with r = 1 to 5
  
    -- number of files in the folder images; should be changed 
    -- to reflect the number you use in your own Shopping Cart 
    -- movie...here, 5 is fine 'cause that's the number of files I used...
    
    set okay = getNthFileNameInFolder(the moviePath & "IMAGES" & gSep, r)
    
    -- get the name of the first file in the folder 
    -- holding the files on the CD-ROM...
    
    append(gFolderList, okay)
    
    -- creates a list of all files in folder to check against...
    
  end repeat
  
  -- checks file name in item list against that folder list...
  -- if not there then exit the download loop...
  -- and if present then set a var to true for downloads...
  
  set endOfCart = the number of lines in field "itemFile"
  
  -- tracking by file names in this field as 
  -- they are supposed to be different...
  
  repeat with x = 1 to endOfCart
    
    set FileName = word 1 of line x of field "itemFile"
    
    -- creates a variable to hold the name of 
    -- each file to be d/l...
    
    repeat with j = 1 to count(gFolderList)
      if FileName = gFolderList[j] then
        set goAhead = TRUE
        put "FolderList has a file named " & gFolderList[j]
        exit repeat
      else
        set goAhead = FALSE
      end if
    end repeat
    
    --  above parses gFolderList to check that the 
    -- FileName is there and sets a var to go ahead 
    -- with the download of that item...
    -- download loop to transfer files to user's hard 
    -- drive but only if they are on the cd...
    
    if goAhead = TRUE then
      
      if line x of field "itemFile" = "" then exit repeat
      
      -- kick out if there's nothing to d/l or list 
      -- is now empty...
      if the platForm contains "Windows, 32" then
       
        -- wintel platform...
        set here = FileSaveAsDialog(the moviePath,fileName,"Save As...","",)
        CopyFile(gCDDrive & "IMAGES" & gSep & fileName, here)
      end if
      
      if the platForm contains "Macintosh" then
      
        -- mac platform...
        set here = FileSaveAsDialog(the moviePath,fileName,"Save As...")
        CopyFile(gCDDrive & "IMAGES" & gSep & fileName, here)
        
      end if
    end if
    
    if goAhead = FALSE then
    
      alert "Sorry, the file" && FileName && "is missing on the CD..."
      
      -- the above user message alerts the user that the 
      -- file they chose is not on the CD
      
    end if
    
  end repeat
  
  eraseEm
  -- used just to empty on screen fields for user view... 
end

Here's a screen shot of the dialog box that comes up when you are downloading to your user's hard drive...

Now that you've worked your way through the code, there is one more thing you must do. You must create a folder to hold your images so you can test this Shopping Cart functionality. Begin, by creating a folder and call it images. In it, for purposes here, create 5 files and name them after item #3 in each of the 5 different items in our linear list. Ummm....problem? Okay, call them this then...

"LOGO1.pct","LOGO2.bmp", "LOGO3.pct", "LOGO4.bmp", "LOGO5.pct"

I used the above filenames just to show you that the movie will download any type of file, and in this case you could simply make 5 copies of a SimpleText (Mac) or a NotePad (wintel) type file to watch the downloads work. One other thing here too...I usually 'work' off a removable, a Zip or a Jazz. That way, I get to work 'realworld' when it comes to mapping to files and pathnames etc. etc. although I always make sure that I save to various HD's on the network here at the office.

If you do this, then put both the movie "Shopping Cart" and its needed folder images with those 5 properly named files in it on your own removable, and give it a try. You should also note, that you will have to put the proper Xtra in the Director 7 Xtras folder for this movie to work properly...and if you don't have the Xtra handy here's a quick link to Kent's website to go and get same...

While the Shopping Cart methodolgy above is not new, it is tried and true and I've tried to make it as compact and as simple as is possible. Sure, there's more'n likely hundreds of other ways to accomplish the same thing, but for me, this works! So give it a try, won't you and thanks for dropping by today!

A sample movie demonstrating this technique is available in Mac (320K) or PC (233K) format. Note: this movie is in Director 7 format.

Beginning with HyperCard on a Mac Plus over 12 years ago, Jim began his digital career as a developer, programmer and owner of his own multimedia firm, KKT Interactive. Moving from HyperCard to SuperCard was a natural transition, as was the move to Director 4.0 almost 5 years ago. Since then, Jim has worked on honing his knowledge by teaching both Director and Lingo for community colleges and digital studios in and around the Toronto area. Jim was also a member of the Director 6 BetaTeam, which successfully brought that version of Director to the marketplace in mid 1997. Jim's true strengths are his ability to create assets while conceiving, coding and test programming routines at great length, all the while remaining on-time and on-budget contracting for clients that include QuakerState Oil, MercedesBenz, Reuters, the AdLib AdAgency, Simon & Schuster, SAAB, the New York Yankees and the VanHorne Winery.