Smart Client Quick Start Guide

SmartClient_Quick_Start_Guide

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 122

Download
Open PDF In Browser	View PDF

SmartClient™ Quick Start Guide
SmartClient v11.1

Isomorphic Software

SmartClient™ Quick Start Guide
Copyright ©2017 and beyond Isomorphic Software, Inc. All rights reserved. The
information and technical data contained herein are licensed only pursuant to a license
agreement that contains use, duplication, disclosure and other restrictions; accordingly, it
is “Unpublished-rights reserved under the copyright laws of the United States” for
purposes of the FARs.
Isomorphic Software, Inc.
1 Sansome Street, Suite 3500
San Francisco, CA 94104
U.S.A.
Web:
Email:

www.isomorphic.com
info@isomorphic.com

Notice of Proprietary Rights
The software and documentation are copyrighted by and proprietary to Isomorphic
Software, Inc. (“Isomorphic”). Isomorphic retains title and ownership of all copies of the
software and documentation. Except as expressly licensed by Isomorphic in writing, you
may not use, copy, disseminate, distribute, modify, reverse engineer, unobfuscate, sell,
lease, sublicense, rent, give, lend, or in any way transfer, by any means or in any medium,
the software or this documentation.
1. These documents may be used for informational purposes only.
2. Any copy of this document or portion thereof must include the copyright notice.
3. Commercial reproduction of any kind is prohibited without the express written
consent of Isomorphic.
4. No part of this publication may be stored in a database or retrieval system
without prior written consent of Isomorphic.
Trademarks and Service Marks
Isomorphic Software, SmartClient, and all Isomorphic-based trademarks and logos that
appear herein are trademarks or registered trademarks of Isomorphic Software, Inc. All
other product or company names that appear herein may be claimed as trademarks or
registered trademarks of their respective owners.
Disclaimer of Warranties
THE INFORMATION CONTAINED HEREIN IS PROVIDED “AS IS” AND ALL EXPRESS
OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING
ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT AND ONLY TO
THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

iii

Isomorphic Software

SmartClient Quick Start

Contents
Contents ..................................................................................iv
How to use this guide ............................................................. vii
Why SmartClient? ................................................................. viii
More than Just Widgets —A Complete Architecture .................. viii
Eliminates Cross-Browser Testing and Debugging..................... viii
Complete Solution ......................................................................... ix
Open, Flexible Architecture .......................................................... ix
1. Overview............................................................................ 11
Architecture ................................................................................... 11
Capabilities and Editions of SmartClient ...................................... 12
Standard Capabilities .................................................................... 13
Optional Modules .......................................................................... 14
SDK Components .......................................................................... 15
2. Installation ........................................................................ 16
Requirements ................................................................................ 16
Steps .............................................................................................. 16
Server Configuration (optional) .................................................... 19
3. Resources ......................................................................... 20
Showcase ...................................................................................... 20
Demo Application .......................................................................... 21
Developer Console ........................................................................ 22
Reference ...................................................................................... 27
Community Wiki .......................................................................... 28
4. Coding .............................................................................. 29
Languages ..................................................................................... 29
Headers ........................................................................................ 30
Components .................................................................................. 31
Hello World .................................................................................. 32
Deploying ..................................................................................... 33
5. Visual Components ........................................................... 34
Component Documentation & Examples ..................................... 34
Identifying Components ............................................................... 35
Manual Layout.............................................................................. 35
Drawing, Hiding, and Showing Components ............................... 37
Handling Events ........................................................................... 37
6. Data Binding ..................................................................... 39
Databound Components .............................................................. 39
Fields ............................................................................................ 40
iv

Isomorphic Software

SmartClient Quick Start

Form Controls .............................................................................. 42
DataSources .................................................................................. 44
DataSource Operations ................................................................ 48
DataBound Component Operations ............................................. 49
Data Binding Summary ................................................................ 50
7. Layout ............................................................................... 52
Component Layout ....................................................................... 52
Container Components ................................................................ 54
Form Layout ................................................................................. 55
8. Data Integration ................................................................ 57
DataSource Requests.....................................................................57
SmartClient Server Framework.................................................... 58
DSRequests and DSResponses ..................................................... 59
Request and Response Transformation ....................................... 59
Criteria, Paging, Sorting and Caching ........................................... 61
Authentication and Authorization ............................................... 62
Relogin.......................................................................................... 63
Binding to XML and JSON Services ............................................ 64
WSDL Integration ........................................................................ 65
9. SmartClient Server Framework ........................................ 68
DataSource Generation ................................................................ 68
Server Request Flow ...................................................................... 71
Direct Method Invocation ............................................................ 73
DMI Parameters ........................................................................... 74
Adding DMI Business Logic ......................................................... 74
Returning Data .............................................................................. 77
Queuing & Transactions ............................................................... 78
Queuing, RESTHandler, and SOAs .............................................. 80
Operation Bindings ...................................................................... 80
Declarative Security...................................................................... 82
Declarative Security Setup ........................................................... 84
Non-Crud Operations ................................................................... 85
Dynamic Expressions (Velocity) .................................................. 87
Server Scripting ............................................................................ 89
Including Values from Other DataSources ................................... 91
SQL Templating............................................................................ 93
SQL Templating — Adding Fields ................................................ 96
Why focus on .ds.xml files? ...................................................... 98
Custom DataSources .................................................................... 99
Generic RPC operations (advanced) ........................................... 101
10. Extending SmartClient .................................................... 103
Client-side architecture ...............................................................103
Customized Themes ................................................................... 104
Customized Components ........................................................... 106
New Components ........................................................................ 107
New Form Controls .................................................................... 109
11. Tips................................................................................... 111
Beginner Tips ............................................................................... 111
v

Isomorphic Software

SmartClient Quick Start

HTML and CSS Tips ..................................................................... 111
Architecture Tips ......................................................................... 112
12. Evaluating SmartClient .................................................... 116
Which Edition to Evaluate .......................................................... 116
Evaluating Performance .............................................................. 117
Evaluating Interactive Performance ........................................... 119
Evaluating Editions and Pricing................................................. 120
A note on supporting Open Source ............................................. 121
Contacts ................................................................................ 122

Isomorphic Software

SmartClient Quick Start

How to use this guide
The SmartClient Quick Start Guide is designed to introduce you to the
SmartClient™ web presentation layer. Our goals are:
To have you working with SmartClient components and
services in a matter of minutes.
To provide a conceptual framework, with pointers to more
detail, so you can explore SmartClient in your areas of
interest.
This guide is structured as a series of brief chapters, each presenting a set
of concepts and hands-on information that you will need to build
SmartClient-enabled web applications. These chapters are intended to be
read in sequence—earlier chapters provide the foundation concepts and
configuration for later chapters.
This is an interactive manual. You will receive the most benefit from this
guide if you are working in parallel with the SmartClient SDK—following
the documented steps, creating and modifying the code examples, and
finding your own paths to explore. You may want to print this manual for
easier reference, especially if you are working on a single-display system.
We assume that you are somewhat acquainted with basic concepts of web
applications (browsers, pages, markup, scripting), object-oriented
programming (classes, instances, inheritance), and user interface
development (components, layout, events). However, you do not need
deep expertise in any specific technology, language, or system. If you
know how to navigate a file system, create and edit text files, and open
URLs in a web browser, you can start building rich web applications with
SmartClient today.
If you can’t wait to get started, you can skip directly to
Installation (Chapter 2) to start a SmartClient development server
and begin Resources (Chapter 3) and Coding (Chapter 4). But if you
can spare a few minutes, we recommend reading the introductory
chapters first, for the bigger picture of SmartClient goals and
architecture.
Thank you for choosing SmartClient, and welcome.

vii

Isomorphic Software

SmartClient Quick Start

Why SmartClient?
Smart Client helps you to build and maintain more usable, portable,
efficient web applications faster, propelled by an open, extensible stack of
industry-tested components and services.
In this chapter we explore the unique traits of the SmartClient platform
that set it apart from other technologies with similar purpose.

More than Just Widgets —A Complete Architecture
SmartClient provides an end-to-end application architecture, from
UI components to server-side transaction handling.
The examples included with SmartClient demonstrate the simplicity that
can only be achieved by a framework that addresses both server- and
client-side architectural concerns to deliver globally optimal solutions.
SmartClient’s UI components are carefully designed to maximize
responsiveness and minimize server load, and SmartClient’s server
components are designed around the requirements of high-productivity
user interfaces.
Even if you adopt only part of the SmartClient solution, you benefit from
an architecture that takes into account the entire problem you need to
solve, not just a part of it. Every integration point in the SmartClient
platform has been designed with a clear understanding of the
requirements you need to fulfill, and, the solutions built into SmartClient
provide a “blueprint” for one way of meeting those requirements.

Eliminates Cross-Browser Testing and Debugging
SmartClient provides a clean, clear, object-oriented approach to UI
development that shields you from browser bugs and quirks.
Even if you need to create a totally unique look and feel, SmartClient’s
simplified skinning and branding requires only basic knowledge of page
styling, and you never have to deal with browser layout inconsistencies.

viii

Isomorphic Software

SmartClient Quick Start

In contrast, lower-level frameworks that provide a thin wrapper over
browser APIs can’t protect you from the worst and most destructive of
browser issues, such as timing-dependent bugs and memory leaks.
SmartClient’s powerful, component-oriented APIs give SmartClient the
flexibility to use whatever approach works best in each browser, so you
don’t have to worry about it.
This allows SmartClient to make a simple guarantee: if there is a crossbrowser issue, it's our problem, not yours.

Complete Solution
SmartClient offers a complete presentation layer for enterprise
applications: everything you need for the creation of full-featured, robust,
high-productivity business applications.
The alternative—throwing together partial solutions from multiple
sources—creates a mish-mash of different programming paradigms,
inconsistent look and feel, and bizarre interoperability issues that no
single vendor can solve for you.
Whether you are a software vendor or enterprise IT organization, it never
makes sense to build and maintain a UI framework of your own, much
less to own “glue code” tying several frameworks together. A single,
comprehensive presentation framework gives you a competitive
advantage by enabling you to focus on your area of expertise.

Open, Flexible Architecture
Because SmartClient is built entirely with standard web technologies, it
integrates perfectly with your existing web content, applications, portals,
and portlets. You can build a state-of-the-art application from scratch, or
you can upgrade existing web applications and portals at your own pace,
by weaving selected SmartClient components and services into your
HTML pages.
By giving you both options, SmartClient allows you to address a broader
range of projects with a single set of skills. You can even reuse existing
content and portlets by embedding them in SmartClient user interface
components. SmartClient allows a smooth evolution of your existing web
applications—you aren’t forced to start over.
Next, SmartClient is fully open to integration with other technologies. On
the client, you can seamlessly integrate Java applets, Flash/Flex modules,
ActiveX controls and other client technologies for 3D visualization,
desktop integration, and other specialized functionality. On the server,

