Curl Global Community - Curl Clues

XML3:XPATH Expressions

Thu, 16 Jun 2011 01:09:14 +0000

Path expressions allows you to specify objects and object values from the Document Object Model using expressions. The expressions are defined using the W3C XPath's functions and the results are returned within the framework of DOM APIs in a standard, interoperable way. Path expressions conform to the XPath 1.0 standard, and are represented as XDMPath objects.

It is often more concise to use reference paths to locate data items in XML structures. This approach allows for a clearer distinction between the document structure, and the processing. The result of a path expression may be a nodeset, or an atomic value (text, number or boolean). In this Curl Cue, we will describe general XPath expressons that will get you started.

First, we need to describe general XPath expressions.

Now we can apply the expressions above to the example XML data where

•inventory is the root node

•item is a child node of inventory

•title, part, and price are children of item

•loc is an attribute

Code:
ff123 

9.99 

np213 

6.95

Let's take a look at the following XPath expressions...

1. /inventory/item

Reading from left to right:

•/: is the root node of the document

•inventory/: specifies go to the inventory tag

•item: find all elements with an item tag

In this case, the result will be all item nodes in the samples root element.

2. /inventory/item/title/@loc

Reading from left to right:

•/: is the root node of the document

•inventory/: specifies to go to the inventory tag

•item/: go to all elements with an item tag

•title/: go to all elements with a title tag

•@loc: select loc attributes

In this case, the result will be all loc attributes from title nodes under item.

3. //title\[@loc\]

Reading from left to right:

•//: search the entire document

•title\[@loc\]: find all title elements that have a loc attribute

In this case, the result will be all the item elements that have an attribute named loc. Note that example 2 will return the loc attributes, while this example will return item elements that have a loc attribute.

4. //title\[@loc ="us"\]

Reading from left to right:

•//: search the entire document

•title\[@loc\]: find all title elements that have a loc attribute with the value of 'us'

In this case, the result will be the item elements that have a loc attribute equal to 'us'.

5. /inventory/item\[1\]

Reading from left to right:

•/: is the root node of the document

•inventory/: specifies to go to the inventory tag

•item\[1\]: select the first item element

In this case, the result will be the first item element that is the child of the inventory element. Note that expressions enclosed in \[ \] are predicates. A predicate is used to find a specific node or node that contains a specific value.

XDMPath Display

Now that we understand some XPath syntax, the following applet allows us to experiment with the expressions. The XDMPath Display applet has three panes:

•The top pane allows us to select an XML file from a dropdown list.

•The left pane displays the entire XML structure includijkng nodes, elements, attributes, and associated values.

•The right pane allows us to input an XPath query and display the results.

Once you have entered the desired XPath expression, click on the 'Select' button. The results of the query will be displayed in the right pane. Selecting the 'Highlight' button will highlight the corresponding nodes withing the XML display on the left pane.

Code:
||| Copyright (C) 1998-2009, Sumisho Computer Systems Corp. All Rights Reserved. 

||| 

||| An OpenCurl project. 

||| Licensed under the Apache License, Version 2.0 (the "License"); 

||| you may not use this file except in compliance with the License. 

||| You may obtain a copy of the License at 

||| 

||| http://www.apache.org/licenses/LICENSE-2.0 

||| 

||| Unless required by applicable law or agreed to in writing, software 

||| distributed under the License is distributed on an "AS IS" BASIS, 

||| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

||| See the License for the specific language governing permissions and 

||| limitations under the License. 

{curl 6.0, 7.0 applet} 

{applet manifest = "../manifest.mcurl"} 

{import * from COM.CURL.WSDK.XML-DOCUMENT-MODEL} 

{import * from COM.CURL.WSDK.XML-DISPLAY} 

|| prefix declarations 

{define-proc {dwim-prefix-declarations 

subject:XDMElement, 

context:XDMNamespaceContext = xml-namespace-context 

}:void 

{subject.walk-children 

|| walk descendants and self 

include-self? = true, 

include-descendants? = true, 

{proc {n:XDMNode}:bool 

{type-switch n 

case e:XDMElement do 

|| check declared prefixes 

{if-non-null ps = e.namespace-declarations then 

{for p in {ps.get-prefixes} do 

{if-non-null ns = {ps.get-uri p} then 

{if {context.get-uri p} == null 

then 

|| extend global declarations accordingly 

{context.declare-prefix? p, ns}}}}}} 

|| continue walking 

{return true}}} 

} 

{document-style PlainDocument} 

{set-document-properties 

hstretch? = true, 

vstretch? = true 

} 

{persistent-data "Settings"} 

{value 

|| defaults 

let base-url:Url = {{get-the-applet}.url.parent.canonicalize} 

let restore-settings?:bool = true 

let factory-settings:XDMElement = 

{XDMElement "settings", 

{XDMElement "filename", "inventory.xml"}, 

{XDMElement "path", "*"} 

} 

let settings:XDMElement = {factory-settings.clone} 

|| TODO: list model 

|| - recent files 

|| - recent paths 

{if-non-null settings-xml = 

{if restore-settings? then 

{get-persistent-data "settings", error-if-missing? = false} 

else null} 

then 

{try 

set settings = 

{build-xml preserve-whitespace? = false, 

settings-xml}.root 

catch e:Exception do 

{popup-message {message Ignoring faulty settings}}}} 

let settings-context:XDMDataBindingContext = 

{XDMDataBindingContext model = settings} 

{on-applet-suspend do 

{set-persistent-data "settings", 

{settings.to-XML}} 

{commit-persistent-data}} 

|| model 

let xmldoc:#XDMDocument = null 

let xml:#XDMElement = null 

|| model tree 

let tm:XDMTreeModel = 

{XDMTreeModel null} 

let tc:XDMTreeControl = 

{XDMTreeControl tm, 

tree-connector-color = "silver", 

selection-policy = "multiple"} 

|| subset 

let xs:XDMNodeSet = {XDMNodeSet} 

|| subset tree 

let stm:XDMTreeModel = 

{XDMTreeModel null} 

let stc:XDMTreeControl = 

{XDMTreeControl stm, 

tree-connector-color = "silver", 

xdm-text-breakable? = true, 

selection-policy = "multiple"} 

|| actions 

let search-status:TextDisplay = {TextDisplay} 

let search-command:ComboBox = 

{ComboBox 

{bind value to "path"}, 

width = 4in, 

vorigin = 70%, 

{on ValueFinished at c:ComboBox do 

{with-busy-cursor 

|| clear highlighted nodes 

{tc.clear-categories category = "highlight"} 

{tc.select-nothing} 

{if c.value.empty? then 

set stm.root = null 

else 

{try 

|| apply specified xpath 

let w:StopWatch = {StopWatch} 

{w.start} 

set xs = {xml.search c.value} 

{w.stop} 

set search-status.value = 

{message Found {value xs.size} nodes in {w.elapsed}} 

set stm.root = xs asa XDMTreeNode 

{stc.expand-node {non-null stm.root}} 

|| note new setting 

{c.update-data-binding "value"} 

|| remember new query 

{if {c.find c.value} < 0 then 

{c.append c.value}} 

catch e:Exception do 

set search-status.value = e.message 

{popup-message e}} 

}}}} 

let load:{proc-type {Url}:void} = 

{proc {loc:Url}:void 

{try 

|| load document 

set xmldoc = 

{build-xml loc, preserve-whitespace? = false} 

set xml = xmldoc.root 

|| populate displays 

set tm.root = xml asa XDMTreeNode 

{tc.expand-node {non-null tm.root}} 

|| augment global prefix declarations 

{dwim-prefix-declarations {non-null xml}} 

|| reset path 

||-- {search-command.clear-items} 

{search-command.set-value-with-events "*"} 

catch e:Exception do 

{popup-message e}}} 

let load-command:DropdownList = 

{DropdownList 

"inventory.xml", 

"samples.xml", 

{bind value to "filename"}, 

vorigin = 70%, 

{on ValueFinished at c:DropdownList do 

{with-busy-cursor 

{load {base-url.concat c.value}} 

|| note new setting 

{c.update-data-binding "value"} 

|| remember new query 

{if {c.find c.value} < 0 then 

{c.append c.value}}}}} 

|| display 

let pane-style:Arguments = 

{Arguments 

border-width = 3px, 

border-style = "ridge"} 

let display-full:Graphic = 

{VBox 

margin = 3px, 

width = 2in, 

tc, 

{Fill}} 

let display-subset:Graphic = 

{VBox 

margin = 3px, 

{HBox 

spacing = 3pt, 

margin = 3pt, 

{text XPath:}, 

search-command, 

{CommandButton 

label = {message Select}, 

{on Action do 

|| select corresponding tree nodes 

{with-busy-cursor do 

{tc.collapse-node {non-null tm.root}, 

collapse-descendants? = true} 

{for x in xs do 

let n:XDMTreeNode = tm[x] 

{tc.select-nodes additive? = true, n}}}}}, 

{CommandButton 

label = {message Highlight}, 

{on Action do 

|| highlight corresponding tree nodes 

{with-busy-cursor do 

|| clear this category 

{tc.clear-categories category = "highlight"} 

{for x in xs do 

let n:XDMTreeNode = tm[x] 

|| assure node is visible 

{if-non-null p = n.parent then 

{tc.expand-node p, 

expand-ancestors? = true}} 

{tc.set-category n, "highlight"} 

}}}}, 

{Fill}}, 

{ScrollBox 

hstretch? = true, 

hscroll? = false, 

stc}, 

{Fill}, 

search-status} 

|| behavior 

let expand-action:EventHandler = 

{on Action at c:TreeControl do 

{if-non-null node = c.current-node then 

{with-busy-cursor 

{if {c.expanded-nodes.member? node} then 

{c.collapse-node node, 

collapse-descendants? = true} 

else 

{c.expand-node node, 

expand-descendants? = true}}}}} 

{tc.add-event-handler expand-action} 

{stc.add-event-handler expand-action} 

|| arrangement 

let main:PanedWindow = 

{PanedWindow orientation = "horizontal"} 

{main.add-pane 

{ScrollBox 

margin = 1px, 

hstretch? = true, 

vstretch? = true, 

{splice pane-style}, 

display-full}} 

{main.add-pane 

{Frame 

margin = 1px, 

hstretch? = true, 

vstretch? = true, 

{splice pane-style}, 

display-subset}} 

{main.set-pane-sizes {{Array-of double} 30%, 70%}} 

|| initialize 

{after 0s do 

{load-command.handle-event {ValueFinished}}} 

|| layout 

{VBox 

data-binding-context = settings-context, 

margin = 3pt, 

spacing = 3pt, 

{splice pane-style}, 

{HBox 

spacing = 3pt, 

margin = 3pt, 

{title XDMPath Display}, 

{Fill width = .5in}, 

{text File:}, 

load-command, 

{Fill}, 

{CommandButton 

label = {message Restore Settings}, 

{on Action do 

set settings = {factory-settings.clone} 

set settings-context.model = settings 

{load-command.handle-event {ValueFinished}} 

}}}, 

{hrule}, 

main 

} 

}

Since the above applet allows us to quickly view XPath query results, XDMPath Display is definitely an asset for developers. We have made this available for you to download on your machine to use with other XML files. Please select the following link to download a zip file of the XPath Explorer: XPath Explorer. Once you unzip the files, select xpath-explorer.curl to run the applet. Note that this Curl applet is also included within the WSDK documentation.

XPath in a Nutshell
Just to summarize using XPath expressions, we have put together a list of points worth noting:

•Path expressions navigate nodes in an XML document (these resemble filesystem paths).

•Paths return collections of nodes (nodesets)

•Absolute paths, starting with '/' begin at the start of the document. Other paths are relative.

•Paths consist of steps separated by slashes '/'.

•Each step builds on the nodeset from the previous step.

•Steps can follow different "axes": child elements (by name), attributes (name prefixed with '@'), descendants (starting wtih '//').

•Steps can be filtered using a predicate inside square brackets \[ \].

Of course, this is just a short list. There is a lot more on XPath such as datatypes, functions, axes, shorthand, context-node, and operators. For a complete listing of XPath expressions, please see W3C XML Path Language (XPath).

Using XPath1.JPG (Size: 33.51 KB / Downloads: 1964)

XML2:Transforming XML

Thu, 16 Jun 2011 00:59:45 +0000

The last Curl Cue addressed how to access XML data from a server and store the information as an XML document model (XDMNodes). Now the content must be transformed or processed to meet the application functionality. Since the data has already been internalized, all we need to do is:

•query the relevant information,

•perform relevant processesing,

•and diplay the requested information to the user.

One of the most common types of display is a grid. In the first example, we query data and dislay it using a standard Table and in the second example we will display it using a RecordGrid.

Querying the Data
Once the data is contained within the Curl XML DOM structure, the goal is to extract elements and their associated values by traversing the node tree. This includes element types, element values, and element attributes. Using the WSDK, there are three different ways to obtain this information. Either by using object methods, XPath expressions, or elaboration. In this Curl Cue, we will focus on using XPath expressions to query relevant content.

We will use the same data from the last Curl Cue (XML Data). The following is the XDMDocument view so that you can recall the structure of the XML.

Code:
{curl 6.0, 7.0 applet}

{applet manifest = "manifest.mcurl"}

