Amazon S3 Quick Start

&ot

About DreamFactory

DreamFactory is both an IDE and a runtime engine for rich internet applications.

Let's look at some of the basic facts about DreamFactory

• DreamFactory can run in a browser or as a traditional desktop application
• At runtime DreamFactory can run in the browser or standalone on the desktop
• DreamFactory applications are work in both Windows and Mac environments
• DreamFactory works within all of the leading browsers - IE, Firefox, Opera, Safari, etc.
• DreamFactory applications are entirely client-side applications - no servers required.
• DreamFactory applications can easily interact with any service-based architecture. If it has a web services API, you can build a rich DreamFactory application to work with it.
• You can write DreamFactory applications in your choice of 3 scripting languages: JavaScript, VBScript, or our own DFScript.

Salesforce.com has a robust and well-supported service architecture - the AppExchange API. The following pages will walk you through everything you need to know to build a DreamFactory application that leverages the Salesforce API.

Installation Information

DreamFactory consists of a software engine and various project files. The engine is either an ActiveX control, a Netscape Plug-in or a stand-alone executable.

The stand-alone version of the DreamFactory and the browser plug-ins are available from:

http://www.dreamfactory.org/download/

Download and run the DreamFactory Professional installation program. The stand-alone IDE will be installed, along with a desktop shortcut and a Start > Programs > DreamFactory menu item.

After installation, the DreamFactory installation folder will contain help files, default scripts, plug-ins, a download folder, and some other text files. The DreamFactory document type uses the extension .dfac and the registered MIME type application/dreamfactory.

IDE Basics

Browser based authors will not see the menu bar pictured at the top of the screen below. Instead, the system menus are available as a pop-up from the Message Box, Debugger, or Script Editing Windows in the Menu button to the right of the information bar. Other than that, the standalone and browser-based IDE are identical.

Utility Palettes

The Utility Palette contains all the key buttons that contol what Palettes you see on your screen. The Utility Palette at right provides access to many useful functions with a tool bar. Expand the window by clicking in the zoom box to see more controls.

Let's look at the available controls on the Utility Palette:

Icon	Function
	Click this button to open an existing DreamFactory project.
	Click this button to close an existing DreamFactory project.
	Click this button to save your existing DreamFactory project.
	Click this button to zip up a copy of your DreamFactory project and deploy it on the Internet.
	Click this button to close all projects and quit DreamFactory.
	Click this button to run the current project. Click this button twice to resume editing of the project.
	Click this button to launch the degugger on your current project.
	Click this button to open the Message Box and run new scripts.
	Click this button to show/hide the Tools Palette.
	Click this button to show/hide the Project Manager Palette.
	Click this button to show/hide the Alignment Palette.
	Click this button to check for updates to the libraries, palletes, and dialogs in DreamFactory.

Tools Palette

The Tools Palette launches every time you open a project.

Click the main Tools icon at the top of the Tools Palette (upper left) to cycle through the various node types available in DreamFactory. You can choose from

Note: Click the Maximize button to expand the Tools Palette to show all available node types.

Figure 1 above shows the Draw nodes that are available in DreamFactory. Let's look at how to get started on a project and some of the key functions you can use on the Tools Palette.

1. Select a node and drag on the desktop to create that node.
2. Press Shift + click (click on the node with your mouse) on the node to open the script for that node. Alternatively, right-click on the node (option-click on the Mac) to see a pop-up menu of options or the properties dialog for that object.
3. Click the Reshaper Tool icon on the Tools Palette to reshape the node.
4. Click the arrow tool to the top left to hide the handles and resume normal operation.

Alignment Palette

The Alignment Palette allows you to align or nudge currently selected objects. Use the Tools Palette Reshaper Tool to select nodes to align. Ctrl-click to select multiple nodes.

Pop-up Menus

Right-click on any DreamFactory node on your main screen and you will see a pop-up menu with a list of available options, with a Properties option at the bottom of the menu. The first menu items will always be:

The next set of available menu options are: Cut, Copy, Paste, Delete, and Duplicate. These are self explanatory, but be aware that these operations apply to the node and all of its children.