Isomorphic Software

SmartClient Quick Start

SmartClient provides flexible, generic interfaces to integrate with any data
or service tier that you can access through Java code.
Finally, SmartClient is completely extensible, all the way down to the
web standards on which the system is constructed. If you can’t do
something “out of the box,” you can build or buy components that
seamlessly extend SmartClient in any manner you desire.
We welcome your comments and requests, however large or small, to
feedback@smartclient.com.

Isomorphic Software

1. Overview
Architecture
The SmartClient architecture spans client and server, enabling Rich
Internet Applications (RIAs) that communicate transparently with your
data and service tiers.
Client
GUI Rendering & Interactivity
Local
Operations

Server

DataSource
schema

DataSource Binding

Communication Layer
Web Browser

Data Providers

Metadata and Operations
HTTP(S)
XMLHttp

Communication Layer

Application Server

Within the web browser, SmartClient provides a deep stack of services
and components for rich HTML5 / Ajax applications. For those using a
Java-based server, SmartClient provides a server-side framework that can
be added to any existing Java web application.
The client- and server-based components have a shared concept of
DataSources, which describe the business objects in your application. By
working from a single, shared definition of the data model, client- and
server-side components can coordinate closely to deliver much more
sophisticated functionality “out of the box” than either a standalone
client-based or server-based solution can deliver.
For example, validation rules are declared within the DataSource—these
rules are then enforced client-side by SmartClient Ajax components, and
server-side by SmartClient server components. Similarly, the set of valid
operations on an object is declared in a DataSource, and this single
declaration controls client-side behaviors like whether an editing interface
is enabled, and controls security checks on the server for safe enforcement
of business rules.

SmartClient Quick Start

Using a DataSource as a shared data definition also greatly reduces
redundancy between your user interface code and server-side code,
increasing agility and reducing maintenance effort.
DataSources can be derived on-the-fly or as a batch process from other,
pre-existing sources of metadata, such as annotated Java Beans and XML
Schema, further reducing system-wide redundancy.
This concept of a DataSource as a shared client-side data definition can be
used with or without the optional SmartClient Java server components.
However, if you do not use the SmartClient server components, all serverside functionality of DataSources must be implemented and maintained
by your team.
Finally, note that SmartClient does not require that you adopt this entire
architecture. You may choose to integrate with only the layers and
components that are appropriate for your existing systems and
applications.

Capabilities and Editions of SmartClient
SmartClient comes in several editions, and the features included in each
of the editions are described on the SmartClient.com website at
http://www.SmartClient.com/product
The portions of this document that make use of SmartClient server
components require the Pro license or above. Certain features
demonstrated or referred to in the document require Power or Enterprise
Editions of SmartClient - this is mentioned in each case.
If you have downloaded the LGPL version, we recommend downloading
the commercial trial version for use during evaluation. Applications built
on the commercial edition can be converted to the LGPL version without
wasted effort, but the reverse is not true—using the LGPL version for
evaluation requires you to expend effort implementing functionality that
is already part of the commercial version. For more details, see Chapter
12, Evaluating SmartClient.

Isomorphic Software

SmartClient Quick Start

Standard Capabilities
The standard capabilities of the SmartClient web presentation layer
include:
Area

Description

Foundation
Services

SmartClient class system, data types, JavaScript
extensions, and browser utilities.

Foundation
Components

Building-block visual components, including
Canvas, Img, StretchImg, and StatefulCanvas.

Event
Handling

SmartClient event handling systems, including
mouse, keyboard, focus, drag & drop,
enable/disable, and selection capabilities.

Controls

Basic visual controls, including Button, Toolbar,
Menu, and Menubar.

Forms

Form layout managers, value managers, and
controls (including TextItem, DateItem,
CheckboxItem, SelectItem, etc.).

Grids

GridRenderer, ListGrid and related subclasses,

providing grid rendering, selection, sorting,
editing, column handling, and cell events.

Trees

Tree data structures,

Layout

Component layout managers and layoutmanaged containers, including HLayout,
VLayout, Window, and TabSet.

Data
Binding

Data model, cache management, and
communication components including
DataSource, ResultSet, and RPCManager.

Themes/
Skins

Pervasive support and centralized control over
theme/skin styles, images, and defaults, for
personalization or branding.

and TreeGrid UI
components, for managing hierarchical data.

Isomorphic Software

SmartClient Quick Start

Optional Modules
Isomorphic also develops and markets the following optional modules to
extend the standard SmartClient system. For more information on these
modules, see SmartClient Reference → Optional Modules.
Option

Description

SmartClient
Server

Provides direct Java APIs for databinding and
low level client-server communications, deep
integration with popular Java technologies such
as Spring, Hibernate, Struts, and others.
Extensive server-side validators that match the
client-side versions and work automatically. For
more information, please see the “SmartClient
Server Feature Summary” in the Concepts
section of the SmartClient Reference.

Analytics

Multi-dimensional data binding and interactive
CubeGrid components (cross-tabs, dynamic data
loading, drag-and-drop pivoting).

Real-Time
Messaging

Real-time, server push messaging over HTTP,
with Java Message Server (JMS) backed publish
and subscribe services.

Network
File packaging, caching, and compression
Performance services for optimal performance of distributed
applications.

Isomorphic Software

SmartClient Quick Start

SDK Components
The SmartClient Software Developer Kit (SDK) includes extensive
documentation and examples to accelerate you along the learning curve.
These resources are linked from the SDK Explorer, and are available in
the docs/ and examples/ directories of your SDK distribution.
The SmartClient SDK also provides the following supplementary,
develop-time components for rapid development:
Development
Component

Component Description

Developer Console

Provides client-side application
debugging, inspection, and profiling.

Admin Console

Provides a browser-based UI for server
configuration and datasource
management. Note: Requires
SmartClient Server.

Embedded server
(Tomcat)

Enables a lightweight, stand-alone
development environment.

Embedded database
(HSQLDB)

Provides a basic persistence layer for
rapid development. Note: Requires
SmartClient Server.

Object-relational
connector
(JDBC/ODBC)

Enables rapid development of your
presentation layer against a relational
database, prior to (or in parallel with)
development of your server-side
business logic bindings. Note: Requires
SmartClient Server.

The SmartClient SDK provides direct database support for lightweight
application development purposes only. Production SmartClient
applications are typically bound to application-specific data objects (EJBs,
POJOs), web services, email and IM servers, and structured data feeds.
Chapter 8 (Data Integration) outlines the integration layers and
interfaces for your production data and services.

Isomorphic Software

SmartClient Quick Start