{import * from COM.CURL.WSDK.XML-DOCUMENT-MODEL}

{import * from COM.CURL.WSDK.XML-DISPLAY}

{value 

   let xml-data:Url ={url "services.xml"}

   let xmldoc:XDMDocument =

       {build-xml preserve-whitespace? = false, xml-data}

    {XDMTreeControl open?=true, xmldoc}

}

Using XPath to Query Data

All of the nodes in the XDMDocument can be queried using an XPath expression. Nodes include XDMElement,XDMAttribute, XDMText, and XDMProcessingInstruction.

XPath expressions are used to traverse the nodes in the XML structure and extract elements and their associated values. XPath queries return an XPathValue which can be one of the following types:

•XDMNodeSet

•String

•double

•bool

In our example, a XDMNodeSet is first created to gather all Sample nodes.

Code:
def items:XDMNodeSet = {model.search Samples/Sample}

Then, standard XPATH expressions are used to query relevant data.

•item.search "@xx" returns an attribute value of xx

•item.search "xx" returns an element value of xx

For more information regarding XPath, please see XPath Curl Cue: About XPath.

Tabular Display
In the first example, we will be extracting data from th displaying relevant XML data in a table. This is an example of transforming the data for presentation.

All XPATH queries will return an XDMNodeSet, therefore we need to convert it to a String before it is able to be used in the table. For example:

Code:
{item.search title}.as-String

Code:
{curl 6.0, 7.0 applet}

{applet manifest = "manifest.mcurl"}

{import * from COM.CURL.WSDK.XML-DOCUMENT-MODEL}

{import * from COM.CURL.WSDK.XML-DISPLAY}

{value 

   let xml-data:Url ={url "samples.xml"}

   let model:XDMDocument =

       {build-xml preserve-whitespace? = false, xml-data}

   let display:Table =

       {Table

           columns = 2,

           cell-border-width = 1px,

           cell-border-color = "brown",

           cell-border-style = "flat"}

||--    def items:XDMNodeSet = {model.search "Samples/Sample"}

   def items:XDMNodeSet = {model.root.search "sample"}

   {for item in items do

       {display.add

           {row-prototype

               {item.search "@id"}.as-String,

               {item.search "title"}.as-String,

               {link href = 

                   {url  {item.search "doclink"}.as-String},

                   {value  {item.search "title"}.as-String}}

           }}}

   display

}

Record Display

In the next example, we are using the XPath to query the title, description and link. The information is stored in a RecordSet and displayed to the user with a RecordDisplay. This is an example of transforming the data into a model for further processing. The model data is then transformed for presentation in to a grid display.

Code:
{curl 6.0, 7.0 applet}

{applet manifest = "manifest.mcurl"}

{import * from COM.CURL.WSDK.XML-DOCUMENT-MODEL}

{import * from COM.CURL.WSDK.XML-DISPLAY}

{value 

   let xml-data:Url ={url "samples.xml"}

   let model:XDMDocument =

       {build-xml preserve-whitespace? = false, xml-data}

   let display:Table =

       {Table

           columns = 2,

           cell-border-width = 1px,

           cell-border-color = "brown",

           cell-border-style = "flat"

       }

   def items:XDMNodeSet = {model.search "samples/sample"}

   let rs-samples:RecordSet =

       {RecordSet

           {RecordFields

               {RecordField 

                   "Title", domain = String

               },

               {RecordField 

                   "Description", domain = String

               },

               {RecordField 

                   "Link", domain = String

               }

           }

       }

   {for item in items do

       {rs-samples.append

           {RecordData Title =  {item.search "title"}.as-String,

               Description = {item.search "description"}.as-String,

               Link = {item.search "doclink"}.as-String}

       }

   }

   {RecordGrid

       height = 3cm,

       width = 30cm,

       record-source = rs-samples

   }

}

For more information about RecordSets, please see RecordSets.

XML1:XML Data

Thu, 16 Jun 2011 00:56:17 +0000

Most data can be transformed into XML content. This provides a drive to use XML as a medium for structuring information the Web for the purpose of data exchange between applications. XML structures data using a text-based markup language similar to HTML and is non-proprietary and platform independent. Open standards and the focus on communication and collaboration among people and applications have created and environmnet where XML Web services are becoming a standard platform for application integration in the move to distributed computing on the Internet. From a Curl client perspective, XML information can be obtained from communicating with a Web service over HTTP or using XML over HTTP.

In either case, the data that is queried and obtained is XML. Therefore it is necessary to first concentrate on handling XML data in the Curl client over HTTP. Once these fundamental principles are understood, then we will access XML data via a Web service in a subsequent Curl Cue.

Curl's XML Document Model

Curl's XML Document Model (XDM) provides functionality for processing XML data in Curl: reading, creating, modifying and writing XML documents. XML document contents are represented as a hierarchy of Curl objects which can be accessed using Curl methods and XPath expressions. Once accessed, the contrent can be displayed, transformed, and processed to meet the application functionality

Curl's XDM is accessible through the Curl Web Services Development Kit (WSDK). The WSDK library must be installed and accessed in order to use access its functionality which include SOAP/WSDL support, and an XML document model. If you plan on displaying and manipulating the examples contained within this Curl Cue, there is no need to download the WSDK. However, once you download and run the examples on your local machine, you will need to download the libraray.

You can download the WSDK library from the official WSDK download page by selecting the following link: WSDK Download.

XDM Nodes

The XDM views XML documents as a tree structure of elements embedded within other elements. All elements, their containing text and their attributes can be accessed through the XDM structure. Their contents can be modified, deleted, and new elements can be created. The elements, associated text and attributes are modeled as nodes.

In the WSDK, XDMNodes are represented by XDMElements, XDMAttributes, XDMText, XDMProcessingIstructions.

Displaying the XML DOM Structure

In the first example, we read the XML, store the data as an XDM document, and then display the data using a tree control structure that allows you to visually expand and compress the XML nodes. This method is very useful during development, but not as common in production applications.

Steps: the quickest way to read and view the XML data is to:

1.Import necessary WSDK packages

2.Create an XML Document model (XDMDocument) using the build-xml procedure.

3.Display the stored XML data using XDMTreeControl

In this example we use XML data created directly in the code using the xml-string variable for simplicity.

width='100%' height='550' src='/wiki/samples/generic-example.curl?WSDKSamples/XML/xmldata.curl'

Note that 2 packages need to be imported from the WSDK:

•COM.CURL.WSDK.XML-DOCUMENT-MODEL: this allows us to access XDMDocument

•COM.CURL.WSDK.XML-DISPLAY: this allows us to access XDMTreeControl

In the second example, we query the XML data from a known Url. This scenario is typical of what you would expect from a deployed application where the xml data resides on a company server.

For this example, the XML data is stored in the file sample.xml. It represents an inventory or resources from the Widgets/Gadgets/Curlets section on Curl's Developer Community (www.developers.curl.com).

Code:
curl 

Hardware-accelerated rendering is used to show a 3D view of chemical molecules. 

http://developers.curl.com/docs/DOC-1060 

http://developers.curl.com/demos/molecules/start.curl 

curl 

This example displays flames by simulating them mathematically, not just by showing a series of precomputed images. 

http://developers.curl.com/docs/DOC-1057 

http://developers.curl.com/demos/fire/start.curl 

curl 

The teapot is a classic example of 3D rendering. 

http://developers.curl.com/docs/DOC-1059 

http://developers.curl.com/demos/teapot/start.curl

Note: the full list code samples can be found here: Widgets/Gadgets/Curlets.

width='100%' height='390' src='/wiki/samples/generic-example.curl?WSDKSamples/XML/xmldata2.curl'

About build-xml: The build-xml function uses the standard Curl SAX parser and has corresponding keyword arguments. The input source can be specified as a Url or a String, as well as text and byte streams.

The XDMTreeControl displays and exact representation of the XML using a tree structure of elements embedded within other elements. If the XML data had multiple levels, the tree control nodes would expand to view all children.

Since the XDM presents stores XML data as a tree structure, it gives us access to the information through a set of objects. This allows us to query relevant information, transform and process the data, and display the requested information to the user. Thus, we can state the the XDM model is needs to be obtained first before any processing can occur. The following Curl Cues will discuss methods of transformation and display.

CurlClientXML.png (Size: 21.34 KB / Downloads: 3135)

XDMNodes.png (Size: 18.02 KB / Downloads: 2541)

Styling3:Creating Styles with the Style Designer

Thu, 16 Jun 2011 00:52:37 +0000

Overview

The Style Designer is a Curl application that allows you to define styling preferences that can be written out as a Curl style sheet. This application allows you to easily create your own control styles without coding. You can...

•visually modify control styles including buttons, tabs, group boxes, text fields, and more

•create style templates for use with different applets

•share styles with other developers

•write out style sheets for use in Curl applets

Launching the Style Designer
The Style Designer is designed to run as a Curl detached applet, meaning that it can run from the web but without a web browser. You can run the Style Designer two different ways: directly from our website or from a downloaded copy.

1.To launch the Style Designer as a detached applet, by copy and paste this link into your browser: curl://launch/http://developers.curl.com/demos/style-designer/style-designer.dcurl

2.Download and unzip the source code from the bottom of the following page: Style Designer. Once you have unzipped the contents, navigate to the style-designer folder and double-click on style-designer.dcurl.

In the case of the downloaded version, you will also need to grant privilege to the style-designer directory. You can do this by selecting the Curl RTE icon on the Windows task bar to bring up the Curl control panel (when the Curl RTE is running). Select the Security tab, then click This Computer heading to open the security settings for your computer. Click the Add Privileged Directory... link and enter the directory where you unzipped the Style Designer (or a parent directory). Click OK. From now on, any Curl applet launched from this directory will have full access to the local machine.

Using the Style Designer

Once you have launched the Style Designer applet, use this graphical interface to create your own unique look for the Curl styled controls. The left side of the applet is a collection of properties for individual Curl controls as well as general color preferences.

Each style created has an associated Name that is specified in the General Information section. When you initially launch the Style Designer, the default name is S-001.

Adjust the colors, highlighting, and other attributes to design custom look. Each section displays attributes that can be changed until you are satisfied with the desired look. When an attribute is modified, for example Dialog Color, the sample controls on the right hand side of the window will automatically refresh to display the updated value.

The control groupings in this pane include the following:

•General Information: includes the style name, a place for you to record your personal rating of this style, and any notes. Error messages will also appear here if selection values are invalid.

•Global Colors, Gradient Angle: sets general colors for all controls.

•Controls Options: grouped in a set of tabs, allows you to specify specific attributes for buttons, tabs, group labels, fields, and other controls. Each control has control-specific attributes that can be set.

Changing Attribute Values
All field selections can be modified by either typing in a value or selecting a check box. If a selection is not valid, an error message will be displayed in the General Information section.
[img]attachment.php?aid=54[/timg]

Creating a Style Sheet

When you are happy with a style you've created you can write out a style sheet file that you can use in any Curl 6.0 applets you develop. Choose File > Write Style Sheet... to write out a Curl style sheet.

Note that style sheets use the styled controls library that was introduced with Version 6.0 of the Curl RTE. Therefore, in order to use the style sheet and associated skinned controls in your applets, you must first download the library from the the Curl web site and integrate it into your development environment. If you have not downloaded the library, please select the following link: STYLED-CONTROLS Library.

For more information regarding style sheets, please refer to the Curl Styled Controls Library User's Guide that you installed in the Curl Documentation

  styledesigner_verylight_scaled.png (Size: 162.2 KB / Downloads: 1859)

  style_properties.png (Size: 17.36 KB / Downloads: 1750)

  Creating Styles with the Style Designer1.JPG (Size: 229.72 KB / Downloads: 1313)

Styling2:Style Sheets

Thu, 16 Jun 2011 00:36:45 +0000

Style sheets are now supported in the Curl GUI Toolkit. (In version 6.0 they were available as an external library. This older note describes how to use styled sheets in version 6.0: Using Style Sheets - Curl 6.0 .)

You can create and use one or more style sheet files in a Curl application. You can also create your StyleSheet objects directly in the Curl code. In general, follow these basic rules:

" Each style sheet consists style rules and nested style sheets.

" A nested style sheet can be defined in a curl file and imported by giving the url for the file.

" Any nested style sheets must appear before the style rules.

" A style rule consists of a selector string followed by any number of option settings.

" If two rules specify the same option, the rule that comes later overrides the earlier rule.

" If you set an option directly on an object, it cannot be overridden by a style rule.

Style Sheet Syntax
In Curl, a StyleSheet contains a set of rules that affect the look of the GUI objects the rules apply to. Each StyleRule uses a pattern, or "selector", to identify the controls or GUI components that are affected by the rule.

Let's examine a example style sheet definition.

Code:
let ss:StyleSheet 

{StyleSheet 

{StyleRule VBox.panel-vbox 

background = blue, 

margin = 2px, 

spacing = 4px 

} 

}

where:

" ss a variable that defines the StyleSheet

" VBox.panel-vbox is the selector

" VBox is the style-element

" panel-vbox is the style-class

This selector has two components. For the rule to apply, the first component must match the style-element property of an object and the second component must match the style-class property. If either component is omitted, then it doesn't apply. (So ".panel-vbox" would apply to any object with a style-class that includes the string "panel-vbox".)

Using the Style Sheet

