Getting Started
Welcome to the DreamFactory Getting Started Documentation. This manual provides a broad overview of building DreamFactory applications and includes most everything you need to get started. Be sure at least to read the Architectural Overview and New Projects sections. After that, check out the DreamFactory Tutorial and Reference Manual . You may also be interested in the Technical White Paper , the Scripting Reference , and the Security White Paper .
Introduction
DreamFactory is the first browser based development environment. You can build web services applications with rich media assets right in the browser or use the stand-alone application version for either Macintosh or Windows. There is no difference between the development environment and the runtime: applications can be created and modified while they run and you can see results immediately. Objects can be further customized with the DreamFactory scripting language. You can switch between DFScript (our native language) and VBScript and JavaScript as you work. DreamFactory is compatible with many other familiar web standards and formats, but you still need an overview of the development process and an understanding of how DreamFactory Projects are put together. After a brief discussion of Installation, the following chapters cover: Architectural Overview, Plug-Ins, New Projects, and Scripting Basics.
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. 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.com/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.
The DreamFactory installation folder contains 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." DreamFactory runs in mirror identical fashion on Macintosh System 9 and OSX, and on Windows 98, 2000, ME, and XP. Both Internet Explorer, Netscape Navigator, and Mozilla browsers are supported with a 400K one time control download. Every document is identical pixel for pixel, platform for platform no mater where it is displayed. The fact that DreamFactory is a MIME type means that it can run full screen or as multiple instances on a web page, can be embedded in Microsoft Word or Excel, and can be sent directly as an e-mail extension.
Removal
DreamFactory is very careful not to modify your system software in any way. In general, DreamFactory can be removed by going to the "Start/Programs/DreamFactory" menu and uninstalling the stand-alone application or plug-in as desired. To delete everything by hand, first delete the "DreamFactory" folder inside of "Program Files." If you have an ActiveX control or Netscape plug-in, they can also be deleted. On Windows, search for the "Downloaded Program Files" folder, right click on the file "DreamFactory Control" and select "remove" from the pop-up menu. The Netscape plug-in "NPdfac.dll" will be in your Netscape or Mozilla plug-ins folder, just delete it. On the Macintosh the Netscape plug-ins are used for the Internet Explorer Browser as well, and are clearly labeled in the plug-ins folder. You might also need to clear your browser cache.
Architectural Overview
Every DreamFactory project is a hierarchical collection of objects called nodes. Each node has a script and is associated with a plug-in that manages additional data of a specific nature. All of the nodes, scripts, and additional data are stored in a single project file with a ".dfac" extension. The first node is the "root" node, and all other nodes are connected to it. Each project also has a special script called "project" that receives most system messages and parcels them out to the appropriate node. This is similar to HyperCard, where buttons stick to the card, and the cards are in stacks, except that the DreamFactory hierarchy is entirely freeform and can be re-wired on the fly as desired. A better analogy is XML: the nodes are like elements, and their attributes are defined by the associated plug-in. Each node can have brothers or contain children. The diagram below illustrates a simple DreamFactory project and some plug-ins:
The illustration below shows how this project might appear on the screen. The hierarchical structure of the nodes determines the visual organization of the screen and the logical organization of the project. The structure also determines the message passing hierarchy, so a message naturally passes down from node to node to the root script down to the libraries searching for a handler. A "handler" is a scripted command or function (like a subroutine in VBScript). A node will automatically inherit the capabilities of all of the lower nodes in the hierarchy. What this means is that if you put a handler in a parent, the child will have automatic access to it, and can call that function. So in the picture below, if both the "button" and the "text" need a particular handler, you might place that in the "window" script. The handlers in the library scripts are available to all nodes because they reside at the bottom of the hierarchy.
Each node is a control and potentially a container -- they determine the clipping and coordinates of their children. This simple paradigm allows the rapid construction of essentially every user interface scenario: multiple windows, child windows, palettes, dialogs, scrolling areas, menus, hierarchical menus, controls, tabbed pages, tables, etc.
Editing operations also obey the hierarchy, allowing the rapid transport of useful widgets between web applications. Every logical subset of the project works. This is extremely important for "universal canvas" environments that manage collections of interactive tools that can be shared across pages. The plug-ins provide special capabilities to a node, and each node is associated at birth with a plug-in. Essentially the plug-ins are like definition functions or drawing engines that can be controlled like puppets. The vast majority of plug-in commands and functions are simply drawing attributes for the object. When you set an attribute, the associated node will be persistently changed in appearance. The hierarchy of scripts in the document coordinates the actual behavior of the nodes. The plug-ins also organize DreamFactory commands and functions into easy to understand categories.
The DreamFactory scripting language is the result of 18 years of research into how creative people build things. The problem with languages like HyperTalk that use English-like commands and functions is that they end up with extremely complex syntactical rules. Languages like Java require hundreds of abstract class definitions that also have to be remembered. The DreamFactory scripting environment is designed so that you seldom have to remember anything. We follow the syntax of the JavaScript standard and also support VBScript, providing for easy skills transfer from existing languages.
The language has two types of commands and functions: system and plug-in. The system commands are universally available core routines that manage nodes and perform other generally useful functions. The plug-in commands are associated with a specific plug-in and usually control the appearance of the associated node.
In the following code snippet, the system command nodenew() in green is used to create a new node with the "draw" plug-in inside the parent window. Then the plug-in command draw.styleset() in purple sets the style of the new draw object to "oval". As you type the syntax of all commands and functions is illustrated in the information bar at the top of the window. Everything is color-coded, potential errors and comments are in various shades of red. DreamFactory automatically predicts future keystrokes as you type. Spelling errors are corrected as each word is finished. You can type junk and DreamFactory will try to make sense of it based on context.
You should create variables and handlers before referencing them, so that auto-typing can work. You can also turn off this feature in the system edit menu. In our example, this just means that you should define the variable "newname" before referencing it on the next line.
The small "Menu" button to the right of the information bar gives you access to the system pop-up menus. If you get stuck the help system is context sensitive and immediately available and can be used to quickly review all of the functionality in the system commands or a specific plug-in, simply select a scripted line and click on the little question mark symbol at the top of the window. Clicking on the scroll icon to the right of the help system will flip between VBScript, JavaScript, and DFScript.
Try scanning your script with the mouse while the Control Key is down: all pertinent features of the language and documentation for commands and functions will appear in the information bar. Try scanning outside the window: the names of all the DreamFactory objects will appear.
Along with commands and functions, you can also access all nodes with object-oriented properties and methods. This will be more comfortable for the object-oriented programmer, and provides a convenient and terse scripting alternative. For example, in the preceding example, you could replace the draw.styleset() line with any of the following:
newname.style = "oval"
newname.draw.style = "oval"
newname.styleset("oval")
newname.draw.styleset("oval")
If you include the plug-in name (in this case "draw") with the property or method syntax the scripting language pre-binds to the given plug-in for speed. If not, the language dynamically figures out which plug-in you are talking about at runtime. There is more information in the Reference Manual on the use of object-oriented syntax. By the way, the word "oval" above need not appear in quotes; single unquoted names are recognized as strings unless there is a variable by that name.
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, and various Script Editing windows.
The Debugger can be brought up at any time and can set breakpoints and step through scripts as they execute. The Debugger also tracks the values of local, global, and regional variables, and 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 hit 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 allows instant execution and exploration of the DreamFactory language. Right-click any node and select the Target pop-up menu command. Then the Message Box will 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 objects by hand (if desired) or test out the scripting language. Hold down the control-key and scan with the mouse to identify visible nodes by name.
The Help System documents all system and plug-in commands. First, read through the system commands and find out what DreamFactory can do. The system commands are sorted into logical groups with common prefixes. Then read the help file on a specific plug-in to find out what specialized capabilities are offered. The Help Window is always available and context sensitive, and is intended as a general DreamFactory reference.
The Background Desktop is the main window that holds the project and all the 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.
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, hold down the Control Key and scan with the mouse to see every language element documented and explained in the information bar at the top of the window. Bring up the Find Dialog (Control-F, 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. This is very useful for following messages down the hierarchy. The "Menu" button to the right of the information bar provides access to DreamFactory system menus.
Plug-Ins
All DreamFactory functionality is provided by plug-ins. Some plug-ins are standard, and you can expect them to be available at all times. The standard ones include Chart, Border, Button, Desktop, Draw, Guage, Icon, List, Menu, Movie, Picture, Sound, Sprite, Slider, Table, Text, Window and XML. New plug-ins can be developed as necessary, and they become first-class objects available to the system 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 the plug-ins control the visual appearance of the node. Often the script will use these commands or functions to manage the appearance and behavior of the 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.
Nodes created with the standard plug-ins are shown below, some plug-ins can appear in a variety of styles and many of these are also shown. Most of the examples just show objects on the desktop; normally the nodes will be used inside windows or borders in an application setting.
Border, Desktop
Border - Tabs, scrolling areas, dotted lines, invisible groups, and other style borders
Desktop - Usually the desktop is connected directly to the root node and holds the document's objects
Button
Button - All button styles including radio and check boxes in all user interface styles
Chart
Chart - Business charts and graphs in editable styles with single and multiple data sets
Draw
Draw - A workhorse object that does simple bitmaps, simple text, ovals, rectangles, polygons, lines, and round rectangles
Guage
Guage - Dials, knobs and guages of every description. There are four major parts to a guage: the dial and face, the ticks and ramp, the numbers, and the needle. Each of these parts can be individually styled
List
List - Lists of names, outlines, and tabbed lists in a variety of styles
Menu
Menu - Pop-up menus, pull-down menus, hierarchical menus, button menus and menu bars in all user interface styles.
Movie, Picture, XML, Sound, Sprite, Icon
Movie - QuickTime and Windows Media Format movies plus various movie based features
Picture - Photographic quality controlled pictures plus rotation and scaling, automatic thumbnails
XML - Build XML soap transactions, and read and write any XML format
Sound - Looping, volume controlled, panning sounds can be imported and exported as necessary
Sprite - Irregular edge graphics that can animate automatically or under script control
Icon - Simple 32-bit color images for patterns, cursors, and icons. The icon data can be transferred to lists, menus, windows, and buttons.
Slider
Slider - Scrolling bars of every description and style. There are four parts to a slider: the thumb, the bar, the stops, and the tick marks, and each part can be given a separate style and other attributes
Table
Table - Full blown table editing with multiple cells and layout capabilities.
Text
Text - Rich text edit records with cursor placement, hypertext capabilities, styles and color. Rich text display is identical on every platform.
Window
Window - All window styles including dialogs, scrolling, and palettes. Every user interface style is supported
New Projects
DreamFactory provides some basic tools for building new projects. These tools are written in DreamFactory and can be modified as necessary. Builders of advanced applications will end up creating additional tools for specific purposes. The project "bootfile.dfac" is an empty shell that contains the basic toolset. If you want to use a stand-alone executable to build your project, you can download this for Windows or Macintosh from:
http://www.dreamfactory.com/download/
Browser based authors can simply jump to a blank project at:
http://www.dreamfactory.com/projects/bootfile.html
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.
Utility Palettes
Click the main icon at the top of the Tools Palette (upper left) to see entirely different pages of tools. The tools will cycle from Draw, to List, Button, Window, Text, Border, Table, Slider, Menu, Chart, Guage, and Miscellaneous. The illustration above is currently showing the slider tools. Select a tool and drag on the desktop to create that node. Shift-click the node to bring up the script, or right-click the node (option-click on the Mac) to see a pop-up menu of options or the properties dialog for that object. The handle tool to the top right of the Tools Palette will allow object reshaping. Click the arrow tool to the top left to hide the handles and resume normal operation.
The Project Manager will show you a tree view of your current project, which can be edited from the outline list. Child nodes can be edited with the tool bar at the top of the list. Try right clicking on the items in the Project Manager for additional editing options.
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. They allow you to change display modes or change the user interface style of the entire project. You can also customize security options with the Utility Palette, see the Security White Paper for more information.
The Alignment Palette will allow you to align or nudge currently selected objects. Use the Tools Palette reshapper tool to select nodes to align. Control-click to select multiple nodes. The palettes above and all of the property dialogs are written entirely in DreamFactory and can be modified or replaced as needed.
Pop-up Menus
Try right clicking on any DreamFactory node and you will see a pop-up menu with some options, and usually a Properties Dialog option at the bottom of the menu. Explore these menus and use the Properties Dialogs to customize your objects. The first menu items will always be: Help, Name, Script, Resize, and Target. The option Help brings up the help system for that object. Name lets you name the object, more on that below. Script brings up the script, you can also shift-click any object to see the script. Resize turns on handles for the object; control-click to select or deselect multiple objects and use the Alignment Palette to move them. Target directs the Message Box to call commands and functions in the selected node.
The next set of menu options will be: Cut, Copy, Paste, Delete, and Duplicate. These are self explanatory, but be aware that these operations apply to the node and also all node children. This is a little bit like editing an XML DOM. 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 some objects.
Properties Dialogs
In general the Properties Dialog will let you explore the various capabilities of the node, but sometimes there are additional features available for a plug-in that are not edited with the Property Dialog, check the help system for complete documentation. Below is the property dialog for a slider. These dialogs are also written in DreamFactory, and can be modified if needed.
Quick Tutorial
Here is a tutorial that makes use of the Utility Palettes, Pop-up Menus, and Property Dialogs. We are going to create a window with a slider and a button inside. Clicking the button will set the slider to a value of 2. Follow the steps below:
1) First, start a new project as described above. If you have created test objects you can delete them by right-clicking the desktop and selecting "Clear Desktop" from the pop-up menu.
2) Now navigate the tools palette to the Windows Tools (in light blue), select a window type, and drag on the desktop to create the window. The window should be big enough to hold the button and the slider that we will create next.
3) Now navigate to the Button Tools (in light yellow) and select a regular button (not a check box or radio button) and create the button in the window (not on the desktop).
4) Navigate to the sliders page (in light purple, pictured above) and create a slider in the new window as well.
5) At this point you may want to change the properties of these objects, or give your window a title. Right-click any node to edit the properties.
6) If you want to adjust the position of the objects, choose the Handle Tool, which is available at the top right of the tools palette. This brings up handles that can be used to adjust the position of screen objects. Select the Arrow Tool (at the top left of the tools palette) to hide the handles and continue.
7) Now we are ready to do some scripting. First, you will need to name your slider, so that when you click on the button the button's script will be able to refer to the slider and control it. Right-click the slider and choose "Name" from the top of the pop-up menu. Enter the node name "myslider" and click OK. You could also name the button "mybutton" if you like.
8) Now shift-click the button to edit the script, or select "script" from the pop-up menu. In the "mycontent" handler at the top of the script add the line:
slider.valueset("myslider", 2)
Or, for the object-oriented programer:
myslider.value = 2
This will call the slider command "valueset" with the name of your new slider and set the value to 2. Notice that this command is automatically documented in the information bar at the top of the window, and color coded as each word is typed. Try retyping it with minor spelling errors and see how it corrects automatically. Try selecting the line and type Control-Slash to bring up the help system (or click on the question mark icon at the top right of the Script Editing Window). This explains the command in the context of other useful commands and functions for the slider plug-in.
9) Now close the scripting window and save changes. You have to correct syntax errors (if any) before this is possible.
10) Click the button; the slider moves to value 2. Move the thumb on the slider and click the button again. This illustration below shows an example of this tutorial. Note the current hierarchical layout of your project in the Project Manager.
Throughout the scripting process, you may come across various scripting errors. For example, shift-click on your button "mybutton" to open the script, and then rename the reference to your slider "myslidr" (forget the 'e') instead of "myslider". Save the script, click on the button to execute, and you will see the error dialog below. Through the long force of habit most scripters usually dismiss error dialogs quickly because they seldom contain useful information. I know this sounds crazy, but take a moment to read the DreamFactory error dialogs. First of all, scripting errors are not serious. Your system is not unstable; you do not need to restart. Scripting errors are a normal part of DreamFactory execution; they are more like suggestions that point you to things that need to be looked at than serious problems. DreamFactory has hundreds of error messages, and they almost always contain useful information. There is a real effort to figure out what you were attempting to do and to help. In the example below, the error dialog understands that there has been a spelling error in the slider name, and suggests a correction. Clicking Debug will bring up the Debugger Window at the current execution point. Click Exit to exit the script at that point. Click Ignore to keep going. Click Edit to open that script positioned at the error. Click Quit to exit DreamFactory for now.
Scripting Basics
This section discusses some of the most common issues in DreamFactory scripting and Project design. This information is intended to familiarize the reader with the basic concepts, there is more detailed information in the Reference Manual .
Node Names
In the preceding example you used the node name "myslider" to refer to the slider you created. The name could have been more explicit. For example, you could have referred to the slider as:
"slider:myslider"
This combines a plug-in name with a node name. A colon must separate the two names. This is useful for distinguishing between nodes with the same name but created with different plug-ins. Give your nodes unique names and you won't have to worry about that particular problem. By the way, node names must start with a letter and may contain numbers or the underscore symbol. Almost nothing in DreamFactory is case sensitive. You could also type:
"window:node_375<slider:myslider"
DreamFactory automatically assigned the node name "node_375" when you created the window; the less-than symbol shows that the slider is the next object down the hierarchy (like a tree). The window is the slider's parent. So the node name above will only find a slider node named "myslider" in a window node named "node_375" somewhere in the current project. There is a special reserved word called "me" that always refers to the fully specified node name of the script that is currently running. So when you click the button in the example above "me" would be:
"root:newfile<desktop:mydesk<window:node_375<button:mybutton"
You can see this in the title of the button's Script Window above (I named the button "mybutton" back in the tutorial.) Anyway, the reserved word "me" is a handy way to refer to the current object, and the reference is unambiguous because it is a fully specified path. Notice that the first plug-in name is "root", which is the root object at the base of the tree that everything is attached to.
If the node name you use is less than fully specified (like "mybutton" or "window:node_375<slider:myslider") then there might be more than one node with that name in the current project. This is made more likely by numerous cut, copy, and paste operations. In order to avoid confusion, DreamFactory will always magically find the node closest in the hierarchy to the referring node. So in our tutorial above, the button "mybutton" is pretty much guaranteed to find the slider "myslider" right next door. If there is a slider named "myslider" somewhere else in the current project the button will not find it. This is a really cool feature: DreamFactory objects automatically maintain their internal self-consistency even if they are reconfigured or pasted into a new project. The context sensitive binding between nodes is loose but smart.
While we are on the topic of node names, there are three other things to be aware of. First, you can refer to a node by just the plug-in's name. Often people will refer to the desktop node by simply typing "desktop" because there won't be any other desktop node. Second, all nodes have IDs. The ID is assigned at birth, sticks to the node for its lifetime, and will not change, even though the name might. The reserved word "hit" will always refer to the node under the mouse right now. For example, point to the slider and try this in the Message Box:
hit.value ++
The reserved word "myid" will return the numeric ID of the current node, which is a permanent and unique ID number. You can always refer to a node with the node's raw ID. In the example below our slider has ID 380. Your slider might have a different ID. One last note: brother nodes can't have the same name.
slider.valueset(380, 2)
File Names
DreamFactory references all files with a simplified and consistent syntax of the volume name, folder name, and then the file name all separated by colons. For example, type "dreamfactorypath()" into the message box, and you will see the path to the currently installed DreamFactory folder. A more useful path is the "projectpath()" which returns the path to your project. Multiple projects can be opened and directories and folders can be searched using file path names. Be aware that there are security restrictions in the browser based version that may limit you to only looking inside the project folder, the rest of the hard disk might not be accessible. Check the Security White Paper for details on sandbox security.
The example below shows how to read one of the DreamFactory help files into a text variable. Note the usage of the "@" operator for string concatenation. DreamFactory does NOT implement overloaded operators like Java or C++. In the example below, JavaScript would normally use "+" and VBScript would normally use "&", but in the DreamFactory scripting environment "+" always generates a numeric result and "&" always generates a logical result, so you must use @. There is more information on operators below.
var myvar = textfileread(dreamfactorypath() @ "help:system.txt")
DreamFactory will accept native Windows file path names such as "C:\myfolder\myfile.txt". Note that if this string were inside a DreamFactory script you would want to write it with double backslashes because of the string escaping rules, like this: "C:\\myfolder\\myfile.txt". Be aware that Windows native file path names are not portable and have no meaning on the Macintosh or Linux. DreamFactory will also accept: "Drive_C:myfolder:myfile.txt" where "Drive_C" is used instead of the volume name for the C drive. DreamFactory will automatically assign unnamed volumes on Windows with "Drive_" followed by the drive letter. Again this is not a portable way to refer to files, normally you should use colon-delimited file names.
Variables
DreamFactory supports four basic data types: long integer, floating point double, boolean, and string. DreamFactory help files and documentation consistently use the following symbols to denote these types: long is #, float is #.#, boolean is TF, and string is $. Variables and expressions used as arguments are always automatically converted to the desired destination type. So in our example above, you could have typed:
slider.valueset("myslider", "1" + 1)
but not:
slider.valueset("myslider", "what?")
In general, you never have to worry about variable typing or expression evaluation, DreamFactory will make sense of it if there is any possibility of doing so. This is designed for the text-based world of XML where everything starts out as text and becomes a type with specific usage.
There are three different scopes available for variables: local, regional, and global. Local variables have handler-wide scope, which means they cannot be referred to outside the current handler. Input arguments are also local. So in this handler:
code mousedown(which, hor, ver) local fred fred = 37 endcode
The local variable "which" is a string variable that specifies which mouse button is down ("right", "middle", or "left") and "hor" and "ver" are numeric screen coordinates. The local variable "fred" will initially have a value of zero and is then assigned a value of 37. When this handler ends "which", "hor", "ver" and "fred" will be thrown away. You can use the JavaScript and VBScript reserved word "var" or "dim" as a synonym for "local."
Regional variables have a script-wide scope, which means they cannot be referred to outside of the current script, this is kind of like a "static" global in C. Different scripts can reference the same regional variables by name but each instance of the variable can have a different value. This is an important feature for cut, copy, and paste situations where nodes have been duplicated.
Global variables have project-wide scope, which means they cannot be referred to outside of the current project. DreamFactory can open and edit multiple projects, but each project has its own set of global variables. You can see the local, regional, and global variables in the Debugger Window, and set read, write, and value breakpoints on them.
There is a useful additional feature available for regional and global variables. If the variable declaration is followed by the reserved word "persistent" then those variables are saved and restored with the current project. This is a very powerful way to make a project remember things automatically. When you use the "persistent" reserved word after a "regional" variable declaration the regional variables are saved and restored for use by that node. This feature is a great for small, mobile web applications and smart icons that need persistent but private data.
You can also get rid of variables that were created earlier. This makes little sense for local variables, but is useful for maintenance of regional and global variable lists. Here are some legal scripting commands with variables:
local fred = 37, bub = "a string", joe, tim global persistent mary = 8.3 dumpglobal susan regional persistent jen = true
The variable assignment after the "local", "regional" or "global" reserved word occurs every time the line is encountered. A variable is persistent or not depending on the last encountered declaration.
Variable assignment outside the handler (say, at the top of the script) is not implemented because DreamFactory has a hierarchical tree of scripts that changes constantly, not a single script file where the initializations at the top of the page happen once in the beginning. If you need to do special variable initializations when the script is opened or made visible check out the NodeOpen() and NodeShow() system messages discussed in the System Messages topic below.
Structures and Arrays
The DreamFactory scripting language has wide abilities to build various types of structures and associative arrays. These are stored in regular variables as strings, and can be local, regional, global, or persistent like other variables. DreamFactory strings are unlimited in size, manipulated very quickly, and benefit from automatic garbage collection.
Some scripters will be familiar with the HyperCard/SuperCard/Lingo practice of storing arrays of complex types in text strings separated by commas. For example:
"John Doe,175,false,34.7"
Structured data like this is easy to read and makes sense in an XML and SOAP based world. To concatenate two strings use the @ symbol; the @@ operator will concatenate two strings together with a comma. There are specialized functions for retrieving and storing character-delimited strings. See the system commands: stringlistget(), stringlistset(), stringitemget(), and stringitemset() for more information.
You can also access raw strings as simple arrays, and the "length" property will get or set the length of a string. For example:
var mystring = "abcdef"
for (count = 1; count <= mystring.length; count ++) {
var onechar = mystring[count];
}
Many other scripters will want to build associative arrays using syntax consistent with VBScript and JavaScript. These languages allow you to create complex data structures and arrays that store structured information. Here is an example:
var mycar mycar.make = "Ford" mycar.year = 1998 mycar.owner[1] = "Bob" mycar.owner[2] = "Jim"
DreamFactory implements associative array and structures internally as native XML. This is a huge advantage because the structures are human readable and DOM editable, and any XML envelope is automatically a structure addressable as an object or array. In the case above the variable "mycar" is just:
<make>Ford</make> <year>1998</year> <owner> <item_1>Bob</item_1> <item_2>Jim</item_2> </owner>
This is very useful because now you can simply store XML in a variable and reference the data directly. There is no need to "marshal" data between XML and some other internal data format because XML already IS the internal data format for structures and arrays. DreamFactory automatically skips namespaces or lets you reference them. You can also use a double-dot to search for the next matching element. There is more information about structures and arrays in the Reference Manual . All of the statements below set the same data in an example SOAP envelope:
mysoap["soap-env:envelope"].body.symbol.value = "BEA" mysoap.envelope.body.symbol.value = "IBM" mysoap..value = "MSFT"
Operators
Since DreamFactory is a polyglot language that accepts multiple syntaxes, expression evaluation is simplified by not overloading operators but instead type converting arguments. This is much better for XML applications because everything starts out as text and the type of the result is implied by the usage. All of the following examples can be typed into the Message Box (be sure to enter the statement "globals myvar, yourvar" so that the variables in the example are available). The following mathematical operators always yield a numeric result:
myvar += 2 3 - yourvar 21 / 5 21 / 5.0
Long integer arithmetic is promoted to floating point math if one of the arguments is a floating-point number. So the third expression above will yield 4, while the fourth expression will yield the floating-point result of 4.2. Check out the system functions coercetolong(), coercetostring(), coercetofloat(), coercetoboolean(), typeof(), and stringformatfloat() if you would like more control over types. The operators:
2 < yourvar myvar <= 56 56 > yourvar myvar >= yourvar
Always yield logical results, true or false. The "and" and "or" operators take logical arguments and return logical results. Short-circuiting is implemented as usual, so a true expression followed by an "or" operation will jump to true, and a false expression followed by an "and" operation will jump to false without evaluating the rest of the line. This is useful in situations where the rest of the line has a side effect that you would like to avoid.
(3 = myvar) and (yourvar = 98) (3 = myvar) or (yourvar = 98)
Lastly the operators "@" and "@@" are implemented for string concatenation. The "@@" symbol inserts a comma between the strings for structures. Also below is the reserved word "comma", which returns the string literal comma, similar reserved words include: cr, lf, tab, colon, space, slash. and backslash. Lastly string escaping is fully supported for \r, \t, \f, \\, and \". The "@" operator is important for concatenating node names and file names on the fly as needed, and as the hierarchy changes.
("fred" @@ 3) = "fred,3"
myvar = "a line\ranother line\t\tand some tabs"
"window:node_" @ myvar
"fred,3" = "fred" @ comma @ 1 + 1 + 1
Handlers
Scripted commands and functions in DreamFactory are called "handlers." They always begin with the "code" or "sub" or "function" statement, followed by the name of the handler and the input arguments, after which follows the body of the script. A DFScript handler is ended by the "endcode" statement, VBScript uses "end sub" or "end function" and JavaScript uses braces. If the handler is a function then it will "return" a value at some point. Below is the same handlers written in DFScript, VBScript, and JavaScript:
// DFScript Handler
code squarenumber(numberin)
return numberin * numberin
endcode
REM VBScript Handler
function squarenumber(numberin)
squarenumber = numberin * numberin
end function
// JavaScript Handler
function squarenumber(numberin) {
return numberin * numberin
}
Objects
DreamFactory's native XML implementation extends all the way to objects, which are also implemented with pure XML. So while the syntax to manipulate objects follows the JavaScript standard, the objects themselves are just XML text. This is an exciting development that blends object-oriented programming and XML DOM manipulation seamlessly. Take the following example from a JavaScript textbook:
function areafx( ) {
return this.w * this.h
}
function rectangle(w, h) {
this.w = w
this.h = h
this.area = "areafx"
}
var myrect = new Rectangle(3, 4)
var myvar = myrect.area()
This example uses the "new" keyword to declare a constructor function, and the "this" keyword to refer to the calling object. After execution "myvar" will equal 12, and the object "myrect" will contain the properties and methods:
<w>3</w> <h>4</h> <area>areafx</area>
The variable allocation and de-allocation statements "local", "global", "dumpglobal", etc. can also be used with structures and arrays. The JavaScript keyword "delete" is a synonym for "dumplocal." For example:
local x.a = 99 x.b = 88 dumplocal x.a
After dumplocal the "a" element has been destroyed, and x is:
<b>88</b>
Properties
DreamFactory implements a slew of simple properties for the basic data types. Rectangles can be referred to with "top", "left", "bottom", "right", "width", and "height." Colors can be referred to with "red", "green", "blue", and "alpha." Points can be referred to with "hor" and "ver" or "x" and "y." You can combine these property references and dotted property chains that manipulate nodes. For example:
mybutton.bounds.top ++ myoval.fillforecolor.red = 129 mybutton.bounds.width = 60
Since the XML plug-in exposes native XML through the "data" property, you can also use dotted property chains to directly access XML nodes as if they were just variables. So if you had an XML node called "myxml" then you could type:
myxml.data.envelope.body.result ++
Even better, you can use XML nodes as visible, persistent objects. In the preceding JavaScript rectangle example, you could replace "myrect" with an XML node "myxml.data" and view a living object dynamically manipulated by the scripting language in an editable DOM environment.
Flow Control
There are a number of reserved words to control the flow of execution in the handler. This includes standard for / next loops, while loops, switches, and if / then / else constructions. Below are examples written in some of the various scripting languages DreamFactory will accept:
1) If / Else / Endif statements
// JavaScript
if (3 < myvar) myfx(33);
else return myvar;
// VBScript
if 3 < myvar
myfx(33)
else
return myvar
end if
2) Switch / Case / Endswitch statements
// VBScript
select case myvar
case "x"
myfx(3)
case "y"
myfx(18)
case else
myfx(531)
end select
// JavaScript
switch (myvar) {
case 1:
myfx(3);
break;
case 2:
myfx(18);
break;
default:
myfx(531);
}
3) Dowhile / Endwhile statements
// VBScript
do while myvar = true
myfx(73)
loop
// JavaScript
while (x < 3) {
myfx(73);
}
4) Doloop / endloop statements
// VBScript
do
myfx(-45)
loop while myvar = true
// JavaScript
do {
myfx(-45);
} while (x < 3);
5) For / Endfor statements
// JavaScript
for (count = 1 to 10; count < 20; count += 2) {
myfx(count);
}
// VBScript
for count = 1 to 10 step 2
myfx(count)
next
The Hierarchy
Handlers can call other handlers in the same script. In the example below the handler "mycontent" calls the function "squarenumber" defined below, and prints "4" in the Message Box. You could also just call "squarenumber(2)" without the Message Box, but the result "4" would be lost. This is similar to simply calling a command; commands don't "return" values, they just do something in the body of the script.
If the handler "squarenumber" is NOT in the current script, DreamFactory will automatically look for it in the father script of the current node, and so on, all the way down to the root script and then the libraries. This is similar to the notion of inheritance in advanced programming languages. If the handler is never found this will trigger a "handler not found" scripting error. System messages (like MouseDown(), discussed in more detail below) are just discarded if their handler is not found.
code squarenumber(numberin) return numberin * numberin endcode code mycontent(hor, ver) messageboxdisplay(squarenumber(2)) endcode
In general, handlers that implement more specific functionality will be found closer to the top of the hierarchy (like the button and slider in the previous example) and handlers that implement more generic functionality (shared by other nodes) will be implemented closer to the bottom of the hierarchy near the root script. In other words, you will want to put common functions and commands in the father (or grandfather, etc.) scripts of the objects that use them, so that the children can automatically share the handlers.
Once a handler is encountered, the "endcode" statement (or the "return" statement in a function) will return execution (and possibly a result) to the calling handler. A command may also call "exitcode" to abort handler execution at any time. The "passcode" statement will terminate handler execution and CONTINUE down the hierarchy. This is useful for subclassing: you can modify the behavior of a message intended for a parent. There is also an "abortcode" statement for exiting all handlers immediately, as if there was an error, but without generating an error dialog.
Lastly, you can send messages outside the current hierarchy at any time. The system commands nodemessage() and nodemessagefx() will send commands or functions to any node in the current project. The system commands projectmessage() and projectmessagefx() will send commands and functions to the project script, although this is rare. The system commands librarymessage() and librarymessagefx() will send commands and functions directly to the library scripts, but since they are at the bottom of the hierarchy anyway and available to all nodes this is also rare. Here is an example:
code mycontent(hor, ver)
local fred
fred = nodemessagefx("myslider", somehandler(1, "x"))
nodemessage("mybutton", mycontent(hor, ver))
endcode
Once received at the target, execution will follow down the hierarchy as expected before returning to the caller. In fact the reserved word "target" will always be the fully specified node name of the recipient of the original message; "target" is like "me" except "target" is the top of the current scripted hierarchy, the object to whom the message was initially sent. In summary, you can call commands and functions from anywhere with the nodemessage() and nodemessagefx() routines.
System Messages
DreamFactory sends system messages triggered by various events directly to the project script. The project script examines the messages and the current project tree and then passes them on to the nodes. These system messages appear in the Script Editing windows with a unique teal green color. Control-B will bring up the project script, and you can see for yourself how the system messages are parceled out to the appropriate nodes. These messages include ProjectOpen(), ProjectIdle(), ProjectClose(), MouseDown(), MouseEnter(), MouseExit(), MouseMove(), KeyDown(), KeyEnter(), KeyExit(), and others. For the most part you don't need to worry about this process, the project script operates in a standard way that works fine for most situations. However the project script can also be fully customized to change message-passing behavior. This addresses a major problem in many scripting languages where the messages are "magically" sent to the objects but you can't do much if you need to change things.
Other messages are sent to the nodes directly. The messages NodeOpen() and NodeClose() are sent when the node originally starts up in the new project or right before the node closes down. Use these messages to perform special startup or shutdown tasks. For example, you might want a window to always hide itself when the project closes. NodeShow() and NodeHide() are sent each time the node is made visible or hidden with the system command nodevisibleset(). This is useful for the node to set something up right before being shown. The message NodeResize() is sent when the project boundary changes (for example, the browser window is resized). This might be a good time to call the plug-in function desktop.boundsget() to discover the new screen dimension and size yourself accordingly. The message WebTransferDone() is sent when a file has been uploaded or downloaded, and ServerTransaction() is sent when the DreamFactory Micro-Server receives information from a socket. These last two are for advanced users; the Help System has more complete documentation.
Lastly, the plug-ins themselves can trigger special system messages. The message NodeMove() is sent any time a node boundary rectangle changes. NodeChange() is sent when the node's data changes. NodeStart() and NodeStop() are sent when the node begins or ends media playback. NodeSelect() is sent when a selected object in the node changes, such as a selected list item or table cell. The plug-in messages vary somewhat by use; check the plug-in documentation for more detailed and specific information.
Some common messages such as NodeOpen() and NodeMove() are not sent unless there is a corresponding handler in the target node. The reason for this is to prevent message "storms" of common messages that are not handled. This can be a problem in the case where you would like a node's parent to handle the message. The Reference Manual discusses this issue in more detail and includes a simple work-around.
Useful System Commands and Functions
The system commands and functions are grouped into broad categories in the Help System. Here are the major categories of system commands and functions:
|
Here are some examples of system commands that are either popular or generally useful. We suggest reading most of the system section in the Help System to get an overview of what is possible. Some highlights:
REM Turn runtime mode on or off. If runtime is on, you
REM can't edit scripts, debug, or use the Message Box.
projectruntimeset(runtime mode TF)
myvar = projectruntimeget()
REM Test the state of the mouse button.
currently down TF = mousebutton()
still down TF = mousestilldown()
REM Set the cursor: arrow, watch, hand, touch, etc.
cursorset(cursor name $)
REM Show a simple dialog message. There are many more
REM dialog commands, check the Dialog... section of the
REM help system
dialogshow(title $, message $)
REM Test the state of the keyboard. There are many more,
REM look in the Key... section of the Help System.
shift key currently down TF = keyshift()
"P" key currently down TF = keytest("P")
REM Output anything to the message box.
messageboxdisplay(whatever ?)
REM Return the mouse location in global coordinates.
REM See globaltolocalhor() and globaltolocalver() below.
mouseread()
myx = mousehor()
REM Convert global coordinates to local.
myx = globaltolocalhor(me, myx)
myy = globaltolocalhor(me, myy)
REM We have all kind of node management functions.
nodedelete(me)
mydad = nodefatherget(me)
myfirstchild = nodechildget(me)
myfirstbrother = nodebrotherfront(me)
mynewchild = nodenew(me, "slider")
REM And some very useful or common node functions.
nodevisibleset(me, false)
booleanresult = nodeexistsget("window:temporary")
nodepluginname = nodepluginget(me)
booleanresult = nodehashandler(me, "mycontent")
REM Edit the script of a node, project, or library.
nodescriptedit(me)
libraryscriptedit(3)
projectscriptedit()
REM Update the current screen after changes.
REM Useful in animated loops.
update()
updatefx("dissolve", 1000, me)
REM Discover some useful file paths
mypath = projectpathget()
mypath = dreamfactorypathget()
REM Write a text file to the project folder
textfilewrite(projectpath() @ "myfile.txt", "some text.")
myvar = textfileread(projectpath() @ "myfile.txt")
Useful Plug-in Properties
In general, building DreamFactory applications will follow the same pattern. First, open the Help System and try to find the right plug-in for the task at hand, then create some nodes and then customize them further on the basis of what they need to do. All of the plug-ins are different, but here are some common properties that they can share:
|