2. Installation
Requirements
To get started quickly, we will use the embedded application server
(Apache Tomcat 5.0) and database engine (HSQL DB 1.7) that are
included in the SmartClient SDK distribution.
Your only system requirements in this case are:
Java SDK (JDK) v1.4+ (you can download JDK 1.5/5.0
from http://java.sun.com/j2se/1.5.0/download.jsp)
a web browser to view SmartClient examples and
applications (see docs/readme.html in the SDK for a
complete list of supported browsers and versions)
a text editor to create and edit SmartClient code and
examples
If you wish to install SmartClient in a different application server and/or
run the SDK examples against a different database, please see
docs/installation.html in the SDK. For purposes of this Quick Start, we
strongly recommend using the embedded server and database. You can
always redeploy and configure your SmartClient SDK in another
application server later.

Steps
To install and start your SmartClient development environment:
1. Download and install JDK 1.4+ if necessary (Mac OS X users
note: a JDK is pre-installed on your system)
2. Start the embedded server by running
start_embedded_server.bat (Windows), .command (Mac OS X),
or .sh (*nix)

Isomorphic Software

SmartClient Quick Start

3. Open the open_ISC_SDK_from_server shortcut
(Windows/MacOS) or open a web browser and browse to
http://localhost:8080/index.html (all systems)
Depending on your system configuration, you may need to perform
one or more additional steps:
If you already have a JDK or JRE installed on your system,
you may need to set a JAVA_HOME environment variable
pointing to the home directory of JDK 1.4+, so the server
will use the correct version of Java.
If port 8080 is already in use on your system, you may
specify a different port for the embedded server by
appending
--port newPortNum (e.g. --port 8081) to the
start_embedded_server.bat, .command, or .sh command. If
you do change the default port, you must browse directly to
http://localhost:newPortNum/index.html. to open the SDK
Explorer
If your web browser is configured to use a proxy server,
you may need to bypass that proxy for local addresses. In
Internet Explorer, go to Tools → Internet Options… →
Connections → LAN Settings..., and check “Bypass proxy
server for local addresses”. In Firefox, go to Tools →
Options… → General → Connection Settings… and enter
“localhost” in the “No Proxy for” field.

Isomorphic Software

SmartClient Quick Start

When you have successfully started the server and opened
http://localhost:8080/index.html in your web browser, you
should see the SmartClient SDK Explorer:

Instructions for adding SmartClient to any existing Java web project in
any IDE are in the SmartClient Reference - Concepts > Deploying
SmartClient.

Isomorphic Software

SmartClient Quick Start

Server Configuration (optional)
You do not need to perform any server configuration for this Quick Start.
However, for your information:
The SmartClient Admin Console (linked from the SDK
Explorer) provides a graphical interface to configure direct
database connections, create database tables from
DataSource descriptors, and import test data. Note:
Requires SmartClient Server.
Other server settings are exposed for direct configuration in:
WEB-INF/classes/server.properties
WEB-INF/web.xml

If you have any problems installing or starting SmartClient, try the
SmartClient Developer Forums at forums.smartclient.com.

Isomorphic Software

SmartClient Quick Start

3. Resources
Showcase
From the SmartClient SDK Explorer, pick Showcase. When the
Showcase has loaded, you should see the following screen:

The Showcase is your best starting point for exploring SmartClient
capabilities and code.
The code for the examples in the Showcase can be edited within the
Showcase itself, however, changes will be lost on exit. To create a
permanent, standalone version of an example found in the Showcase,

Isomorphic Software

SmartClient Quick Start

copy the source code into one of the templates in the templates/ directory
(discussed in more detail in Headers of the next chapter, Coding).
All of the resources used by the Showcase are also available in the
isomorphic/system/reference/ directory. In particular, exampleTree.xml
establishes the tree of examples on the left hand side of the Showcase
interface, and contains paths to example files in the inlineExamples/
subdirectory. Note that some DataSources shared by multiple examples
are in the central shared/ds and examples/shared/ds directories.

Demo Application
From the SmartClient SDK Explorer, pick Docs then Demo App. The
first launch of this application will take several seconds, as the application
server parses and compiles the required files. When the application has
loaded, you should see the following screen:

This example application demonstrates a broad range of SmartClient user
interface, data binding, and layout features.
To experience this application as an end user, follow the steps in the
Instructions window at the bottom left of the application window.

Isomorphic Software

SmartClient Quick Start

The SmartClient SDK provides two versions of the code for this
application, one in JavaScript and one in XML, to demonstrate alternate
coding formats.
SmartClient JS and XML coding formats are discussed in detail in
Chapter 4 (Coding)
To explore the application code for this application, click on the XML or
JS links underneath the Demo App icon in the SDK Explorer. You can
also view and edit the source code for this application directly from the
isomorphic/system/reference/inlineExamples/demoApp/ directory in the
SDK. After you make changes to the code, simply reload the page in your
web browser to see the results.
Each .jsp file in the demoApp/ directory contains all component
definitions and client-side logic for the application. The only other source
files for this application are demoApp_helpText.js and
demoApp_skinOverrides.js in the same directory, and the two datasource
descriptors in:
examples/shared/ds/supplyItem.ds.xml
examples/shared/ds/supplyCategory.ds.xml

The key concepts underlying this application—SmartClient JS and XML
Coding, Visual Components, DataSources, and Layouts—are covered in
chapters 4 through 8 of this guide. You may want to briefly familiarize
yourself with the code of this example now, so you can refer back to the
code to ground each concept as it is introduced.

Developer Console
The SmartClient Developer Console is a suite of development tools
implemented in SmartClient itself. The Console runs in its own browser
window, parallel to your running application, so it is always available in
every browser, and in every deployment environment. Features of the
Developer Console include:
logging systems
runtime code inspection and evaluation
runtime component inspection
tracing and profiling
integrated reference docs

Isomorphic Software

SmartClient Quick Start

You can open the Developer Console from any SmartClient-enabled page
by typing javascript:isc.showConsole() in the address bar of your web
browser. Try it now, while the demo application is open in your browser.
The following window will appear:

Popup blocker utilities may prevent the Developer Console
from appearing, or browser security settings may disallow
JavaScript URLs. Holding the Ctrl key while opening the console
will bypass most popup blockers. Creating a bookmark for a
JavaScript URL will allow you to execute it by clicking on the
bookmark.

Isomorphic Software

SmartClient Quick Start

The Results pane of the Developer Console displays:
Messages logged by SmartClient or your application code
through the SmartClient logging system. The Logging
Preferences menu allows you to enable different levels of
diagnostics in over 30 categories, from Layout to Events to
Data Binding.
SmartClient component statistics. As you move the mouse in
the current application, the ID of the current component
under the mouse pointer is displayed in this area. For
example, try mousing over the instructions area for the
demo application; you should see “helpCanvas” as the
Current Event Target.
A runtime code evaluation area. You may evaluate
expressions and execute actions from this area. For example,
with the demo application running, try evaluating each of
these expressions:
categoryTree.getSelectedRecord()
helpCanvas.hide()
helpCanvas.show()

The Watch pane of the Developer Console displays a tree of SmartClient
user interface components in the current application. With the demo
application running, this pane appears as follows:

Isomorphic Software

SmartClient Quick Start

In the Watch pane, you may:
Click on any item in the tree to highlight the corresponding
component in the main application window with a flashing,
red-dotted border.

Right-click on any item in the tree for a menu of operations,
including a direct link to the API reference for that
component’s class.

Right-click on the column headers of the tree to show or
hide columns.
The Developer Console is an essential tool for all SmartClient application
developers and should be open whenever you are working with
SmartClient. For easy access, you should create a toolbar link to quickly
show the Console:
In Firefox/Mozilla:
1. Show your Bookmarks toolbar if it is not already visible (View
→ Toolbars → Bookmarks Toolbar).
2. Go to the Bookmarks menu and pick Manage Bookmarks…
3. Click the New Bookmark button and enter
“javascript:isc.showConsole()” as the bookmark Location, along
with whatever name you choose.
4. Drag the new bookmark into the Bookmarks Toolbar folder

Isomorphic Software

SmartClient Quick Start

In Internet Explorer:
1. Show your Links toolbar if it is not already visible (View →
Toolbars → Links)
2. Type “javascript:isc.showConsole()” into the Address bar
3. Click on the small Isomorphic logo in the Address bar and drag
it to your Links toolbar
4. If a dialog appears saying “You are adding a favorite that may
not be safe. Do you want to continue?”, click Yes.
5. If desired, rename the bookmark (“isc” is chosen as a default
name)
The Developer Console is associated with a single web
browser window at any time. If you have shown the console for
a SmartClient application in one browser window, and then open an
application in another browser window, you must close the console
before you can show it from the new window.

Isomorphic Software

SmartClient Quick Start

Reference
The core documentation for SmartClient is the SmartClient Reference, an
interactive reference viewer implemented in SmartClient. You may access
the SmartClient Reference in any of the following ways:
from the Reference Docs tab of the Developer Console
by right-clicking on a component in the Watch tab of the
Developer Console, and selecting “Show doc for…”
from the SmartClient Reference icon in SDK Explorer →
Docs → SmartClient Reference
from the docs/SmartClient_Reference.html launcher in the
SDK
The SmartClient Reference provides integrated searching capabilities.
Enter your search term in the field at top-left, then press Enter. The
viewer will display a list of relevance-ranked links. For example, searching
on “drag” generates the following results:

If you are new to SmartClient, you may want to read the conceptual topics
in the SmartClient Reference for more detail after completing this Quick
Start guide. These topics are indicated by the blue cube icon ( ) in the
reference tree.

Isomorphic Software

SmartClient Quick Start

Community Wiki
The wiki is a place where community members and Isomorphic engineers
can work together to add new documentation and new samples especially samples and documentation involving third-party products,
where it would not be possible to create a standalone running sample in
the SDK.
This is the right place to look for articles on how to integrate with a
specific authentication system, application server, reporting engine,
widget kit, cloud provider or similar major third-party product.
Isomorphic also publishes example code on the wiki before it becomes an
official product sample, or is incorporated as a new product feature.
http://wiki.smartclient.com/

Isomorphic Software

SmartClient Quick Start

4. Coding
Languages
SmartClient applications may be coded in:
XML—for declarative user interface and/or datasource
definitions – development in this format requires the
SmartClient Server.
JavaScript (JS) —for client-side user interface logic, custom
components, and procedural user interface definitions
Java—for data integration when using the SmartClient Java
Server
SmartClient provides multiple layers of structure and services on top of
the JavaScript language, including a real class system, advanced data
types, object utilities, and other language extensions. The structure of
SmartClient JS code is therefore more similar to Java than it is to the freeform JavaScript typically found in web pages.
To define user interface components, you may use either SmartClient
XML or SmartClient JS. Both formats have their merits:
SmartClient XML
more tools available for code validation
more familiar to HTML programmers
forces better separation of declarative UI configuration, and
procedural UI logic
SmartClient JS
more efficient
easier to read when declarative and procedural code must be
combined
works in stand-alone examples (no server)
allows programmatic (runtime) component instantiation

Isomorphic Software

SmartClient Quick Start

Each format also has its quirks: In JS, missing or dangling commas are a
common cause of parsing errors. In XML, quoting and escaping rules can
make code difficult to read and write.
Isomorphic currently recommends using JavaScript (JS)
to define your SmartClient user interface components, for
maximum flexibility as your applications evolve. However, the
SmartClient SDK provides examples in both JS and XML. You can
decide which is appropriate for your style and your specific needs.
If you are new to JavaScript, you will need to be aware that:
JavaScript identifiers are case-sensitive. For example,
Button and button refer to different entities. SmartClient
component class names (like Button) are capitalized by
convention.
JavaScript values are not strongly typed, but they are typed.
For example, myVar=200 sets myVar to the number 200, while
myVar="200" sets myVar to a string.

Headers
Every SmartClient application is launched from a web page, which is
usually called the bootstrap page. In the header of this page, you must
load the SmartClient client-side engine, specify a user interface “skin,”
and configure the paths to various SmartClient resources.
The exact format of this header depends on the technology you use to
serve your bootstrap page. The minimal headers for loading a
SmartClient-enabled .jsp or .html page are as follows.
Java server (.jsp)
<%@ taglib uri="isomorphic" prefix="isomorphic" %>

Generic web server (.html)

Isomorphic Software

SmartClient Quick Start

If you use the isomorphic:loadISC tag (available in .jsp pages only),
SmartClient will automatically detect and set the appropriate file paths. If
you use the generic header (which will work in any web page), you may
need to change the file paths to locate the isomorphic/ directory. This
example assumes that the bootstrap page is located in a directory that is
adjacent to the isomorphic/ directory.
Note that both examples above load all standard modules. Your
application may need only some modules, or may also load the optional
modules discussed in Chapter 1.
The SmartClient SDK provides complete .jsp and .html template
pages in the top-level templates/ directory, for easy integration with
your development environment.
For information about switching to a different skin or using a
custom skin, see the Customized Themes section in Chapter 9,
Extending SmartClient.

Components
SmartClient is an object-oriented system. You assemble your web
application GUIs from SmartClient components. These components are
defined as reusable classes, from which you create specific instances.
Component classes and instances provide properties (aka attributes) that
you can set at initialization, and methods (aka functions) that you can call
at any time in your client-side logic.
You use the create() method to instantiate SmartClient components in
JS code. This method takes as its argument a JavaScript object literal—a
collection of comma-delimited property:value pairs, surrounded by curly
braces. For example:
isc.Button.create({title:"Click me", width:200})

For better readability, you can format your component constructors with
one property per line, as follows:
isc.Button.create({
title: "Click me",
width: 200
})

The most common syntax errors in JS code are missing or
dangling commas in object literals. If you omit the comma
after the title value in the example above, the code will not parse in
any web browser. If you include a comma following the width value,
the code will not parse in Internet Explorer. SmartClient scans for
dangling commas and will log this common error to your server
output (visible in the terminal window where you started the
server), for easier debugging.

Isomorphic Software

SmartClient Quick Start

To create a SmartClient component in XML code, you create a tag with
the component’s class name. You can set that component’s properties
either as tag attributes:

The latter format allows you to embed JS inside your XML code, e.g., for
dynamic property values, by wrapping it in tags:

At the page level, SmartClient XML code must be wrapped in
tags—see below for an example.

Hello World
The following examples provide the complete code for a SmartClient
“Hello World” page, in three different but functionally identical formats.
Try recreating these examples in your editor. You can save them in the
examples/ directory of the SmartClient SDK, with the appropriate file
extensions (.html or .jsp).
helloworld.jsp (SmartClient JS)
<%@ taglib uri="isomorphic" prefix="isomorphic" %>

Isomorphic Software

SmartClient Quick Start

helloworldXML.jsp (SmartClient XML)
<%@ taglib uri ="isomorphic" prefix="isomorphic" %>

helloworld.html (SmartClient JS)

You can open the .html version directly from your file system (by doubleclicking the file’s icon), provided your browser allows interactive web
pages to run from your file system.
You must open the .jsp versions through your server, as follows:
http://localhost:8080/examples/helloworld.jsp
http://localhost:8080/examples/helloworldXML.jsp

These examples are also provided in the top-level templates/
directory —but we highly recommend creating them yourself for the
learning experience.

Deploying
For instructions on deploying a SmartClient application, see:
SmartClient Reference – Concepts > Deploying SmartClient
The next chapter explains how to configure and manipulate SmartClient
visual components in more detail.

Isomorphic Software

SmartClient Quick Start

5. Visual Components
SmartClient provides two families of visual components for rich web
applications:
Independent visual components, which you will create
and manipulate directly in your applications.
Managed form controls, which are created and managed
automatically by their “parent” form or editable grid.
This chapter provides basic usage information for the independent
components only. Managed form controls are discussed in more detail in
Chapter 6, Data Binding, and especially Chapter 7, Layout.

Component Documentation & Examples
Visual components encapsulate and expose most of the public capabilities
in SmartClient, so they have extensive documentation and examples in
the SmartClient SDK:
SmartClient Reference – For component interfaces (APIs), see
Client Reference. Form controls are sub-listed under Client
Reference > Forms > Form Items.
Component Code Examples – For live examples of component
usage, see the SmartClient Showcase (Examples → Showcase in the
SDK Explorer, or http://localhost:8080/showcase/ from a
running SmartClient server).
The remainder of this chapter describes basic management and
manipulation of independent visual components only. For
information on the creation and layout of managed form controls,
see Chapters 6 (Data Binding) and 7 (Layout), respectively.

Isomorphic Software

SmartClient Quick Start

Identifying Components
You can identify SmartClient components by setting their ID property:
isc.Label.create({
ID: "helloWorldLabel",
contents: "Hello World"
})

By default, component IDs are created in the global namespace, so your
client-side code may reference helloWorldLabel to manipulate the Label
instance created above. You should assign unique IDs that are as
descriptive as possible of the component’s type or purpose. Some
common naming conventions are:
include the component’s type (such as button or btn)
include the component’s action (such as update)
include the datasource the component affects (such as
salesOrder). For example, salesOrderUpdateBtn
You can alternatively manage your components by saving the internal
reference that is returned from the create() call. For example,
var helloWorldLabel = isc.Label.create({
contents: "Hello World"
});

In this case, a unique ID will be assigned to the component. The current
internal format for auto-assigned IDs is isc_ClassName_ID_#.

Manual Layout
You can configure and manipulate SmartClient components by setting
component properties and calling component methods. The most basic
properties for a visual component involve its position, size, and overflow:
left
top
width
height
overflow
position

Isomorphic Software

SmartClient Quick Start

left and top take integer values,

representing a number of pixels from the
top-left of the component’s container (typically a web page, Layout,
Window, or TabSet). width and height take integer pixel values (default 100
for most classes), and can also take string percentage values (e.g. "50%").
For example:
isc.Label.create({
left: 200, top: 200,
width: 10,
contents: "Hello World"
})

In this example, the specified width is smaller than the contents of the
label, so the text wraps and “overflows” the specified size of the label. This
behavior is controlled by the overflow property, which is managed
automatically by most components. You may need to change this setting
for Canvas, Label, DynamicForm, DetailViewer, or Layout components
whose contents you want to clip or scroll instead. To do this, set the
overflow property to "hidden" (clip), "scroll" (always show scrollbars),
or "auto" (show scrollbars only when needed). For example:
isc.Label.create({
left: 200, top: 200,
width: 20,
contents: "Hello World",
overflow: "hidden"
})

By default, SmartClient visual components are positioned at absolute
pixel coordinates in their containers. If you need to embed a component
in the flow of existing HTML, you may set its position property to
"relative". For example:
first item

last item

If you work directly with HTML or CSS code, you must test
your code on all supported browsers for inconsistencies.
In particular, the same HTML and CSS layout code can produce
many different results in different browsers, browser versions, and
DOCTYPE modes. Whenever possible, you should consider using
SmartClient components and layouts to insulate you from browserspecific interpretations of HTML and CSS.

Isomorphic Software

SmartClient Quick Start

In most applications, you will want more flexible, dynamic layout of your
visual components. Chapter 7 (Layout) introduces the SmartClient Layout
managers, which you can use to automatically size, position, and reflow
your components at runtime.

Drawing, Hiding, and Showing Components
In a SmartClient-enabled application, you may load hundreds of user
interface components in the bootstrap page, and then navigate between
views on the client by hiding and showing these components. The basic
APIs for hiding and showing components are:
autoDraw
show()
hide()

The autoDraw property defaults to true, so a component is usually shown
as soon as you create() it. Set autoDraw to false to defer showing the
component. For example:
isc.Button.create({
ID: "hiddenBtn",
title: "Hidden",
autoDraw: false
})

To show this button:
1. Open the SmartClient Developer Console from the page that
has created the button.
2. Type hiddenBtn.show() in the JS evaluation area.
3. Click the “Eval” button to execute that code.
For more information on architecting your applications for highperformance, client-side view navigation, see SmartClient
Reference → Concepts → SmartClient Architecture.

Handling Events
SmartClient applications implement interactive behavior by responding to
events generated by their environment or user actions. You can provide
the logic for hundreds of different events by implementing event
handlers.

Isomorphic Software

SmartClient Quick Start

The most common SmartClient component event handlers include:
click

(for buttons and menu items)

recordClick

(for listgrids and treegrids)

change

(for form controls)

tabSelected

(for tabsets)

Component event handlers are set using a special type of property called a
string method. These properties may be specified either as:
a string of JavaScript to evaluate when the event occurs; or
a JavaScript function to call when the event occurs
For example:
isc.Button.create({
ID: "clickBtn",
title: "click me",
click: "isc.warn('button was clicked')"
})

Is functionally identical to:
isc.Button.create({
ID: "clickBtn",
title: "click me",
click: function () {
isc.warn('button was clicked');
}
})

For event handling in applications, you can set your event handlers to
strings that execute external functions. This approach enables better
separation of user interface structure and logic:
isc.Button.create({
ID: "clickBtn",
title: "click me",
click: "clickBtnClicked()"
})
function clickBtnClicked() {
isc.warn('button was clicked');
})