Once you have a StyleSheet defined, you can use the definitions after it has been installed. For example:

Code:
{install-style-sheet ss}

In our example code, each time we call VBox, we have the option of specifiying the style-class of panel-vbox. For example:

Code:
{value 

let my-panel:VBox = 

{VBox 

style-class = panel-vbox, 

{Frame Top content}, 

{Frame Bottom content} 

} 

}

Using a StyleSheet in the Login Example
Let's pull together these concepts and apply them to our login example. We created a style sheet common-style-sheet that contains definitions for common properties (widths) specified in the login screen. We can use these styles by specifying the style-class.

Code:
{curl 7.0 applet} 

|| Identify a StyleSheet 

|| The common StyleSheet sets up some rules (primarily widths) common to the 

|| different versions of the login form. 

{let common-style-sheet:StyleSheet = 

{StyleSheet 

{StyleRule "CommandButton.ok", 

width = 1.75cm 

}, 

{StyleRule "TextField.login", 

width = 2cm 

}, 

{StyleRule "PasswordField.login", 

width = 2cm 

}, 

{StyleRule "GroupBox.dialog", 

width = 4.5cm 

} 

} 

} 

|| Form creation procs 

{define-proc {login-dialog 

tf:TextField, pf:PasswordField, cb:CommandButton 

}:Graphic 

{return 

{GroupBox 

style-class="dialog", 

label = "", 

{Dialog 

use-look-and-feel? = false, 

{Table 

{row 

{cell {Label"Username:"}} 

{cell {value tf}} 

}, 

{row 

{cell {Label "Password: "}} 

{cell {value pf}} 

}, 

{row 

{cell 

colspan = 2, 

halign = "center", 

{value cb} 

} 

} 

}, 

{validate-with {DialogValidator}} 

} 

} 

} 

} 

{value 

let tf:TextField = 

{TextField 

style-class="login", 

width = 2cm, 

{validate-with ValidationPattern.email-address, required? = true} 

} 

let pf:PasswordField = 

{PasswordField 

style-class="login", 

width = 2cm, 

{validate-with {StringValidator}, required? = true} 

} 

let cb:CommandButton = 

{CommandButton 

style-class = "ok", 

label = "Submit", 

{on Action at cb:CommandButton do 

{if-non-null dlg = cb.dialog then 

{if {validate-dialog dlg} then 

let dlg:Dialog = 

{Dialog 

{GroupBox 

width = 4.5cm, 

label = "", 

{hcenter 

{VBox 

halign = "center", 

spacing = 0.1cm, 

{Label "Submitted"}, 

{ok-button} 

} 

} 

} 

} 

{dlg.show title = "Validated"} 

} 

} 

} 

} 

|| NOTE: In this case it is a composite of the styled controls StyleSheet, 

|| another StyleSheet, and an additional StyleRule. 

let ss:StyleSheet = 

{StyleSheet 

common-style-sheet, 

{get-default-style-sheet} 

} 

|| Install the StyleSheet. 

{install-style-sheet ss} 

|| Create the UI. 

{Frame 

{login-dialog tf, pf, cb} 

} 

}

Creating the Style Sheet File
Defining style sheet rules directly in your source code is a good approach for testing your rules. Once you are satisfied with the StyleRules, you can place them in one or more style sheet files. The default style sheet is a prime example of this implementation in which it has rules that implement a new look for all of the Curl GUI Toolkit controls. Let's first examine the the contents of the files that define the default style sheet. They are contained within two files: default-style.scurl and dss-defs.scurl (dss-defs.scurl is included in default-style.scurl). These files are located in the Curl install directory. For example, on Windows it is C:\Program Files\Curl Corporation\Surge\8\ide\gui\controls\styled-controls.

One thing to recognize is that a style sheet in Curl is simply a file containing Curl code. The file extension is *.scurl and the last expression in this file must return a StyleSheet object. Aside from that, the file can include any Curl code that is needed to implement the style. In particular, you may need to import packages such as CURL.GUI.STANDARD in order to implement your style.

Our style sheet file resembles the following:

Code:
|| StyleSheet 

{import * from CURL.GUI.STANDARD} 

{StyleSheet 

{StyleRule CommandButton.ok, 

width = 1.75cm 

}, 

{StyleRule TextField.login, 

width = 2cm 

}, 

{StyleRule PasswordField.login, 

width = 2cm 

}, 

{StyleRule GroupBox.dialog, 

width = 4.5cm 

} 

}

In our login example, reference the StyleSheet file using the url.

Code:
{let common-style-sheet:StyleSheet = 

{url styles/my-styles/common-style-b.scurl} 

}

Code:
{curl 7.0 applet} 

{let common-style-sheet:StyleSheet = 

{url "styles/my-styles/common-style-b.scurl"} 

} 

|| Form creation procs 

{define-proc {login-dialog 

tf:TextField, pf:PasswordField, cb:CommandButton 

}:Graphic 

{return 

{GroupBox 

style-class="dialog", 

label = "", 

{Dialog 

use-look-and-feel? = false, 

{Table 

{row 

{cell {Label"Username:"}} 

{cell {value tf}} 

}, 

{row 

{cell {Label "Password: "}} 

{cell {value pf}} 

}, 

{row 

{cell 

colspan = 2, 

halign = "center", 

{value cb} 

} 

} 

}, 

{validate-with {DialogValidator}} 

} 

} 

} 

} 

{value 

let tf:TextField = 

{TextField 

style-class="login", 

width = 2cm, 

{validate-with ValidationPattern.email-address, required? = true} 

} 

let pf:PasswordField = 

{PasswordField 

style-class="login", 

width = 2cm, 

{validate-with {StringValidator}, required? = true} 

} 

let cb:CommandButton = 

{CommandButton 

style-class = "ok", 

label = "Submit", 

{on Action at cb:CommandButton do 

{if-non-null dlg = cb.dialog then 

{if {validate-dialog dlg} then 

let dlg:Dialog = 

{Dialog 

{GroupBox 

width = 4.5cm, 

label = "", 

{hcenter 

{VBox 

halign = "center", 

spacing = 0.1cm, 

{Label "Submitted"}, 

{ok-button} 

} 

} 

} 

} 

{dlg.show title = "Validated"} 

} 

} 

} 

} 

|| NOTE: In this case it is a composite of the styled controls StyleSheet, 

|| another StyleSheet, and an additional StyleRule. 

let ss:StyleSheet = 

{StyleSheet 

common-style-sheet, 

{get-default-style-sheet} 

} 

|| Install the StyleSheet. 

{install-style-sheet ss} 

|| Create the UI. 

{Frame 

{login-dialog tf, pf, cb} 

} 

}

Code:
Customization of Login Screen

The following code defines the customization of controls displayed in the "Custom" selection of our example applet. In the following applet we have customized the look and feel using a style sheet defined in the custom-style-sheet.scurl file. used in this applet can be viewed by selecting this link:
custom-style.scurl (Size: 11.93 KB / Downloads: 1435)

Code:
{curl 7.0 applet} 

|| Identify the StyleSheets. 

|| The common StyleSheet sets up some rules (primarily widths) common to the 

|| different versions of the login form. 

{let common-style-sheet:StyleSheet = 

{url "styles/my-styles/common-style.scurl"} 

} 

|| The "custom" StyleSheet sets up rules for an appearance that is different 

|| from the "default" StyleSheet. 

{let custom-style-sheet:StyleSheet = 

{url "styles/my-styles/custom-style.scurl"} 

} 

|| Form creation procs 

{define-proc {login-dialog 

tf:TextField, pf:PasswordField, cb:CommandButton 

}:Graphic 

{return 

{GroupBox 

label = "", 

{Dialog 

{Table 

{row-prototype 

{cell-prototype 

{TextDisplay 

|| Specify the style-class you want applied. 

style-class = "login", 

value = "Username: " 

} 

}, 

{cell-prototype tf} 

}, 

{row-prototype 

{cell-prototype 

{TextDisplay 

|| Specify the style-class you want applied. 

style-class = "login", 

value = "Password: " 

} 

}, 

{cell-prototype pf} 

}, 

{row-prototype 

{cell-prototype 

colspan = 2, 

halign = "center", 

cb 

} 

} 

} 

} 

} 

} 

} 

{value 

let tf:TextField = 

{new TextField, 

style-class = "login", 

{on v:Validate at tf:TextField do 

{if not v.partial? then 

{if tf.value != "CurlUser" then 

let dlg:Dialog = 

{new Dialog, 

{GroupBox 

label = "", 

{hcenter 

{VBox 

halign = "center", 

{Fill height = 0.1cm}, 

{TextFlowBox 

paragraph-justify = 

"center", 

"The correct " & 

"username is " & 

"'CurlUser'." 

}, 

{Fill height = 0.1cm}, 

{CommandButton 

label = "OK", 

style-class = "ok", 

{on Action at cb:CommandButton 

do 

{cb.dialog.close 

"ok" 

} 

} 

}, 

{Fill height = 0.1cm} 

} 

} 

} 

} 

{dlg.show title = "Validate"} 

{tf.mark-invalid} 

set tf.style-class = "validation-error" 

else 

set tf.style-class = "TextField" 

} 

} 

} 

} 

let pf:PasswordField = {new PasswordField} 

let cb:CommandButton = 

{CommandButton 

label = "Submit", 

{on Action at cb:CommandButton do 

{if-non-null dlg = cb.dialog then 

{if {validate-dialog dlg} then 

let dlg:Dialog = 

{new Dialog, 

{GroupBox 

label = "", 

{VBox 

halign = "center", 

{Fill height = 0.1cm}, 

{TextFlowBox 

text-breakable? = false, 

"Submitted" 

}, 

{Fill height = 0.1cm}, 

{CommandButton 

label = "OK", 

style-class = "ok", 

{on Action at 

cb:CommandButton 

do 

{cb.dialog.close 

"ok" 

} 

} 

}, 

{Fill height = 0.1cm} 

} 

} 

} 

{dlg.show title = "Validate"} 

} 

} 

} 

} 

|| Create a StyleSheet 

|| NOTE: In this case it is a composite of the common StyleSheet, and the 

|| custom StyleSheet. 

let ss:StyleSheet = 

{new StyleSheet, 

common-style-sheet, 

custom-style-sheet 

} 

|| Install the StyleSheet. 

{install-style-sheet ss} 

|| Create the UI. 

{Frame 

{StandardActiveTraversalContainer 

halign = "center", 

margin = 1cm, 

{login-dialog tf, pf, cb} 

} 

} 

}

For more information regarding paragraph formats, please refer to the Curl Styled Controls Library User's Guide that you installed in the Curl Documentation

Styling1:Curl Styles

Thu, 16 Jun 2011 00:14:08 +0000

Curl supports custom style sheets that are similar in functionality to Cascading Style Sheets (CSS). It allows developers to control the style and layout of displayed Curl elements all at once.

A Curl style sheet is used to help authors of web pages to define colors, fonts, layout, and other aspects of document presentation. It is designed primarily to enable the separation of document content from document presentation. This separation can provide more flexibility and control in the specification of presentational characteristics and can reduce unnecessary complexity and repetition caused by intertwining the structural content with presentation styles.

In referring to the following applet, select the dropdown list to display three different login views.

•The first item in the dropdown list displays controls created with Curl by removing the default style options.

•The second item on the dropdown list displays controls using our default styles.

•The third item on the dropdown list displays formatted controls using a custom style sheet.

Note that the login screen does not implement a login procedure, rather it displays the controls for example purposes. We have, however, included validation on the text fields.

In this Curl Cue, we will be addressing the first two items: creating controls with Curl and using a default style sheet. Creating custom style sheets will be discussed in a subsequent Curl Cue.

Default Style

Before we style controls, let's first create the login interface using Curl's default styling. From working with Curl containers and controls, you should be familiar with creating the following login screens. The following code displays standard look and feel of Curl graphical objects created to display a standard login screen.

Code:
{curl 7.0 applet}

|| Form creation procs

{define-proc {login-dialog

                tf:TextField, pf:PasswordField, cb:CommandButton

            }:Graphic

   {return

       {GroupBox

           label = "",

           {Dialog

               {Table

                   {row

                       {cell {Label"Username:"}}

                       {cell {value tf}}

                   },

                   {row

                       {cell {Label "Password: "}}

                       {cell {value pf}}

                   },

                   {row

                       {cell

                           colspan = 2,

                           halign = "center",

                           {value cb}

                       }

                   }

               },

               {validate-with {DialogValidator}}

           }

       }

   }

}

{value

   let tf:TextField =

       {TextField

           width = 2cm,

           {validate-with ValidationPattern.email-address, required? = true}

       }

   let pf:PasswordField = 

       {PasswordField width = 2cm,

           {validate-with {StringValidator}, required? = true}

       }

   let cb:CommandButton =

       {CommandButton

           label = "Submit",

           {on Action at cb:CommandButton do

               {if-non-null dlg = cb.dialog then

                   {if {validate-dialog dlg} then

                       let dlg:Dialog =

                           {Dialog

                               {GroupBox

                                   width = 4.5cm,

                                   label = "",

                                   {hcenter

                                       {VBox

                                           halign = "center",

                                           spacing = 0.1cm,

                                           {Label "Submitted"},

                                           {ok-button}

                                       }

                                   }

                               }

                           }

                       {dlg.show title = "Validated"}

                   }

               }

           }

       }

   {login-dialog tf, pf, cb}

}

