DreamFactory Tutorial

• Starting A New Project
• Building Some Objects
• Get A WSDL From XMethods
• Put Everything Together
• What Just Happened?
• Finishing Touches
• The Document Exchange Wizard

Welcome to the DreamFactory Tutorial. This document shows how to build a working web services client application in a few minutes right in the browser. Before starting the Tutorial, you may want to take a look at the DreamFactory Getting Started Manual for a broad overview of all of the main issues. The project that we will build has a window with a pop-up menu button allowing you to select the number for a California highway. We call a web service with the number, and then the current traffic conditions for that highway are then displayed in a text field. Our friends at XMethods provide the web service that we will use. The XMethods web site has a large directory of publicly available web services that you may find useful.

In general, DreamFactory can take advantage of web services or XML from any
source given a WSDL file or just a SOAP envelope. In this demo we use the WSDL
for the service, so this tutorial also provides basic information on how to
import a WSDL, get the SOAP envelope, and then call the service. Be sure to
check out the last section on the DreamFactory Document Exchange Wizard, which
discusses an easy way to automatically generate complex user interfaces for
any web service. Here are the steps for the tutorial project:

Throughout this document you will see sections labeled as an "Important Note" in bold type. Read these sections carefully, they identify important issues for the DreamFactory author.

Installation

DreamFactory consists of a software engine and various project files. The
engine is either an ActiveX control, Netscape Plug-in, or stand-alone executable.
There is no distinction between the development environment and the runtime
engine: they are one and the same. You can either build or run your application
in either the browser or from the stand-alone executable. The browser-based
control can be installed by running any of the example projects in the "Live
Demo" section of our website:

http://www.dreamfactory.com/demo/

Navigate to an example project, click the "Install/Update" button, accept
the code-signing certificate, and DreamFactory Runtime will install itself if
necessary and run the selected project file. The stand-alone version of DreamFactory
and the browser plug-in for Netscape users is available from:

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

This runs the DreamFactory Professional environment as a stand-alone application,
which may be more convenient for some users. Download and run the installation
program, and the stand-alone version will be installed, along with a desktop
shortcut and a "Start/Programs/DreamFactory" menu item. There is also
an installation program for just the plug-in, which can be downloaded from the
same location. Both installers have un-install functionality.

Starting A New Project

This section shows how to start a new project in the browser-based DreamFactory
Runtime and stand-alone DreamFactory Professional application.

DreamFactory Runtime

You will need to go to a URL with a blank DreamFactory project. There is a full-screen MIME type new document available at:

http://www.dreamfactory.com/projects/bootfile.html

If for any reason there has been something already built on this project, and your screen does not look like the screen pictured below, please right-click on the desktop and select the "Clear Desktop" pop-up menu option. Macintosh users should option-click for right-click. Throughout the tutorial we will go to other web pages to get graphics or text, and then return to this page. Just use the "Back" button of your browser to do this.

DreamFactory Professional

Go to the "Start/Programs/DreamFactory/New Project" menu item in Microsoft
Windows, or launch the DreamFactory stand-alone executable on Macintosh and
select "New" from the File Menu. Locate a destination and save your project
there. You will need to open a browser to get some other web-based resources
needed to complete the tutorial. Just navigate to the desired browser page,
and then click on the DreamFactory stand-alone executable in the task bar to
return. On Macintosh use the System 9 Application Menu or the OS X Icon Dock
to switch between the browser and DreamFactory Professional.

When you are finished, your screen should look something like the one below. As you can see, there are four Utility Palettes in the upper left of the window. These are also written in DreamFactory, and can be modified as necessary.

The Tools Palette (upper left) can create new objects; we are getting ready to use the Tools Palette to build assets for our web services client. The Project Manager shows the tree view of your project. As you create objects in the tutorial they will show up in the Project Manager. The Utility Palette sets the control style, invokes the Debugger, and handles Project Security. Lastly the Alignment Palette will align selected nodes in various ways. This is mainly useful in dialog boxes with many controls.

Important Note: All of the palette windows can be expanded to expose more controls and capabilities by clicking the zoom box in the title bar. The rest of this Tutorial works with the palettes in their original, more compact size.

Back to top

Building Some Objects

Next we are going to build a series of object. In general, you will need to select the correct set of tools by clicking on the top button of the Tools Palette until the right page comes up (a control-click will go backwards through the pages). Then, you will want to select one of the creation tools below. Next, click and drag on the desktop to create a new node of the appropriate type and size. You can also just "drag" a node right off the Tools Palette and drop it anywhere. With this method the node is given a default width and height and can be resized later.