For more information on available SmartClient events, see:
SmartClient Reference – Component-specific APIs under
Client Reference
SmartClient Reference – EventHandler APIs under Client
Reference → System → EventHandler

Isomorphic Software

SmartClient Quick Start

6. Data Binding
Databound Components
You can bind certain SmartClient components to DataSources that
provide their structure and contents. The following visual components are
designed to display, query, and edit structured data:
Visual
Component

Display
Data

Query
Data

Edit
Data

DynamicForm
ListGrid
TreeGrid
CubeGrid

(Analytics option)

DetailViewer
TileGrid
ColumnTree

Databound components provide you with both automatic and manual
databinding behaviors. For example:
Automatic behavior – A databound ListGrid will generate
Fetch operations when a user scrolls the list to view more
records.
Manual behavior – You can call removeSelectedData() on a
databound ListGrid to perform Remove operations on its
datasource.
This chapter outlines the client-side interfaces that you may use to
configure databound components and interact with their underlying
datasources. Chapter 8 (Data Integration) outlines the interfaces
for server-side integration of datasources with your data and service
tiers.

Isomorphic Software

SmartClient Quick Start

Fields
Fields are the building blocks of databound components and datasources.
There are two types of field definitions:
Component fields provide presentation attributes for
databound visual components (such as title, width,
alignment). Component fields are discussed immediately
below.
DataSource fields provide metadata describing the
objects in a particular datasource (such as data type, length,
required). DataSource fields are discussed in DataSources.
Component fields display as the following sub-elements of your
databound components:
Component

Fields

DynamicForm

form controls

ListGrid

columns & form controls

TreeGrid

columns & form controls

CubeGrid

(Analytics option) facets (row & column headers)

DetailViewer

rows

TileGrid

rows within tiles

Calendar

event duration and description

You can specify the displayed fields of a visual component via the fields
property, which takes an array of field definition objects. For example:
isc.ListGrid.create({
ID: "contactsList",
left: 50, top: 50,
width: 300,
fields: [
{name:"salutation", title:"Title"},
{name:"firstname", title:"First Name"},
{name:"lastname", title:"Last Name"}
]
})

Isomorphic Software

SmartClient Quick Start

Try reproducing this example. When you load it in your web browser, you
should see a ListGrid that looks like this:

The name property of a field is the special key that connects that field to
actual data values. For a simple ListGrid or DetailViewer, you can specify
data values directly via the data property, which takes an array of record
objects. Add this code to the ListGrid definition above (remembering to
add a comma between the fields and data properties):
data: [
{salutation:"Ms", firstname:"Kathy", lastname:"Whitting"},
{salutation:"Mr", firstname:"Chris", lastname:"Glover"},
{salutation:"Mrs", firstname:"Gwen", lastname:"Glover"}
]

Now when you load this example, you should see:

This approach (directly setting data) is appropriate mainly
for lightweight, read-only uses (i.e., for small, static lists of
options). When your components require dynamic data operations,
data-type awareness, support for large datasets, or integration with
server-side datasources, you will set the dataSource property instead
to bind them to DataSource objects. See DataSources for details.

Isomorphic Software

SmartClient Quick Start

The basic field definitions in the ListGrid above are reusable across
components. For example, you could copy these field definitions to create
a DynamicForm:
isc.DynamicForm.create({
ID: "contactsForm",
left: 50, top: 250,
width: 300,
fields: [
{name:"salutation", title:"Title"},
{name:"firstname", title:"First Name"},
{name:"lastname", title:"Last Name"}
]
})

which will display as:

For complete documentation of component field properties
(presentation attributes), see:
SmartClient Reference – Client Reference → Forms →
Form Items (all entries)
SmartClient Reference – Client Reference → Grids →
ListGrid → ListGridField
DataSource field properties (data attributes) are discussed in
DataSources.