[b]Removing Default Styling[.b]

We can remove all default styling by using install-standard-look-and-feel. This will remove all styling from the controls. Place this procedure at the top of your applet.

Code:
{curl 7.0 applet}

{install-standard-look-and-feel}

|| Form creation procs

{define-proc {login-dialog

                tf:TextField, pf:PasswordField, cb:CommandButton

            }:Graphic

   {return

       {GroupBox

           label = "",

           {Dialog

               {Table

                   {row

                       {cell {Label"Username:"}}

                       {cell {value tf}}

                   },

                   {row

                       {cell {Label "Password: "}}

                       {cell {value pf}}

                   },

                   {row

                       {cell

                           colspan = 2,

                           halign = "center",

                           {value cb}

                       }

                   }

               },

               {validate-with {DialogValidator}}

           }

       }

   }

}

{value

   let tf:TextField =

       {TextField

           width = 2cm,

           {validate-with ValidationPattern.email-address, required? = true}

       }

   let pf:PasswordField = 

       {PasswordField width = 2cm,

           {validate-with {StringValidator}, required? = true}

       }

   let cb:CommandButton =

       {CommandButton

           label = "Submit",

           {on Action at cb:CommandButton do

               {if-non-null dlg = cb.dialog then

                   {if {validate-dialog dlg} then

                       let dlg:Dialog =

                           {Dialog

                               {GroupBox

                                   width = 4.5cm,

                                   label = "",

                                   {hcenter

                                       {VBox

                                           halign = "center",

                                           spacing = 0.1cm,

                                           {Label "Submitted"},

                                           {ok-button}

                                       }

                                   }

                               }

                           }

                       {dlg.show title = "Validated"}

                   }

               }

           }

       }

   {login-dialog tf, pf, cb}

}

For more information please refer to the User Interface Basics section of the Curl Cues or in the Curl documentation:

Curl Developer's Guide > Graphical User Interface > Dialogs and Controls..

For more information regarding style sheets, please refer to the Curl Styled Controls in the Curl Documentation

loginform.curl (Size: 7.36 KB / Downloads: 1344)

Persistent Data2:HTTP Cookies

Wed, 15 Jun 2011 08:27:27 +0000

HTTP Cookies are a standard Web mechanism for state management that allows a server to communicate with a client for purposes of:

•Authentication

•Security

•End user identification

•Preserving application state

Cookies are a way for a server to send information to a client to store, and for the server to later retrieve its data from that client. Servers send cookies to clients by adding fields to HTTP response headers. Clients return cookies to the server by adding fields to HTTP request headers. The information is stored in text files on the client's machine.

In the previous Curl Cue, we discussed the power of storing data on the client machine using Curl's Client-side persistent data. So... Why Would a Curl Applet Need to Use HTTP Cookies? HTTP Cookies are mainly used for storing session information when a Curl applet interacts with a server-side application that requires a cookie. An HTTP cookie contains a session identifier as well as other relevant information about the user -- therefore cookies are necessary when a Curl applet interacts with servers that require a session. Each session has a beginning and an end, can be relatively short-lived, and can be terminated by either the client or the server

For example, if a user logs into a Curl application, you may need get session information from a server. A cookie is sent to the Curl applet upon start up. Once the Curl applet has the cookie data stored, the information is sent to the associated URI with each request.

Working with HTTP Cookies

HTTP Cookies can either be secure or insecure. If you have a secure connection, you can use the HTTPS protocol for communication with the server. For our examples, we will use insecure cookies.

In general, HTTP Cookies are:

•Stored on a client machine as text

•Grouped by URI

•Sent to the server when the specific URI is requested

This HttpCookie class holds all data associated with an HTTP cookie. The associated HttpCookie fields that store the HTTP cookie information are:

•comment: A comment about the cookie variable.

•domain: Domain that the hostname in the URL must match for the cookie to be sent along with requests for that URL.

•expires: When the cookie should expire.

•max-age: How long the cookie should last.

•name: Name of the cookie variable.

•path: Path that the URL must start with for the cookie to be sent along with requests for that URL.

•secure?: Indicates whether this HttpCookie should be sent across "secure" channels such as that provided by HTTPS.

•value: Value of the cookie variable.

•version: Version of the cookie protocol being used; currently 1 is the only known legal value.

Note that When the cookie should expire if expires is null, the cookie is kept only until the current host process exits. Once expires is in the past, the cookie may be deleted. If expires is in the future, the cookie is saved, possibly on disk, until the expiration date.

Setting and Getting HTTP Cookies
Use set-insecure-http-cookie to create the cookie on the local machine.

Code:
|| Let the cookie expire 1 year from now 

let expire-date:DateTime = {new DateTime} + (1day *365) 

|| Set the cookie 

{set-insecure-http-cookie 

{get-the-applet}.url, 

{HttpCookie 

session-id, 

My session, 

expires = expire-date 

} 

}

Once this information is set, then the cookie data is set with future HTTP requests to the given URI. Also note that get-the-applet returns the Url of the running applet.

Use get-http-cookies to retrieve cookie data.

Code:
let jar:{Array-of HttpCookie} = {get-http-cookies 

{get-the-applet}.url 

}

You can also use clear-insecure-http-cookie to clear any cookies. In most cases, you will use clear-insecure-http-cookie to remove cookies before the session ends (unless you want the information stored on the local machine for future use).

Putting it all together...

Ok, let's put everything together. In the following appley we will create a cookie that stores the value of My session that is set to expire 1 year from the creation date. Since cookies require the a browser, the applet must be run over HTTP. Therefore the code has been enclosed in a try expression so that we can catch any HttpExceptions.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes 

character-encoding = "utf8" 

} 

{value 

|| Create a cookie value to set 

let session-id:String = "My session" 

|| Let the cookie expire 1 year from now 

let expire-date:DateTime = {new DateTime} + (1day *365) 

{try 

|| Clear previous cookies 

{clear-insecure-http-cookie 

{get-the-applet}.url, 

"session-id" 

} 

|| Set the cookie with the session-id value 

{set-insecure-http-cookie 

{get-the-applet}.url, 

{HttpCookie 

"session-id", 

session-id , 

expires = expire-date 

} 

} 

|| Get cookie information 

let jar:{Array-of HttpCookie} = 

{get-http-cookies 

{get-the-applet}.url 

} 

|| Loop through the cookie data to find the session-id 

{for cookie:HttpCookie in jar do 

{if cookie.name == "sessionid" then 

set session-id = cookie.value 

else 

|| Do nothing 

} 

} 

catch e:HttpException do 

set session-id = "You must run this applet over HTTP" 

} 

|| Create a graphic to hold the information 

let display:VBox = {VBox 

background = "yellow", 

|| Dispaly the cookie value 

session-id 

} 

|| Return the display 

display 

}

Cookies and Security The only cookies an unprivileged applet can set or clear are those that would be sent with the applet's URL or with the applet's URL's parent directory. Keep in mind that unless the cookie has secure?=true and is used with https URLs, it could be seen by third party applications (snooping) on the network. In addition, unless expires=null, the cookie may be stored on disk.

communication.png (Size: 37.44 KB / Downloads: 5410)

Persistent Data1:Client-side Persistent Data

Wed, 15 Jun 2011 08:24:10 +0000

How do we keep data around to access it later? Or perhaps keep data for another invocation of the same program? To maximize usability and effectiveness, an application must be able to store relevant client data to disk. Depending on the type of application, client data can contain information such as:

•User preferences

•Visual displays

•Game scores

•Application settings

This data can be retrieved at a later time and further processed. Depending on the application, the data can be stored either locally or remotely. In either case, when the application exits, information regarding the state is written. When the user accesses the application at a later time, that same information is read to return the user to the previous state.

Persistent data is data that a Web application should 'remember' as the user moves between pages. There are different approaches to storing information. The approaches depend on the architecture of the system, i.e. whether the program needs to communicate with the server or not.

Instead of explicitly writing to a file, small amounts of data can be stored on a client machine using:

•Client-side persistent data (CSPD)

•HTTP Cookies

In this Curl Cue, we will concentrate on CSPD in which data is stored in a separate repository on the local machine. The Curl runtime environment handles that process of data storage and retrieval automatically. Thus, this provides a consistent method of data storage and retrieval.

Client-side Persistent Data

Curl's Client-side Persistent Data system allows you to store small amounts of data on the client without explicitly writing to a file. Data is stored in a Curl-specific repository in which the data can:

•Handle multiple formats of data

•Be set to expire

•Limit the amount of data stored

•Share data between two or more related applets

Why should you use CSPD?

Applets written in the Curl language cannot read from or write to the file system unless they are privileged. This restriction poses problems if your application needs to store applet data. Applets that have been run from a Web site could transmit data back to the host system, but this can be slow and could put a strain on the server. In addition, the data involved may be specific to the user or the client machine, such as the user name. Instead, you can use the persistent data system to store small amounts of data on the client.

CSPD stores and retrieves data using key/value pairs. The steps are as follows:

1.Define a private persistent data repository

2.Write key/value pairs to the repository

3.Commit the repository

4.At a later time, use the key name to retrieve data from the repository

Creating the Repository

Create the private persistent data repository using the persistent-data procedure. This procedure call needs to occur at the top-level of your file (outside of any code block). It must appear before any attempt to read or store data in the repository.

In the following code, we are defining a repository that will store values for up to 180 days (if not accessed) and that has a maximum size of 1024 bytes. The "Date storage" argument is a required comment that describes what is stored in the repository.

Code:
{persistent-data 

Date storage, 

duration = 180days, 

max-size = 1024 

}

Setting and Committing Persistent Data

Each item stored in a repository is identified by a key (or name). Each key has a datatype of String in which it cannot contain slashes (/) (otherwise there are no restrictions). To store data in the repository, call the set-persistent-data procedure, passing it a key and the associated data.

In the following example, the key is visit data and the data will be the current time (stored as a string).

Code:
{set-persistent-data visit date, {String {DateTime}}}

After you have added all of the data you want to store in the repository, you need to call commit-persistent-data to store the data to disk.

Code:
{commit-persistent-data}

Retrieving CSPD Values

Use the get-persistent-data procedure to get data from the repository. You specify the key, and the procedure returns the value associated with the key. Returned values have the same data type as the stored data.

If the key does not match an entry in the repository, a KeyNotFoundException is thrown. Therefore, it is wise to use a try expression with a catch clause to handle any exceptions.

Code:
{try 

set x = {get-persistent-data visit date} 

catch not-found:KeyNotFoundException do 

set x = You have not been here before 

}

Putting it all together

Let's put the entire example together. Note that since CSPD is stored on each client machine, you will get a different time stamp than your neighbor!

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes 

character-encoding = "utf8" 

} 

|| Defining the repository 

{persistent-data 

"Date storage", 

duration = 180days, 

max-size = 1024 

} 

{value 

|| Retrieving persistent data 

let x:#String 

{try 

set x = {get-persistent-data "visit date"} 

catch not-found:KeyNotFoundException do 

set x = "You have not been here before" 

} 

|| Setting and committing persistent data 

{set-persistent-data "visit date",{String {DateTime}}} 

{commit-persistent-data} 

|| Returning the value of x 

{text The last time you visited this site was: {value x}} 

}

For more information regarding Curl's Client-side persistent data system, please refer to the Curl Developer's Guide under Interacting with External Resources/Client-side Persistent Data.

cspd.png (Size: 58.81 KB / Downloads: 2693)

Serving Content3:Dynamically Generating Curl Content

Wed, 15 Jun 2011 08:19:57 +0000

With server-side technologies such as ASP and PHP, you can use Curl applets that are generated on the fly. Dynamic data can be placed into a Curl applet that is sent from a server to the user's browser.

Curl works with server languages such as ASP, JSP, PHP, and CGI. Scripts in these languages can generate Curl applets to be launched on the client machine, after which all Curl processing happens on the client machine.

Generating Curl from a Script
In the following examples, we are using ASP or PHP to dynamically generate Curl content. If you are familiar with scripting languages, you will notice that what would otherwise be HTML has been replaced with Curl code.

In either case, you will have to:

1.Identify the server scripting language, for example: ?php

2.State the MIME type declaration for Curl content, for example: text/vnd.curl

3.Embed correctly formed Curl applet code

The following examples both generate similar Curl code. They produce a display like this when run.

PHP Example

Code:
/** 

* 

* PHP example 

* 

*/ 

header('Content-type: text/vnd.curl'); 

// All of the above code is PHP. 

// What follows the next line (i.e., after "echo <{curl 5.0 applet} 

{value 

{Frame 

width = 5cm, 

height = 5cm, 

border-color = "gray", 

border-width = 0.1cm, 

border-style = "raised", 

background = "#4578ef", 

{hcenter 

{vcenter 

"A PHP script on the server generated this applet." 

} 

} 

} 

} 

END; 

// The Curl code ended before the previous line (i.e., before "END;"). 

?>

ASP Example

Code:
{curl 5.0 applet} 

{value 

{Frame 

width = 5cm, 

height = 5cm, 

border-color = "gray", 

border-width = 0.1cm, 

border-style = "raised", 

background = "#4578ef", 

{hcenter 

{vcenter 

"An ASP script on the server generated this applet." 

} 

} 

} 

}

