Username: Password:
Home / Documentation / Salesforce.com Quick Start

Salesforce.com Quick Start



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

• Draw
• Window
• List
• Tabl
• Menu
• Gauge 		• Button
• Border
• Rich Text
• Slider
• Chart
• Misc

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:

Menu Item Function
Help Click this button to open the help system for that node
Name Click this button to give the node a name
Script Click this button to view or edit the node script
Resize Click this button to activate the handles on the node and to drag or resize the node.
Press Ctrl + click to select or deselet multiple nodes.
Use the Alignment Palette to move nodes around.
Target Click this button to direct the Message Box to call commands and functions on the selected nodes.
Comment Click this button to create a comment for this particular node.

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:

• Chart
• Button
• Draw
• Icon
• Menu
• Picture
• Sprite
• Table
• Window 		• Border
• Desktop
• Gauge
• List
• Movie
• Sound
• Slider
• Text
• XML

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:

Handler Action
List A list item was seleted
Text A mouse was clicked/released in the text field
Table A cell was selected
Menu A menu item was selected

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.

  1. Click Save to save the script.
  2. Right-click on the Dismiss button you created and select Script. The Script Window is displayed.
  3. 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.

  1. 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.

  1. Change the name of the border to mylist and the name of the list to list_contents.
  2. Cycle the Tools Palette to Draw Tools and drag a Draw Text node onto My Popup.
  3. 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.

  4. 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.

  1. Right-click on My Popup and select Script.
  2. Add a new nodemove() function at the top of the script. This is what the nodemove() function should look like:
    3. 
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
  3. Click Save to save the script.
  4. Now try resizing the My Popup window. The button will remain anchored regardless of the size of the window:

Salesforce.com Basics

  • AppExchange
  • Web Services API
  • Data model

The salesforce.com application suite is an on-demand offering, accessed through a traditional browser-based interface. Salesforce.com also has an online marketplace - the AppExchange - where both salesforce.com and their partners offer applications and add-on components that run on top of the salesforce.com platform.

Salesforce.com was one of the first application vendors to create a truly robust web services interface. DreamFactory has been providing development tools and building applications for salesforce.com using this API - now branded as the Apex Web Services API - since its inception. Through the API, you can programmatically do almost (but not quite) everything you can do through Salesforce's own browser-based UI.

For developers, it is useful to know that the salesforce.com platform is built on an Oracle database. Salesforce entities like Account, Opportunity and Lead are implemented as tables in that database, and relationships between entities are fundamentally foreign keys into those tables. The Apex API reflects that underlying structure. The uniformity of the underlying data model simplifies the effort of building applications that interact with salesforce.com entities. The basic set of operations is exactly what you would expect: Login, Describe, Retrieve, Search, Filter, Create, Read, Update, Delete, etc. Refreshing, isn't it?

Salesforce.com has a wealth of background information on AppExchange, the Apex Web Services API and much more. You can access all of that information at the Apex Developer Network site. This tutorial will walk you through the basic "getting started steps, but we also recommend you take a look at the salesforce.com site. Here are pointers to some of the more relevant items:

In the DreamFactory IDE and runtime, we've greatly simplified the process of building applications that integrate with salesforce.com. Read on!

Sforce Console

In the Project Manager palette, under desktop:mydesk you'll see window:access_panel. This node will be blue in the palette, because the node is currently hidden.

  1. Right-click on window:access_panel and select Copy. This will copy this node and all of its children.

  1. On the Main Toolbar, select File > View Project and then select tutorial.dfac. This will switch your view over to your tutorial project.

  1. In the Project Manager palette, right-click on desktop:mydesk and select Paste. The Salesforce Integration Panel now appears in your window.

In the Project Manager palette it is a child of desktop:mydesk and in the UI you will see the integration panel.

Tutorial: Part 4 - Salesforce Integration Panel

In this part of the tutorial, we're going to import the Salesforce Integration Panel into our tutorial application. This will let us begin integrating with Salesforce, and it'll teach us a bit about DreamFactory library and node copying.

Step 1 The StartingPoint Project