Form Controls
Field definitions also determine which form controls are presented to
users, for editable data values in forms and grids. You can specify the
form control to use for a field by setting its editorType property.
The default editorType is "text", which displays a simple text box editor.
This control is an instance of the TextItem class.
If a component is bound to a DataSource, it will automatically display
appropriate form controls based on attributes of its DataSource fields (e.g.
checkbox for boolean values, date picker for date values, etc). However,
there may be more than one way to present the same value. For example,
a dropdown control (selectItem) and a set of radio buttons
(radioGroupItem) are both appropriate for presenting a relatively small set
of values in a form.

Isomorphic Software

SmartClient Quick Start

To override the default form control for a field, set editorType to the class
name for that control, in lower case, minus the "Item". For example, for a
CheckboxItem, you can set editorType:"checkbox".
The following code extends the previous DynamicForm example to use an
assortment of common form controls, specified by editorType:
isc.DynamicForm.create({
ID: "contactsForm", left: 50, top: 250, width: 300,
fields: [
{name:"salutation", title:"Title", editorType: "select",
valueMap:["Ms", "Mr", "Mrs"]
},
{name:"firstname", title:"First Name"},
{name:"lastname", title:"Last Name"},
{name:"birthday", title:"Birthday", editorType:"date"},
{name:"employment", title:"Status", editorType:"radioGroup",
valueMap:["Employed", "Unemployed"]
},
{name:"bio", title:"Biography", editorType:"textArea"},
{name:"followup", title:"Follow up", editorType:"checkbox"}
]
})

This form will appear as follows:

For more information on the layout of managed form controls, see
“Form Layout” in Chapter 7 (Layout).

Isomorphic Software

SmartClient Quick Start

DataSources
SmartClient DataSource objects provide a presentation-independent,
implementation-independent description of a set of persistent data fields.
DataSources enable you to:
Separate your data model attributes from your presentation
attributes.
Share your data models across multiple applications and
components, and across both client and server.
Display and manipulate persistent data and data-model
relationships (e.g. parent-child) through visual components
(such as TreeGrid).
Execute standardized data operations (fetch, sort, add,
update, remove) with built-in support on both client and
server for data typing, validators, paging, unique keys, and
more.
Leverage automatic behaviors including data loading,
caching, filtering, sorting, paging, and validation.
A DataSource descriptor provides the attributes of a set of DataSource
fields. DataSource descriptors can be specified directly in XML or JS
format, or can be created dynamically from existing metadata (for more
information, see SmartClient Reference → Client Reference → Data
Binding → DataSource → Creating DataSources). The XML format is
interpreted and shared by both client and server, while the JS format is
used by the client only. Note that use of the XML format requires the
optional SmartClient Server.
There are four basic rules to creating DataSource descriptors:
1. Specify a unique DataSource ID attribute. The ID will be used to
bind to visual components, and as a default name for objectrelational (table) bindings and test data files. Appending “DS” to
the ID is a good convention to easily identify DataSource
references in your code.
2. Specify a field element with a unique name (in this DataSource)
for each field that will be exposed to the presentation layer.
3. Specify a type attribute on each field element (see below for
supported data types).
4. Mark a field with primaryKey="true". The primaryKey field must
have a unique value in each data object (record) in a
DataSource. A primaryKey field is not required for read-only
DataSources, but it is a good general practice to allow for future
add, update, or remove data operations. If you need multiple
primary keys, see Chapter 11, Tips.

Isomorphic Software

SmartClient Quick Start

Following these rules, a DataSource descriptor for the “contacts” example
earlier in this chapter looks like:

Ms
Mr
Mrs

Employed
Unemployed

For your convenience, this descriptor is already saved in
shared/ds/contactsDS.ds.xml. Note that this code is the entire content of
the file—there are no headers, tags, or other wrappers around the
DataSource descriptor.
Every DataSource field must specify a type, and editable
DataSources (i.e., supporting Add, Update, or Remove operations)
must specify exactly one field with primaryKey="true".
For more information on defining, creating, and locating
DataSources, see SmartClient Reference → Client Reference →
Data Binding → DataSource. The Creating DataSources and Client
Only DataSources subtopics provide additional detail.
To load this DataSource in previous “contacts” example, add the following
tag inside the

This example entirely replaces fields with a dataSource for simplicity.
However, these two properties will usually co-exist on your databound
components. The component field definitions in fields specify
presentation attributes, while the DataSource field definitions specify data
attributes (see table below).
SmartClient merges your component field definitions and DataSource
field definitions based on the name property of the fields. By default, the
order and visibility of fields in a component are determined by the fields
array. To change this behavior, see useAllDataSourceFields in the
SmartClient Reference.

Isomorphic Software

SmartClient Quick Start

Common DataSource field properties include:
Property

Values

name

unique field identifier (required on every
DataSource field)

type

See reference for full list of field types.
length

maximum length of text value in characters

hidden

true; whether this field should be entirely
hidden from the end user. It will not appear in
the default presentation, and it will not appear
in any field selectors (e.g. the column picker
menu in a ListGrid) available to the end user.

required

true | false

valueMap

an array of values, or an object containing
storedValue:displayValue pairs

primaryKey

true; specifies whether this is the field that
uniquely identifies each record in this
DataSource (that is, it must have a unique value
for each record). The primaryKey field is often
specified with type="sequence" and
hidden="true", to generate a unique internal
key. For multiple primary keys, see Chapter 11,
Tips.

foreignKey

a reference to a field in another DataSource
(for example, dsName.fieldName)

rootValue

for fields that establish a tree relationship (by
foreignKey), this value indicates the root node
of the tree

For complete documentation of the metadata properties supported
by SmartClient DataSources and components, see SmartClient
Reference → Client Reference → Data Binding → DataSource →
DataSourceField.
For DataSource usage examples, see the descriptors in
examples/shared/ds/. These DataSources are used in various
SmartClient SDK examples, including the SmartClient Showcase
For an example of a DataSource relationship using foreignKey, see
examples/databinding/tree_databinding.jsp (TreeGrid UI) and
shared/ds/employees.ds.xml (associated DataSource).

Isomorphic Software

SmartClient Quick Start

As mentioned under “Form Controls” above, databound components will
automatically display appropriate form controls based on attributes of
their DataSource fields. The rules for this automatic selection of form
controls are:
Field attribute
valueMap

provided

Form control
SelectItem (dropdown)

type:"boolean"

CheckboxItem

(checkbox)

type:"date"

DateItem

length > 255

TextAreaItem (large text box)

(date control)

You can override this automatic behavior by explicitly setting editorType
on any component field.

DataSource Operations
SmartClient provides a standardized set of data operations that act upon
DataSources:

Operation Methods

Description

Fetch

fetchData(…)

retrieves records from the
datasource that exactly match the
provided criteria

filterData(…)

retrieves records from the
datasource that contain (substring
match) the provided criteria

Add

addData(…)

creates a new record in the
datasource with the provided
values

Update

updateData(…)

updates a record in the
datasource with the provided
values

Remove

removeData(…)

deletes a record from the
datasource that exactly matches
the provided criteria

Isomorphic Software

SmartClient Quick Start

These methods each take three parameters:
a data object containing the criteria for a Fetch or Filter
operation, or the values for an Add, Update, or Remove
operation
a callback expression that will be evaluated when the
operation has completed
a properties object containing additional parameters for
the operation—timeout length, modal prompt text, etc. (see
DSRequest in the SmartClient Reference for details)
You may call any of these five methods directly on a DataSource object, or
on a databound ListGrid or TreeGrid. For example:
contactsDS.addData(
{salutation:"Mr", firstname:"Steven", lastname:"Hudson"},
"say(data[0].firstname + 'added to contact list')",
{prompt:"Adding new contact..."}
);

or
contactsList.fetchData(
{lastname:"Glover"}
);

DataSource operations will only execute if the DataSource
is bound to a persistent data store. You can create relational
database tables as a data store for rapid development by using the
“Import DataSources” section in the SmartClient Admin Console.
For deeper integration with your data tiers, see Chapter 8 (Data
Integration).

DataBound Component Operations
In addition to the standard DataSource operations listed above, you can
perform Add and Update operations from databound form components
by calling the following DynamicForm methods:

Method

Description

editRecord()

starts editing an existing record

editNewRecord()

starts editing a new record

saveData()

saves the current edits (Add new
records; Update existing records)

Isomorphic Software

SmartClient Quick Start

Databound components also provide several convenience methods for
working with the selected records in a databound grid:
Convenience Method
listGrid.removeSelectedData()
dynamicForm.editSelectedData(listGrid)
detailViewer.viewSelectedData(listGrid)

examples/databinding/component_databinding.jsp shows

most of
these DataSource and databound component methods in action,
with a ListGrid, DynamicForm, and DetailViewer that are
dynamically bound to several different DataSources.
For more information, see the Datasource Operations, Databound
Components, and Databound Component Methods subtopics
under SmartClient Reference → Client Reference → Data Binding.

Data Binding Summary
This chapter began by introducing Databound Components, to build on
the concepts of the previous chapter (Visual Components). However, in
actual development, DataSources usually come first. The typical steps to
build a databound user interface with SmartClient components are:
5. Create DataSource descriptors (.ds.xml or .js files),
specifying data model (metadata) properties in the DataSource
fields.
6. Back your DataSources with an actual data store. The
SmartClient Admin Console GUI creates and populates
relational database tables for rapid development. Chapter 8
(Data Integration) describes the integration points for binding
to production object models and data stores.
7. Load DataSource descriptors in your SmartClient-enabled
pages with the isomorphic:loadDS tag (for XML descriptors in
JSP pages) or client-only JS format. See Creating DataSources
in the SmartClient Reference for more information.
8. Create visual components that support databinding
(primarily form, grid, and detail viewer components).
9. Bind visual components to DataSources using the
dataSource property and/or setDataSource() method.
10. Modify component-specific presentation properties in
each databound component’s fields array.

Isomorphic Software

SmartClient Quick Start

11. Call databound component methods (e.g. fetchData) to
perform standardized data operations through your databound
components.
DataSources effectively hide the back-end implementation of your data
and service tiers from your front-end presentation—so you can change the
back-end implementation at any time, during development or postdeployment, without changing your client code.
See Chapter 8 (Data Integration) for an overview of server-side
integration points that address all stages of your application lifecycle.

Isomorphic Software

SmartClient Quick Start