Passing Variables from a Script
The previous examples demonstrate how to generate Curl content directly from a server script. Now we are adding in the use of variables. It is common that you may have script variables that store relevant information about the session such as:

•Session ID

•Cookie information

•Username

•Other user identification information

The following is an example of Curl being generated by a PHP script. It includes the use of a variable ($variable) which is set by calling a function in a separate PHP file to obtain a username for display in the Curl applet.

The resulting content displayed is:

PHP Example

Code:
// Include any supporting PHP code. 

include("supporting-php-code.php"); 

// Set the Curl MIME type 

header('Content-type: text/vnd.curl'); 

// Set a variable using your PHP code. 

$variable = getUsername(); 

// All of the above code is PHP. 

// What follows the next line (i.e., after "echo <{curl 5.0 applet} 

{value 

{Frame 

width = 5cm, 

height = 5cm, 

border-color = "gray", 

border-width = 0.1cm, 

border-style = "raised", 

background = "#4578ef", 

{hcenter 

{vcenter 

"Hello " & "$variable" & "!" 

} 

} 

} 

} 

END; 

// The Curl code ended before the previous line (i.e., before "END;"). 

?>

Notice on the code displayed above that we are including supporting PHP code. In this case, the file supporting-php-code.php contains the following content:

Code:
function getUsername() { 

return "Curl User"; 

} 

?>

In an actual application, the getUsername function retrieves information from one of the data sources mentioned above.

ASP Example

Code:
{curl 5.0 applet} 

{value 

{Frame 

width = 5cm, 

height = 5cm, 

border-color = "gray", 

border-width = 0.1cm, 

border-style = "raised", 

background = "#4578ef", 

{hcenter 

{vcenter 

"Hello " & "" & "!" 

} 

} 

} 

}

Other ways to run Curl applets include the following:

•Launching a Curl applet from another Curl applet. Please see Launching a Curl Applet.

•Embedding Curl in HTML. Please see Launching and Embedding Curl in HTML.

phpscript.jpg (Size: 7.48 KB / Downloads: 1821)

phpvariable.jpg (Size: 4.96 KB / Downloads: 1886)

Serving Content2:Launching and Embedding Curl in HTML

Wed, 15 Jun 2011 08:15:40 +0000

Working with HTML
As you have already seen, the browser can directly load an applet, allowing the applet to take over the entire display area of the browser. A Curl applet can also be launched or embedded in an HTML page that the browser loads. Embedding a Curl applet allows the applet to share the browser's display area with HTML content.

For Web pages that contain both HTML and Curl content, the following scenario occurs:

1.The browser sends a request to the server

2.The browser interprets the information sent from the server in which HTML is rendered and Curl content is recognized by the browser

3.The browser starts the Curl runtime environment to handle the Curl content

Let's examine each of these scenarios.

Launching a Curl applet from an HTML file
From an HTML file, users can launch a Curl applet by selecting a link that targets Curl content using the Anchor tag .

Embedding a Curl applet in an HTML file
A Curl applet can be embedded in an HTML page using HTML's EMBED tag. Because of the way EMBED works, you will need to specify the MIME type for the Curl file explicitly in the HTML page.

Your Curl applet will appear within a rectangular area in the HTML page, similar to the way other embedded content appears.

In HTML, use the EMBED tag to specify information about Curl content

Code:
SRC=embed-applet.curl 

TYPE = text/vnd.curl 

PLUGINURL = http://www.curl.com/download/rte/ 

width = 300 

height = 300 >

Where:

•SRC: Identifies the Curl applet that will be launched

•TYPE: Identifies the MIME type

•PLUGINURL: Identifies the Curl runtime environment location (if not previously installed on system)

For example:

Select this link to view the running HTML page:

Embedded Applet

The EMBED tag contains the MIME type for the Curl content as well as the URL information about where to direct the user in the case the Curl runtime is not available on the user's browser. The attributes used in the example do not constitute a full list of what is available for the EMBED tag. However, they are sufficient for creating a working embedded applet.

The HTML code is as follows:

Code:
This is an example of embedding Curl content into HTML. 

This is a standard HTML page, with a Curl applet embedded into it. 

Beginning of the embedded Curl applet 

 SRC="../samples/ServingContent/launch-1.curl" 

TYPE = "text/vnd.curl" 

PLUGINURL = "http://www.curl.com/html/products/surge.jsp" 

width = "300" 

height = "300" > 

End of the embedded Curl applet.

If you want your applet to take over the entire browser display area, you can just link to its source file directly, rather than an HTML file that embeds it.

For more information regarding Embedding HTML, please refer to the following section in the Curl Documentation:Curl Developer's Guide > File Systems and Networking > Interacting with the Browser

Other ways to run Curl applets...

•Launching a Curl applet from another Curl applet. Please see Launching a Curl Applet.

•Generating Curl using PHP or similar scripts. Please see Dynamically Generating Curl Content.

embeddedapplet.jpg (Size: 30.84 KB / Downloads: 3125)

Serving Content1:Launching a Curl Applet

Wed, 15 Jun 2011 08:12:26 +0000

The design and development is complete and now you are ready to deploy your Curl application on a server. Storing the files on your local machine allows you to easily build and test the application and now all the Curl and supporting files must be moved to the server. The first item is to identify the server and move the files over. Next, you must configure your server to accept Curl application requests.

Server Requests
Each time a user selects a link to navigate to a new Web page, the browser sends request to the server. The server receives the request and sends the requested information back to the browser. The browser then interprets and displays the information to the user.

When the requested information contains Curl content, the browser receives the information and launches the Curl runtime environment if it is not previously loaded. The processing of the applet is performed on the client and the content is presented to the user in the browser window.

Server Configuration
How does the server know about Curl? When you are ready to deploy a Curl application, you will need to configure your server to work with Curl files.

•The first step is to take the application files and place them on your server

•Next, allow access to files

•Finally, configure the MIME type

We'll go through all the steps in more detail.

Placing Files on your Server
In addition to your application and data files, you will need to put a server license file on your server. The Curl RTE will not execute a curl applet from an http:// or https:// location unless there is a valid license file on the server.

There are two kinds of server licenses, the free personal license and a paid license for commercial use.

•A Curl/Personal Server License unlocks most features of the Curl platform, excepting several features whose primary value is for enterprise applications. You can get a Curl/Personal Server License at no charge for your Web site if you are a noncommercial user.

•A Curl/Pro Server License unlocks the full capabilities of the Curl platform. If you are an enterprise, you need to use a Curl/Pro license.

Each kind of server license takes the form of a file called curl-license-5.dat that you obtain from Curl and place on your Web server to indicate that you are licensed to deploy Curl applications on the Web. In the simplest case, you put this file in the root directory of your Web server. Other options are also available such as placing the server license in the same directory as your Curl applet files.

For more information regarding server licenses, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Configuring Your Web Server > License Keys

Allowing Applets to Access Files
The curl-access.txt file contains directives that define which Curl applets can access the Web site's files. Applets are restricted based on their home site, which is the Web site from which they were downloaded. Using curl-access.txt, a server administrator can allow all Curl applets to access files on that server, or can restrict access so that, for example, only Curl applets hosted on other servers in the same domain, or only Curl applets from that server, can access the files. Generally, a Curl applet will access at least some files on the same server where the applet is deployed, so it is usually necessary to have some form of curl-access.txt file on that server.

The directives in the curl-access.txt file declare which Curl applets are authorized to access its files. The following curl-access.txt file grants access to applets from all servers:

Code:
#Allow applets free access 

version: 2.0 

allow-all:

The next curl-access.txt file grants access to Curl applets from specific sites and can selectively filter access to the server from publicly deployed applets:

Code:
#Allow applets free access 

version: 2.0 

allow: *.mydomain.com, test.mysupplier.com 

except: public-ftp.mydomain.com

The curl-access.txt mechanism does not override any other protections that your Web site has in place to restrict access to files. If the user could not access a file directly using a browser, then an applet on his or her system will not be able to access the file either. This is true even with a curl-access.txt file that grants the applet access to files on that server.

You can either place this file in the root directory of your Web server or in the same directory as the data files whose accessibility you want to control. When placed at the root of the Web site, the curl-access.txt directives will override all other directives found in the subdirectories of that Web site. Consequently, this method will subject all the files on your Web site to the same rules. When the curl-access.txt file is placed at the local directory level, it controls the access to just the files contained in that directory.

For more information regarding Curl access, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Configuring Your Web Server > Allowing Applets to Access Files

Configure Mime Type
In order to serve Curl applets from your Web site, you also need to add MIME type definitions for Curl source files and package files to your Web server's configuration. The MIME type is how the server tells the browser that a file should be handled by the Curl runtime environment.

The .dcurl and .car file types are used for specialized purposes. .dcurl files are used for detached applets, which run outside of a browser window as standalone applications. .car files are used when deploying an applet that can be used offline as well as online.

For more information regarding MIME Types, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Configuring Your Web Server > Source MIME Types for Curl files

Launching a Curl applet
Now you are all ready to serve Curl content. The easiest way to launch a Curl applet from a server is to type the url location of the start file (start.curl) of the application. The following Curl applet can be accessed by directly selecting the link. (Select the back button in the browser window to return to Curl Cues.)

Select this link to launch a Curl applet

Launching a Curl applet from a Curl applet
It is common to have one Curl applet launch another Curl applet. One example is login capability in which the "login applet" launches another Curl applet based on the required authentication.

The browse-url method in the Applet class allows you to load a given url; it has the same effect as selecting a link. The browser's history will be updated appropriately.

Code:
{curl 6.0, 7.0 applet} 

{applet {compiler-directives careful? = true}} 

{value 

let my-applet:Applet = {get-the-applet} 

let browse-button:CommandButton = 

{CommandButton 

label = "Launch Applet", 

{on Action do 

{my-applet.browse-url 

{url "./launch-1.curl"}, 

target = "_blank" 

} 

} 

} 

{VBox 

{bold The following button launches another Curl applet}, 

browse-button 

} 

}

The above example launches a Curl applet when the CommandButton is pressed. The browse-url method is associated with the action of the CommandButton. The target specified in browse-url ("_blank") will open a new browser window. The default behavior is to use the same window as the running applet ("_self").

Other ways to run Curl applets...

•Embedding Curl applets in HTML. Please see http://developers.curl.com/docs/DOC-1127.

•Generating Curl using PHP or similar scripts. Please see http://developers.curl.com/docs/DOC-1128.

Launching a Curl Applet1.JPG (Size: 19.91 KB / Downloads: 1934)

Forms3:HTTP Forms

Wed, 15 Jun 2011 08:02:00 +0000

One of the most common ways to communicate with a server is over HTTP. Curl's HttForm class acts as a container for controls that will be part of the web form. Users complete the form by modifying its controls before submitting hte form to an agent for processing. The function of HttpForm is similar to the FORM tag in HTML.

Lets look at the following simple example. In this case, we are creating a Google query that also specifies the language and the interface. Enter text that you would like to query in Google, e.g. "Baseball". Then hit thie "Submit" button. A new browser window will be launched to display the results.

width='100%' height='60' src='../../wiki/samples/Forms/http2.curl'

In this case, HttpForm is used to create the Web form

•A Dialog is created to contain the controls

•The user fills out the form and clicks the Submit button

•Key/value pairs are sent to the server script using GET or POST

•Returned information is sent to the user

When instantiating an HttpForm object, you provide the URL of the CGI program or script on the Web site that will receive the request, as well as the HTTP request method of GET or POST.

Let's break down this example. First we will create an form that only submits the query. Afterwards, we can add the additional query elements and expand the example.

width='100%' height='450' src='/wiki/samples/generic-example.curl?Forms/http.curl'

In this example, we will be sending the following HTTP request using GET: http://www.google.com/search?q=Baseball (where "Baseball" represents the text typed in by the user). In order to accomplish this, we need to first specify the url of the server.