Important Note: When creating nodes, DreamFactory pays attention to where you begin the mouse drag. If you click in the desktop and drag, then the node is created on the desktop. If you click in a window and drag, the new node is created as a child of that window. This also works when pasting objects. If you right-click on an object and choose "Paste" from the pop-up menu, the contents of the clipboard will become children of that object. Check the Project Manager for a graphical view of the current tree structure of your application if you need more information.

The illustration below shows all of the different tools available in the Tools Palette. These are just a fraction of the total number of tools and styles available to the DreamFactory author. And these tools can be combined hierarchically to build up tool-based components that can be copied and re-used.

To build the tutorial example, navigate the Tools Palette to the window tools by clicking the top button. Then select the document window tool; this tool is on the left-hand side halfway down, see the following illustration. Now, click on the desktop and drag to create the window. After that, we are going to create the rest of the nodes as children of this window. To do so, select the correct tool, click and drag to create. Remember that your first click must be inside your new window; this lets DreamFactory know that the node you are creating should be a child of that window. The children will stick to the window's coordinate system, and you can also have the window clip the children if desired. Below is a list of all the objects that need to be created, and after that there is a picture of what the screen will look like.

When you create the draw node you will be prompted with a Get File Dialog
for an image. Simply cancel this dialog, we will get a picture for the draw
bitmap later.

When you are finished, the screen should look something like the illustration below. Try to create your objects in the basic layout we have here so that the rest of the tutorial works correctly. If you would like to re-size something, that's easy. Select the reshape tool (to the right of the arrow in the Tools Palette) and then click on various objects. Control-click to select or de-select multiple objects. Then drag or resize the objects as desired. You can even use the Align Palette to line up multiple selected objects. When you want to go back to run the application (and complete our tutorial) choose the arrow tool again, and all handles will disappear.

Now we are going to grab a graphic to paste into the bitmap. There is a selection of clip art available at:

http://www.dreamfactory.com/myclipart/

Go there, right click the truck, and choose "Copy Image" to copy the image
to the clipboard. Go back to your DreamFactory project, right-click on the draw
bitmap node, and choose "Paste Image Clip" near the bottom of the menu. Do not
choose the "Paste" near the top of the menu, that is the option to cut, copy,
or paste the actual nodes themselves.

When finished, you should have the truck picture pasted into the draw bitmap
node. Right-click the draw bitmap node and choose "Reset Bits" from the pop-up
menu, this will make the image display at 100% with no scaling. The Reset option
is also available for the list, table, menu, movie, text, and picture nodes
whenever you need to display them at their native 100% size.

Back to top

Get A WSDL From XMethods

Browse to the XMethods web site and scan down the list of many web services
they have available. At the bottom, click the service named "California Traffic
Conditions" and you will go to a page that looks like the picture below. The
URL to the WSDL shown below documents the SOAP entry point for this service,
and that is what we need to call the function. Select the WSDL in the yellow
bar with the mouse and copy the URL as a text string to the clipboard. Click
the "back" button in the browser to return to your DreamFactory project.

Back to top

Put Everything Together

Now we are going to invoke the Web Services Wizard on the pop-up menu we created
earlier. Right-click the pop-up menu (the title will be "Item 1" or
something like that) and select the "Web Services Wizard" option from the pop-up
menu that appears. This will bring up the dialog shown below. Paste the URL
you copied from XMethods into the field at the top of the Wizard and click the
"Load WSDL" button at left. Your screen will look like this:

The ports and functions available in this WSDL are shown in the box labeled
"Step 1" above. This WSDL has one port named "CATrafficPort"
and a single function named "getTraffic." Multiple ports are rare,
but many WSDLs have more than one function, so do not forget to select a function
name if necessary. Below that, in the box labeled "Step 2", you will
see the request parameters for this web service. These are the input arguments
that the service expects you to specify. In this case, there is only one input
argument, "hwynums" which is of type string. We will need to connect
this argument to the pop-up menu which is going to contain the source highway
numbers. Below that, in the box labeled "Step 3", you will see the
response parameters for this web service. These are the output arguments that
the service returns. In this case, there is only one output argument, "return"
also of type string. We will need to connect this parameter to the destination
text field where we are going to display the current traffic conditions.

To connect a user interface to the correct SOAP request or response parameter,
simply click on the "User Interface" radio button, and then click
on the menu node or text field you created earlier. You might have to reposition
the Web Services Wizard dialog window to click on the node you want. You can
also select the user interface manually from the list in the Wizard. Do this
for both the request and response parameters, and your screen will look something
like the picture below. Now click the "OK" button and the user interfaces
will be automatically hooked up to the web service.