7. Layout
Component Layout
Most of the code snippets in this guide create just one or two visual
components, and position them manually with the left, top, width, and
height properties.
This manual layout approach becomes brittle and complex with more
components. For example, you may want to:
consistently position your components relative to each other
allocate available space based on relative measures (e.g.
30%)
resize and reposition components when other components
are resized, hidden, shown, added, removed, or reordered
resize and reposition components when the browser window
is resized by the user
SmartClient includes a set of layout managers to provide these and other
automatic behaviors. The SmartClient layout managers implement
consistent dynamic sizing, positioning, and reflow behaviors that cannot
be accomplished with HTML and CSS alone.
The fundamental SmartClient layout manager is implemented in the
Layout class, which provides four subclasses to use directly:
HLayout—manages the positions and widths of a list of

components in a horizontal sequence

VLayout—manages the positions and heights of a list of

components in a vertical sequence

HStack—positions a list of components in a horizontal

sequence, but does not manage their widths

VStack—positions a list of components in a vertical

sequence, but does not manage their heights

Isomorphic Software

SmartClient Quick Start

These layout managers are themselves visual components, so you can
create and configure them the same way you would create a Label, Button,
ListGrid, or other independent component.
The key properties of a layout manager are:
Layout property

Description

members

an array of components managed by this
layout

membersMargin

number of pixels of space between each
member of the layout

layoutMargin

number of pixels of space surrounding the
entire layout

The member components also support additional property settings in the
context of their parent layout manager:
Member
property

Description

layoutAlign

alignment with respect to the breadth axis of
the layout ("left", "right", "top", "bottom",
or "center")

showResizeBar

determines whether a drag-resize bar
appears between this component and the
next member in the layout
(true | false)

width

layout-managed components support a "*"
value (in addition to the usual number and
percentage values) for their size on the
length axis of the layout, to indicate that
they should take a share of the remaining
space after fixed-size components have been
counted (this is the default behavior if no
width/height is specified)

height

Components that automatically size to fit their contents
will not be resized by a layout manager. By default, Canvas,
Label, DynamicForm, DetailViewer, and Layout components have
overflow:"visible", so they expand to fit their contents. If you want
one of these components to be sized by a layout instead, you must
set its overflow property to "hidden" (clip), "scroll" (always show
scrollbars), or "auto" (show scrollbars only when needed).

Isomorphic Software

SmartClient Quick Start

You can specify layout members by reference, or by creating them in-line,
and they may include other layout managers. By nesting combinations of
HLayout and VLayout, you can create complex dynamic layouts that would
be difficult or impossible to achieve in HTML and CSS.
You can use the special LayoutSpacer component to insert extra space into
your layouts. For example, here is the code to create a basic page header
layout, with a left-aligned logo and right-aligned title:
isc.HLayout.create({
ID:"myPageHeader",
height:50,
layoutMargin:10,
members:[
isc.Img.create({src:"myLogo.png"}),
isc.LayoutSpacer.create({width:"*"}),
isc.Label.create({contents:"My Title"})
]
})

See the SmartClient Demo Application (SDK Explorer → Getting
Started → Demo App) for a good example of layouts in action
For more information, see SmartClient Reference → Client
Reference → Layout.

Container Components
In addition to the basic layout managers, SmartClient provides a set of
rich container components. These include:
SectionStack—to

manage multiple stacked, user-expandable
and collapsible ‘sections’ of components
TabSet—to

manage multiple, user-selectable ‘panes’ of
components in the same space
Window—to provide free-floating, modal and non-modal

views that the user can move, resize, maximize, minimize, or
close
See the SmartClient Demo Application (SDK Explorer → Getting
Started → Demo App) for examples of SectionStack and TabSet
components in action.
For more information, see SmartClient Reference → Client
Reference → Layout.

Isomorphic Software

SmartClient Quick Start

Form Layout
Data entry forms have special layout requirements—they must present
their controls and associated labels in regularly aligned rows and
columns, for intuitive browsing and navigation.
When form controls appear in a DynamicForm, their positions and sizes are
controlled by the SmartClient form layout manager. The form layout
manager generates a layout structure similar to an HTML table. Form
controls and their titles are rendered in a grid from left-to-right, top-tobottom. You can configure the high-level structure of this grid with the
following DynamicForm properties:
DynamicForm

property

Description

numCols

Total number of columns in the grid, for form
controls and their titles. Set to a multiple of 2,
to allow for titles, so numCols:2 allows one
form control per row, numCols:4 allows two
form controls per row, etc.

titleWidth

Number of pixels allocated to each title
column in the layout.

colWidths

Optional array of pixel widths for all columns
in the form. If specified, these widths will
override the column widths calculated by the
form layout manager.

You can control the positioning and sizing of form controls in the layout
grid by changing their positions in the fields array, their height and
width properties, and the following field properties:

Field
property

Description

colSpan

number of form layout columns occupied by this
control (not counting its title, which occupies
another column)

rowSpan

number of form layout rows occupied by this
control

startRow

whether this control should always start a new
row (true | false)

endRow

whether this control should always end its row
(true | false)

showTitle

whether this control should display its title
(true | false)

Isomorphic Software

SmartClient Quick Start

Field
property

Description

align

horizontal alignment of this control within its area
of the form layout grid ("left", "right", or "center")

See Showcase → Forms → Layout for examples of usage of these
properties
You can also use the following special form items to include extra space
and formatting elements in your form layouts:
header
blurb
spacer
rowSpacer

To create one of these special controls, simply include a field definition
whose type property is set to one of these four names. See the properties
documented under headerItem, blurbItem, spacerItem, and rowSpacerItem
for additional control.
For more information on form layout capabilities, see:
SmartClient Reference – Client Reference → Forms →
DynamicForm
SmartClient Reference – Client Reference → Forms →
Form Items → FormItem

Isomorphic Software

SmartClient Quick Start

8. Data Integration
SmartClient DataSources provide a data-provider-agnostic interface to
databound components, allowing those components to implement
sophisticated behaviors that can be used with any data provider. In this
chapter, we explain how to integrate a DataSource with various
persistence systems so that the operations initiated by databound
components can retrieve and modify persistent data.

DataSource Requests
When a visual component, or your own custom code, attempts to use a
DataSource operation, a DSRequest (DataSource Request) is created
representing the operation. “Data Integration” is the process of fulfilling
that DSRequest by creating a corresponding DSResponse (DataSource
Response), by using a variety of possible approaches to connect to the
ultimate data provider.
There are two main approaches to fulfilling DataSource Requests:
Server-side integration (SmartClient Server
Framework): DataSource requests from the browser arrive
as Java Objects on the server. You deliver responses to the
browser by returning Java Objects. This is the simpler and
more powerful approach.
Client-side integration: DataSource requests arrive as
HTTP requests which your server code receives directly (in
Java, you use the Servlet API or .jsp files to handle the
requests). Responses are sent as XML or JSON, which you
directly generate.

Isomorphic Software

SmartClient Quick Start

The possible approaches to data integration are summarized in the
following diagram. Paths 2, 3 and 4 are client-side integration
approaches, while path 1 includes all server-side integration approaches.

SmartClient Server Framework
Path 1 makes use of the SmartClient Server Framework. Available with
Pro edition and above, the server framework is a set of Java libraries and
servlets that can be integrated with any pre-existing Java application.
Unless you are forced to use a different approach (for example, you are
not using a Java-based server, and cannot deploy a Java-based server in
front of your existing server), it is highly recommended that you use the
SmartClient Server Framework for data integration. The server
framework delivers an immense range of functionality that compliments
any existing application and persistence engine. Chapter 9, SmartClient
Server Framework, provides an overview.
If you cannot use the SmartClient Server Framework, the best approaches
for data integration are covered later in this chapter.

Isomorphic Software

SmartClient Quick Start

DSRequests and DSResponses
Regardless of the data integration approach used, the data in the request
and response objects has the same meaning.
The key members of a DSRequest object are:
data: the search

criteria (for “fetch”), new record values (“add” or
“update”) or criteria for the records to delete (“remove”)
sortBy: requested sort direction for the data (“fetch” only)
startRow and endRow: the range of records to fetch (if paging is active)
oldValues: values of the record before changes were made, for checking

for concurrent edits (all operations but “fetch”)
The key members of a DSResponse object are:

whether the request succeeded or encountered a validation or
other type of error
status:

the matching records (for “fetch”), data-as-saved (“add” or
“update”), or deleted record (“remove”)
data:

startRow and endRow: the range of records actually returned (if paging is

active)

totalRows: the total number of records available
errors: for a validation error response, fields

that were invalid and error

messages for each

Request and Response Transformation
If you are using the SmartClient Server Framework with one of the builtin DataSource types (such as SQL or JPA/Hibernate), you will not need to
do any request or response transformation work and can proceed directly
to Chapter 9, SmartClient Server Framework.
If you cannot use the server framework, but you are free to define the
format and content of messages passed between the browser and your
server, the simplest data integration approach is the RestDataSource class.

Isomorphic Software

SmartClient Quick Start

The RestDataSource performs the four core DataSource operations using a
simple, well-documented protocol of XML or JSON requests and
responses sent over HTTP. The HTTP requests sent by the client will
contain the details of the DSRequest object and your server-side code
should parse this request and output an XML or JSON formatted
response containing the desired properties for the DSResponse.
If, instead, you are required to integrate with a pre-existing service that
defines its own HTTP-based protocol, you can configure a subclass of the
DataSource class to customize the HTTP request format and the expected
format of responses.
For services that return XML or JSON data (including WSDL), you can
specify XPath expressions indicating what part of the data should be
transformed into dsResponse.data. If XPath expressions are not sufficient,
you can override DataSource.transformRequest() and
DataSource.transformResponse() and add Java code to handle those
cases.
These same two APIs (transformRequest and transformResponse) enable
integration with formats other than XML and JSON, such as CSV over
HTTP or proprietary message formats.
Finally, setting DataSource.dataProtocol to DSProtocol.CLIENTCUSTOM
prevents a DataSource from trying to directly send an HTTP request,
allowing integration with data that has already been loaded by a third
party communication system, or integration in-browser persistence
engines such as HTML5 localStorage or in-browser SQLite databases.
To learn more about using the RestDataSource and client-side data
integration options, see:
SmartClient Reference – Client Reference > Data Binding >
RestDataSource
SmartClient Reference – Concepts > Client-Server
Integration
For a live sample of RestDataSource showing sample responses, see:
SmartClient Showcase
http://www.smartclient.com/index.jsp#featured_restfulds

Isomorphic Software

SmartClient Quick Start