Code:
{url http://www.google.com/search},

The target specifies the browser window in which the action will be displayed. Values are as follows:

•_self: Returns results in the current browser window (default)

•_blank: Returns results in a new browser window

•_parent: Returns results in the parent frameset of the current frame.

•_top: Returns the results in the top-level window (full browser window)

Since the HttpForm is a Dialog, we must create one child object that can contain multiple children. In our example, we are using a VBox. Control values that are passed to the HTTP request must include the name attribute. The TextField has name = "q" defined.

Code:
{TextField

    width = 2in,

    name = q

}

The submit-button is a Curl procedure that creates a CommandBuitton with at "Submit" label. When the user clicks on the button, it automatically passes the form information to the specified Url.

Code:
{submit-button}

We have created this proc as a convenience procedure. For custom submit functionality, you can always create your own procedure or method. Another convenience procedure that we have created for you is reset-button. In this case, it creates and returns a standard "Reset" button for use in the HttpForm. Let's add this functionality to our example.

Code:
{curl 6.0, 7.0 applet}

{curl-file-attributes character-encoding = "utf8"}

{applet manifest = "manifest.mcurl",

   {compiler-directives careful? = true}

}

{HttpForm

   {url "http://www.google.com/search"},

   target = "_blank",

   {HBox

       margin = 5pt,

       spacing = 3.5pt,

       {text Query:  },

       {TextField

           width = 2in,

           name = "q",

           value = "Pizza"

       },

       {submit-button},

       {reset-button}

   }

}

Note that the reset button will 'reset' all controls to their default state. In the above example the initial value has been set to "Pizza". If no initial value is specified, the "Reset" button will leave the TextField blank.

Forms2:Form Validation

Wed, 15 Jun 2011 07:59:58 +0000

One of the most important aspects of building and processing a form is how you validate the input data. You want to assist users by providing them with information to help them make choices as they fill out the form and to understand what's required and optional before selecting the submit button.

In classic server-based Web applications, once the enter or submit button is clicked, form data is passed to CGI script, or some other technology. If the data contains an error, there will be a delay before the information travels over the Internet to the server, is examined on the server, and then returns to the user along with an error message.

We will incrementally build the registration page. Let's first start with a simple example using a TextField in order to discuss the syntax. The idea is to create a validation requirement that is associated with the control. The validate-with procedure is placed on each control that uses validation. The validator is the only required argument. This specifies the type of validation for the control to be valid, in our case a StringValidator.

A StringValidator ensures that a input value is not blank. We have also added keyword arguements to enforce size limits (min-chars and max-chars).

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{applet manifest = "manifest.mcurl", 

{compiler-directives careful? = true} 

} 

{value 

let full-name:TextField = 

{TextField 

width = 3cm, 

{validate-with 

{StringValidator min-chars = 3, max-chars = 25}, 

required?=true 

} 

} 

{HBox "Name:", full-name} 

}

The procedure validate-with requests validation on the control. In our case, a TextField. A ValueChanged or ValueFinished event on the control triggers the validation cycle. Note that if you do not specify min-chars and min-chars, then any length String is acceptable.

Let's add a MessageDisplay to the validation. A MessageDisplay is graphical object used to display validation messages to the user. In the following example, the first control uses the default message created by Curl. We have also added a user-age input that validates using a NumericValidator that displays a custom message.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{applet manifest = "manifest.mcurl", 

{compiler-directives careful? = true} 

} 

{value 

let name-feedback:MessageDisplay = {MessageDisplay} 

let age-feedback:MessageDisplay = {MessageDisplay} 

let full-name:TextField = 

{TextField 

width = 3cm, 

message-display = name-feedback, 

{validate-with 

{StringValidator min-chars = 3, max-chars = 25}, 

required? = true 

} 

} 

let user-age:TextField = 

{TextField 

width = 3cm, 

message-display = age-feedback, 

{validate-with 

{NumericValidator min-allowable = 18, max-allowable = 40}, 

required? = true, 

message = "Users must be between 18 and 40" 

} 

} 

{Table 

columns = 3, 

"Name:", full-name,name-feedback, 

"Age: ", user-age, age-feedback 

} 

}

The MessageDisplay object needs to be created in order to hold the message. The MessageDisplay is referenced in each control, for example:

Code:
message-display = neme-feedback

Since each control object has its own MessageDisplay, if the user inputs an invalid value, then the associated message will display to the right of the control until the input becomes valid. A message will also appear if the user does not input a value for the user-age since required? = true is specified.

Now, let's place additional controls that target common types of entries such as phone number, email, and zip code. In these cases, we can specify a ValidationPattern. For example {validate-with ValidationPattern.us-zip-code} is used to validate a us zip code. Other patterns include credit cards, http-urls, social security numbers, as well as patterns for French, German, Japanese, and Chinese entries. Please see ValidationPattern for more information.

If you run a validation of the user’s form input before the form is submitted, there will be no wait time and redundant load on the server. Invalid inputs are already filtered out when input is passed to the server-based program. It also allows to simplify server-based program. In Curl, data can be validated in real-time, as the user enters information into the form.

Our example is a simple registration page that will validate the entries on the client machine (without the need to query the server). If an entry requires a specific input that has not been entered, a validation message will be displayed to the user. Once all valid information has been input into the dialog, the Enter button will be enabled. When the user clicks the Enter button, it will display the input information in a popup dialog.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{applet manifest = "manifest.mcurl", 

{compiler-directives careful? = true} 

} 

{value 

let feedback:MessageDisplay = {MessageDisplay} 

let full-name:TextField = 

{TextField 

width = 8cm, 

message-display = feedback, 

{validate-with {StringValidator min-chars = 3, max-chars = 25}, required?=true} 

} 

let user-age:TextField = 

{TextField 

width = 1cm, 

message-display = feedback, 

{validate-with {NumericValidator min-allowable = 18, max-allowable = 40}, required? = true, message = "Users must be between 18 and 40"} 

} 

let address1:TextField = 

{TextField 

width = 8cm, 

message-display = feedback, 

{validate-with {StringValidator min-chars = 3}} 

} 

let address2:TextField = 

{TextField 

width = 8cm, 

message-display = feedback, 

{validate-with {StringValidator min-chars = 3}} 

} 

let zip-code:TextField = 

{TextField 

width = 3cm, 

message-display = feedback, 

{validate-with ValidationPattern.us-zip-code} 

} 

let home-phone:TextField = 

{TextField 

width = 5cm, 

message-display = feedback, 

{validate-with ValidationPattern.us-phone-number, required?=true} 

} 

let email-address:TextField = 

{TextField 

width = 5cm, 

message-display = feedback, 

{validate-with ValidationPattern.email-address, required? = true} 

} 

let enter-button:CommandButton = 

{CommandButton 

label = "Enter", 

{on Action do 

{popup-message 

{VBox 

"You entered:", 

full-name.value, 

address1.value, 

address2.value, 

zip-code.value, 

home-phone.value, 

email-address.value, 

user-age.value 

} 

} 

} 

} 

{Table 

columns = 2, 

"Name:", full-name, 

"Address: ", address1, 

"City, State: ", address2, 

"Zipcode: ", zip-code, 

"Phone: ", home-phone, 

"Email: ", email-address, 

"Age: ", user-age, 

enter-button, feedback 

} 

}

In the previous example, we also:

•Created an Enter button to display the input values.

•Used the same MessageDisplay for each control. The feedback will be displayed to the right of the Enter button.

While it is possible to use validation on individual controls, the system is most often used to validate controls grouped in a Dialog (including subclasses such as RecordForm or HttpForm). The validation cycle starts when an entry is changed and ends when all necessary feedback has been shown. This also allows us to enable the Enter button when the Dialog is valid.

Note that the Dialog has the following validation entries:

Code:
message-display = feedback, 

{validate-with {DialogValidator}},

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{applet manifest = "manifest.mcurl", 

{compiler-directives careful? = true} 

} 

{value 

let feedback:MessageDisplay = {MessageDisplay} 

let full-name:TextField = 

{TextField 

width = 8cm, 

{validate-with {StringValidator min-chars = 3, max-chars = 25}, required?=true} 

} 

let user-age:TextField = 

{TextField 

width = 1cm, 

{validate-with {NumericValidator min-allowable = 18, max-allowable = 40}, required? = true, message = "Users must be between 18 and 40"} 

} 

let address1:TextField = 

{TextField 

width = 8cm, 

{validate-with {StringValidator min-chars = 3}} 

} 

let address2:TextField = 

{TextField 

width = 8cm, 

{validate-with {StringValidator min-chars = 3}} 

} 

let zip-code:TextField = 

{TextField 

width = 3cm, 

{validate-with ValidationPattern.us-zip-code} 

} 

let home-phone:TextField = 

{TextField 

width = 5cm, 

{validate-with ValidationPattern.us-phone-number, required?=true} 

} 

let email-address:TextField = 

{TextField 

width = 5cm, 

{validate-with ValidationPattern.email-address, required? = true} 

} 

let enter-button:CommandButton = 

{CommandButton 

label = "Enter", 

name = "e-button", 

{on Action do 

{popup-message 

{VBox 

"You entered:", 

full-name.value, 

address1.value, 

address2.value, 

zip-code.value, 

home-phone.value, 

email-address.value, 

user-age.value 

} 

} 

} 

} 

{Dialog 

{Table 

columns = 2, 

"Name:", full-name, 

"Address: ", address1, 

"City, State: ", address2, 

"Zipcode: ", zip-code, 

"Phone: ", home-phone, 

"Email: ", email-address, 

"Age: ", user-age, 

enter-button, feedback 

}, 

message-display = feedback, 

{validate-with {DialogValidator}}, 

{on vc:ValidationComplete at d:Dialog do 

set {d.get-by-name "e-button"}.enabled? = d.valid? 

} 

} 

}

In summary, form validation is the first step for allowing users to easily input form values. In our example, we presented the input values using a popup-message. If you wish to submit the valid information to a server for processing, please see the Curl Developer's Guide for more information.

formvalid.curl (Size: 2.66 KB / Downloads: 1230)

Forms1:Creating Forms

Wed, 15 Jun 2011 07:55:38 +0000

Forms-based transactions and data entry are a key part of most enterprise workflows. Well-designed forms streamline users' work through attractive, usable visual design; by providing well-chosen, relevant predefined options for user input; and by interactively providing help and validating information entered by users. Most of all, a high-functioning form never requires its users to pause to wait for processing. These principles apply whether a form is used for sales orders, feedback surveys, product requests, or expense reporting.

A classic server-based Web application is structured as a series of one or more forms. A user using a client machine enters information into a form and clicks a Submit or Go button. The information is sent to a server, where it is processed and a new page or form is created that is sent back to the user. This architecture makes few demands on the client machine.

Unfortunately, this architecture also brings about the “World-Wide Wait” – that phenomenon where users around the world see an unresponsive screen after clicking the submit button. As a result, the usability and responsiveness of server-based Web applications represent a big step backward from the client/server or locally installed applications that they replaced.

Curl applications do the presentation work and, where appropriate, run application logic on the client side. Curl’s client-side processing capabilities offload a major computational burden from server machines and greatly reduce the amount of data transmitted from servers to clients.

This architecture allows Curl applications to provide “Active Forms” where validation and computations can be performed on the client without needing to continually submit information to the server. Certain selections by a user, such as indicating multiple beneficiaries on an insurance application, can even dynamically open out new panels required by the user's specific situation.

One of the easiest examples is a form where the user inputs information which is then sent to a server.

FormProcessing.jpg (Size: 22.92 KB / Downloads: 1833)

FormProcessingCurl.jpg (Size: 18.5 KB / Downloads: 1782)

Files over HTTP4:Viewing RecordSet Data

Wed, 15 Jun 2011 07:46:07 +0000

The primary class for the display of RecordSet data in a tabular format is RecordGrid. This provides a row and column display with built-in functionality for managing the display. The display can easily be modified, allowing you to add your own colors and preferences.

An included navigation bar enables you to move to the first or last record, or up or down by one record. It also indicates the total number of records currently displayed, and the position of the current record in the display. By default, a RecordGrid includes the following functionality:

•Move columns

•Resize columns

•Sort records

•Filter records

•Select and edit a field

•Select one or more records

Modeling data in a RecordSet provides access to many convenience features and functions. This Curl Cue concentrates on displaying RecordSet data in a grid fomat. RecordSet data can also be transformed into other display types such as bar, pie, line, scatter, and bubble charts.

Creating a RecordGrid
Use the RecordGrid class to create the tabular display. The only input needed is the record-source which specifies the RecordSet data.

Notice that the rows and columns correspond to records and fields from the source RecordSet. The navigation panel at the bottom of the display enables you to move to the first or last record, or up or down by one record. It also indicates the total number of records currently displayed, and the position of the current record in the display.

Context sensitive menus are available by right-clicking on the column header. Options include sorting and filtering the displayed data.

Changing the RecordGrid Appearance
In the next example, we will change the appearance of the table using formatting options on the RecordGrid.

width='100%' height='740' src='/wiki/samples/generic-example.curl?Data/recordset-2.curl'

There are many options that can be used to specify the formatting. The following is a list of possibilities:

•alternate-row-background

•background

•color

•header-spec

•display-column-headers?

•display-filler-column?

•grid-line-color

•horizontal-grid-line-width

•vertical-grid-line-width

You can also turn off the standard grid features, such as the column headings (at the top of the display) and navigation panel (at the bottom of the display):

Code:
{curl 6.0, 7.0 applet} 

{value 

let items:RecordSet = 

{RecordSet 

{RecordFields 

{RecordField "Item", domain = String}, 

{RecordField "Description", domain = String}, 

{RecordField "Quantity", domain = int} 

}, 

{RecordData Item = "PR1400", Description = "Blue pens", Quantity = 12}, 

{RecordData Item = "LG4597", Description = "Envelopes", Quantity = 100}, 

{RecordData Item = "NP3400", Description = "Notepads", Quantity = 6}, 

{RecordData Item = "PN5601", Description = "Pencils", Quantity = 28} 

} 

let record-display:RecordGrid = 

{RecordGrid 

record-source = items, 

display-navigation-panel? = false, 

display-column-headers? = false, 

height = 2.5cm, 

width = 9.9cm, 

display-filler-column? = true, 

alternate-row-background = "#ccccff", 

grid-line-color = "gray", 

horizontal-grid-line-width = 2px, 

vertical-grid-line-width = 4px 

} 

record-display 

}

Specifying Columns and Display Formats
The default display for a RecordGrid is to sequentially present the defined Record data. In some cases, you may only want to display a portion of the data. In other cases you may want to rearrange the column order or provide special formatting.