Important Note: When you created the text field earlier you really created
two nodes, not one. The scroll bar and the surrounding frame are really a border
node with a rich text node inside. So, when you click on the text, be sure to
click in the text area, not the scroll-bar or frame area because that is really
the border. Check the Project Manager to see how everything is connected.

There is one detail left to finish up: the pop-up menu needs the names of California
Highways instead of the default menu values "Item 1", "Item2",
etc. To do this right click the pop-up menu and select the "Menu Properties"
option. Enter some popular California Highway numbers in the Menu Properties
Dialog. Here are some Bay Area highway numbers that you may have been stuck
on recently: 85, 280, 101, 1, 17. The picture below shows the pop-up menu being
edited.Click "OK" when you are done.

Now you are ready to test the service. Select a Highway from the menu, and
see the traffic conditions appear in the field. The Web Services Wizard can
be used to connect any number of input parameters in a service to any number
of output parameters through any number of user interfaces or constant values.
The Wizard works great with any correctly formed RPC-Style or Document-Style
WSDL, and can be used for complex XML document exchange. The next section discusses
how the Web Services Wizard works internally. This is useful for scripters who
want to modify the output of the Wizard to solve special case problems and implement
more sophisticated applications.

Back to top

What Just Happened?

The Web Services Wizard actually adds a new function to the script of the
pop-up menu node which is called when an item is selected. This function gets
the source highway number from the menu, inserts it into the SOAP request envelope,
calls the web service entry point, and then retrieves the result from the response
envelope and places it into the correct destination text field. To see the proxy
stub function, right-click the menu node and select the "script" option:

The actions of the proxy stub function are documented in the comments above.
Most of this is accomplished with some simple library functions that you could
trace into with the Debugger if you wanted more detail on how this SOAP transaction
is supported by DreamFactory. To do this set a breakpoint for the getTraffic()
function by clicking in the dotted box to the far left of the Script Editing
Window. When the function is called the Debugger will appear, click the "Step"
or "Step In" button and watch. Hit the "Run" button to dismiss the Debugger().
Actually there are many ways to call web services or do Internet transactions
in DreamFactory, this is just one. If you drill down into the soapcallfx() handler
you will see that most of the magic is accomplished with the webuploadimmediate()
system command which executes an http POST remote procedure call.

Important Note: DreamFactory supports the VBScript and JavaScript scripting
languages. Click on the "scroll" icon on the far right of any script window's
tool bar to switch between the different scripting styles.

The Web Services Wizard also gives you the option to initialize a request
parameter from a constant value or a functional argument. The response parameter
can be mapped to a local variable or the function result. If you select these
options you will see the results in the proxy stub function that is created.
This is especially useful if you want to design a function with certain input
and output parameters for general purpose use. The function could be copied
to another node or library at that point. Find more information about scripting
in the Getting Started and Reference
Manual .

Along with the new function discussed above, the Web Service Wizard also adds
two hidden XML palettes to your pop-up menu node. These palettes are used to
store the SOAP request and response envelopes. You can locate these windows
in the Project Manager and make them visible, they will be children of the menu
node. When the service is invoked you can watch the actual SOAP transactions
flow across the network. The picture below shows both SOAP palettes and the
Project Manager with one palette selected. The next section adds a simple script
to our project that can hide and show these palettes.

Back to top

Finishing Touches

The rest of the tutorial adds a few bells and whistles to your project. First
we add a script to hide and show the SOAP palettes added by the Web Service
Wizard. Next we make the content area of the window draggable. Lastly we make
clicks on the draw graphic transparent. These finishing touches are of general
use for any DreamFactory application.

Hide and Show the XML Palette

Let's add a script to the standard system button created earlier that will
hide and show the SOAP palettes. First, give the button a clever title like
"Hide / Show SOAP" by right-clicking and editing the Button Properties. Then
copy the following script and replace the button's default mycontent() handler:

code mycontent(hor, ver)

	if nodevisibleget("soap_request") or nodevisibleget("soap_response")
		nodevisibleset("soap_request", false)
		nodevisibleset("soap_response", false)
	else
		nodevisibleset("soap_request", true)
		nodevisibleset("soap_response", true)
	endif
endcode

This will hide and show the SOAP palettes with each click of the button. Edit
the script to change the button title from "Hide XML" to "Show XML" when you
click. Here is an example line of code that you will need to do this: button.titleset(me,
"Hide XML").