At the bottom of most pop-up menus you should see the Properties Dialog, for example, "Slider Properties." You can also access this by double-clicking most nodes.

Properties Dialogs

The Properties Dialog lets you explore the various capabilities of a node. Figure 3 below shows the property dialog for aSlider.

System Editing Windows

There are some important DreamFactory system windows that are used to help author and build your projects:

• The Debugger
• The Message Box
• The Help System
• The Background Desktop

The Debugger

The Debugger is accessible at any time. The Debugger can set breakpoints and step through scripts as they execute. The Debugger also tracks the values of local, global, and regional variables. It will display the hierarchical overview of your project in Outline Form. When the Debugger is active, all script execution stops, but you can still edit scripts and use the Message Box. Simply click the Run button to continue execution, or Step to watch the current script run. Scan your mouse over the various buttons on the Debugger Window and they will document themselves.

The Message Box

The Message Box allows instant execution and exploration of the DreamFactory language.

Right-click any node and select the Target pop-up menu command. The Message Box will then send typed messages to that node, so you can call handlers from the hierarchy, reference variables, etc.

The Message Box is a good place to create or change node properties manually or test the scripting language. Press Ctrl + scan with the mouse to identify visible nodes by name.

The Help System

The Help System documents all system and plug-in commands. The system commands arranged in logical groups with common prefixes. The Help Window is always available and is context sensitive. It is intended as a general DreamFactory reference.

The Background Desktop

The Background Desktop is the main window that stores the project and all its nodes. This window is where all project editing takes place. Be aware that objects in the Background Desktop are all part of your project, even if they look like windows, menus, or other system windows. The Debugger, Message Box, and Script Editing Windows float on top of the Background Desktop.

Script Editing Windows

The Script Editing windows provide powerful editing features and allow you to work on multiple DreamFactory scripts at once. When you are editing a script, press Ctrl + scan with the mouse to see any language element documented and explained in the information bar at the top of the window.

Click Ctrl + F to open up the Find Dialog (Command-F on the Mac) to search and replace the current script, the current hierarchy, or all scripts in the current project.

Click to the left of the script in the dotted rectangle to set or clear break points; when the script runs this point it will trigger the Debugger Window.

The Menu button to the right of the information bar in the Message Box provides access to DreamFactory system menus.

Plugin-Ins

All DreamFactory functionality is provided by what we call plug-ins. Some plug-ins are standardand are available at all times.

The standard plug-ins are:

Plug-ins can also be non-graphic, such as the Outlook plug-in that provides desktop integration with Microsoft Outlook. New plug-ins can be developed when needed. They become first-class entities that expose their own commands and functions. Plug-ins are version controlled and downloaded as necessary to support DreamFactory projects.

Each node has an associated plug-in and script. Most of the commands and functions exposed by a plug-in control the visual appearance of a node. Often a script will use these commands or functions to manage the appearance and behavior of a node. While the details of each node can be controlled by the associated plug-in commands and functions, there are also system commands and functions used for controlling the characteristics of all nodes in general. For example, the system command nodevisibleset("mynode", false) will hide any node regardless of the associated plug-in.

Tutorial: Part 1 - Hello World

In this tutorial you will create the simplest DreamFactory application. It will consist of a dialog with a button. When you press the button, a "Hello World!" popup dialog will appear.

1. Start the DreamFactory IDE.
2. Click File > New Project and name the new project called tutorial.dfac.
3. On the Tools Palette click on the main Tool button until the Windows Tool is selected.
   
4. Select the Dialog Box node and drag it onto the IDE Desktop.
5. Select the Button Palette and adrag a System Button onto the dialog box.
   
6. Right-click on the System Button and select Name. The Enter Name dialog box appears
   
7. Type OK in the text box and click OK to close the text box.
   
8. Right-click on the System Button again and select Button Properties. The Button Properties dialog box is displayed.
   
9. Type OK in the Button Title text box and click OK to close the dialog box.

   

   You can see that all the button has been relabelled OK.

   

Adding Code to a button

The final part of this tutorial will show you how to add code to a button. Let's continue with our example.