You can create columns explicitly with RecordGridColumn, which enables you to set properties that control column appearance and function. Columns can also be created automatically and you only need to add a column yourself it you want to customize the column.

Code:
{curl 6.0, 7.0 applet} 

{value 

let items:RecordSet = 

{RecordSet 

{RecordFields 

{RecordField "Item", domain = String}, 

{RecordField "Description", domain = String}, 

{RecordField "Quantity", domain = int}, 

{RecordField "Price", domain = double} 

}, 

{RecordData Item = "PR1400", Description = "Blue pens", Quantity = 12, Price = 4.75}, 

{RecordData Item = "LG4597", Description = "Envelopes", Quantity = 100, Price = 12.25}, 

{RecordData Item = "NP3400", Description = "Notepads", Quantity = 6, Price = 8.50}, 

{RecordData Item = "PN5601", Description = "Pencils", Quantity = 28, Price = 3.45} 

} 

let record-display:RecordGrid = 

{RecordGrid 

record-source = items, 

display-filler-column? = true, 

alternate-row-background = "#ccccff", 

grid-line-color = "gray", 

horizontal-grid-line-width = 2px, 

vertical-grid-line-width = 4px, 

width = 9.9cm, 

height = 3.5cm, 

automatic-columns? = false, 

{RecordGridColumn "Description"}, 

{RecordGridColumn "Item", font-weight = "bold"}, 

{RecordGridColumn "Price", halign = "right", format-spec = "$%.2f"} 

} 

record-display 

}

We implemented this functionality by setting automatic-columns? = false and then specifying each RecordGridColumn. In the above example, we display three out of four record columns.

Modeling data in a RecordSet provides access to many convenience features and functions. We have already demonstrated the ease of displaying RecordSet data in a grid fomat. RecordSet data can also drive other display types such as bar, pie, line, scatter, and bubble charts

For more information regarding file connections, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Data Management and Display > Data Records and Grids

recordgrid.jpg (Size: 13.15 KB / Downloads: 1643)

Files over HTTP3:Connected Data

Wed, 15 Jun 2011 07:42:00 +0000

Using the Curl API, you can connect directly to a database server or a set of files extracted from a database. You access data through a BasicConnection or a FileConnection. A FileConnection creates a connection to a set of files in comma separated value (CSV) format. A BasicConnection creates a connection to a server-side database management system via a servlet and a simple XML protocol over HTTP. We'll discuss each of these scenarios in this Curl Cue.

Both BasicConnection and FileConnection are subsets of a Connection class that provide access to relational data organized as a collection of databases, each of which contains a collection of tables. Each table, in turn, can be accessed as a Curl RecordSet object.

Using a File Connection
The FileConnection class is easiest for simple applications. You can have a single table or a group of related tables in which specific data can be queried for use within the Curl application. In this scenario, CSV-formatted descriptor files are used to describe the data location and structure. Since this metadata is described in files, is easy to modify and does not need to be embedded in the Curl code.

A FileConnection accesses data structured as a collection of files that play the following roles:

•A database descriptor file

•Table descriptor files

•One or more CSV data files

Database Descriptor File
A database descriptor file describes the databases available on the connection, and the tables in each database. You provide the Url of this file to the constructor when you create the FileConnection. This file is used to locate other descriptor files that describe the databases and tables available through the connection. The database descriptor file contains an initial header line, in which you can put labels that help you remember the meaning of the fields in the following lines. For this example, we created the file connection.csv which contains the following information:

connection.csv

•Database: the name of a database.

•Table: the name of a table in the database.

•Location: the name of the file that contains data stored in this table.

•FieldsLocation: the location and name of the table descriptor file for the table named in the Table field.

•HeaderLines: the number of header lines in the data storage file named in the Location field.

•Encoding: The character encoding for the data storage file.

This file can have multiple records. Each record in the database descriptor file represents a table and specifies the location of the data and the table descriptor files.

Table Descriptor File
The table descriptor file is named in the ''FieldsLocation'' of the database descriptor file and describes the fields of the corresponding table. Here is an example of a table descriptor file:

inventory_fields.csv

•name: the name of a field in the table.

•caption: a caption for the field.

•domain: a string that describes the domain for the field.

•default: the default value for this field.

•modifiable?: specifies whether this field is modifiable.

•nullable?: specifies whether the value of this field can be null.

For example, this table descriptor file specifies the data fields of our example CSV data file. Like the database descriptor file, a table descriptor file begins with a header line that contains labels for the fields in the file.

CSV Data Files
And finally, let's discuss our data. The CSV file stores all the data we will be converting to a RecordSet. Remember that you can access more than one CSV data file, as long as each one is described in the database descriptor file
inventory_fields.csv

Code:
{curl 6.0, 7.0 applet} 

{import * from CURL.DATA-ACCESS.CONNECTED} 

{value 

let con:FileConnection = {FileConnection {url "connection.csv"}} 

let rs:RecordSet = {con.create-record-set "sample", "inventory"} 

{RecordGrid record-source = rs, 

width = 6in, 

height = 2in 

} 

}

It is important to note that FileConnection is defined in the CURL.DATA-ACCESS.CONNECTED package. Therefore, we need to explicitly import this package.

For more information regarding file connections, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Data Management and Display > Managing Data from External Sources > Using RecordSets with Data Files

Using a Basic Connection
The BasicConnection class allows you to directly connect to a database server and create RecordSets that are used in a Curl application. To use the BasicConnection object you need to create a servlet on the server that implements the server side of the BasicConnection protocol.

Once this infrastructure is set up, you create a connected record set in two steps.

1.Create a BasicConnection object,

2.Call the method Connection.create-record-set

The url provided to the BasicConnection constructor identifies the servlet that implements the server side of the protocol.

Code:
{import * from CURL.DATA-ACCESS.BASE} 

{import * from CURL.DATA-ACCESS.CONNECTED} 