Drag Your Window

The next feature that would be nice to have is the ability to drag your new
window when the user clicks in the content area, not just the title bar. Right-click
on the document window and select the "script" option. Add the following lines
to the mycontent() handler:

code mycontent(hor, ver)

	cursorset("fist")
	dragany(me, hor, ver)
endcode

This is a simple trick that can be used with any node: dragany() is a library
command that will drag any type of object on demand. Set a breakpoint on dragany()
and follow it down into the library if you want to see how this works. The image-conscious
author will also want to change the cursor in the window's mousemove() handler
to a "hand" (instead of an "arrow") indicating that the window can be dragged,
and then the cursor changes to a "fist" for the actual dragging, above.

Dump The Truck

One last point. You might want to make your truck picture essentially transparent. In other words, when the mouse passes over the truck, or when someone grabs the truck, you really just want it to act like the window and drag. To do this, use the "passcode" reserved word to jump out of the current handler and continue execution down the hierarchy to the window script. This makes the current handler invisible, and passes the message on down the hierarchy. Here's the script for the truck bitmap modified with the passcode reserved word:

code mousedown(which, hor, ver)

	if hijackmousedown(me, which, hor, ver)
		exitcode
	endif
	passcode
endcode

code mousemove(which, hor, ver)

	if hijackmousemove(me, which, hor, ver)
		exitcode
	endif
	passcode
endcode

The passcode reserved word passes the mousedown() and mousemove() message on down the hierarchy to the father window. The truck is now transparent to mouse clicks, and seems to be part of the window. This is a useful technique for many situations, especially where you want a complex set of controls to behave like a single widget.

Important Note: The other two handlers hijackmousedown() and hijackmousemove() are part of any default script. These allow the DreamFactory system scripts to implement pop-up menus, shift clicking for the script window, and handle resizing. If these handlers are removed your node will be difficult to edit.

Congratulations! You just built a complete web services application and never
left the browser. The basic techniques employed are of general use. First, create
some nodes and reshape them into a prototype of your application. Right-click
to modify the appearance or properties of the nodes or invoke the Web Services
Wizard. Next, edit the scripts to add or change functionality. Remember that
complete online help is always available, just select the scripted line in question
and type Control-slash. Watch the information bar in the script-editing window
for useful feedback, or use the Message Box to experiment with the language.
The next section discusses an easy way to generate user interfaces automatically
with the Document Exchange Wizard.

Back to top

The Document Exchange Wizard

The Web Services Wizard is somewhat limited when it comes to service transactions
that require nested arrays of data: an additional layer of user interface is
required to manage the array elements themselves. The Document Exchange Wizard
solves this problem by inspecting the XML Schema in the WSDL and automatically
generating complex user interfaces that include tables, scrolling lists, nested
arrays, pick lists, check boxes, radio buttons, and edit fields. This capability
allows you to call virtually any web services no matter how complex the transaction.
The downside is that the Document Exchange Wizard does not produce a single
proxy stub function that can be easily edited, but instead a complex tree of
interfaces that is somewhat more difficult to modify.

First create a Window or Border node, and right-click to select the Document
Exchange Wizard option. Be careful, because any existing scripts or node children
in the selected window or border will be erased when the Wizard creates the
new interface. You will be presented with the dialog shown below. Select and
load a WSDL like we just did with the Web Services Wizard:

Next, click on the Request Form or Response Form tabs and see the user interface
that was generated. A style palette will appear to allow customization of the
appearance and layout of the interface. Fill in the request form, and click
the Send SOAP Request button at the bottom of that tab. This will generate a
SOAP request, and send it to the server specified in the WSDL. Then you should
see the result in the response form. You can also look at the actual SOAP request
and response XML by selecting the appropriate tab.

Lastly, go back to the first tab and select how you would like to save the
layout for your document. The Horizontal Divider option shows the request document
above a horizontal bar with the response document below. The Vertical Divider
option shows the request document to the left of a vertical bar with the response
document to the right. The In & Out Tabs option will generate a request
and response tab with the buttons above. The picture below shows the results
of the California Traffic Conditions service with a draggable Horizontal Divider
interface.

The Wizard is compatible with both RPC and Document style WSDL files. Complex
transactions can be conducted with multiple request and response parameters
if desired. You can apply the Wizard to a window or border any number of times,
but the old settings are not saved because of space limitations. Once created,
the window or border node can be copied into any Dreamfactory project and will
work as expected.

Back to top