To access the Salesforce Integration Panel, we're going to open a second DreamFactory project (application). This project is called StartingPoint, and the easiest way to get it is this:

  1. In a browser, go to http://www.dreamfactory.com/startingpoint/startingpoint.html

This will open Starting Point in your browser, and it will also download the actual project file to this folder:

C:\Program Files\DreamFactory\downloads\www.dreamfactory.com\startingpoint\
startingpoint.dfac
  1. Now go back into the DreamFactory IDE, where your tutorial.dfac is already open.
  2. From the File menu select Open Project...
  3. Navigate to the startingpoint folder (see the path listed in step 1). Select startingpoint.dfac and click Open:
  4. Press Ctrl+Click on the StartingPoint logo in the upper right of the window.

This will switch you into development mode, where you can see all the palettes you're now accustomed to.

You now have two projects open at the same time in the DreamFactory IDE. You can easily switch between projects via the File > View Project menu.

From StartingPoint we want to grab three things: the Salesforce Integration Panel UI and two convenience libraries.

Sforce Console

In the Project Manager palette, under desktop:mydesk you'll see window:access_panel. This node will be blue in the palette, because the node is currently hidden.

  1. Right-click on window:access_panel and select Copy. This will copy this node and all of its children.

  1. On the Main Toolbar, select File > View Project and then select tutorial.dfac. This will switch your view over to your tutorial project.

  1. In the Project Manager palette, right-click on desktop:mydesk and select Paste. The Salesforce Integration Panel now appears in your window.

In the Project Manager palette it is a child of desktop:mydesk and in the UI you will see the integration panel.

Libraries

In DreamFactory, libraries are convenient places to keep scripts that are used throughout your project. The first six libraries - library1 through library6 - are created by default when you begin a project. From there, you can add libraries as you see fit.

Copying Libraries

To copy a library, basically you have to create a new library and then copy the contents from another library into it. Follow these steps to copy the Salesforce Integration libraries from startingpoint.dfac to tutorial.dfac. We'll also be creating our own library for this tutorial.

  1. In the DreamFactory IDE, press Ctrl-M to open the Message Box.

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

    • Type libraryinsert(6) into the entry box and press Enter.
    • Type libraryinsert(7) into the entry box and press Enter.
    • Type libraryinsert(8) into the entry box and press Enter.

  2. Now, when you click on the Project Manager Palette you'll see library7, library8 and library9 just below library6. At this point, these new libraries are empty.

  1. Right-mouse on library7 and click Comment. Type Sforce Library and click OK.
    • Right-mouse on library8 and click Comment. Type Tutorial Library and click OK.
    • Right-mouse on library9 and click Comment. Type Sforce Persistence Utilities and click OK.

  2. Switch to the StartingPoint project by selecting File > View Project > startingpoint.dfac.
  3. In the Project Manager Palette, right-click on library7 (Sforce Library, Version 7.0) and click Export Script.
  4. Save the script as library7.txt in the same folder with your tutorial project.
  5. Right-click on library9 (Sforce Persistence Utilities) and click Export Script. Save the script as library9.txt in the same folder with your tutorial project
  6. Switch back to your tutorial project File > View Project > tutorial.dfac.
  7. In the Project Manager Palette, right-click on library7 and select Import Script.

  8. Click Yes in the Are You Sure? popup.
  9. Navigate to your tutorial folder, select library7.txt and click Open.
  10. Now right-click on library9 and select Import Script. Click Yes in the Are You Sure? popup.
  11. Navigate to your tutorial folder, select library9.txt and click Open.
  12. Now, if you right-mouse on library7 or library9 and click Script you will see all of the convenience functions for salesforce.com integration.

    Most of these functions will be used directly by the Salesforce Integration Panel, but you'll use some of them yourself in this tutorial.

    library8, Tutorial Library is empty for now. It will eventually have a function that is used by library9, though, so it is important that it appears before the Sforce Persistence library.

Tutorial: Part 5 - Calling Salesforce.com

In this part of the tutorial, we're going to start making actual calls to salesforce.com. Since we don't want to mess with real production data, we're going to use a Developer Account. It's easy to get one, and we'll walk you through the process right now.