Criteria, Paging, Sorting and Caching
SmartClient UI components such as the ListGrid provide an interface
that allows an end user to search data, sort data, and page through large
datasets. As this interface is used, the UI component generates DSRequests
that will contain search criteria, requested sort directions and requested
row ranges.
However, SmartClient does not require that a data provider implement all
of these capabilities. In fact, SmartClient is able to use a “flat file” as a
response to the “fetch” operation, and implement searching and sorting
behaviors within the browser.
If a data provider cannot implement paging and sorting behaviors, it is
sufficient to simply ignore the startRow, endRow and sortBy attributes of
the DSRequest and return a DSResponse containing all data that matches
the provided criteria, in any order. SmartClient will perform sorting
client-side as necessary. This does not need to be configured in advance –
a data provider can decide, on a case-by-case basis, whether to simply
return all data for a given request.
If a data provider also cannot implement the search behavior, the
DataSource can be set to cacheAllData. This means that the first time any
data is requested, all data will be requested (specifically, a DSRequest will
be sent with no search criteria). SmartClient will then perform searches
within the browser. Data modification requests (“add”, “update” or
“remove” operations) are still sent normally – in effect, a “write-through”
cache is maintained.
To learn more about searching, sorting, paging and caching
behaviors, see:
SmartClient Reference – Client Reference > Data Binding >
ResultSet
SmartClient Reference – Client Reference > Data Binding >
DataSource.cacheAllData

Isomorphic Software

SmartClient Quick Start

Authentication and Authorization
Securing SmartClient applications is done in substantially the same way
as standard web applications. In fact, SmartClient’s advanced architecture
actually simplifies the process and makes security auditing easier.
For example, enabling HTTPS requires no special configuration. Simply
ensure that any URLs provided to SmartClient do not include an explicit
“http://” at the beginning, and all DSRequests, requests for images and so
forth will automatically use the “https://” prefix and be protected.
Although it is straightforward to build a login interface in SmartClient, it
is generally recommended that you implement your login page as a plain
HTML page, due to the following advantages:
interoperable/single sign-on capable —if your application
may need to participate in single sign-on environment (even
in the distant future), you will be in a better position to
integrate if you are making minimal assumptions about the
technology and implementation of the login page
login page appears instantly—the user does not have to wait
for the entire application to download in order to see the
login page and begin entering credentials
background loading – use techniques such as off-screen
tags and
...

There is no need for a formal class or method definition - the
context of a DMI Script is always the same, and the Server
Scripting system avoids the need to add this "boilerplate code".
Using scriptlets has a couple of major advantages as compared to
using :
1. Simplicity & Clarity: scriptlets put business logic right next to
the relevant persistence operation instead of requiring that you
look in a separate .java file
2. Faster Development Cycle: scriptlets are compiled and executed
dynamically, so you do not need to recompile or redeploy your
server code to try out changes to scriptlets. Just edit your
DataSource, and then either reload the page or retry the
operation. The SmartClient Server framework automatically
notices the changed DataSource and uses the updated scriptlet.
Note that scriptlets are only recompiled when you change them, so
will only be compiled once ever in the final deployment of your
application.
The ability to use Groovy as a "scripting language" is particularly
powerful:
1. Developers do not have to know more than one language to work
with the code for your application (Groovy syntax is, for all intents
and purposes identical to Java syntax).
2. Scriptlets can easily be moved into normal .groovy or .java files
if they are identified as reusable, become too large to manage in
a .ds.xml file, or if the (small) performance boost of compiling
them to .class files is desired. There is no need to translate from
some other language into Java

Isomorphic Software

SmartClient Quick Start

For these reasons we recommend use of Server Scripting with
the Groovy language even for teams that would not normally
consider adopting a "scripting language".
For examples of Server Scripting see:
SmartClient Enterprise Showcase:
http://www.smartclient.com/index.jsp#_Featured.Samples_
Server.Examples_Server.Scripting
For more information on Server Scripting see:
SmartClient Reference:
Concept> Server Script for SmartClient

Including Values from Other DataSources
Frequently, you will need to show a UI that includes fields from two
related DataSources - something typically accomplished in SQL with a
"join". For simple cases of this, you can
use DataSourceField.includeFrom.
For example, a DataSource stockItem may store information about items
for sale in a store, including "itemName" and "price". A related
DataSource orderItem may store the "id" and "quantity" of a stockItem
that was ordered. When the user views all the orderItems in a order, they
want to see the "itemName"s of the related stockItems, not their "id"s.
To accomplish this, you can declare an additional field in the orderItem
DataSource like so:

Now, when the orderItem DataSource responds to a "fetch" request, it will
include an additional field "itemName" which comes from the related
stockItem DataSource. Note how the field declared in XML above is not
given a "name" attribute - the name is optional in this case, and will
default to the name of the included field.
In order for included fields to work, the foreignKey attribute must be used
to declare the relationship between the two DataSources. In this case,
there might be a field orderItem.stockItemId with
foreignKey="stockItem.id"). Once relationships are declared, multiple
fields may be included from multiple different DataSources by simply
adding more includeFrom declarations.

Isomorphic Software

SmartClient Quick Start

When includeFrom is used with the built-in SQLDataSource,
HibernateDataSource or JPADataSource (when the provider is
Hibernate), an efficient SQL join is used to include the field from the
related DataSource, and search criteria and sort directions work normally
with included fields.
For other kinds of DataSources, includeFrom operates by first fetching
records from the main DataSource, then fetching related records from the
included DataSource. In this case search criteria and sort directions
specified for included fields only work if data paging is not in use.
In the upcoming discussion of SQL Templating we'll see how to do more
advanced joins as well as make use of SQL features such as expressions,
grouping and aggregation.

Isomorphic Software

SmartClient Quick Start

SQL Templating
A DataSource declared with serverType=”sql” uses the SQLDataSource,
which automatically generates and executes SQL statements against a
database in response to DSRequests sent by the client.
When using the SQLDataSource with the Power Edition of SmartClient,
SQL Templating enables fine-grained customization of generated SQL.
The SQL generator in Power Edition can take the DSRequests generated by
DataBound components and automatically handle:
Generation of a where clause from complex criteria,
including nested “and” and “or” sub-expressions
Database-specific SQL for the most efficient ranged
selections on each platform, for fast data paging
Multi-level sorting including support for sorting by
displayed rather than stored values
Several different styles of storing basic types like booleans
and dates, for adapting to existing tables
When you inevitably have to customize the generated SQL for a particular
use case, it’s critical to preserve as much of this powerful, automatic
behavior as possible.
Most systems that allow customization of generated SQL provide only an
all-or-nothing option: if you need to customize, you write the complete
SQL query from scratch, and handle all database-specific SQL yourself.
In contrast, the SQL Templating system lets you change small parts of the
generated SQL while leaving all the difficult, database-specific SQL up to
SmartClient. SQL Templating also allows you to take advantage of
database-specific features where appropriate, without losing automatic
SQL generation for standard features.

Isomorphic Software

SmartClient Quick Start

The following table summarizes the SQL statements that are generated
and how the DSRequest is used (note, these aren’t the actual statements –
additional SQL exists to handle data paging and database-specific quirks):
Type

SQL statement

DSRequest usage

fetch

SELECT
FROM
WHERE
GROUP BY
ORDER BY

add

INSERT INTO

data becomes

update

UPDATE
SET
WHERE

data becomes

and

data becomes

sortBy becomes

outputs becomes

(primary key only)

remove

DELETE FROM
WHERE

data becomes
clause

(primary key only)

To customize SQL at a per-clause level, you can add tags to your
named after SQL clauses. Each clause allows a
Velocity template, and the default SQL that would have been generated is
available to you as a Velocity variable:
XML Tag

Velocity Variable

SQL Meaning

$defaultSelectClause

List of columns or expressions
appearing after SELECT

$defaultTableClause

List of tables or table
expressions appearing after FROM

$defaultWhereClause

Selection criteria appearing after
WHERE

$defaultValuesClause

List of expressions appearing
after SET (for UPDATE) or list of
column names and VALUES()
around list of expressions (for
INSERT)

$defaultOrderClause

List of columns or expressions
appearing after ORDER BY

List of columns or expressions
appearing after GROUP BY

As a simple example, in an order management system, you may want to
present a view of all orders for items that are not in stock. Given two
94

Isomorphic Software

SmartClient Quick Start

tables, orderItem and stockItem, linked by id, you could add an
to the DataSource for the orderItem table:

orderItem, stockItem
orderItem.stockItem_id == stockItem.id AND
stockItem.inStock == 'F' AND
$defaultWhereClause)

Note the use of $defaultWhereClause—this ensures that any criteria
submitted to this operation still work. Data paging and sorting likewise
continue to work.
It is also possible to override the entire SQL statement by using the
tag. This makes it very easy to call stored procedures:
< operationBinding operationType ="remove">
call deleteOrder($criteria.orderNo)

When customizing a "fetch" operation, use clause-by-clause overrides
instead where possible. Using the tag for a "fetch" operation
disables the use of efficient data paging approaches that can only be used
when SmartClient knows the general structure of the SQL
query. However, if you know that your customized SQL is still compatible
with the SQL added for data paging, you can use the
operationBinding.sqlPaging attribute to re-enable it.
For more information on SQL Templating, see:
SmartClient Reference – Client Reference > Data Binding >
DataSource > Custom Querying Overview

Isomorphic Software

SmartClient Quick Start

SQL Templating — Adding Fields
A customized query can return additional fields that aren’t part of the
DataSource’s primary table, and even allow criteria to be automatically
applied to such fields.
For the common case of incorporating a field from another table, declare
a field as usual with a tag, then add the attribute
tableName="otherTable". Setting tableName enables a field to be fetched
from another table and used in the WHERE clause, but automatically
excludes the field from the SQL for any operationType except “fetch.”
For example, given the orderItem and stockItem tables from the
preceding example, imagine stockItem had a column itemName that you
want to include in results from the orderItem DataSource.

orderItem, stockItem
orderItem.stockItem_id == stockItem.id AND
($defaultWhereClause)

This approach can be extended to any number of fields from other tables.
For an example of SQL Templating being used to add a searchable
field, see:
SmartClient Enterprise Showcase:
http://www.smartclient.com/index.jsp#largeValueMapSQL

Isomorphic Software

SmartClient Quick Start

In some cases, you may have several different Operation Bindings that use
different sets of added fields. In this case, you can set customSQL="true"
on the element to turn off automatic generation. Then, use the
following properties to control whether SQL is
generated for the field on a per- basis.
Setting

Meaning

customValueFields

Comma-separated list of fields to allow in SELECT
clause despite being customSQL="true"

customCriteriaFields