1. Right click on the button and select Script. Alternatively, press Shift-click to open the script for the button.
   
2. Modify the mycontent function to look like:
   

   
   code mycontent(hor, ver)
   	dialogshow("Hello Title", "Hello World!")
   endcode
   

3. Click Save on the main toolbar of the Script Window. the script, and "¦ congratulations! The OK button will now return a working "Hello World" dialog.

Note: There is no need to save the overall project in the IDE because it is continuously saved. There is also a limited undo. i.e., be careful about your changes. Changes are not easy to undo.

Buttons and mycontent()

In the case of a button, mycontent() will be called when the button is pressed. Each node has a mycontent() function - initially empty - that is called when that node is activated. Here are some examples of actions that will trigger a node's mycontent() handler:

Tutorial: Part 2 - Debugging

Sometimes, things go wrong. In this tutorial, you'll learn about the debugger built into the DreamFactory IDE and how it can help you with errors.

1. Press Shift-click on the OK button, we created in Tutorial 1, to open the script.
2. In your call to dialogshow(), remove the comma between the two parameters.
   
3. Click Save to save the script. Then click on the OK button again to execute the script. The following Scripting Error dialog below will appear.

Wait - before you dismiss the dialog, note the following choices you have:

• Since this is a scripting environment, nothing catastrophic has happened. Your application is still running and you could just Ignore the error and continue on, hoping that the error is minor and the rest of your application will run fine.
• If you already know what the problem is, you could Edit the script directly. The script editor will appear positioned at the line where the error occurred.
• You could Debug the application, identify the error, fix it and be done. The Debugger Window will open at the current execution point - the call to dialogshow()
• You could Exit the current handler (function). In this case the mycontent() handler of the OK button.
• Finally, you could Quit the DreamFactory IDE entirely

Now, before we forget, fix your scripting error by reinserting the comma and saving the script.

Tutorial: Part 3 - Window/Dialog Manipulation

This tutorial will cover all you need to know about window/dialog manipulation. Instead of using a system function to pop up a dialog box, we're going to create our own window and pop it up and down ourselves. We're also going to add list and text nodes to our original window. Then we will make our window and all of its children resize smoothly.

There are a lot of steps to this tutorial, so we have broken it down into smaller stages.

Create a Second Dialog Window

The first part of this tutorial involves creating a second dialog window. For information on how to create a dialog window, see Tutorial 1 - Hello World.

1. Drag a second dialog box on your Desktop. For information on how to do this, see Tutorial 1 - Hello World.
2. Right-click on the dialog box and select Window Properties. The Windows Properties dialog box appears.
3. Type My Popup in the Window Title textbox and click OK.
   
4. Drag and drop a System Button onto the Dialog window.
5. Right-click on the System Button and select Button Properties. The Button Properties dialog box is displayed.
6. Type Dismiss in the Button Title text box. Click OK to save your changes.

How to make a Dialog Window pop up and down

Now let's make our new dialog pop up and down.

1. Go back to the OK button in the first Dialog Window we created. Right-click on the button and select Script. The Script Window is displayed.
2. Modify the mycontent() function to look like this:
   

   
   code mycontent(hor, ver)
   	nodevisibleset("mypopup", true)
   nodebringtofront("mypopup")
   endcode
   

This will make your new "My Popup" dialog appear, and it will bring it to the fore ensuring that it isn't obscured by any other windows.

3. Click Save to save the script.
4. Right-click on the Dismiss button you created and select Script. The Script Window is displayed.
5. Modify the mycontent() function to look like this:
   

   
   code mycontent(hor, ver)
   	nodevisibleset("mypopup", false)
   endcode
   

This, in turn, will hide your My Popup dialog.

6. Click Save to save the script, and then try it out. When you click the OK button in your original dialog window, you will see the following:

When you click the Dismiss button in your My Popup dialog window, the pop-up window will close.

Add a list and text to your Popup Window

If you look closely at the node hierarchy in the Project Manager palette, you'll see that both window:mypopup and button:dismiss are blue in the node hierarchy.

This indicates that these nodes are not visible. Right-click on window:mypopup and select Show Node. This will make your popup dialog visible once again.