Step 1: SFDC Developer Account

Salesforce.com is eager to get you (and every other developer on the planet) building applications on their platform. If you join the Apex Developer Network (ADN), they'll give you a free two-user Developer Edition Account. This account has all of the application functionality of the Enterprise Edition, and it comes pre-loaded with sample data including Accounts, Contacts, Leads, Opportunities, etc.

To set up a free salesforce.com account, follow these steps:

  1. Go to http://www.salesforce.com/form/trial/freetrial-developer.jsp
  2. Fill out the form,and salesforce.com will email you a login URL and your temporary password.
  3. Click on the URL and change your password, and you are ready to go.

Note: Remember your username (it's the email address you provided in the form) and password. We'll need them later in this tutorial.

Step 2: Log into Salesforce.com

  1. In the DreamFactory IDE, right-click on the OK button and click Script.
    We're going to modify the mycontent() script so that it logs into salesforce.com when the button is pressed.
  2. At the beginning of the mycontent() script, add the following code:
    
sforce_login("dfdeveloper@dreamfactory.com", "tutorial")
  3. You should change the username (email address) and password.

Note: We still want to popup My Popup, so don't remove that code. Your script should look like this when you're done:


code mycontent(hor, ver)

	sforce_login("dfdeveloper@dreamfactory.com", "tutorial")
	
	nodevisibleset("mypopup", true)
	nodebringtofront("mypopup")
endcode

Don't forget to save your script. You won't notice anything new when you press the OK button, other than a slight delay while the login to salesforce.com is happening, but you've just made your first Web Services call from your DreamFactory application to salesforce.com!

Step 3: Fetch Lead Data

Lead is a standard Salesforce object and one of the most common integration scenarios is extracting Lead data from salesforce.com and passing Lead data into salesforce.com. Let's make a call to salesforce.com to gather some lead data. We will populate the List box in My Popup with the Lead data we retrieve.

However, we still need to declare the leads variable and populate the list with our Lead data.

  1. Right-click on the OK button and select Script.
  2. Modify the mycontent() function to look like this:
    
code mycontent(hor, ver)
	local leads
	
	sforce_login("dfdeveloper@dreamfactory.com", "tutorial")

	leads = sforce_filter("Lead", "Id, Name, Title", "Name != 'Z'")
	list.dataset("list_contents", leads)

	nodevisibleset("mypopup", true)
	nodebringtofront("mypopup")
endcode
  3. Click Save to save your script.
  4. Now, when you click the OK button, what happens? Oops! The call to Salesforce was correct, but what comes back is XML, not a set of list elements.

If you want to see the full set of XML data returned, use the Salesforce Integration Panel (Sforce Console).

  1. Open the Salesforce Integration Panel.
  2. Scroll down to the FILTER section.

  3. Ensure you have the following text typed in the appropriate text boxes:
    • Type Lead in the Entity field
    • Type Name, Id in the Fields field
    • Type Name != 'Z' in the Filter String field.

  4. Click the Filter >> button. The list on the left contains the request XML and the list on the right contains the reply XML.

We know that 22 leads were returned and we can scroll through and see all of the lead data. The Salesforce Integration Panel is a really useful debugging/testing tool.

That didn't solve our problem, though. How can we slog through the XML data? Do we actually have to parse it? The short answer is "No but read on to lean more.

Tutorial: Part 6 - Working with Salesforce Data

In this tutorial, we'll learn how to work with salesforce.com data. We will use some of the functions in the Sforce persistence library we copied into our project. We will also modify our popup window to allow us to send updated data back to salesforce.com.

Sforce Persistence

The primary purpose of the functions in the Sforce Persistence library is to make it easy to get data from salesforce.com, modify it locally and then update salesforce.com based on your local changes. As an example, by the time we're finished with this part of the tutorial, our popup dialog will:

  • Get Lead data from salesforce.com
  • Let you change the data - as many of the Leads as you like - locally
  • Make a single call to update all of the Leads at once

The DreamFactory convention for a persistence layer is a hidden XML Palette that stores an unmodified version of the data (the original data) and a version of all locally-made changes. Elements in the palette are created, updated and deleted locally. When you're finished making changes, you simply pass your XML palette to the xml_update_palette() function in the Sforce Persistence library. xml_update_palette() will identify all of your changes, additions, deletions and modifications and then make the appropriate calls to salesforce.com to apply your changes.

Step 1: Create two XML Palettes

  1. In the Tool Palette click on the main Tool button untilMisc. Tools is selected.
  2. Select XML Palette and drag it onto the IDE desktop (not as a child of any other node).
  3. Right-click on the XML Palette and select Name.
  4. Type master_scratchpad in the text box.


    This is the palette that will be used by the Sforce persistence library to see what you've changed.

  5. For your own use, create another XML Palette and name it master_leads.


    One of the conventions across all DreamFactory applications is the special_object function. This application-specific convenience function takes a node's name and returns the fully-qualified pathname of that node in the node hierarchy. The Sforce Persistence library depends on this function, so let's add it to our Tutorial Library. Here is the code for this function:

  6. Right-click on the XML palette and select Script.
  7. Paste the following code at the end of the existing script.
    
code special_object(what)
	local thename, prefix
	
	switch what
	case "master_scratchpad"
		thename = "<window:master_scratchpad"
	case "master_leads"
		thename = "<window:master_leads"
	default
		report_error("bad window", "unknown special window: " @ what)
		return empty
	endswitch
	prefix = nodefindplugin(nodefirst(), "desktop")
	return prefix @ thename
endcode
  8. Click Save to save your script. We won't need this function right away, but we will later.
  9. Right-click on the OK button and select Script. Instead of pushing our Lead data directly into our list, we're going to populate our new XML palette.
  10. Type the following code into the mycontent() function for your OK button.
    
code mycontent(hor, ver)
	local leads
	
	sforce_login("dfdeveloper@dreamfactory.com", "tutorial")

	leads = sforce_filter("Lead", "Id, Name, Title", "Name != 'Z'")
	xml_store_data("master_leads", leads)

	nodevisibleset("mypopup", true)
	nodebringtofront("mypopup")
endcode

  11. Click Save to save your script. Now, when you press the OK button your XML palette master_leads will contain your Leads:

Step 2: Populating the List

To populate our list, we need to pull the Lead data out of the palette. We will only display the Lead names in the list. We'll take advantage of a property of the List node to match list items with the corresponding items in the XML palette.

  1. Right-click on the OK button and select Script.
  2. Type the following code at the end of the existing script to create a new function:
    
code populate_list(mylist, xml_palette)
	local count, itemId, nameId, name
	
	list.dataset(mylist, empty)
	for count = 1 to xml.countelements(xml_palette, 0)
		itemId = xml.indextoelement(xml_palette, 0, count)
		nameId = xml.findelementchild(xml_palette, itemId, "Name")
		name = xml.elementvalueget(xml_palette, nameId)
		
		list.insertitem(mylist, count - 1)
		list.itemnameset(mylist, count, name)
		list.itemrefset(mylist, count, itemId)
	endfor
list.reset(mylist)
endcode

Let's look at some of the important points about this code:

  • Passing an empty data set to list.dataset() clears out the list
  • As we're iterating on the items in the XML palette, we first get the element ID. DreamFactory automatically assigns an ID to every XML element. We use this ID to fetch the Name (and later, the Title) of each Lead
  • When populating a list, you first insert an item and then set its name.
  • Each list item has a ref - a numeric value associated with the item. By setting this to the element ID from the XML palette, we'll later be able to match list items to XML palette items.
  • list.reset() resets the height of a list so that its parent scrolling window knows how big it is.

Now we need to call this new function from our OK button's mycontent() script.

  1. Right-click on the OK button and select Script.

Note: The XML palette (master_leads) actually consists of a parent window with a child XML node. It is actually the child XML node that we want.

  1. Click Save to save your script. Click the OK button. You should now see a list of leads in the My Popup dialog box.

Step 3: Display Title

Now that we're pulling and displaying Leads from salesforce.com, let's take it one step further. Let's display the Title of the selected Lead. First, let's change the label above the text box node in My Popup.

  1. Right-click on the Text Box label and select Enter Text.
  2. Type Title: in the text box and click OK.

    Let's also change the name of our Text Box node so that it's easier to use.

  3. Right-click on the Text Box node and select Name.
  4. Type lead_title in the text box and click OK. The Text Box Label now appears as lead_title in the Project Manager Palette.

Now, let's display the Title for each Lead selected in the list.

  1. Right-click on the List node and select Script.

Note: Ensure you have the list's script and not that of its parent border.

  1. Type the following code in the mycontent() function of the List node:
    
code mycontent(newitem)
	local xml_palette, itemId, titleId, title
	
	itemId = list.itemrefget(me, newitem)
	
	xml_palette = nodechildget("master_leads")
	titleId = xml.findelementchild(xml_palette, itemId, "Title")
	title = xml.elementvalueget(xml_palette, titleid)
	
	text.dataset("lead_title", title)
	text.textrefset("lead_title", titleId)
endcode

This code is doing two things:

  • Using the ref of the selected list item, we're fetching the Lead's Title from the XML Palette. Remember, we set the ref for each list item to the ID of the corresponding element in the XML Palette. That made it really easy to go back and get more info about the same Lead (in this case, the Title).
  • We're putting the Lead's title into the text field.
  1. Click Save to save your script.
  2. Click on any of the leads in the list in your My Popup dialog. Now the Title for that person appears in the text field to the right of the list:

Step 4: Local Editing and Salesforce.com Updates

It would be nice to be able to change the Titles of our Leads, wouldn't it? Let's do that now!

First we need to add a button to do the local update.

  1. Cycle through the Tools Palette to find Buttons Tools. Drag and drop a System Button onto the My Popup dialog window.

  2. Right-click on the Button and select Name.
  3. Type change_title in the text box and click OK to save your changes.

  4. Right-click on the Button and select Button Properties.
  5. Type Change Title in the Button Title text box.

  6. Right-click on the Change Title button and select Script.
  7. Type the following code in the mycontent() function.
    
code mycontent(hor, ver)
	local xml_palette, item, itemId, titleId, title
	
	item = list.selectget("list_contents")
	itemId = list.itemrefget("list_contents", item)

	title = text.dataget("lead_title")
	
	xml_palette = nodechildget("master_leads")
	titleId = xml.findelementchild(xml_palette, itemId, "Title")
	xml.elementvalueset(xml_palette, titleId, title)
endcode

Let's look at what this code is doing. When you click on the Change Title button, it is

  • Getting the selected item in the list
  • Using that to get the corresponding index into the XML palette (usin the "ref again)
  • Updating the Title for the selected Lead - but only locally!

Updating Salesforce.com

The last thing we want to do is actually update salesforce.com. Remember, we're using a Developer account so we won't be changing production data.

  1. Cycle through the Tools Palette until you find the Buttons Tools. Drag and drop a System Button onto My Popup dialog window.
  2. Right-click on the System Button and select Button Properties.
  3. Type Save in the Button Title text box and click OK.

  4. Right-click on the Dismiss Button and select Button Properties.
  5. Type Cancel in the Button Title text box and click OK.

    The My Popup window should look like this.

    Now let's make the Save button function.

  6. Right-click on the Save button and select Script.

We're now going to use the xml_update_palette() function in the Sforce Persistence library. All we have to do is pass it our XML palette, and it does the rest.

  1. Type the following code in the mycontent() function of the Save button:
    
code mycontent(hor, ver)

	xml_update_palette("Lead", "master_leads")
	
	nodevisibleset("mypopup", false)
endcode
  2. Click Save to save your script.

Now change the title for one of the Leads.

  1. Select the lead in the list that you want to change. Change the title in the Title text box and click Change Title.

Note: This is only making the change locally.

  1. Click the Save button to apply the change in salesforce.com:

If you log into your salesforce.com Developer account and look at this Lead, you can see the change you just made:

At this point, we've gone end-to-end. We've built a simple DreamFactory application that integrates with salesforce.com through the Web Services API. Pretty cool!

Launching Your App from a Browser

So far, we've had fun playing in the DreamFactory IDE, but to actually publish DreamFactory applications and to launch them in a browser or from within salesforce.com, you'll need to package your application. DreamFactory makes this really easy.

A DreamFactory application is just a single binary file - in this tutorial, it's called tutorial.dfac. It's a registered MIME type, and it's easy to launch in any browser or anywhere there is an IFrame to house it.

Packaging a DreamFactory application is a two-step process from within the DreamFactory IDE:

  • Zip the project file tutorial.dfac
  • Generate an HTML stub that launches your application.

Move on to Tutorial 7 to see how to do this.

Note: If you want to protect your application, you can also lock and password-protect the zipped project file.

Tutorial: Part 7 - Packaging the Application

It's time to package our application. In this part, we'll assume that you're running a local web server (something like IIS) for testing. We'll package the application, generate an HTML stub, put both into a folder on our web server and launch our application from a browser.

Preparing to zip your project

Before you zip your application, you need to hide all of the development -time windows:

  1. In the Project Manager palette, right-click on window:access_panel and click Hide Node.
    Repeat this step for: window:master_scratchpad, window:master_leads, and window:mypopup
  2. To close the IDE palettes, just right-mouse on the IDE background and click Hide All Palettes.
    You should end up with only the original dialog window showing:

    You can't zip a project you're actively editing, so close tutorial.dfac.

  3. From the File menu, select Close Project.
  4. Select File > Zip Project File...
  5. Select your tutorial.dfac and click Open. A HTML Stub File dialog box appears.
  6. Ensure the following properties are set:
    • Server name: = localhost
    • Folder name: = tutorial
    • Select both 100% checkboxes to ensure your application will grow to fill the browser window.
  7. Click Save and save tutorial.html in the same folder as your project .dfac file.

Note: The tutorial.dfac file should end up being less than 500KB in size.

In the future, you'll be able to click Skip. That'll still zip your project file, but it won't regenerate an HTML stub. Unless you need to change its location or properties, here's no need to regenerate the HTML stub.

  1. Now create a tutorial folder on your local web server.
  2. Copy both tutorial.dfac and tutorial.html into the new tutorial folder:
  3. Now point your browser to http://localhost/tutorial/tutorial.html

    When you click the OK button for the first time you'll see a security popup dialog.

    You don't yet have a developer certificate, so the DreamFactory runtime wants to make sure you trust your application to connect to another server (salesforce.com in this case).

  4. Click Grant.

Congratulations... We just logged into salesforce.com, queried to get a list of Leads and displayed them in our popup! Now grab your My Popup dialog and move it around - it's just like a desktop app, but it's running in your browser!

You just created a completely server-less (100% client-side) application that can talk to any Web Services server anywhere. It can even talk to more than one back-end system at the same time - try to do that that in AJAX!

A glance at the HTML Stub

Here is the stub created by DreamFactory. Note two key things:

  • We use the embeded tag to embed the DreamFactory runtime
  • The openfile attribute points to the dfac on your local web server


<HTML>
	<HEAD>
		<title>DreamFactory 6.40 Project: tutorial.dfac</title>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	</HEAD>
	<BODY bgcolor="#FFFFFF" topmargin="0" leftmargin="0" marginwidth="0" marginheight="0">
		<object
			classid="clsid:226906C8-B911-11D5-82A3-0000F81A655B"
			codebase="http://www.dreamfactory.com/codebase/dfacactx.cab#Version=6,4e,0,1"
			id="dfacinst"
			border=0
			width=100%
			height=100%>
			<param
				name="htmldata"
				value="Pass any string to your project here...">
			<param
				name="openfile"
				value="http://localhost/tutorial/tutorial.dfac">
			<embed
				type="application/dreamfactory"
				pluginspage="http://www.dreamfactory.com/codebase/winplug.exe"
				width=100%
				height=100%
				htmldata="Pass any string to your project here..."
				openfile="http://localhost/tutorial/tutorial.dfac">
			</embed>
		</object>
	</BODY>
</HTML>

Integrating your Application with Salesforce.com

There are several ways to integrate a DreamFactory application into the salesforce.com user interface. The most common ways include

  1. Custom Link - A custom link is a live link that appears on the salesforce.com page layout for some Salesforce entity (Lead, for example). The most common place for a custom link is on a detail page. When you click the link, your DreamFactory application can launch in place, taking over the current page, or it can launch in a new browser window.
  2. Custom Button - A set of buttons appears at the top of any detail page within the salesforce.com UI. Salesforce.com allows administrators to add buttons that perform custom functions. A common use of custom buttons is to launch DreamFactory applications. As with custom links, the DreamFactory application can either launch in place, taking over the current page, or it can launch in a new browser window.
  3. Custom S-Controls - In Salesforce-speak, an S-Control is a component that you set up and define in Salesforce to store your custom code. An S-Control can also point to a URL, such as the URL tat launches your DreamFactory application. The interesting thing about S-Controls is that they can launch in-line, taking over a section of any salesforce.com page.

All three of these integration mechanisms has advantages and disadvantages. Custom links have been around longer than the others, so you will see custom links more often than the others. Custom buttons are becoming more popular, as they are more intuitive and better looking - a button stands out more, so is easier for users to find and use. Inline S-Controls are very interesting, because they allow you to pop up something - your DreamFactory application, for instance - without having to take over the entire page. DreamFactory's commercial applications make use of all three of these integration mechanisms:

In this picture, Carousel (our dynamic presentation, report and dashboard application) is presenting an opportunity dashboard directly in an Opportunity page, using an inline S-Control. OrgView (graphical organization charts) launches from a custom link.

In the next tutorial, we'll integrate your DreamFactory application into salesforce.com via a custom button. Once you know how to use one of the integration mechanisms, you have all of the information you need. They are all very similar in the way they work and in how you configure them. Salesforce.com has a built-in help system and examples available if you need additional information.

Tutorial: Part 8 - Integrating with the Salesforce UI

In this tutorial, we'll create a custom button in our salesforce.com developer account. We'll configure the button to launch your DreamFactory application, and you'll nearly be done!

Step 1: Create a Custom Button

Creating a custom button in salesforce.com is a two-step process. First, you create the button and configure its behavior. Then you need to include the button in a page layout. In salesforce.com, a page layout defines which fields, buttons, etc. will be displayed on a page, and in what order. The salesforce.com UI is a traditional two-column HTML layout, so you don't have a lot of flexibility in your UI. That's one of the advantages of DreamFactory - you can make your application look, behave, and interact in any way you like.

Log into your salesforce.com developer account. The login URL is: https://www.salesforce.com/login.jsp

At the top of the page, click "Setup. On the left side of the page, under "App Setup, click "Customize, then "Leads and then "Buttons and Links. This will take you to a page that lets you create a custom button on the "Leads tab.

Click "New to create a new custom button.

In the next page, fill in the Label and Description. The "Behavior" dropdown lets you decide whether your application will pop up in the current page or in a new browser window. Let's choose "Display in existing window with sidebar. This will launch our DreamFactory application in the current page. Choose "Detail Page Button for the Display Type and "URL as the Content Source. In the large text field at the bottom, enter the URL for the HTML stub you created in Part 7 of this tutorial. For me, the URL is http://localhost/tutorial/tutorial.html

When you click "Save" you'll see the following popup:

Step 2: Add your Button to a Page Layout

You still need to add your button to the Leads page layout in order to see and use it. On the left side of the page, under "Leads", click "Page Layouts" and then click the "Edit" link next to "Lead Layout":

To add your button to the page layout, click on "Detail Page Buttons" in the Button Section and then click the "Edit Properties" button just above the Button Section:

In the popup, select your new button in the "Available Buttons" list on the left, click the right arrow (Add) so that your button appears in the "Selected Buttons" list on the right, and click "OK":

Click through this popup

and then click "Save" at the top (or bottom) of the "Edit Page Layout" page.

There. You've created a custom button in salesforce.com, and you've configured it to launch your DreamFactory application. Now let's try it out! Click on the Leads tab

and click on any of the Leads listed. On the detail page for that lead, you'll see your new custom button:

Step 3: Try It!

Click on the button - go ahead, it won't bite! Et voila! Your DreamFactory application will appear inside salesforce.com!

Tutorial: Part 9 - Packaging for AppExchange

We're almost done! We've gone from zero - no DreamFactory IDE, no salesforce.com account, nothing - to a DreamFactory application that is integrated with salesforce.com and launches from within the native Salesforce UI. The final step is to package your application so that you can share it with others.

In this part of the tutorial we will create an AppExchange application with its own custom tab. That tab will house your DreamFactory application. We'll then create what Salesforce calls an AppExchange Package. You can make that package available to others via the AppExchange.

Step 1: Create a Custom Tab

First, let's create a custom tab. Log into your salesforce.com devekoper account, if you're not already there. At the top of the page, click "Setup". On the left side of the page, under "App Setup", click "Build", then "Custom Tabs" and then click the "New" button next to "Web Tabs".

This will start a 5-step "wizard" to create your custom Web Tab. In Step 1, click "2 columns with Salesforce sidebar" and then click "Next".

In step 2, select "URL" as the Tab Type. Give your tab a label, style and description and click "Next".

In step 3, enter the URL of your HTML stub. This will be the same URL you used for your custom button in the previous part of the tutorial. In my case, the URL is http://localhost/tutorial/tutorial.html

In step 4, just click "Next". In step 5, uncheck all of the boxes on the right and click "Save". We'll add our new web tab to the custom app we're about to make in a few minutes.

Step 2: Create a Custom Application

Now let's create a custom application. On the left side of the page, under "App Setup", click "Build", then "Custom Apps" and then click the "Continue" button on the right.

On the Custom Apps page, click "New".

This will start a 4-step "wizard" that will help you create your custom app. In Step 1, give your application a label and description.

In step 2, just click "Next". In step 3, select your custom tab - "My Leads" in the "Available Tabs" list on the left. Click the right arrow (Add) to move your tab into the "Selected Tabs" list on the right and click "Next".

In step 4, make your new app visible to all user profiles by clicking the checkbox next to the "Visible" label at the top. Click "Save" to complete your new custom app.

To test your new app, go to the Appexchange dropdown in the upper right corner of the salesforce.com pane. There should be an entry for your new app. Select your app froim the list. You'll see two tabs now: "Home" and "My Leads". Every salesforce.com app has a "Home" tab - that's not the interesting part. Click on "My Leads" and you'll see your DreamFactory application running in your new custom tab.

Step 3: Packaging Your Application for the AppExchange

Finally - the last step! To share your application with other salesforce.com users, you need to create an AppExchange package. This package will allow someone else to install your application in their salesforce.com org (account). If you want to sell your application on the AppExchange, you need to go through Salesforce's certification process. I don't think our app is quite ready to sell yet, so let's just create a private package.

At the top of the page, click "Setup". On the left side of the page, under "Exchange", click "Shared Apps" and then click the "New" button next to "Package List".

Give your package a name and description, and click "Save".

Click the "Add" button next to "Package Items".

Click the checkbox to the left of your new custom app ("My Leads") and click "Add To Package".

Now, under "Package Items" you will see both your custom app and your custom web tab. Your custom app includes your web tab, so Salesforce was nice enough to include both for you. Click "Upload to AppExchange" to upload your new package.

Give your package a version and click "Upload to AppExchange" one more time.

This time, the upload will really happen. When the upload is complete, click the "here" link to check on your package status.

Click the "Register" button to register your package with AppExchange.

The "Reference URL" in the next page is the link yo your new AppExchange package. Click on this link to see your new package, or give it to a friend to install in another salesforce.com org.

Click on the link, and you'll be there - your package on the AppExchange! This is a private package, so you can't search for it on the AppExchange. You'll have to give the URL to anyone with whom you want to share your package.