{let connection:BasicConnection = 

{BasicConnection {url http://localhost:8080/test-server/TestServlet}} 

}

In this case, TestServlet is the servlet located on the data server. Once the connection is established, the create-record-set method will directly create a RecordSet using data from the server.

Code:
{RecordGrid 

record-source = {connection.create-record-set sample, inventory} 

}

Once the RecordSet is created, the API for accessing the data is the same as with a FileConnection.

Use a ConnectedRecordSet just as you use any other RecordSet. If it is modifiable, and if the database server allows it, committing changes to the ConnectedRecordSet updates the data on the database server.

  databasedescriptor.jpg (Size: 12.53 KB / Downloads: 2583)

  datadescriptor.jpg (Size: 16.28 KB / Downloads: 2431)

  conncsvdata.jpg (Size: 9.81 KB / Downloads: 2565)

Files over HTTP2:Organizing Data using RecordSets

Wed, 15 Jun 2011 07:35:57 +0000

Handling the management of structured data can take on many different forms in the Curl language. Our goal is to obtain content into a form we can easily represent internally for manipulation and display. A primary class for data management is RecordSet, which organizes data in terms of records and fields, and manages events having to do with changes in the data. RecordSets are especially useful for dealing with data derived from one or more databases on a server, or data that is intended to be written to a database. It enables the end user to perform many database-like operations on the data, such as filtering and sorting, directly on the client machine without needing to invoke database functions on the server.

The standard Curl API provides a foundation for representing relationally structured data. RecordSet and related classes provide support for representation, manipulation, display and coordination of such data, thoroughly integrated with Curl graphics. Thus, a RecordSet is the obvious choice for model representation for 'data centric' applications which consume structured datasets from some external (server) provider. Furthermore, because of the breadth of standard functionality, RecordSets should also be considered as the basis for internal structures.

RecordSet Data
A RecordSet holds a collection of Records, each of which contains values for a predefined set of keys (columns). The column structure is specified by field descriptors (using RecordField and RecordFields), which name and characterize the allowable values.

In Curl, there are two ways to easily create a RecordSet:

1.Build the RecordSet programmatically directly in the source code

2.Import data that is structured using comma separated values

Both methods allow you to quickly create data structured in record format. The methods above should be used for small amounts of data, or data that does not change rapidly. You can easily adapt these concepts to your own data, allowing you quickly create a RecordSet structure that can be used as input into grid, charts, and forms.

The Curl API also includes features for creating a RecordSet that is directly connected to a database or remote data file. This is discussed in the http://developers.curl.com/docs/DOC-1109 Curl Cue.

Programmatically Create a RecordSet
As with most Curl objects, a RecordSet can be specified completely declaratively, using the rest arguments of its constructor.

•The RecordFields object is used to define the collection of RecordField objects, each of which describes the data format and type of one column in the RecordSet.

•The RecordData object is used to organize value tuples which produce successive member Records.

Code:
{curl 6.0, 7.0 applet} 

{value 

let items:RecordSet = 

{RecordSet 

{RecordFields 

{RecordField "Item", domain = String}, 

{RecordField "Description", domain = String}, 

{RecordField "Quantity", domain = int} 

}, 

{RecordData Item = "PR1400", Description = "Blue pens", Quantity = 12}, 

{RecordData Item = "LG4597", Description = "Envelopes", Quantity = 100}, 

{RecordData Item = "NP3400", Description = "Notepads", Quantity = 6}, 

{RecordData Item = "PN5601", Description = "Pencils", Quantity = 28} 

} 

let record-display:RecordGrid = 

{RecordGrid 

record-source = items 

} 

record-display 

}

In the example above, we are specifying the item name and type using a RecordField. For example, the first RecordField is defined as {RecordField "Item", domain = String} . This specifies the name of the field to be "Item" and the type of the data in the field to be a String. Each record is specified by a RecordData expression where the value of each field is specified as a keyword argument using the name of the field as the keyword. A RecordGrid is used to automatically provide a tabular display of the RecordSet data.

Standard Domains are defined for the following basic Curl types: char, String, int, int64, float, double, bool, DateTime, Time, or any

For more information regarding RecordSets, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Data Management and Display > Data Records and Grids

Code:
Creating a CsvRecordSet

CSV stands for Comma Separated Values, sometimes also called Comma Delimited. A CSV file is a specially formatted plain text file which stores spreadsheet or basic database-style information in a very simple format, with one record on each line, and each field within that record separated by a comma.

CSV files are often used as a simple way to transfer a large volume of spreadsheet or database information between programs, without worrying about special file types. For example, transferring a home-made address book from Microsoft® Excel into a database program such as Filemaker® Pro could be done by exporting the file as a CSV from Excel, then importing that CSV into Filemaker.

Curl also has APIs for working directly with data files in CSV format. CsvRecordSet is a subclass of RecordSet and it allows you to automatically create one or more Records in a RecordSet.

Let's begin our example with a CSV file. This example uses a data file created using Microsoft ® Excel and saved in CSV format. Each line in the file is a record. Each field in the file is separated from its neighbor by a comma.

We'll use a CsvRecordSet to import the contents of our file into Curl. CsvRecordSet does the following:

•Creates a Record from each line of the CSV data

•Parses each field of the data

•Converts each field into a Curl datatype

Code:
{curl 6.0, 7.0 applet} 

{value 

let rs:CsvRecordSet = 

{CsvRecordSet 

{url "inventory_items.csv"} 

} 

{RecordGrid record-source = rs, 

width = 6in, 

height = 2in 

} 

}

The above example shows how you can quickly bring your data into Curl. CsvRecordSet automatically attempts to map the CSV content into an equivalent datatype using DomainDetector. This automatically detects the type of data in each column of a CSV file.

Alternatively, we can provide a RecordFields object that defines the expected structure and domain of the data. In this case, CsvRecordSet attempts to parse each field of the data file in terms of the Domain specified in the corresponding RecordField.

Code:
{curl 6.0, 7.0 applet} 

{value 

let rs:CsvRecordSet = 

{CsvRecordSet 

{url "inventory_items.csv"}, 

fields = 

{RecordFields 

{RecordField "Item", 

domain = String, 

index-type = RecordFieldIndexType.unique 

}, 

{RecordField "Description", 

domain = String 

}, 

{RecordField "Quantity", 

domain = int 

}, 

{RecordField "Price", 

domain = double 

} 

} 

} 

{RecordGrid record-source = rs, 

width = 6in, 

height = 2in 

} 

}

In this case, CsvRecordSet parses each field of the data file in terms of the Domain specified in the corresponding RecordField. In our example, we are specifying the following data types:

•Item --> String

•Description --> String

•Quantity --> int

•Price --> double

Also note that the column headings for each Record are specified by the RecordFields object. A caption can also be set for each column, allowing you to keep the internal name and specify a different name for display.

If the string data in the file cannot be converted to an object of the appropriate type, the code throws an error.

In summary, a RecordSet enables you to write applications that manage data organized in records and fields.

•Manage events corresponding to data changes

•Perform many database-like operations on the local data, such as filtering and sorting

Two easy ways to create Record data in Curl are to programmatically create a RecordSet or use CsvRecordSet to import CSV data.

For more information regarding CsvRecordSets, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Data Management and Display > Managing Data from External Sources > Using CSV Data Files

Organizing Data using RecordSets1.JPG (Size: 22.02 KB / Downloads: 1834)

csvdata.jpg (Size: 9.81 KB / Downloads: 1874)

Files over HTTP1:Files over HTTP

Wed, 15 Jun 2011 07:30:36 +0000

File Access
It is common for programs to read text from and write text to local or remote data files. An applet may need to read data from a Web page, or write data to the local machine for use the next time the program is run.

Reading from and writing to resources are generally accomplished the same way. A resource is identified, a stream is opened to it, the data is transferred, and the resource is closed. The resource is typically identified using a Url object. This Curl Cue will demonstrate how to read file resources. The examples will use text files obtained via HTTP, but it is worth noting that file access is the same whether the file is local or obtained over HTTP.

An input stream object provides the methods necessary to transfer the data. There are general classes and methods that provide the essential means for reading and writing data, but there are also high-level, convenience procedures that simplify many tasks.

The easiest way to read data from a resource is to treat the resource as a text file. Many resources, such as configuration files and Web pages, are commonly handled this way. In all textual cases, you will have to:

1.Identify the Url

2.Create a TextInputStream to read the data

3.Read and store the data

4.Close the TextInputStream

Reading File Contents
So, how do you read the contents of a file? For our example, we will access the business.txt file that has the following content:

Local Businesses

Bakery

Convenience Store

Coffee Shop

Print Shop

Chiropractor

Fitness Center

Acupuncture

Photo Shop

Optician

Shoe Store

The easiest way to read the entire contents of a file is to use the read-from procedure. This procedure is actually a utility procedure that combines several operations:

1.It automatically opens the given url as a TextInputStream

2.It reads all the characters out of it into a StringBuf

3.It returns the StringBuf.

Code:
{curl 6.0, 7.0 applet}

{pre {read-from {url "business.txt"}}}

The pre text format displays the paragraph contents in a monospace font, preserving whitespace and newlines.

Once the file is read, the program can manipulate the StringBuf, or in the case above, we just displayed the content using pre. You may need to convert the content to a String for further processing, for example: {{read-from {url "business.txt"}}.to-String}.

Reading Line by Line
One of the most common ways to read text from a file is line by line. Most text files will have multiple lines to read, so this approach makes sense, especially if a line needs to be processed by the applet before the next line is read.

The next example demonstrates a simple way to read a text file line by line.

Code:
{curl 6.0, 7.0 applet}

{value

   || Create a StringBuf to hold the data

   let lines:StringArray = {StringArray}

   || Identify the url

   let location:Url = {url "business.txt"}

   {with-open-streams in = {read-open location} do

       {until in.end-of-stream? do

           {lines.append {{in.read-one-line}.to-String}}

       }

   }

   || Display the stored information

   let display:VBox =   

       {VBox

           background = "beige",

           border-style = "sunken",

           border-width = 2pt,

           border-color = "navy",

           margin = 4pt

       }

   {for line key k in lines do

       {if k==0 then

           {display.add {bold {underline {value line}}}}

        else

           {display.add line}

       }

   }

   display

}

We use with-open-streams to read each line of a given file and store it in a StringArray. Notice that we detect the end of the file using the end-of-stream? accessor.

Code:
{with-open-streams in = {read-open location} do

       {until in.end-of-stream? do

           {lines.append {{in.read-one-line}.to-String{font}

       }

  }

For the display VBox content, we looped through the lines StringArray. The loop is organized so that the first line will be displayed underlined and bolded.

Code:
{for line key k in lines do

       {if k==0 then

           {display.add {bold {underline{value line{font}{font}

        else

           {display.add line}

       }

  }

In this Curl Cue, we identified two main ways to read file content. The Curl language has many stream classes that can be used based on your application needs. These include:

•Text and binary streams

•Buffered and unbuffered streams

•Seekable and nonseekable streams

For more information regarding reading file content, please refer to the following section in the Curl Documentation:Curl Developer's Guide > File Systems and Networking > Accessing Files and Other Resources

User Interface Basics7:Stretching Graphical Objects

Wed, 15 Jun 2011 07:12:52 +0000

Wouldn't it be easy if everyone had the same size monitor and same resolution? Fortunately, Curl makes it easy to build applications that stretch and compress. It is common to have fixed graphical elements in your applet, as well as elements that stretch and compress with the browser window.

When Curl displays a page, it negotiates the layout of each element to determine the final size of each graphic. For graphics that do not have a height or width specified, Curl will look to the dimensions of the child objects.

Common Applet Scenario
It is common in Web design to have the following scenario:

•One area of the page set as the navigation portion. This layout object will have a static width.

•Another area of the page able to expand and compress in order to display the selected content

In Curl Cues up until now, we have always specified a fixed width or height, e.g. height = 1in. Extra stretchiness can be added to specific objects in your graphical hierarchy using the add-stretch procedure. This example demonstrates how a child object can specify its stretchiness using {add-stretch} for the value of either the width or height option of the object. Select the Show View button to view the example. Try resizing the window that pops up, to compare how the stretchy and non-stretchy objects behave.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{value 

let stretch-box:HBox = {HBox 

height = {add-stretch}, 

{VBox 

background="teal", 

width=1in, 

{bold This is a fixed-width column of text}, 

{Fill} 

}, 

{VBox background="silver", 

width = {add-stretch}, 

{bold This is the stretchable content area. Using the mouse, resize the window making it larger and smaller}, 

{Fill} 

} 

} 

{CommandButton 

label = "Show View", 

{on Action do 

let v:View = {View stretch-box} 

{v.show} 

} 

} 

}

So what is actually happening? When the View is initially displayed:

•The left VBox initializes with a width of 1in

•The right VBox initializes using the preferred width of the text that it contains. The preferred width is automatically calculated by the TextFlowBox that is implicitly created to hold the text in the VBox. When sized according to this preferred width, the TextFlowBox will be able to display its contained text on one line.

Notice that when you expand and compress the View, the left VBox maintains a constant width of 1in. Curl will adjust the width accordingly as long as the minimum size of each object can be obtained. The minimum sizes in our example are:

•1in for the left VBox

•The longest word contained within the TextFlowBox for the right VBox. In our example, this word (amusingly!) is the word "stretchable".

Now, if you resize the window so its width is smaller than the sum of the minimum sizes, both VBoxes will compress proportionately. This is demonstrated in the picture below.

Of course, there are many scenarios that we can think of for stretching and compressing Curl graphics. For common cases, it is easiest to add elasticity using add-stretch. Alternatively, there are other ways to control stretchiness in Curl. Some containers have vstretch? and/or hstretch? options, and comprehensive control over the stretchiness, compressibility, and size properties of objects is available through the make-elastic procedure. (These features are beyond the scope of this Curl Cue.)

For more information regarding elastics, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > Elastics and Page Layout

Filling Space
You can use the Fill object to provide a form of stretchy spacing in your applications. A Fill object provides padding to fill empty spaces in graphical displays. These objects are intended to stretch easily to fill excess space, avoiding the stretching of other objects next to which the Fill may be placed. In other words, a Fill object creates highly stretchy Graphic that is typically used for setting the spacing between less stretchy objects.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{HBox 

width = 5in, 

{Frame 

width = 1in, 

height = 1in, 

background = "green", 

{bold Green} 

}, 

{Fill}, 

{Frame 

width = 1in, 

height = 1in, 

background = "blue", 

{bold Blue} 

}, 

{Fill}, 

{Frame 

width = 1in, 

height = 1in, 

background = "red", 

{bold Red} 

} 

}

Each Fill object in a container represents one unit of fill space. That is, if object A and object B are separated by one Fill, and object B and object C are separated by two Fills, then the space between B and C is twice as large as the space between A and B.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{HBox 

width = 5in, 

{Frame 

width = 1in, 

height = 1in, 

background = "green", 

{bold Green {br} (Object A)} 

}, 

{Fill}, 

{Frame 

width = 1in, 

height = 1in, 

background = "blue", 

{bold Blue {br} (Object B)} 

}, 

{Fill}, 

{Fill}, 

{Frame 

width = 1in, 

height = 1in, 

background = "red", 

{bold Red {br} (Object C)} 

} 

}

For more information regarding Fills, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > Graphical Shapes> Rule and Fill > Fill

Stretching Graphical Objects1.JPG (Size: 21.5 KB / Downloads: 1790)

Stretching Graphical Objects2.JPG (Size: 7.18 KB / Downloads: 1736)

User Interface Basics6:Object Layout

Wed, 15 Jun 2011 07:08:46 +0000

Because the Curl language relies on nested graphical containers to place objects, it is helpful to understand the relationship between objects and their containers as well as the relationship between sibling objects within the same container.

Graphical objects can be sized, aligned, and formatted according to their object property types. Each type of graphical container will have specific defaults used for alignment.

You may think of aligning graphical objects from two perspectives:

•Alignment is specified by the parent container. All child objects are aligned in the same manner.

•Alignment is individually specified by each child object. This allows each child object to individually specify its alignment. In this case, the parent container can override the child specifications.

Alignment Defaults
Before we get into alignment details, let's back up and discuss the default behavior. Each graphical container will align its children using its own particular default behavior. The default alignment behaviors of HBox and VBox, two of the most common containers, are as follows:

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{HBox 

height = 2in, 

spacing = 2pt, 

border-style="raised", 

border-width = 2pt, 

border-color = "teal", 

{Fill 

width = .5in, 

height = .5in, 

background = "maroon" 

}, 

{Frame 

width = .5in, 

height = .5in, 

background = "green" 

}, 

{EllipseGraphic 

width = .5in, 

height = .5in, 

fill-color = "blue" 

}, 

{TextFlowBox 

border-style="raised", 

border-width = 2pt, 

margin=3pt, 

border-color = "red", 

{text Align Me} 

}, 

{CommandButton 

label = "Press Me" 

}, 

{DropdownList 

"Red", "Yellow", "Blue", 

value="Yellow" 

}, 

{image source = {url "image.jpg"}} 

}

Specifying Alignment on Child Objects
Many containers, such as HBox, use the outside origins of child objects to align the child objects relative to one another. The outside origin is a certain defined point on each graphical object that is available for use by its graphical parent for aligning graphics within the parent.

You can change an object's outside origin location by setting its vorigin or horigin option to one of the following string values:

•Possible values for vorigin are: "top", "center", "bottom"

•Possible values for horigin are: "left", "center", "right"

You can also specify an object's origin using a numerical value between 0 and 1. The following example shows several possible locations of an object's origin, at the corners and midpoints of the object's bounding box.

Move your pointer over the shaded area for numerical values you could use to specify outside origin locations. (You may need to click on the shaded area first, to activate this behavior.)
Tip: Notice that the numerical origin values in the top-left corner are 0,0 and the bottom-right corner are 1,1.

In the next example, we set the vertical origin to a value of "center" for each child object. Note that vorigin = 0.5 is equivalent to vorigin = "center".

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{HBox 

height = 2in, 

spacing = 2pt, 

border-style="raised", 

border-width = 2pt, 

border-color = "teal", 

{Fill 

width = .5in, 

height = .5in, 

background = "maroon", 

vorigin = "center" 

}, 

{Frame 

width = .5in, 

height = .5in, 

background = "green", 

vorigin = "center" 

}, 

{EllipseGraphic 

width = .5in, 

height = .5in, 

fill-color = "blue", 

vorigin = "center" 

}, 

{TextFlowBox 

border-style="raised", 

border-width = 2pt, 

margin=3pt, 

border-color = "red", 

vorigin = "center", 

{text Align Me} 

}, 

{CommandButton 

label = "Press Me", 

vorigin = "center" 

}, 

{DropdownList 

"Red", "Yellow", "Blue", 

value="Yellow", 

vorigin = "center" 

}, 

{image source = {url "image.jpg"}, 

vorigin = "center" 

} 

}

Aligning Objects Specified by the Parent
Instead of specifying the alignment using each child object, we can often change the parent container's alignment behavior. Many containers have valign or halign options that change their alignment behavior. If these options are set to values other than "origin", they will also override any outside origins specified by a child object.

•Possible values for valign are: "top", "center", "bottom", "origin" (default)

•Possible values for halign are: "left", "center", right", "origin" (default)

In the next example, we add valign = "center" to the parent container. This aligns all children at the center of the HBox.

Code:
{curl 6.0, 7.0 applet} 

{curl-file-attributes character-encoding = "utf8"} 

{HBox 

valign = "center", 

height = 2in, 

spacing = 2pt, 

border-style="raised", 

border-width = 2pt, 

border-color = "teal", 

{Fill 

width = .5in, 

height = .5in, 

background = "maroon" 

}, 

{Frame 

width = .5in, 

height = .5in, 

background = "green" 

}, 

{EllipseGraphic 

width = .5in, 

height = .5in, 

fill-color = "blue" 

}, 

{TextFlowBox 

border-style="raised", 

border-width = 2pt, 

margin=3pt, 

border-color = "red", 

{text Align Me} 

}, 

{CommandButton 

label = "Press Me" 

}, 

{DropdownList 

"Red", "Yellow", "Blue", 

value="Yellow" 

}, 

{image source = {url "image.jpg"}} 

}

In conclusion, you may think of aligning graphical objects from two perspectives.

•By placing the responsibility on the children. Each parent container has its own way of displaying its children, often using the children's outside origins. You can change the children's outside origins to accommodate the parent's display algorithm.

•By placing the responsibility on the parent. Most container objects use the halign and/or valign options to provide an additional way to control alignment.

For more information regarding object alignment, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > Elastics and Page Layout > Aligning Graphical Objects

Object Layout1.JPG (Size: 41.72 KB / Downloads: 1640)