Comma-separated list of fields to allow in WHERE
clause despite being customSQL="true"

excludeCriteriaFields

Comma-separated list of fields to exclude from
$defaultWhereClause

You can also define custom SQL on a per-field basis rather than a perclause basis using the following properties on a :
Setting

Meaning

customSelectExpression

Expression to use in SELECT and WHERE clauses

customUpdateExpression

Expression to use in SET clause of UPDATE

customInsertExpression

Expression to use in VALUES clause of INSERT.
Defaults to customUpdateExpression

customSelectExpression alone is enough to

create a searchable field that
uses a SQL expression to derive its value, which can be used for SQLbased formatting, including combining values from multiple database
columns into one logical DataSource field. For example, the following
field definition would combine firstName and lastName columns at the
database:

Applied in combination, the custom..Expression properties can be used to
create a field that uses SQL expressions to map between a stored SQL
value and the value you want to use in SmartClient UI components. This
can be used to handle legacy formats for date values, database-specific
variations of boolean storage including “bit vector” columns, and other
use cases. For example, you might store a price in cents, but want to work
in the UI in terms of dollars:

Isomorphic Software

SmartClient Quick Start

Before using these properties, take a look at DataSourceField.
sqlStorageStrategy, which encapsulates some common scenarios as a
single setting.
For more information on SQL Templating, see:
SmartClient Reference – Client Reference > Binding >
DataSource:
DataSourceField.customSQL
OperationBinding.customCriteriaFields
DataSourceField.customSelectExpression
DataSourceField.sqlStorageStrategy
For a sample of SQL Templating involving a complex, aggregated
query that still supports paging and search, see:
SmartClient Enterprise Showcase:
http://www.smartclient.com/index.jsp#dynamicReporting

Why focus on .ds.xml files?
Having read about operation bindings, declarative security, dynamic
expressions and SQL Templating, you probably now realize that 95% of
common web application use cases can be handled with simple settings in
a .ds.xml file. This short section is a reminder of why this brings
tremendous benefits.
Declarative
Far more compact than creating a Java class to hold equivalent
logic, and can be read and understood by people who would not be
able to read equivalent Java, such as QA engineers, UI engineers
or product managers with XML and SQL skills.
Centralized
Security rules and other business rules appear right in the
business object definition, where they are more easily found.

Isomorphic Software

SmartClient Quick Start

Secure
.ds.xml files are evaluated server-side, so all business

rules
declared there are securely enforced. By driving client-side
behavior from secure server declarations, you avoid the common
error of implementing a business rule client-side only, and
forgetting to add server enforcement.
Further, the DataSource definition delivered to the client
automatically omits all declaration that only drive server-side
behaviors (such as DMI), so there is no information leakage.
Finally, in sensitive contexts like SQL Templating, automatic
quoting is applied, making it far more difficult to accidentally
create common security flaws like SQL injection attacks.
Faster development cycle
To test new functionality in a DataSource .ds.xml file, just reload
the web page—the SmartClient server framework automatically
notices the modified DataSource. No compilation and deployment
step required.

Custom DataSources
You can create a DataSource that calls existing business logic by simply
using DMI to declare what Java method to call for each operation. This is
a good approach if you have only a few DataSources, or while you are still
learning the basics.
However, SmartClient allows you to create a custom, reusable DataSource
classes in Java, which can then be used with an unlimited number of
.ds.xml files. Do this when:
you have several DataSources that all use a similar
persistence approach, and DMI declarations and associated
code would be highly repetitive
you are using a built-in DataSource such as SQLDataSource,
but you would like to extend it with additional behaviors
In both cases, you use the serverConstructor attribute of the
tag to indicate the Java class you would like to use. Your
Java class should extend the DataSource class that you are using for
persistence, or, if writing your own persistence code, extend
com.isomorphic.datasource.BasicDataSource.

Isomorphic Software

SmartClient Quick Start

Providing responses from a custom DataSource works similarly to DMI—
there are 4 methods on a DataSource, one per DataSource operation type,
each of which receives a DSRequest and returns a DSResponse. They are
executeFetch, executeUpdate, executeAdd and executeRemove.
If you are extending a built-in DataSource that provides persistence, you
can override one or more of these methods, add your custom logic, and
call the superclass implementation with the Java super keyword.
If you are implementing your own persistence, you need to provide an
implementation for each of the operations you plan to use. Once these
methods are implemented, convenience methods such as
DataSource.fetchById() become functional automatically. Use
getFieldNames(), getField() and the APIs on the DSField class to
discover the field definitions declared in the .ds.xml file. You can return
data in the DSResponse in exactly the same formats as are allowed for DMI.
A fifth override point, DataSource.execute(), can be used for common
logic that should apply to all four DataSource operations. The execute()
method is called before operation-specific methods such as
executeFetch() and is responsible for invoking these methods. Here
again, use super to allow normal execution of operation types you don’t
wish to centrally customize.
You can also add custom attributes to your DataSource
.ds.xml file. The APIs DataSource.getProperty() and
DSField.getProperty() allow you to detect added attributes
at the DataSource and DataSourceField level respectively.
Use these attributes to configure your persistence behavior
(for example, the URL of a remote service to contact) or use
them to control additional features you add to the built-in
persistent DataSources.
For more information on creating custom DataSources, see:
SmartClient Reference - Concepts > Custom Server
DataSources

100

Isomorphic Software

SmartClient Quick Start

Generic RPC operations (advanced)
Generic RPCs allow you to make arbitrary service calls and content
requests against any type of server, but they also require you to
implement your own request/response processing and GUI integration
logic.

User action
(eg ListGrid scrolled)

Client
GUI

DataSource
operation
DSRequest

SmartClient
server
DSRequest

Other server
(JSON, XML,
SOAP)

Program action
(explicit method call)

Generic RPC
RPCRequest

SmartClient
server
RPCRequest

Server
Data &
Services

Other server
(any content)

RPC operations sent to the SmartClient Java Server can use DMI
declarations to route requests to appropriate server-side code, or a
custom servlet can interact with the server-side RPCManager class to
receive the RPCRequest.
For information about implementing RPCs with the SmartClient
server, see the client and server documentation for DMI,
RPCManager, RPCRequest, and RPCResponse:
SmartClient Reference → Client Reference → RPC
JavaDoc for com.isomorphic.rpc
examples/server_integration/custom_operations/ shows how to

implement, call, and respond to generic RPCs with the SmartClient
Java Server

101

Isomorphic Software

SmartClient Quick Start

RPC operations can also be performed with non-SmartClient servers.
If you are using a WSDL-described web service, the operations of that web
service can be invoked either through DataSource binding (as described
under the heading WSDL Integration in the Data Integration chapter), or
can be invoked directly via webService.callOperation(). Invoking
callOperation() directly is much like an RPC operation, in that it allows
you to bypass the DataSource layer and retrieve data for custom
processing.
If you are not using a WSDL-described web service, you can retrieve the
raw HTTP response from a server (in JavaScript String form) by setting
the property serverOutputAsString on an RPCRequest. For an XML
response, you may then wish to use the facilities of the XMLTools class,
including the parseXML method, to process the response.
Responses that are valid JavaScript may be executed via the native
JavaScript method window.eval(), or can be executed automatically as
part of the RPC operation itself by setting rpcRequest.evalResult.
For information about implementing RPCs with non-SmartClient
servers, see:
SmartClient Reference - Client Reference > RPC
SmartClient Reference - Client Reference > Data Binding >
Web Service (for WSDL-based RPCs)

102

Isomorphic Software

SmartClient Quick Start

10. Extending SmartClient
SmartClient provides a rich set of components and services to accelerate
your development, but from time to time, you may want to extend outside
the box of prefabricated features. For example, you might need a new user
interface control, or special styling of an existing control, or a customized
data-flow interaction. With this in mind, we have worked hard to make
SmartClient as open and extensible as possible.
An earlier chapter (SmartClient Server Framework) outlined the
approaches to extending SmartClient on the server. This chapter outlines
the customizations and extensions that you can make on the client.

Client-side architecture
The SmartClient client-side system implements multiple layers of services
and components on top of standard web browsers:

Application
Components

Application
Services

Virtual Browser
Layer

Foundation
Layer

103

Controls

Editors

Forms

Grids

Visualization

Containers

Navigation

Collections

Design

Skinning

Layout

Localization

Drag & Drop

Data Binding

Context Menus

Rendering

Event Handling

Browser Utilities

Communication

Timing

Accessibility

Object Utilities

Data Structures

Class System

Language Extensions

Logging & Debugging

Isomorphic Software

SmartClient Quick Start

From the bottom up:
The Foundation Layer extends JavaScript to make it a
viable programming language for enterprise applications.
SmartClient adds true class-based inheritance, superclass
calls, complex data structures, logging and debugging
systems, and other extensions that uplift JavaScript from a
lightweight scripting language, to a serious programming
environment.
The Virtual Browser Layer handles the most difficult
part of rich web application programming—the vast
collection of workarounds to avoid browser-specific bugs,
and to implement consistent behavior across all supported
browser types, versions, and modes. SmartClient makes web
browsers appear to have standard rendering, event
handling, communication, timing, and other behaviors—
behaviors are not fully specified by web standards, or not
implemented consistently in real web browsers.
The Application Services layer provides higher level
services that are shared by all SmartClient components and
applications. This sharing radically reduces the footprint
and complexity of rich web application code.
The Application Components layer provides the prefabricated visual components—ranging from simple buttons,
to interactive pivot tables—that you can assemble and databind to create rich web applications.
Earlier chapters of this guide have dealt primarily with the component
layer—because most application development uses pre-fabricated
components, most of the time. But all of these layers are open to you, and
to third-party developers. If you need a new client-side feature, you can
build or buy components that seamlessly extend SmartClient to your exact
requirements. The following sections detail how.

Customized Themes
The first way to extend a SmartClient application is to change the overall
look-and-feel of the user interface. You can “re-skin” an application to
match corporate branding, to adhere to usability guidelines, or even to
personalize look & feel to individual user preferences.
The SmartClient SDK includes example themes (a.k.a. “skins”) for you to
explore. Use the Showcase to browse through each theme.

104

Isomorphic Software

SmartClient Quick Start

You can specify a different user interface theme in the header of your
SmartClient-enabled web pages:
In the isomorphic:loadISC tag, set the skin attribute to the
name of an available user interface skin, e.g.
skin="SmartClient".
In a client-only header, change the path to load_skin.js, e.g.

Smart Client Quick Start Guide

SmartClient_Quick_Start_Guide

Navigation menu

Versions of this User Manual:

Views

Navigation