Now we're going to add three children to My Popup:

1. Cycle the Tools Palette to show List Tools.
2. Drag a Standard Scroll node onto My Popup.

If you look in the Project Manager palette, you'll see that you actually created two nodes: a border and a list. The border provides the scrolling, and the list will actually contain whatever items you populate it with.

3. Change the name of the border to mylist and the name of the list to list_contents.
   
4. Cycle the Tools Palette to Draw Tools and drag a Draw Text node onto My Popup.
5. Change this node's name to item_label and change its Text to Selected Item:

   Note: You can do this either through its Properties dialog or by right-clicking on the node and selecting Enter Text.

   

6. Cycle the Tools Palette to Rich Text Tools and drag an Entry Field onto My Popup. Change this node's name to myitem.

   You're My Popup dialog should now look like this:

   

Resizing - nodemove()

One of the other handlers (functions) that is very useful is nodemove(). When a node is moved or resized, nodemove() is called (makes sense, doesn't it?) The most common use of nodemove() is for a parent (a dialog or window) to reposition its children based on its size.

For this part of the tutorial, we're going to do something simple. We're going to keep the Dismiss button at the bottom right of the My Popup window no matter how we resize the window.

First, let's make My Popup resizeable.

1. Bring up the Properties dialog for My Popup, select the Grow Icon checkbox and click OK.
   
2. Now you will see a a Grow Box in the lower right corner of My Popup.

   

If you resize now, you'll see that all of the children of My Popup, including the Dismiss button, stay exactly where they are, regardless of the size of the window.

What we want, though, is for the Dismiss button to remain anchored to the bottom right corner of the window.

3. Right-click on My Popup and select Script.
4. Add a new nodemove() function at the top of the script. This is what the nodemove() function should look like:

code nodemove()
	local mybounds, mybutton, button_bounds, width, height
	
	// Find my child button
	mybutton = nodefindchild(me, "dismiss")
	
	// Get the bounds of the window and the button
	mybounds = window.boundsget(me)
	button_bounds = button.boundsget(mybutton)
	width = button_bounds.width
	height = button_bounds.height
	
	// Anchor the button 20 pixels up and to the left
	// of the lower right corner of the window
	button_bounds.right = mybounds.width - 20
	button_bounds.bottom = mybounds.height - 20
	button_bounds.left = button_bounds.right - width
	button_bounds.top = button_bounds.bottom - height
	
	// Set the button's bounds accordingly
	button.boundsset(mybutton, button_bounds)
endcode

5. Click Save to save the script.
6. Now try resizing the My Popup window. The button will remain anchored regardless of the size of the window:
   

The Amazon S3 Integration Panel

In 2006, Amazon released Simple Storage Service (S3) as part of hits web-services suite. Amazon S3 provides unlimited storage through a simple web services interface. Data can easily be stored and retrieved at any time, from anywhere on the web.

DreamFactory has developed an S3 Integration Panel that allows developers to take advantage of the S3 web service allowing the developer to easily store and retrieve data with a backend that is scalable, reliable, fast and inexpensive.

The panel was designed to include 100% of the features offered by S3. As Amazon S3 was intentionally built with a minimal feature set, this will be reflected in the features provided by the adapter. (For instance, no rename or move functions). Such additional functionality, if so desired, should be included in the application layer.

Key S3 links

• S3 Home
• S3 Developer Forum
• S3 API Docs

Setting up an S3 account

To set up an S3 account, follow these steps:

1. Create an Amazon Web Services Account and sign up for the Amazon Simple Storage Service.
2. Login into your account to get your Access Key ID and Secret Access Key.
   You can then use the AWSZone website to verify that Access Key ID and Secret Access Key are working.
3. Download the DreamFactory S3 adapter from the DreamFactory Developer Portal.

The S3 adapter is designed similarly to the Salesforce Integration Panel in that it is both a developer aid and a runtime abstraction layer that simplifies the integration process. One key difference is that the library is included in the UI so importing a corresponding library is not required.

All API calls are included in the main window:s3 node script.

Creating a New Bucket with the UI

Every object stored in Amazon S3 is contained within a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. For more information, see the Amazon Web Services site.

Let's try out the adapter by creating a new bucket via the UI.

Bucket names must be globaly unique and each account is allotted only 100 buckets. As such, it is unlikely that you will create buckets programmatically using the library.

1. Enter your Access Key in the AWS Access Key Id text box.
2. Enter your Secret Key in the Secret Access Key text box.
3. Enter a globaly unique bucket name in the Bucket Name text box.
4. Click Create Bucket->->.
5. Click the List All->-> button in the LIST ALL BUCKETS panel. You should see your new bucket listed in the panel.

Tutorial: Part 4 - Creating an application

Now that we know the basics and we have created our bucket, we want to actually create an application. In our example we are going to create a Poem Bank © - a place that stores poems. We want to create an application that will use our S3 panel to store, read, and delete poems. We want to create an application with a scrolling listbox, a scrolling textbox, and 3 buttons (Save, Read, Delete).

Setting up our Objects in DreamFactory IDE

The first thing we want to do in this example is to create a new project ensure that we have all the necessary objects on our IDE Desktop.

1. Start the DreamFactory IDE.
2. Click File -> New Project and name the new project called poembank.dfac.
3. On the Tools Palette click on the main Tool button until the Windows Tool is selected.

   

4. Select the Dialog Box node and drag it onto the IDE Desktop.
5. Again cycle through the Tools Palette until the Button Palette is selected. Drag 3 System Buttons onto the dialog box.
6. Again cycle through the Tools Palette until the Lists Tool is selected. Drag a Standard Scroll onto the dialog box.
7. Again cycle through the Tools Palette until the Rich Text Tool is selected. Drag a Text Area onto the dialog box.
8. Again cycle through the Tools Palette until the Draw Tool is selected. Drag a Draw Text node onto the dialog box.

   Your dialog box should now look like this:

   

Renaming the nodes in DreamFactory IDE

Now we want to rename all the nodes on our screen.

1. Right-click on the Dialog box and select Window Properties.
2. Type Poem Bank in the Windows Title text box.
   
3. Right-click on the Poem Bank window and select Name. Type poemBank in the Enter Name text box.
4. Right-click on each System Button and select Button Properties. Change the Button Title of the the three System buttons as follows: Save, Read, and Delete.
   Your Poem Bank should now look like this:
   
5. Right-click on each button again and select Name. Change the name of each button to match its title. E.g. Save = save, Read = read, and Delete = delete.
6. Right-click on the Draw Text node and select Enter Text. Type Stored Poems in the Enter new text data text box. Click OK to close the dialog box.
   
7. Right-click on the Standard Scroll and select Name. Type poemListBorder in the Enter Name text box.
   
   Click OK to close the dialog box.
8. Right-click on the Child List node and select Name. Type poemList in the Enter Name text box.
   
   Click OK to close the dialog box.
9. Right-click on the Rich Text node and select Name. Type poemText in the Enter Name text box.
   
   Click OK to close the dialog box. Your Poem Bank should now look like this:
   

Adding the Functionality behind our nodes

First things first, lets create some convience functions that will return the access key, secret key, and bucket name that we have just created. All S3 functions will require an access key and secret key.

1. Right-click on the Poem Bank window and select Script.
2. Type the following code in the Script window.
   You will need to return the accessKey and secretKey you received from Amazon. The bucketName will be your own unique bucket. Do not use the keys or the bucket name in the example below.

   
   code getAccessKey()
   	return "7XZWTVSXQ511FKNTFYG2"
   endcode
   
   code getSecretKey()
   	return "jEBx7dZl7CcEizCLGg7CIq0sVk06dUbqORda1WTm"
   endcode
   
   code getBucket()
   	return "uniqueBucket"
   endcode
   

3. Click Save to save your changes.
4. Now we want to set up the code that will save a poem from our Poem Bank into S3. Right-click on the Save button and type the following code in the Script window. This script will ask for a title and a textFile then finally make a call to S3 to save the poem.
   

   
   code mycontent(hor, ver)
   	global titleCount
   	local s3Node, textNode, listNode
   	local title, poemPath, poemData
   		
   	s3Node = nodelongnameget("window:s3")	
   	textNode = nodelongnameget("poemText")
   	listNode = nodelongnameget("poemList")
   	
   	// Get a poem title from the user.
   	title = dialogtext("Poem Title", "Poem Title", "")
   	if title = empty
   		exitcode
   	endif
   
   	// Get the poem text file from the user.
   	poemData = dialogopenfile("Please select a poem.", "textfiles", false)
   	if poemData = ""
   		exitcode
   	else
   		poemData = xml.binaryread(poemData)
   	endif
   		
   	s3Node.putObject(getAccessKey(), getSecretKey(), getBucket(), title, poemData, empty, empty,
                           empty, empty, empty, empty, empty)
   	//listNode.fillList()
   	
   endcode
   

5. Now we need to create a savePoem() function in our Rich Text node, poemText. Right-click on the poemText node and select Script.
6. Type the following code in the Script window.
   

   
   code savePoem(titleKey)
   	local poem, s3Node
   	
   	s3Node = nodelongnameget("window:s3")
   	poem = me.data
   	if poem = empty
   		exitcode
   	endif
   	
   	s3Node.putObject(getAccessKey(), getSecretKey(), getBucket(), titleKey,
                           poem, empty, empty, empty, empty, empty, empty, empty)
   endcode
   

   If we hit the Save button now, our poem should be saved into the S3 account. Unfortunately, our list will not reflect this fact just yet, so let us now create an updateList function in the listbox.

7. Right-click on the poemList node and select Script.
8. Type the following code in the Script window.
   

   
   code fillList()
   	local s3Node, list, poemNames
   	
   	s3Node = nodelongnameget("window:s3")
   
   	// Clear listbox.
   	me.data = ""
   	
   	// Make s3 call.
   	list = s3Node.listBucket(getAccessKey(), getSecretKey(), getBucket(), 
                                   empty, empty, empty)
   	
   	// Populate listbox.
   	for i = 1 to list.length
   		list.insertitem(me, 0)
   		list.itemnameset(me, 1, list[i].Key)
   	endfor
   endcode
   

   Note: The return value of the listBucket() function is in XML. Since any XML envelope is automatically a structure addressable as an object or array in DreamFactory, we can simple refer to the xml elements using the dot-notation (list[i].Key).

   Now that we have written the fillList() function, we should call on it everytime we update our s3 account.

9. Right-click on the Save button and select Script. Locate the SavePoem() function and uncomment the fillList line which was conviently commented-out for you
10. Now save some of your favorite poems into the "Poem Bank", or if you feel inspired, create some of your own.
    
11. Finally, we need to create the readPoem() and the deletePoem() functions in the poemList node. Right-click on the poemList node select Script. Type the following code in the Script window.
    

    
    code readPoem()
    	local s3Node, textNode
    	local poemData, poemKey
    	
    	poemKey = me.list.selectname
    	s3Node = nodelongnameget("window:s3")
    	textNode = nodelongnameget("poemText")
    	
    	// Read poem from S3 and put it in the text widget.
    	poemData = s3Node.getObject(getAccessKey(), getSecretKey(), getBucket(),
                                       poemKey, empty, empty, empty, empty, empty)
    	textNode.data = poemData	
    endcode
    
    
    code deletePoem()
    	local s3Node, textNode
    	local poemKey
    	
    	poemKey = me.list.selectname
    	s3Node = nodelongnameget("window:s3")
    	
    	s3Node.deleteObject(getAccessKey(), getSecretKey(), getBucket(), poemKey)
    	fillList()
    endcode
    

    Lastly, call these functions from the Read button and Delete button respectively.

12. Right-click on the Read button and select Script. Type the following code in the Script window.
    

    
    code mycontent(hor, ver)
    	local listNode = nodelongnameget("poemList")
    	listNode.readPoem()
    endcode
    

13. Right-click on the Delete button and select Script. Type the following code in the Script window.
    

    
    code mycontent(hor, ver)
    	local listNode = nodelongnameget("poemList")
    	listNode.deletePoem()
    endcode