Office of Digital Humanities

Array Exercise—Dictionary array

This exercise is intended to give you basic experience with creating, adding to, and saving array data in LiveCode. When you are finished you should know:

1. How to create an array.
2. How to use the split command to convert a text file into an array.
3. How to reference elements of an array variable using array [ ] notation syntax.
4. How to get a list of keys of an array using the keys function.
5. How to use the arrayEncode() and arrayDecode() functions to save array data to an external file.

An important secondary objective of this assignment is to get you thinking about designing your stack to produce a good end-user experience.

Instructions

1. Create a text file (using BBEdit, Notepad or any other text editor). This text file will contain a list of keys and element contents. We'll use a simple dictionary as an example. The lines in the text file should be formatted like this:
   

   keyword (tab) definition (return)
   

   Here's a sample text file:

   bread	edible thing made out of grain
   milk	nutritious liquid produced by female mammals
   rock	a hard thing
   table	a flat surface raised from the floor on legs
   carpet	a floor covering made of fibers
   printer	a device for producing printed text on a page
   car	a mechanical device for conveying people and goods
   

2. Create a stack, and place two fields on the card, named "keyword" and "definition".


3. Create a button called "makeArray" or something similar. In this button write a handler that will read your text file into a variable. Then use the split command to make the text into an array. The keys in our text file are separated from the element content by a tab, and the elements are separated from one another by returns. So your split command might look like this:
   

   split gDictionary by return and tab
   

   
   Be sure to make your array variable a global variable so that all other scripts in your stack can have access to the array.


4. Create a button called "addToArray". Write a mouseUp handler for the button that puts the definition field into an array, using the keyword field as the key. For example:

put fld "definition" into gDictionary[fld "keyword"]

5. Remember that you will want to declare the variable gDictionary as global, because you'll want to have access to it in other scripts.


6. Now enter a few keyword and definition pairs.


7. Once you have several pairs saved, create a way to look up the definitions. Make a button called "lookup". In the mouseUp handler, ask the user to type in a word to look up. (Don't forget to declare the gDictionary variable as global here, too!) You might use:

ask "What word do you want to look up?"

8. During a lookup operation, the user should enter a keyword and the definition should be returned. That might look something like this:

answer gDictionary[it]

9. Think about ways to make your lookup program a better user experience. For example, what will happen if the user cancels the ask dialog? One of the hallmarks of well-written software is its ability to robustly handle all user inputs.


10. Figure out a way to display a list of the available keywords to look up. By clicking on a word in the list you could display the definition the word. The keys function will help you here.


11. Once this clickable list was working, how could you make sure it always has the most up-to-date list of keywords in it? Modify your stack to do this.

Assignment

In class we did all 11 points above. To complete this assignment do the following to your stack:

• Add a way to save the data in your array so that the entire dictionary, including words added by the user, is present the next time you launch the stack. There is a discussion of various ways to save array data at the end of the Intro to Arrays reading. Use the following criteria:
  • Automatically read in the latest dictionary array when you open the stack.
  • Make sure that the latest array data is saved out to an external file. This could either be done each time you make a change to the dictionary or when you close the stack.
• Improve the user interface so that a novice user seeing your stack for the first time would understand how to look up and add words to the dictionary. To this end, consider the following improvements:
  • Adding labels or simple instructions to direct the user on how to use your dictionary.
  • The "makeArray" button was useful in helping us understand how to create an array and for doing the first import of the word list into the global array. It probably wouldn't be needed for a novice user.
  • Letting the user add terms to the dictionary is a good feature, but how would you prevent users from adding blank or ill-formed words or definition to the dictionary? You should prevent the user from adding elements to the dictionary array if either the keyword or the definition fields are empty.
  • If you allow users to look up words via the ask dialog, how will you inform them if the word they enter doesn't exist in the dictionary array? How will you know if the word doesn't exist in the array? (Remember that the command put the keys of array name will list all of the key words in your array.)

Once your stack is working the way you want, turn it in to the Assignment_Drop folder on the server. Don't forget to turn in any external storage files together with your stack. (Making them into a .zip archive is a good way of doing this.)

I have put together an example of the kind of "polished", end-user-ready stack that I would like you to build. It is on the DigHT 310 server in Lesson_materials/arrays/ArrayEx-Key.zip. Notice how much of my scripting was dedicated to improving the user experience. (E.g., hiding and showing objects so they appear only when needed, checking for the presence of needed data before allowing the addition of terms, etc.)