Download - Adobe Dream Weaver Developer Toolbox Help

USING THEADOBE® DREAMWEAVER® DEVELOPER TOOLBOX

© 2007 Adobe Systems Incorporated. All rights reserved.Adobe® Dreamweaver® Developer Toolbox User Guide for Windows® and Mac OSIf this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or trans-mitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorpo-rated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner.Any references to company or person names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization or person.Adobe, the Adobe logo, Dreamweaver, Flash, ColdFusion, and JRun are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple and Mac OS are trademarks of Apple Inc., registered in the United States and other countries. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

iii

Contents

Chapter 1: OverviewIntroduction to the Developer Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Minimum requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2: Configuring Developer ToolboxDeveloper Toolbox Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Site-specific settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Dreamweaver-specific settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Developer Toolbox advanced configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3: Dynamic FormsBuild insert/update/delete forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Make existing forms dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Build dynamic forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Add actions to dynamic forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Advanced operations on dynamic forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Many-To-Many wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Build master-detail lists and forms with PHP_MySQL server models . . . . . . . . . . . . . . . . . . . . . . . . 85

Chapter 4: Validate Form InputForm Validation in wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Validate Form server behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Advanced validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Check Multiple Unique Key (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Check Forbidden Words (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Secure forms with Captcha (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Convert to XHTML (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Compare Transaction Fields (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 5: Form ControlsMasked Text Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Numeric Text Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Smart Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Autocomplete Text Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Date Picker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Restricted Textarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Editable Drop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Dependent Drop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Multi-field Drop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Comma-separated Checkboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Comma-separated Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Comma-separated Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

List Sorter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

iv

Chapter 6: File ManipulationUpload Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Download Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Delete Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Download Files (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Delete Folder (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Multiple File Upload (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Chapter 7: Image ManipulationUpload and resize images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Display dynamic images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Display dynamic thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Multiple Image Upload (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Show Media Object (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Multiple Image Upload with Save to Database wizard (PHP_MySQL server model) . . . . . . . . 188

Chapter 8: Retrieve Dynamic DataRetrieve data from databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Developer Toolbox Dynamic Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Transaction Engine generated variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Chapter 9: Display Dynamic DataFront-end dynamic lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Advanced operations on front-end lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

File List Recordset (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Alternate Row Color (PHP_MySQL server model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Back-end dynamic lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Developer Toolbox formats in the Bindings tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Chapter 10: User AuthenticationBuild a user registration page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Build a login form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Restrict access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Logout the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Advanced user login actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Chapter 11: Conditional OperationsShow If Conditional Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Show If Field Has Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Show If File Exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Show If User Is Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Chapter 12: Send MailSend E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Send E-mail To Recipients From Recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Send Page Section By E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

v

Chapter 13: Reuse content with server-side includesServer-side Include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Server-side Includes From Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Server-side Includes From List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Chapter 14: CSS SkinsCreate your own skin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Chapter 15: Export Recordset As XMLAbout the XML Export extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Exporting a recordset as XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Chapter 16: Custom transactions and triggersExecute SQL queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Use transaction fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Add and set transaction fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Check unique key for multiple fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Save additional information on login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Chapter 17: Understanding the Transaction EngineWhat is the Transaction Engine? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Error handling in Transaction Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Extend Transaction Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Transaction recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

How user interface persistence works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

DEVELOPER TOOLBOXUser Guide

1

Chapter 1: Overview

Welcome to the Adobe® Dreamweaver®Developer Toolbox. This chapter provides a brief introduction to the Developer Toolbox and describes the system requirements.

The chapter contains the following topics:

• “Introduction to the Developer Toolbox” on page 1

• “Minimum requirements” on page 2

Introduction to the Developer ToolboxThe Adobe Dreamweaver Developer Toolbox adds a new tab called Developer Toolbox to the Insert bar of Adobe Dreamweaver CS3.

If you configured your Insert bar to not show tabs, click the Insert bar popup menu and select the Developer Toolbox category. The Developer Toolbox also adds a series of server behaviors to the Server Behaviors panel (Window > Server Behaviors). Click the Plus (+) button and select Developer Toolbox from the popup menu.

The Developer Toolbox contains the following modules:


2

• File Upload allows file and image upload in your dynamic site, creates thumbnails on demand, shows images, and allows secure file download. For more information, see “File Manipulation” on page 153 and “Image Manipulation” on page 173.

• Form Validation helps you create usable forms that prevent users from entering the wrong information. For more information, see “Validate Form Input” on page 89.

• Send E-mail lets you stay in touch with your site users by sending e-mail messages after a form is submitted, after user registration, or after placing an order or making a purchase. For more information, see “Send Mail” on page 271.

• User Login helps you create user registration forms and protect areas of your site from unauthorized access. For more information, see “User Authentication” on page 244.

• Form Controls lets you build richer Internet applications by providing you with controls such as cascaded menus, editable drop-down menus, date pickers, numeric text fields, masked text fields, and others. For more information, see “Form Controls” on page 123.

• Dynamic Lists and Forms lets you build dynamic lists with filtering and sorting capabilities, as well as multi-purpose forms. For more information, see “Dynamic Forms” on page 24.

• Query Builder (QuB) lets you visually generate complex recordsets that can be used in Dreamweaver. For more information, see “Retrieve Dynamic Data” on page 192.

• Advanced Repeated Regions provides improved functionality when working with nested repeated regions and horizontal loopers. For more information, see “Advanced operations on front-end lists” on page 217.

• Server-Side Includes offers a fast and efficient way to include reusable code blocks in Dreamweaver. For more information, see “Reuse content with server-side includes” on page 285.

• XMLExport lets you export the content of a recordset as XML. The XML can then be consumed by pages that use XML data sources, such as pages with Spry data sets. For more information, see “Export Recordset As XML” on page 296.

• The Transaction Engine is included in most of the Developer Toolbox modules. Find out more about the core of Developer Toolbox by reading “Understanding the Transaction Engine” on page 312.

Minimum requirements

Browsers• Microsoft Internet Explorer 6 and 7

• Firefox 1.5.x and 2.0

• Safari 2.0

Note: Query Builder is compatible with Internet Explorer 6.


3

Form controls are compatible with the following browsers:

For dynamic lists and forms, the following behaviors will not function properly on Macintosh platforms using the Microsoft Internet Explorer 5.2 browser:

• Multiple update transaction (multiple edit)

• Multiple insert transaction (add multiple records)

• Multiple delete transaction (delete one or more records from the dynamic list).

Dreamweaver CS3The Developer Toolbox is compatible only with Adobe Dreamweaver CS3. It will not work with previous versions of Dreamweaver.

Web server with scripting language support

PHP 4.4.0 or laterWeb Servers:

• Internet Information Services (ISAPI | CGI) (5.1 or 6)

• Apache (1.3.x or 2.0)

Image processing libraries:

• GD

• ImageMagick (with execute permissions) . Version 6.2.5 or higher is recommended. The Expat and mbstring libraries must be installed and enabled. Expat is an XML parser library that is typically included in most server installations. The mbstring library handles multibyte encodings in PHP.


4

Note: Each library has limitations regarding what image handling operations it can perform, and image-supported image types. See the Developer Toolbox on-line documentation and tech notes for more information.

ColdFusion MX or laterWeb Servers:

• Internet Information Services

• Apache (1.3.x or 2.x)

• JRun.

Image processing libraries:

• tmt_img (Massimo's lib)

• ImageMagick Version 6.2.5 or higher is recommended

• CFX_Image 1.4.9 Jukka Manner

• CFX_imageCR3 3.1.


Execute permissions:

• required tags/functions: createobject, shell rights on image lib

• cfexecute must be allowed on the server.

ASP VBscriptWeb Servers:

• Internet Information Services.

Versions:

• 5.1 - Windows XP (Professional)

• 6.0 - Windows 2003.

Required configuration for web server:

• Enable CreateObject rights.

• FileSystemObject is required.

Note: If the ParentPaths options is disabled, you have to set Dreamweaver to use Server relative paths instead of document relative paths. Read this technical note for details.

Scripting Technologies

ASP - 3.0

VBScript - 5.5+. Image processing libraries:

• .NET framework installed and ASP.NET extension enabled for IIS

• MSXML 2.6+


5

• WScript.Shell

• ImageMagick. Version 6.2.5 or higher is recommended.

Note: Components 2 and 3 are installed by default on any of the supported operating systems.


Other components:

• Collaborative Data Object (for sending e-mail).

Note: This component is installed by default on any of the supported operating systems.

6

Chapter 2: Configuring Developer Toolbox

This chapter describes how to configure Adobe® Dreamweaver® Developer Toolbox. This chapter contains the following sections:

• “Developer Toolbox Control Panel” on page 6

• “Site-specific settings” on page 6

• “Dreamweaver-specific settings” on page 21

• “Developer Toolbox advanced configuration” on page 23

Developer Toolbox Control PanelThe Developer Toolbox Control Panel is the central point for configuring Developer Toolbox. The Developer Toolbox Control Panel lets you update your modules, delete the database cache, set the development or production mode for your website, and configure error message logging.

The Developer Toolbox Control Panel is accessible from two locations:

• By clicking the Control Panel button in the Developer Toolbox category of the Insert bar,

• By clicking the Plus (+) button on the Server Behaviors panel (Window > Server Behaviors), and then selecting Developer Toolbox > Control Panel.

The Control Panel options are organized into two main groups:

• Current site settings - changes made to these options effect only the current site.

• Dreamweaver settings - changes made to these options effect all of your web sites.

Site-specific settingsThis site settings you cna specify for the current web site are:

• Date formats - the format you use in the database and the format you wish to display on your web pages (e.g. mm/dd/yyyy)

• Language settings - lets you specify a lnguage to use for a given web site if using different languages, set the current one here.

• Debugging mode - lets you specify the error display options.

• Update includes folder - updates the files contained in the includes folder of the site in order to synchronize the local and testing servers.

• Login settings - configure the unified login options.

• Required server libraries - lets you specify the image processing library to use when resizing or creating thumbnail images.


7

• E-mail settings - lets you specify your mail server options.

• CSS Skins - lets you specify a CSS skin for your web site.

Date formatsIn order to better display date and time, Developer Toolbox allows you to specify the date formats used in the database and in the web application pages displayed by the browser. These options can be set from the Developer Toolbox Control Panel in the Date Formats section.

The database format is the format used for storing, editing, and retrieving date information from the database. The database format is not detected automatically from your current database settings. You should know how date and time are stored in your database, then select the same for the database format in the Developer Toolbox Control Panel. If the database format specified in the control panel is different from the database format actually used, your application may crash ,or information may become incorrect or corrupt.

The screen format is the format used for displaying date and time information from the database in your web appli-cations. This is the also the format that users of your applications will have to use when filling in web forms. The screen format is translated into database format and vice-versa, depending on your actions. You should remember that the database format is the way you store information, while the screen format is the way you see information.

The user interface is organized into two sections: one regarding the database date and time formats, and one referring to the screen date and time formats (the formats used on page).

To set the dialog box options:1 In the Date format drop-down menu (of the database section) select the format used in the database.

2 In the Time format drop-down menu (of the database section) select the format used by the database to store the time.

3 In the Date format drop-down menu (of the screen section) select the way you want to display dates in your pages.

4 In the Time format drop-down menu (of the screen section) select the format to use when displaying time on your pages.

5 The three buttons on the right of the interface offer you the next functionality:

• Click OK when you are done configuring the dialog box.

• Click Cancel to exit without changing the date formats settings.


8

• The Help button takes you to this help page.

The characters used in date formats mean the following:

• d: Day of the month as digits, without leading zero for single-digit days.

• dd: Day of the month as digits, with leading zero for single-digit days.

• m: Month as digits, without leading zero for single-digit months.

• mm: Month as digits, with leading zero for single-digit months.

• yy: Year as last two digits.

• yyyy: Year represented by four digits.

The characters used in time formats mean the following:

• h: Hours, without leading zeros for single-digit hours (12-hour clock).

• hh: Hours, with leading zeros for single-digit hours (12-hour clock).

• H: Hours, without leading zeros for single-digit hours (24-hour clock).

• HH: Hours, with leading zeros for single-digit hours (24-hour clock).

• mm: Minutes, with leading zeros for single-digit minutes.

• ss: Seconds, with leading zeros for single-digit seconds.

• t: One-character time marker string, such as A or P (for ante-meridian, and post-meridian).

• tt: Two-character time marker string, such as AM or PM (for ante-meridian, and post-meridian).

Language settingsSince the Transaction Engine includes internationalization support, this menu of the Developer Toolbox Control Panel enables the user to change the language resource file of the currently active site:

To set the dialog box options:1 In the Select site language drop-down menu select the current site language from available languages: English, French, Italian, German, Spanish, Dutch, Swedish.

2 The three buttons on the right of the interface offer you the next functionalities:


• Click Cancel to exit without changing the date formats settings.


When switching the language for your site, only the following elements will change:


9

• General and field error messages - the error messages displayed on top of the page, as well as those that are displayed next to each field.

• Validation hints (the text that is displayed next to a filed that has a validation rule applied)

Note: When performing an update of Developer Toolbox, the resources files will not be overwritten. If you are missing newly added resources, and do not have any important customizations made (eg. custom error messages), the easiest way to update these files is to switch the site language from your current one to another (eg. from English to French- which will overwrite the existing English resources with the new, but French ones), and another switch back to the original (eg. from French back to English). The new resources will be copied onto your site's resources folder.

Note: If you want to translate Developer Toolbox messages into your language, you will have to edit the files that are located in your site folder, in includes/resources. Each of the files contains the string messages used by Developer Toolbox components (eg. the tng.res.php file contains the messages used by the transaction engine, while wdg.res.php contains the error messages for the Forms Controls module). Make sure that the language you need doesn't already exist before starting work.

Debugging modeThis user interface allows setting the debugging mode to either Production or Development, as well as configuring some particular options. To understand the specifics of these two debugging modes, please see “Development mode error handling” on page 330 and “Production mode error handling” on page 331.

In the Debug mode drop-down menu select the debugging mode to use for the site. There are two modes available: Development and Production.

The Error reporting drop-down menu is enabled when your debug mode is the Production one. Select where to save data about errors:


10

None information about the errors that occurred is not kept.

To file all error data is saved in a log file inside the includes folder (includes/tng/logs).

By email an e-mail message containing the error detail is sent. When selecting this option, the following fields are enabled.

1 In the Email log to text-box, enter the email address where the error logs will be sent.

2 In the Subject text-box enter a subject for the mail. It should be a suggestive one, to make it easier to find.

3 In the From text-box enter the source email address.



• Click Cancel to exit without changing the debugging mode settings.


In order for the change of the debugging mode to take effect, you must upload the includes folder to the remote site.

To get a preview of how errors are handled in each of the two debugging modes, notice the next two images.

This image illustrates the occurred error when the debugging mode is Development:


11

This image illustrates the occurred error (same as above) when the debugging mode is Production:

Update includes folderThis menu enables you to update the includes files of the current site. The interface consists of a table with four columns ("Product name", "Installed version", "Site version", and "Update site version") that lists the installed modules on the local computer and the modules that are used in the current site (with their corresponding version).

The command will check if the installed version of a module is newer than the one used in the site, and it will update it if you choose to.

To set the dialog box options:1 Analyze the first three columns of the table and, if the installed version of a module is newer than the site version (compare the two versions by following the table rows), the checkbox on the fourth column is automatically checked. If you want to update all the modules, check the rest of the checkboxes (for the modules that are not on your site). All the checked modules will be updated.

2 The three buttons on the right of the interface offer you the next functionalities: 2 Use the Update selected button to have the 'includes' files updated (the files corresponding to the checked boxes in the fourth column of the table). The updating takes place by overwriting the versions used in the site with the ones from the local computer.

• Click Cancel to exit without updating the 'includes' folder.


When you update the includes folder, the resource files and the configuration files (the settings chosen in the Developer Toolbox Control Panel) are not overwritten, so you will not lose your current resources (labels, messages etc) and settings.

Login settingsThis section of the control panel allows you to define all options regarding the login action for your site in a single, unified location. You will define everything from the table that stores the user data, to the session variables used in the page.

The user interface is divided into four tabs, each allowing you to set some specific options in regards to the login action:

• The Options tab - set general options here.

• The Database tab - set the database table and fields storing user data.


12

• The Session tab - define what session variables to set, and what their content will be.

• The User Levels tab - set options for each user level.

• The Restrictions tab - set extra options to be used with user conditional blocking. This tab is only available for the PHP_MySQL server model.

• The History tab - set options for user activity logging and statistics. This tab is only available for the PHP_MySQL server model.

The Options tabThis tab allows you to set general options regarding the login action:

To configure this dialog box:1 With the Encrypt password checkbox, you can decide whether to store the passwords as plain text, or using encryption.

2 In the Validate against radio buttons, select what criteria will be used to validate the user data: you can select between Username/Password and the more complex Username/Password/Level.

3 In the Auto login validity text-box, enter the number of days for which the auto login feature will be valid. After this period ends, users will not be automatically logged in when they attempt to visit a page with restricted access, but will be prompted to authenticate first.


13

The Auto login cookie lasts 30 days from the last visit of the user. This means users who visit a website daily are virtually never required to authenticate.

4 The three buttons on the right of the interface offer you the next functionality:


• Click Cancel to exit without changing the login settings.


These buttons are common to all tabs of the Login settings interface.

5 Click on the Database tab to continue configuring the Login settings.

The Database tabThis tab allows you to set up the database and table that stores user data:

To configure this dialog box options:1 In the Connection drop-down menu, select the database connection used for your site.

2 In the Table drop-down menu, select the database table that stores user details.

3 In the Primary key drop-down menu, select the field that stores the primary key for the selected table.

4 In the Username drop-down menu, select the table field that stores the user names. The table column should be set as a UNIQUE Key in the database structure, to prevent duplicate entries that will lead to a non-functional login.


14

5 In the Password drop-down menu, select the table field that stores the user passwords.

6 In the E-mail drop-down menu, select the table field that stores the user's e-mail address.

7 In the Active drop-down menu, select the field that stores the activation state for the user. If no table column is selected in the drop-down menu, the Activation feature will not be available for use in the current application.

8 In the Level drop-down menu, select the table field that stores the user level.

9 In the Random key drop-down menu, select the table field that stores the randomly generated key used when activating the account.

Activation links that use a random key look like this: http://www.yourdomain.com?activate.php?kt_login_id= 3&kt_login_random=3f6de6ea7e1a5897bec5fe997923412c.

Because of the random key that is attached at the end of this URL, this address is virtually impossible to guess. This means other users will not be able to activate your account just by entering the URL address in the browser or use your e-mail address to create accounts. When the user clicks on such a link, aside the account being activated, an automatic login will be performed as well.

10 When done with the database settings, move on to the Session tab.

The Session tabThis is where you can configure what will be stored in session variables for each user that logs in successfully:

To configure this options tab, follow the steps below:


15

1 In the Session variables grid, all session variables and their associated table columns are displayed. You can add or remove an entry by using the +/- buttons. You can only add session variables while there are table columns left unused. The table columns are taken from the user table selected in the Database tab.

You can edit the properties of the session variables that you added to the grid. Select the variable in the grid, then use the Session variable name and Table column text-boxes to set its corresponding options.

Note: These two text boxes are disabled for the session variables that were automatically generated (according to your selection in the Validate against radio buttons of the Options tab).

2 Click on the User levels tab to continue configuring the Login settings.


16

The User Levels tabIn the User Levels tab, you can select global redirect options, as well as redirect options for each user level. Also, this is the place where you can define the user levels to compare against the ones stored in the database:

To configure this user interface:1 In the Login page text-box enter the page that allows the user to login.

2 In the Default redirect on success text-box enter the page that will be opened if the login operation succeeded.

3 In the Default redirect on fail text-box enter the page to be opened when a user tries to access a page for which he/she does not have the needed credentials.

4 In the User levels grid, all defined user levels and their associated redirect pages are displayed. You can add or remove user levels through the +/- buttons on top of the grid. To edit options for any of the user levels, select it from the grid, and set its options in the following text-boxes:

• In the Level text box enter a number (e.g. 0, 1, 2 etc) that would indicate the access level.

• In the Redirect on success text-box, enter the page to open if the login operation for the selected user level is successful. You can use the Browse button to locate the file.

• In the Redirect on fail text-box, enter the page to open if the login operation fails for the selected user level. You can use the Browse button to locate the file.

5 Click OK when you are done configuring the dialog box.


17

The Restrictions tabIn the Restrictions tab you can set options that block users, enable expiration dates for accounts and enforce a maximum number of login tries. This extra tab of the user interface is available only for the PHP_MySQL server model.

To configure the user interface: 1 If you want to allow users only a limited number of login attempts, tick the Limit the login attempts checkbox.

2 In the Allowed attempts text field enter the number of login attempts that an user is allowed to make.

3 In the Login attempts column drop-down menu select the table column used to store the number of login attempts. The field must be set to store integer numbers and have enough length to store the maximum number of tries.

4 In the Disable interval text field enter the duration - in hours - for which the user that has used up the maximum number of attempts is not allowed to login. The minimum is 1 hour.

5 In the Disable date column drop-down menu select the table column used to store the date when the user is allowed to login again.

6 If the account has to expire after an interval, and the user will no longer be allowed access through the login (e.g. for a limited time trial, or demo) tick the Enable account expiration checkbox. This will enable the second set of settings.

7 In the Account expiration column enter the table column where the duration of the account availability is stored.


18

8 In the Default expiration interval text field enter the interval, in days, for which the account is active. After this period passes, the user is no longer allowed access.

9 In the Registration date field drop-down menu select the table field into which the date and time when the user has registered is saved.

The History tabThe History tab allows you to set options on what user action to log, and into which database. You can configure options to allow you to build statistics reports for user activity. This set of options is available only if you have the PHP_MySQL server model.

To configure the user interface: 1 First decide whether you want to use the logging capabilities provided by Developer Toolbox. To save your choice, tick the Use logger feature checkbox. This will enable adding transparent triggers to the login and logout actions which save information to the database.

2 In the Table drop-down menu select the database table that you want to save the logging information into. The table must be related to the user table through a column.

3 In the Primary key drop-down menu select the log table's primary key column.

4 In the Foreign key to users' table drop-down menu select the table column that will store the relation between the user information table and the log table.


19

5 In the IP address drop-down menu select the table column into which to save the user's IP address. The column must allow at least 30 characters.

6 In the Last login date drop-down menu select the table column into which to save the date and time when the user last logged in.

7 In the Last activity date drop-down menu select the table column to store the date and time when the user last left the site - through a logout.

8 In the Session drop-down menu select the table column to store the length of the user session.

Required Server LibrariesTo be able to apply the resize or thumbnail creation operations on images, your web-server must have one of the supported image processing libraries installed and properly configured. Through this control panel option you can set what image library is installed on the server. Also, you can set the path to the external library is any, and the path to the Tidy executable if available. The Tidy program allows you to clean up HTML content.

The following options can be set:

1 In the Preferred library drop-down menu you can see a list of the libraries on server. Select the one to be used first from the list.

2 In the Library path text-box you can enter the path to the image processing library, if it is installed on the server. It must be specified explicitly, as it is not stored in the web-server's folder.

Note: When entering the path for the image library in the text field, you must take into account the following limitations:

• Folder names with less than 8 characters cannot contain spaces.

• Folder names larger than 8 characters can contain spaces, but they can also be addressed by using the short MS-DOS notation (e.g. Progra~1 instead of Program Files).

Note: If you use ImageMagick, you must specify the path to the library executable file. Otherwise, you will not be able to use this image processing library. The path must be absolute, not relative to the current site. For instance, on Windows systems, it can be C:\Program Files\ImageMagick\bin\, and on UNIX systems, it can be /usr/local/bin/ or /urs/bin/.



• Click Cancel to exit without changing the server libraries settings.



20

4 The Tidy text box allows you to enter the path to the HTML Tidy program. You should only enter the path on the server, without the actual file name or the trailing \ sign.

E-mail settingsIn this control panel section you can define the mail server options to use when attempting to send an e-mail message. They are useful when the Debug mode is set to send the log to e-mail, send e-mail triggers, or any other component that makes use of the mail server.

The following options can be set:

1 In the Mail server text-box enter the IP address or hostname of your mail server; if the mail server resides on the same machine as the web-server, use localhost.

2 In the Port text-box enter the SMTP port used by your server. This is the outgoing port, and not the POP3 one.

3 In the Username text-box, enter the username for the mail server.

4 In the Password text-box enter the mail server password, for the user specified in the text-box above.

5 In the Default sender text-box enter an e-mail address to be used in the From field, when no other option has been specified.



• Click Cancel to exit without changing the e-mail settings.


The setting specified above are valid only for the currently selected site.

CSS SkinsIn order to customize the look of each site created with the help of Developer Toolbox, you can use CSS skins. The skin is globally available, covering most of the Developer Toolbox generated elements: the dynamic lists and forms, the Transaction Engine forms (generated by the Insert/Update Record wizards), the form controlst elements.


21

To select the skin to use for the site, you must use the Developer Toolbox Control Panel > CSS Skins entry. The user interface that opens contains the following elements:

1 In the Select skin drop-down menu select one of the available skins. Skins are stored as folders in includes/skins, and if a new folder is added to the structure, it will be automatically recognized and added to the drop-down menu.

2 In the Preview skin area each skin's preview picture can be seen. The image to be displayed is stored inside each of the skins folders, and it must be created for each new skin. Otherwise, the preview feature will not work properly. Also, the file name is preview.gif.



• Click Cancel to exit without changing the skin settings.


In order for the change to take effect, you must upload the entire skins folder to the remote server.

Dreamweaver-specific settingsThis section presents the following options as Dreamweaver settings:

• User interface persistence and database caching - switch the user interface persistence on or off, as well as the database caching.

• Developer Toolbox Favorites - create shortcuts to your favorite server behaviors and put them in an easy-to-access list.

User interface persistence and database cachingOne of the most important features added in Developer Toolbox is the user interface persistence - an improvement that makes the Dreamweaver interfaces smart by remembering your selections. Thus, when configuring a specific form, the user interface persistence layer will memorize your field settings, and subsequent usages of the same table will require no more configuration from your side.


22

To improve performance when working with database related user interfaces, Developer Toolbox uses a special component called the Database Cacher, which stores meta-data regarding the database structure immediately after the first use in a Developer Toolbox interface. This stores locally information regarding the table names, table primary keys and field types. This way, when another user interface requests meta information regarding the tables, it is retrieved from the local cache without having to make another call to the database server.

The Developer Toolbox Control Panel contains a component that allows you to configure the Database Cacher. The user interface is divided into two areas, depending on the purpose of the enclosed options: The UI persistence or the Database caching.

In this dialog box, the elements have the following role:

1 The Enable user interface persistence checkbox determines whether the user interfaces will have persistence or not. When checked, persistence for the user interfaces is active, and when un-checked, it is not.

2 The Remove data button clears all the persistence data accumulated.

3 The Enable database caching checkbox determines whether meta information regarding the database tables is stored locally or not. Checked means that information is stored.

4 The Empty cache button clears all meta information stored until that moment by the database cacher.



• Click Cancel to exit without changing the persistence and caching settings.


When working with the ColdFusion server model, two additional fields need to be filled in: User name and Password. This is the RDS login information. It is used in order to allow the Developer Toolbox extension to connect to the ColdFusion server, and perform the specific actions (e.g. the retrieval and caching of table information etc.).

If the RDS account information (the user name and password) cannot be provided, or is incorrect, the database caching will not work. However, it will not affect the user interface persistence in any way.

Developer Toolbox FavoritesThis entry in the Developer Toolbox Control Panel lets you select your favorite server behaviors and group them in a list for quicker access. This list can be displayed by clicking on the Favorites icon in the Developer Toolbox category of the Insert bar.

1 In the Categories column on the left of the interface, a dynamic list of tree menus is displayed.

• This list is retrieved in concordance with the Developer Toolbox entries from the Server Behaviors tab of the Application panel, in Dreamweaver.

• These tree menus can have one or more levels depending on the levels of the menu options in the entries. When clicking on the '+' icon of a tree menu, the options that expand are the exact ones from the menu in the Server Behaviors tab.

• All the available server behaviors are grouped in categories.

2 When clicking on a server behaviors category, its name will be displayed in bold on the right part of the interface.

• Below the category name, all the server behaviors included in that category will be listed.

• Beside each server behavior (from that category or sub-category, depending on the tree menu level), a checkbox is displayed. By checking it, the respective server behavior is included in you list of favorite and most often used server behaviors.


23

3 The five buttons on the right of the interface offer you the next functionalities:


• Click Cancel to exit without changing your Favorites list.


• The Export button allows you to save (export) the file that contains the favorites list. When clicking Export, the following dialog box will be displayed first:

The backup name is by default the current date, but you can specify any name you want. Then another window is displayed and there you can choose where to save the backup list containing your favorite server behaviors. The default folder is your site root, but you can save it anywhere.

The file format is XML (MXKF-2005-07-29.xml). To see the generated XML, open the file with Internet Explorer.

• The Import button allows you to import an .xml file that includes a favorite server behaviors list (previously saved and then replaced). In the window that opens, select the folder and the respective .xml file, click OK and there you have a new favorite server behaviors list.

4 Afterwards, when displaying the list from the Insert bar, those server behaviors will be listed:

5 If you click the Edit Favorites option in the menu above, the Developer Toolbox Favorite Server Behaviors window will open and you can edit your list.

Developer Toolbox advanced configurationAside the configuration options that can be set through the Developer Toolbox Control Panel, Developer Toolbox also has some advanced configuration variables that did not get a Dreamweaver interface. These settings already have default variables that should work properly for most web sites. If you need to change any of these settings, check out the list of variables and files below for a description on what each variable does.

You can find these configuration settings in the <site root>\includes\common\KT_config.inc.xxx :

1 KT_file_mode - the permission mode which the system tries to apply to an uploaded file. You must use the Unix numbered style. The default is 644.

2 KT_folder_mode - the permission mode which the system tries to apply when creating a folder. You must use the Unix numbered style. The default is 755.

3 KT_default_image_quality - this configuration option is available only for the PHP_MySQL server model. It allows defining the preferred image quality to use when saving an image - a thumbnail is created, a resize takes place, etc. The default value for this option is set to 80, but you can enter any value between 1 and 100.

24

Chapter 3: Dynamic Forms

This chapter provides information on the ways Adobe® Dreamweaver® Developer Toolbox allows the developer to quickly and effectively build dynamic forms that will permit the user to provide input to the application.

This chapter contains the following sections:

• “Build insert/update/delete forms” on page 24

• “Make existing forms dynamic” on page 40

• “Build dynamic forms” on page 49

• “Add actions to dynamic forms” on page 57

• “Advanced operations on dynamic forms” on page 71

• “Many-To-Many wizard” on page 81

• “Build master-detail lists and forms with PHP_MySQL server models” on page 85

Build insert/update/delete formsThis sub-section presents the tools that come with Developer Toolbox and that make it possible to build an entire dynamic form in a single operation. It automatically places all the elements and creates the links between them:

• “Insert Record Form wizard” on page 24

• “Insert Into Two Tables wizard” on page 30

• “Update Record Form wizard” on page 33

• “Delete Record wizard” on page 38

Insert Record Form wizardThe basic building blocks of an insert page can be added in a single operation using the Insert Record Form wizard. The wizard adds an HTML form and a Insert Transaction server behavior to your page. The form objects are laid out in a basic table, which you can customize by using the Dreamweaver page design tools (make sure all the form objects remain within the form’s boundaries). To edit the server behavior, display the Server Behaviors list (Window > Server Behaviors) and double-click on the Insert Transaction server behavior.

You can also add the building blocks separately by using the form tools and the Server Behaviors tab of the Appli-cation panel. For more information on building an insert page in multiple steps, see “Insert Record Transaction” on page 40.

The Insert Record Form wizard is accessible from two locations:

• The Developer Toolbox tab of the Insert bar.

• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Insert Record Form Wizard.

The purpose of this wizard is to build a page that enables users to insert new records in a database table. This wizard is divided into two compulsory steps, based on the type of data the user has to input, and an extra step that contains the validation rules for all fields included in the generated form.


25

To build the insert page with the Insert Record Form wizard:1 Open the page in Design view, and then apply the Insert Record Form wizard. A dialog box appears.

2 Complete the dialog box, following the instructions below for each of the three steps:

• Table and redirect information

• Field information

• Form validation rules

3 Click Finish when done.

Table and redirect informationThe first step into completing the dialog box requires the user to input basic information about the transaction, like the table in which new records will be inserted and the page to which it will be redirected:

To set the dialog box options:1 In the Connection drop-down menu select the database connection defined for your site; if you don't have a connection yet, you can use the Define button and create one now.

2 In the Insert into table drop-down menu, select the database table where you want to insert records;

3 In the Primary key column drop-down menu specify the primary key column for the current table. The content of this drop-down menu is refreshed each time the user changes the table for the insert operation. By default, the first element is selected.

4 The Numeric checkbox specifies whether the selected Primary key column has a numeric type (integer, double, etc). The state for this checkbox is altered each time the user changes the selected value of the Primary key column according to the meta-data retrieved by Dreamweaver for the specified table column.


26

5 In the After inserting, go to text box enter the page to be opened after the record is inserted into the table, click the Browse button to select the file page or use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the file name.

6 The five buttons in the lower part of the interface offer the following functionalities:

• With the < Back / Next > buttons you can navigate through the wizard's steps.

• Click Finish when you are done configuring the wizard.

• Click Cancel to exit without the new settings to be applied.

• The Help button brings you to this help page.

These buttons appear on all three interfaces of the Insert Record Form wizard.

7 Click Next to continue with configuring the wizard.

Fields informationThis dialog box allows you to define exactly which fields get which data and where they get it from. This is where you will determine how an input for a specific field will be displayed as:

To set the dialog box options:1 In the Form fields area specify the form objects you want to include on the HTML form of the insert page, and which columns in your database table each form object should update.

By default, Developer Toolbox creates a form object for each column in the database table. If your database automat-ically generates primary key ID's for each new record created, remove the form object corresponding to the primary key column by selecting it in the list and clicking the Minus (-) button. This eliminates the risk of the user entering an ID value that already exists.


27

Use the Plus (+) button to add form fields to the current transaction.

You can also change the order of the form objects on the HTML form by selecting a form object in the list and clicking the up and down arrows on the right top side of the dialog box.

2 Specify how each data-entry field should be displayed in the HTML form by selecting a row (single click) in the Form fields area and entering information in the boxes below the grid as indicated below.

3 In the Label text box enter a descriptive label to display beside the data-entry field. By default, the column’s 'generic name' is displayed (Developer Toolbox removes the part in the column name that starts with "_" and capitalizes the first part).

4 In the Display as drop-down menu select a form object to serve as the data-entry field. You can select from the following list: Text field, Text area, Menu, Hidden field, Checkbox, Radio group, Password field, Text, File field. Depending on your selection, the interface changes:

1. Text field If you select this option, the following interface fields will be displayed:

• In the Submit as drop-down menu select the data format accepted by your database table. For example, if the table column only accepts numeric data, select Numeric. The available options are: Text, Numeric, Double, Date.

Note: If you are using a Microsoft Access database, in the Submit as drop-down menu, another option will be available: Date MS Access. Select this option when submitting date fields.

• In the Default value text box specify the default value for the selected table column. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the default value.

2. Text area If you select this option, the interface displayed is similar to the one corresponding to the Text field option.

3. Menu If you select this option, the following interface fields will be displayed:

• In the Submit as drop-down menu select the data format accepted by your database table. The available options are: Text, Numeric, Double, Date.

• If the case, use the Add Recordset button to create a recordset from which the menu should retrieve data later on:


28

• Click on the Menu Properties button to populate the menu items. You can this dynamically, by using a recordset, or statically (manually):

4. Hidden field If you select this option, the interface displayed is similar to the one corresponding to the Text field option. There is a difference though, namely the fact that the Label text box is now disabled, given the fact that the field is hidden.

Note: Hidden fields are inserted at the end of the form.

5. Checkbox If you select this option, the following interface fields will be displayed:

• In the Submit as drop-down menu select the available option that fits your needs the best: Checkbox: Y,N; Checkbox: 1,0; Checkbox:-1,0.

• In the Initial State radio group select whether or not you want the control to be checked by default or not.

6. Radio group If you select this option, the following interface fields will be displayed:

• In the Submit as drop-down menu select the data format accepted by your database table. The available options are: Text, Numeric, Double, Date.


29

• By clicking the Radio Group Properties button you can set all the available options that you need for you radio group:

7. Password field If you select this option, the interface displayed is similar to the one corresponding to the Text field option.

8. Text If you select this option, the interface displayed is similar to the one corresponding to the Text field option. Note: For read-only entries, select Text.

9. File field If you select this option, the following interface fields will be displayed:

• In the Submit as drop-down menu there is only one available option: File.

5 You can use the Back button to alter the table and redirect information. If you do not wish to validate the user input, you can click on Finish to add the Insert Record elements to the page. If you want to go to the third and last step of the wizard, click Next.


30

Form validation rulesThis last step of the wizard configures the validation rules for each of the form input fields. You can define a rule for each form element, so that bad input will be avoided:

For instructions on completing this step, see “Form Validation in wizards” on page 89.

Once you click Finish, a Form Validation trigger, with a validation role, will be added to your page.

Insert Into Two Tables wizardThe purpose of this wizard is to simultaneously insert data into two linked tables. The tables must be in a master-detail relationship. The wizard will add two insert forms into the page, one for the master table, and the other for the detail table. The field containing the link between the tables is automatically filled by the wizard.

The Insert Into Two Tables wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Insert Into Two Tables Wizard.

To use the Insert Into Two Tables wizard:1 Create two tables that are in a master-detail relationship, through the use of a foreign key.

2 Apply the Insert Into Two Tables wizard from the Developer Toolbox tab of the Insert bar.

3 Move on through the wizard's steps by clicking the Next button. Configure each one, as shown in the instructions below:

• Step 1: •select tables to use.

• Step 2: •select master table fields.


31

• Step 3: •select detail table fields

• Steps 4 and 5: •set validation options.

4 When all desired options have been configured, click the Finish button to apply the wizard.

The wizard adds two forms in the page, one for the master table and one for the detail table, two Insert Transaction server behaviors and a Link Transactions server behavior, and two additional Form Validation server behaviors, one for each table's fields.

Select tables to useThe first step in the wizard requires the user to select which tables to use. Table information is retrieved through the user interface selected connection:

To set this dialog box's options:1 In the Connection drop-down menu select the database connection you've already created or your site. If you do not have any connections created yet, you can click on the Define button to create it now.

2 In the Master table drop-down menu select the table that acts as the master in the table pair.

3 In the Primary key column drop-down menu select the master table's field that contains the unique, primary key.

4 The Numeric checkbox indicates whether the field selected as a primary key is of numeric type or not. Its state changes when different field types are selected.

5 In the Detail table drop-down menu select the table that acts as the detail in the table pair.

6 In the Primary key column drop-down menu select the detail's table field containing the primary key.

7 The Numeric checkbox indicates whether the field selected as a primary key is of numeric type or not. Its state changes when different field types are selected.


32

8 In the Foreign key column drop-down menu select the detail table's field containing the link to the master table.

9 In the After inserting, go to text-box enter the page which will be opened after the insert operations complete successfully. You can either enter the file name by hand, click the Browse button to search for the file in the local folder structure, or use the Developer Toolbox Dynamic Data lightning icon to construct its name from dynamic variables.






These buttons appear on all five interfaces of the Insert Into Two Tables wizard.


Select master table fieldsThe second step requires the user to configure the master table's field that will be used in the transaction. They will have a visual counterpart in the form, and will be used in the SQL transaction:

To set the dialog box options:1 In the Form fields area specify the form objects you want to include on the HTML form of the insert page, and which columns in your database table each form object should update.


33




2 Specify how each data-entry field should be displayed on the HTML form by selecting a row (single click) in the Form fields area and entering the required information in the boxes below the grid.


4 In the Display as drop-down menu select a form object to serve as the data-entry field for the current selection in the grid. You can choose from the following list: Text field, Text area, Menu, Hidden Field, Check box, Radio group, Password field, Text, File field. To read the detailed description for each of these options, click here.

Set the form object’s properties. You have different options depending on how you want the form field to be displayed as.

5 You can use the Back button to alter the table and redirect information. If you do not wish to validate the user input, you can click on Finish to add the Insert Record elements to the page. If you want to go to the third and last step of the wizard, click Next.

Select detail table fieldsThe third step requires the user to select the detail table's fields to use. It is identical as usage and interface with the second step: Select the master table fields.

Set validation optionsThe fourth and fifth steps allow setting validation options for the master and detail table fields. For instructions on setting the dialog box options, see “Form Validation in wizards” on page 89.

Update Record Form wizardThe basic building blocks of an update page can be added in a single operation using the Update Record Form wizard. The wizard adds an HTML form and an Update Transaction server behavior to your page. The form objects are laid out in a basic table, which you can customize by using the Dreamweaver page design tools (make sure all the form objects remain within the form’s boundaries). To edit the server behavior, display the Server Behaviors list (Window > Server Behaviors) and double-click the Update Transaction server behavior.

You can also add the building blocks separately by using the form tools and the Server Behaviors tab of the Appli-cation panel. For more information on building an update page in multiple steps, see “Update Record Transaction” on page 45.

The Update Record Form wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Update Record Form Wizard.


34

The purpose of this wizard is to build a page that enables users to update records in a database table. This wizard is divided into two compulsory steps, based on the type of data the user has to input, and an extra step that contains the validation rules for all the fields included in the form generated by the wizard.

To build the update page with the Update Record Form wizard:1 Open the page in Design view, and then apply the Update Record Form wizard. A dialog box appears.

2 Complete the dialog box, following the instructions below for each of the three steps:

• Table and redirect information

• Fields information


3 Click Finish when done

Table and redirect informationThe first step into completing the dialog box requires the user to input basic information about the transaction, like the table to be updated and the page to which it will be redirected:


2 In the Update table drop-down menu select the database table into which you want to update records.

3 In the Primary key column drop-down menu specify the primary key column for the current table. The content of this drop-down menu is refreshed each time the user changes the table for the update operation. By default, the first element is selected.


35


5 In the Primary key equals drop-down menu select the way the record ID is passed to the update page (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.

6 In the After updating, go to text box enter the page to be opened after the record is updated or click the Browse button to select the file page.

7 The five buttons in the lower part of the interface offer you the next functionalities:





These buttons appear on all three interfaces of the Update Record Form wizard.


Fields informationThis dialog box allows you to define exactly which fields get which data and where they get it from. This is where you will determine how an input for a specific field will be displayed as:


36

To set the dialog box options:1 In the Form fields area specify the form objects you want to include on the HTML form of the update page, and which columns in your database table each form object should update.

By default, Developer Toolbox creates a form object for each column in the database table. If your database automat-ically generates primary key ID's for each new record created, remove the form object corresponding to the primary key column by selecting it in the list and clicking the Minus (-) button. This eliminates the risk of the user changing the ID value.



2 Specify how each data-entry field should be displayed on the HTML form by selecting a row (single click) in the Form fields area and entering the required information in the boxes below the grid.



Set the form object’s properties. You have different options depending on how you want the form field to be displayed.

5 You can use the Back button to alter the table and redirect information. If you do not wish to validate the user input, you can click on Finish to add the Update Record Form wizard elements to the page. If you want to go to the third and last step of the wizard, click Next.


37

Form validation rulesThis last step of the wizard configures the validation rules for each of the form input fields. You can define a rule for each form element, so that bad input will be avoided:

For instructions on completing this step, see “Form Validation in wizards” on page 89.

Once you click Finish, a Form Validation trigger with a validation role will be added to your page.

Note: If in the first step of the wizard you have selected the user table that is also set in the Login Settings section of the Control Panel, and you've also set the password column to be displayed as a password field, the following will happen:

1 Three different text fields will be generated for the password column: old password, password and re-type password.

2 Two additional server behaviors will be added to the page:

• The Check old Password server behavior.

• A throw error trigger, that verifies if the old password and the re-type password fields match:

If all of the password checks are successful, the update transaction is completed.


38

Delete Record wizardDeleting a certain record from a database table can be done in a single operation using the Delete Record wizard, without having to manually retrieve its ID and build the recordset. The wizard adds a Delete Record server behavior to your delete page. To edit the server behavior, open the Server Behaviors panel (Window > Server Behaviors) and double-click the Delete Transaction server behavior.

The Delete Record wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Delete Record Wizard.

The purpose of this wizard is to build a page that enables users to delete records from a database table. This wizard is divided into two steps.

To build the delete page with the Delete Record wizard:1 Open the page in Design view, and then apply the Delete Record wizard. A dialog box appears.

2 Complete the dialog box, following the instructions below for each of the two steps:

• The Basic tab

• The Advanced tab

3 Click OK when done.

The Basic tabThe first step into completing the dialog box requires the user to input basic information about the transaction, like the table to delete from, the ID of the record to be deleted, and the page to which it will be redirected:


39


2 In the Delete from table drop-down menu select the database table from which you want to delete records.

3 In the Primary key column drop-down menu specify the primary key column for the current table. The content of this drop-down menu is refreshed each time the user changes the table for the delete operation. By default, the first element is selected.


5 In the Primary key equals drop-down menu select the way the record ID is passed to the delete page (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.

6 In the First Check Variable drop-down menu select which element should act as a starter condition for the delete operation (either Primary key value, URL Parameter, Form Variable, Cookie, Session Variable, Server Variable), and type its name in the associated text-box.

Note: The form that performs the delete operation should have the Method attribute set to POST, not GET.

7 In the After deleting, go to text box enter the page to be opened after the record is deleted or click the Browse... button to select the file page.

8 The three buttons in the top right corner of the interface offer you the next functionalities:

• click OK when you are done configuring the server behavior.

• click Cancel to exit without applying the new settings.

• the Help button opens this help page.

These buttons appear on both interfaces of the Delete Record wizard, so their role will not be explained again in the next step.

9 Click on the Advanced tab to continue with configuring the wizard.


40

The Advanced tabThis last step of the wizard requires the user to set some transaction options:

To set the dialog box options:1 In the Transaction name text box enter the desired name for the delete transaction. Be careful when choosing it, because it has to be unique on each page. By default, Developer Toolbox assigns unique names to each transaction, and this setting should not be changed, unless you really know what you are doing.

2 After completing the user interface, click on the OK button to apply the wizard, or Cancel to dismiss it without making any changes to your page.

Make existing forms dynamicThis sub-section presents the tools that come with Developer Toolbox and that make it possible to build a dynamic form by linking all of the separate elements together, in a logic and smooth way:

• “Insert Record Transaction” on page 40

• “Update Record Transaction” on page 45

Insert Record TransactionThe basic building blocks of an insert page can be added separately using the form tools and the Server Behaviors panel. This procedure requires the adding of the following items:

• an HTML form that would allow users to enter data.

• an Insert Record Transaction server behavior to insert records in a database table.


41

The form objects will be laid out in a basic table, which you can customize by using the Dreamweaver page design tools (make sure all the form objects remain within the form’s boundaries). To edit the server behavior, open the Server Behaviors tab of the Application panel (Window > Server Behaviors) and double-click the Insert Transaction server behavior.

You can also add the building blocks all at once by using the Insert Record Form wizard. For more information on building an insert page in a single operation, see “Insert Record Form wizard” on page 24.

To add an HTML form to an insert page:1 Create a new dynamic page (File > New) and lay out your page using the Dreamweaver design tools.

2 Add an HTML form by placing the insertion point where you want the form to appear and selecting Insert > Form > Form; an empty form is created on the page. You may have to turn on Invisible Elements (View > Visual Aids > Invisible Elements) to see the form’s boundaries, which are represented by thin red lines.

3 Name the HTML form by selecting it first (single click on it in the Design View of the involved file), then opening the Property inspector (Window > Properties), and entering a name in the Form Name text box; you don’t need to specify an action or method attribute for the form to tell it where and how to send the record data when the user clicks the Submit button. The Insert Record Transaction server behavior sets these attributes for you.

4 Add a form object such as a text field (Insert > Form > Text Field) for each column of the database table into which you want to insert records; the form objects are for the data entry. Text fields are common for this purpose, but you can also use menus, check boxes, and radio buttons.

For more information on form objects, see the Dreamweaver Help on form elements.

5 Add a Submit button to the form (Insert > Form > Button); you can change the label of the Submit button by selecting the button, opening the Property inspector (Window > Properties), and entering a new value in the Label text box.

To add an Insert Record Transaction server behavior to an insert page:1 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Advanced > Insert Record Transaction.

2 Complete the dialog box that pops-up, following the instructions below for each of the three tabs:

• The Basic tab

• The Fields tab



Dreamweaver adds a server behavior to the page that allows users to insert records in a database table by clicking the Submit button on the form.


42

The Basic tabThe first step into completing the dialog box requires the user to input basic information about the transaction, like the table in which new records will be inserted and the page to which it will be redirected:


2 In the Insert into table drop-down menu select the database table into which you want to insert records.

3 In the Primary key column drop-down menu specify the primary key column for the current table. The content of this drop-down menu is refreshed each time the user changes the table for the insert operation. By default, the first element is selected.


5 In the First check variable drop-down menu select which element should act as a starter condition for the insert operation (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.

6 In the After inserting, go to text box enter the page to be opened after the record is inserted into the table, click the Browse button to select the file page or use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the file name.


• Click OK when you are done configuring the server behavior.


43



These buttons appear on all three interfaces of the Insert Record Transaction server behavior.

8 Click on the Fields tab to continue with configuring the server behavior.

The Fields tabThis dialog box allows you to define exactly which fields get which data and where they get it from, so you can associate database fields with form controls:

To set the dialog box options:1 In the Fields area specify the form objects you want to include on the HTML form of the insert page, and which columns in your database table each form object should update.


The Plus (+) button offers you the opportunity of reintroducing form objects that you had previously removed, but decided that you want them back in the form.



44

2 Specify the required settings for each data-entry in the HTML form by selecting a row (single click) in the Fields grid and entering the required information in the interface controls below the grid. Read along for instructions.

3 In the Submit as drop-down menu select the data format accepted by your database table. For example, if the table column only accepts numeric data, select Numeric. All the options that you have are listed here: Text, Numeric, Double, Date, Check box: Y,N, Check box: 1,0, Check box:-1,0, File.

4 In the Get value from drop-down menu select the way the parameter is passed: URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value, Form in page, File field.

5 The next interface field depends on the selection you made in the Get value from drop-down menu. You might have to enter the Variable name, to enter a static value, or to select a form field in the page.

6 In the Default value text box specify the default value for the selected field in the grid. Notice the lightning bolt icon that is displayed to the right of this field. It gives you the possibility of selecting dynamic data into the field.

7 Click on the Advanced tab to continue with configuring the server behavior.

The Advanced tabThis last step in configuring the server behavior requires the user to set some transaction options:

To set the dialog box options:1 In the Transaction name text box enter the desired name for the insert transaction. Be careful when choosing it, because it has to be unique on each page. By default, Developer Toolbox assigns unique names to each transaction, and this setting should not be changed, unless you really know what you are doing.

2 After completing the user interface, click on the OK button to apply the server behavior, or Cancel to dismiss it without making any changes to your page.


45

Update Record TransactionThe basic building blocks of an update page can be added separately using the form tools and the Server Behaviors panel. This procedure requires the adding of the following items:

• an HTML form that would allow users to enter new data;

• an Update Record server behavior to update records from a database table;

The form objects will be laid out in a basic table, which you can customize by using the Dreamweaver page design tools (make sure all the form objects remain within the form’s boundaries). To edit the server behavior, open the Server Behaviors tab of the Application panel (Window > Server Behaviors) and double-click the Update Transaction server behavior.

You can also add the building blocks all at once by using the Update Record Form wizard. For more information on building an update page in a single operation, see “Update Record Form wizard” on page 33.

To add an HTML form to an update page:1 Create a new dynamic page (File > New) and lay out your page using the Dreamweaver design tools;

2 Add an HTML form by placing the insertion point where you want the form to appear and selecting Insert > Form > Form; an empty form is created on the page. You may have to turn on Invisible Elements (View > Visual Aids > Invisible Elements) to see the form’s boundaries, which are represented by thin red lines;

3 Name the HTML form by selecting it first (single click on it in the Design View of the involved file), then opening the Property inspector (Window > Properties), and entering a name in the Form Name text box; you don’t need to specify an action or method attribute for the form to tell it where and how to send the record data when the user clicks the Submit button. The Update Record Transaction server behavior sets these attributes for you;

4 Add a form object such as a text field (Insert > Form > Text Field) for each column of the database table into which you want to update records; or you can add text fields only for the fields that will be updated; the form objects are for the data entry. Text fields are common for this purpose, but you can also use menus, check boxes, and radio buttons.

For more information on form objects, see the Macromedia Help on form elements.

5 Add a Submit button to the form (Insert > Form > Button); you can change the label of the Submit button by selecting the button, opening the Property inspector (Window > Properties), and entering a new value in the Label text box.

To add an Update Record Transaction server behavior to an update page:1 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Advanced > Update Record Transaction.


• The Basic tab

• The Fields tab



Dreamweaver adds a server behavior to the page that allows users to update records from a database table by clicking the Submit button on the form.


46

The Basic tabThe first step into completing the dialog box requires the user to input basic information about the transaction, like the table in which records will be updated and the page to which it will be redirected:


2 In the Update in table drop-down menu select the database table into which you want to update records.

3 In the Primary key column drop-down menu specify the primary key column for the current table. The content of this drop-down menu is refreshed each time the user changes the table for the update operation. By default, the first element is selected.


5 In the First check variable drop-down menu select which element should act as a starter condition for the update operation (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.

6 In the Primary key equals drop-down menu select by which element the current record to be updated can be identified (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.


47

7 In the After updating, go to text box enter the page to be opened after the record is updated or click the Browse button to select the file page. You can also use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the file name.





These buttons appear on all three interfaces of the Update Record Transaction server behavior.


The Fields tabThis dialog box allows you to define exactly which fields get which data and where they get it from, so you can associate database fields with form controls:

To set the dialog box options:1 In the Fields area specify the form objects you want to include on the HTML form of the update page, and which columns in your database table each form object should update.

By default, Developer Toolbox creates a form object for each column in the database table. If your database automat-ically generates primary key ID's for each new record created, remove the form object corresponding to the primary key column by selecting it in the list and clicking the Minus (-) button. This eliminates the risk of the user changing the ID value, which should not be altered.


48

The Plus (+) button offers you the opportunity of reintroducing form objects that you had previously removed, but decided that you want them back in the form.


2 Specify the required settings for each data-entry in the HTML form by selecting a row (single click) in the Fields area and entering the required information in the interface controls below the grid. Read along for instructions.

3 In the Submit as drop-down menu select the data format accepted by your database table. For example, if the table column only accepts numeric data, select Numeric. All the options that you have are listed below: Text, Numeric, Double, Date, Check box: Y,N, Check box: 1,0, Check box:-1,0, File.

4 In the Get value from drop-down menu select the way the parameter is passed (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value, Form in page, File field).

5 The next interface field depends on the selection you made in the Get value from drop-down menu. You might have to enter the Variable name, to enter a static value, or to select a form field in the page.

6 Click on the Advanced tab to continue configuring the server behavior.

The Advanced tabThis last step in configuring the server behavior requires the user to set some transaction options. It is not mandatory to change or even access this last tab, as it is by default completed with correct settings:


49

To set the dialog box options:1 In the Transaction name text box enter the desired name for the update transaction. Be careful when choosing it, because it has to be unique on each page. By default, Developer Toolbox assigns unique names to each transaction, and this setting should not be changed, unless you really know what you are doing.


Build dynamic formsThis sub-section describes the commands, server behaviors and browser behavior associated to the Dynamic forms:

• “Create Dynamic Form wizard” on page 49

• “Dynamic Form Layout” on page 53

• “Manage Dynamic Form wizard” on page 54

• “Dynamic Form browser behavior” on page 55

Create Dynamic Form wizardIn order to create a form that allows performing insert and update operations on a given table, you can use the Create Dynamic Form wizard. It is a good pair to the Dynamic list, as it can be used to perform multiple operations based on the existence of an URL parameter. The wizard adds all the elements needed in order to build a fully functional form that will perform all three operations: add, modify and remove records.

The Create Dynamic Form wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Create Dynamic Form wizard.

This wizard will create several elements for you:

• The recordset that retrieves the data you specify.

• The HTML elements to display the data, as well as the additional elements (links, buttons, navigation).

• The Dynamic Form Layout server behavior, letting you modify some of the form's properties afterwards.

Before using the Create Dynamic Form wizard, you should have a correctly configured testing site, as it will be required for the database connection setup step.

The wizard contains the following steps:

1 In the first step define the data that will be used.

2 In the second step define which fields are to be displayed in the form.

3 If the third step (out of 4) is available, set the validation rules for each field.

4 In the fourth step set some specific form properties.

Note: You can only create one Dynamic form per page.

To set the dialog box options for the first step of the wizard:1 In the Connection drop-down menu select the database connection you have created for your site. If there are no connections available, you can click the Define button to create a new connection.


50

2 In the Table drop-down menu select the database table retrieved through the selected connection, table that contains the data to manipulate in the form.

3 In the Primary key column drop-down menu select the table field which is set to be the primary key. This field contains unique data and is used by default to check against URL parameters.

4 If in the corresponding list you chose to get data from an advanced recordset (more than one table), make sure you select the database table that contains the primary key selected in the list, and of course, set the same primary key column as in the list.

5 The Numeric check-box sets the primary key type. It is automatically refreshed when a new field is selected in the Primary key column drop-down menu.






These buttons are common to all steps of the Create Dynamic Form wizard interface.


To set the dialog box options for the second step of the wizard:1 In the Form fields grid, you can define what table columns will appear in the form. You can add or remove elements, by clicking on the Plus (+) and Minus (-) buttons on top of the grid. Also, you can change the order columns are displayed in, by pressing the Up (^) and Down (v) buttons.

2 Specify how each data-entry field should be displayed in the Dynamic form by selecting a row (single click) in the Form fields area and entering the required information in the boxes below the grid.


4 In the Show on drop-down menu select one of the three available options:

• Insert and Update - if you want the current field to be available both when you insert or update records.

• Insert only - if you want the current field to only be available only during the insert operation.

• Update only - if you want the current field to only be available only during the update operation (you can modify the value of this field).

Note: Say a form field is set to show only on Insert and it is also required. As expected, it will not show on Update (it being required will be ignored). If you are in an Update form (coming from the corresponding list), and you hit the Update button, no error will be thrown. But if you hit the Insert as new button, an error will occur since that missing field is required (a field set as required is actually required on the transactions on which it shows).

Note: If a form field is set to show only on Update, during an Insert transaction for that form, the NULL value will be stored in the respective database table column.

5 In the Display as drop-down menu select one of the available options: Text field, Text area, Menu, Hidden field, Checkbox, Radio group, Password field, Text, File field. Depending on your selection, the interface may change. Get all the needed information about these options from here.


51

Note: If in the validation step, you set Password and File fields as required, they will only be required in the insert operation, and not in the update operation also.

6 The Char width text box is only enabled when the current form field is displayed either as Text field or Password field. In this case, enter the number of characters that can be displayed at one time in the current form field.

7 The Max chars is also only enabled when the current form field is displayed either as Text field or Password field. In this case, enter in the text box the maximum number of characters accepted in that form field.


Step 3 - Form validation rulesThis step presents a way to validate all form elements. For instructions on completing this dialog box, see “Form Validation in wizards” on page 89.

To set the dialog box options for the fourth step of the wizard:1 In the Move up/down column drop-down menu select the numeric table column that stores the records order. If you did not use an order field in your table, leave this drop-down menu to the None value.

If you select a table column for the records order, the form will automatically generate its value as being the maximum value of all existing entries in the order column + 1 (plus one). This column will not be displayed as a form field in browser (even if it was listed in the Form fields grid on step 2) since it will automatically get a value. This ensures that there will be no problems with the element's order.

Through the Dynamic list, this order in the database can be easily changed.

Note: If you specified a table column in the Move up/down column drop-down menu when creating the related Dynamic list, the same column must be selected in the respective drop-down menu of the Dynamic form. For technical details about selecting the Move up/down column in the Dynamic list and form, see “Dynamic Form Layout” on page 53.

2 The Current skin used in your site (in all the pages included, not only the current one) has its name displayed in bold text. The Change skin button offers the possibility of choosing another skin out of the available ones (aqua, kollection, arktic, formal) or None, if you don't want to use any skin:

You can preview the chosen skin in the image provided along with the selected skin. For more details, see “CSS Skins” on page 294.


52

3 In the Duplicate buttons drop-down menu select one of the 2 possibilities:

• Yes - if you want the action buttons to be displayed both in the form's footer and header.

• No - if you want the action buttons to be displayed only in the form's footer.

This field is similar to the one with the same name in the Dynamic list.

4 In the Display as grid drop-down menu select one of the 2 possibilities (when editing multiple records):

• Yes - if you want the records to be shown in a table that on each row displays the values of a single record (each field in a cell).

• No - if you want the records values to be grouped and displayed one group below another.

5 In the Copy down value drop-down menu select Yes if you want the form to present a button through which the first value (when editing multiple records) can be extended and populate the cells below it. Select No if you don't want the first value to propagate.

6 In the Add "Insert as new" button drop-down menu select Yes if, in your form, you want a button that would insert a new record starting with the values stored in another one (values that are updated). This functionality is similar to one present in most software applications, namely the File /Save as property.

7 When you are done configuring the wizard, you can click the Finish button to close the dialog box and add all the elements into the page.

After the wizard configuration is finished, and the results are applied onto the page, several translators are shown in Dreamweaver's Design View. A translator is in fact visual aid corresponding to a code block behind the action, using simple to understand names (e.g. the Display error message translator is shown instead of the code that will display the error message - if any).

The Form title itself is part of a translator (the Show If translator), because the same form can perform either an insert or an update, and the correct title has to be shown for each. Translators do not appear in the final page, when it is viewed in the browser. The page containing the form created above, looks as in the following image:


53

And this is how the Server Behaviors tab of the Application panel looks like after applying the wizard (with the settings above) in an empty page:

To change any of the form properties at a later time, you can double-click the Dynamic Form Layout server behavior (inserted by the wizard) or apply the Manage Dynamic Form wizard command, accessed from the Insert bar > Developer Toolbox tab.

To learn about the form's behavior in the browser, see “Dynamic Form browser behavior” on page 55.

Frequently Asked Questions• I need to see a list of all the records I have inserted. How do I do that?

• Can I display some fields on insert, but not on update?

• Can I use Developer Toolbox to build administration sections for my site?

• How do I change a Dynamic Form?

Dynamic Form LayoutAfter applying the Create Dynamic Form wizard, you can notice in the Server Behaviors tab the server behavior that is added, namely the Dynamic Form Layout one. You cannot find it in the Developer Toolbox menu as it can only be used after applying the Create Dynamic Form wizard, which adds it to the server behaviors list of the page.


54

You can use the Dynamic Form Layout server behavior (by double-clicking on it) to alter the Dynamic form properties (mainly the visual elements like the skin and the buttons) at a later time.

To set the dialog box options:1 In the Move up/down column read-only drop-down menu you can only view the table column selected previously (in the Create Dynamic Form wizard) for the records order. This is the column on which the auto-increment trigger acts.

2 The Current skin used in your site (in all the pages included, not only the current one) has its name displayed in bold text. You can change it by clicking on the button next to it, Change skin. For more details, read see “CSS Skins” on page 294.

3 In the Duplicate buttons drop-down menu select whether or not you want the form buttons to be displayed both in the form's footer and header, or only in the form's footer.

4 In the Display as grid drop-down menu select Yes if you want the records to be shown in a grid and No if you want them displayed separately.

5 In the Copy down value drop-down menu select Yes if you want the value to be extended and populate the cells below it, and No if you don't want it to propagate.

6 In the Add "Insert as new" button drop-down menu decide whether or not you want a button like this in your form (insert a new record starting with the values stored in another one).

7 Click OK when are done altering the Dynamic form.

Manage Dynamic Form wizardAfter applying the Create Dynamic Form wizard, you can alter the properties of the Dynamic form fields by using the Manage Dynamic Form wizard. It is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Manage Dynamic Form Wizard.

This command has two steps and it can be applied any time you want to make changes in the fields of a Dynamic form in page. These changes regard the three operations: insert, update and delete that can be performed on the Dynamic form fields. So you can add or remove fields from the form, or you can update the existing ones (their label, the way they are displayed).

The first step of the wizard informs you of the recordset associated to the form:Note: Since there can only be one Dynamic form in the page, the wizard automatically opens with the second step. If you want to know which recordset is associated to the form, you can hit the < Back button in that second step and check out the recordset in the first step.

1 In the Recordset drop-down menu, the recordset corresponding to the Dynamic form in page is already selected.




• Click Cancel to exit without applying the new settings.

• The Help button opens this help page.

These buttons are common to both steps of the Manage Dynamic Form wizard interface.


55


To set the dialog box options for the second step of the wizard:1 In the Form fields grid, there are listed the current table columns that appear in the form. You can add or remove elements by clicking on the Plus (+) and Minus (-) buttons on top of the grid. Also, you can change the order columns are displayed in, by pressing the Up (^) and Down (v) buttons.

2 For each field there are some properties that can be modified. To access them, select (single-click) a form field from the grid in order to modify its properties. The available properties are detailed below.

3 In the Label text box you can modify the field's label.

4 In the Show on drop-down menu select the operations on which you want the field to be displayed (insert, update, or both).

5 In the Display as drop-down menu select one of the available options: Text field, Text area, Menu, Hidden field, Checkbox, Radio group, Password field, Text, File field. Depending on your selection, the interface may change. Get all the needed information about these options from here.

6 Click Finish when you are done configuring the wizard.

If for any of the form fields you want to modify the Char width and/or the Max chars properties: 1 Select the corresponding field in Dreamweaver (Design View):

2 Use the Property Inspector to alter these elements:

Dynamic Form browser behaviorA Dynamic form allows you to manipulate data from database tables:

• You can add one or multiple records at the same time.


56

• You can modify one or multiple records at the same time.

• You can delete one or multiple records at the same time.

Note: The multiple operations can be performed when the form is called by the Dynamic list.

It is a complement of the Dynamic list, which calls it to add or edit single or multiple records. The images below present the form server behavior. In order to see the relation with the list browser behavior, see “Dynamic Form browser behavior” on page 55.

A Dynamic form in browser looks similar to the next one (when the Dreamweaver page that contains the Dynamic form was directly previewed):

When the Dreamweaver page that contains a Dynamic form is called by a Dynamic list to allow possible updates or to display the complete information (like the product description when it is longer than the maximum number of characters allowed), the form in browser looks like this:

The elements that compose the Dynamic form are:

1 The form title - it changes depending on the action to perform: Insert or Update. The part that follows one of these two words (Insert or Update) is the generic name of the elements to be inserted or updated. It is taken from the table name (eliminating the underscore "_" and what follows after it).

2 The form header and footer - they contain the buttons that perform the actions. These buttons differ due to the nature of the operation to perform. They are displayed both in the header and footer only if in the Duplicate buttons drop-down menu you selected Yes when creating the form.

3 For the insert case, there are two available buttons:

• Insert - add the form data into the table, as a new record (or as more new records if multiple insert).


57

• Cancel - return to the previous page without performing any action (the previous page is generally the Dynamic list that called the form).

4 For the update case, there are four available buttons:

• Insert as new - the record edited will be left unchanged and the form data will be saved as a new record.

• Update - perform the update operation, changing the record's data.

• Delete - remove the record entirely.

• Cancel - return to the list without performing any changes to the record.

5 A new feature is that during the insert and update transactions, the buttons on the form footer (and header) are disabled (to prevent any disturbance during the operations). So for a fraction of a second, right after pressing the Insert button, the form in browser looks like this:

As for the form elements, any standard form element or widget can be used. Also, as you can see in the above example, dynamic data can be incorporated into the form, as drop-down menus or other type of form controls, to make it more user-friendly.

With the Dynamic form, multiple insert and multiple update operations are possible. They can be executed when the form is called from the Dynamic list for either the insertion of a certain number of records (using the add new button in the list) or the update a certain number of records already selected.

A page containing a Dynamic form can be called directly from a user defined link, and not only from a Dynamic list. When not called from the list, without any parameters, the form will perform an Insert operation. However, if you click on the Cancel button, it will not be able to redirect to the former page. To obtain the redirect, you must add the KT_back=1 URL parameter to the link calling the form (e.g. from index.php you want to call form.php to insert a new record. In order for the form to redirect back to the index.php when the Cancel button is clicked, the link must be of the format: form.php?KT_back=1).

Add actions to dynamic formsThis sub-section provides information on the actions that can be added when submitting a form, enriching the operations that can be performed:

• “Custom Trigger” on page 58

• “Redirect To Page trigger” on page 59

• “Throw Error trigger” on page 61

• “Add Transaction Fields” on page 63


58

• “Auto-increment Column” on page 67

• “Sort Triggers” on page 69

Custom TriggerTo ease the creation of custom triggers, you can use the Custom Trigger server behavior which allows setting the trigger properties in a visual manner.

This trigger is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Custom Trigger. The user interface has a Basic and an Advanced tab.

To set the dialog box options for the Basic tab:1 In the textarea, enter your own function code, in the programming language required by your server model. The function's definition is completed automatically and displayed in a generic manner (above the textarea), all these elements being replaced when the server behavior is applied (e.g. the function's name is displayed as TriggerName, but after you click the OK button, it will be replaced by the name set in the Advanced tab).


• Click OK when you are done configuring the trigger.



These buttons are common to both tabs of the Custom Trigger interface.


59

3 Click on the Advanced tab to continue with configuring the trigger.

For instructions on completing this step, see the Advanced tab. The difference is that for the Custom Trigger, the Type drop-down menu is not read-only and it gives you the opportunity to choose the trigger type. Also, the Priority is by default set to 50.

Redirect To Page triggerThe Redirect To Page server behavior allows the user to set up a redirect operation to a certain page, after a specific condition has been met, or a transaction has finished executing.

This trigger is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Redirect To Page.


60

The user interface has two tabs. Directions about their correct configuration are given below.

To set the dialog box options for the first tab:1 In the Page text-box enter the name of the page to redirect to. You can use the Browse button to select a page in your local folder. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the file name.

2 The Keep parameters checkbox allows passing the existing URL parameters to the page where the redirection is being made.


4 Click OK when you are done configuring the trigger.



These buttons are common to both tabs of the Redirect To Page trigger.


61


For instructions on completing this step, see the Advanced tab. For the Redirect To Page trigger, by default the Priority is set to 90 and the Type is END, as it should be the last one to execute on page.

Throw Error triggerThe purpose of the Throw Error trigger is to allow the user to specify a custom error message to be displayed when something goes wrong. The error can be generic or linked to a specific field. Also, this trigger can be used to start an error transaction when a user-defined condition is not met.

This trigger is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Throw Error.


62

The user interface has two tabs. The Basic tab alone is sufficient in order to define the error message and eventually the associated transaction field, while the Advanced is only required in order to alter the list of transactions to which the trigger is registered, or the trigger's properties. Directions about the tabs correct configuration are given below.

To set the dialog box options for the first tab:1 In the Error message textarea enter the custom message to be displayed when the error occurs. This message will be displayed on top of the page. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the generic error message.

2 In the Transaction field drop-down menu select the field which will have the error message associated to and get highlighted. If this field is left to None, then the error message will be displayed whenever the transaction fails, without highlighting any particular field.

3 In the Field error message text box, enter the error message that will be displayed next to the field's page element. You can also use the Developer Toolbox Dynamic Data to build the specific error message.





These buttons are common to both tabs of the Throw Error trigger.


63


For instructions on completing this step, see the Advanced tab. The difference is that for the Throw Error trigger, the Type drop-down menu is not read-only and it gives you the opportunity to choose the trigger type. By default, it is set to BEFORE as it should execute before the transaction takes place. Also, the Priority is by default set to 50.

Add Transaction FieldsThe Add Transaction Fields trigger allows the adding of fields that do not appear in the form on page, but are taken into account when inserting the new record into the table (as they are present in the database).

It is a BEFORE trigger, and therefore it gets executed before the actual Insert/Update/Custom Transaction, but after the page has been submitted. This way, in order to compute the transaction field's value, other fields from the form can be used. Also, this trigger is executed after the validation has been performed, which guarantees that only coherent and correct data is taken into account.

As an example on where it can be used, consider the insert page for adding a new product into a database table. The table contains both price and price_with_taxes columns, but only price is requested in the form. To add the second price, you can use an Add Transaction Fields trigger which will compute the second price based on the value submitted with the form for the regular price.


64

To add an Add Transaction Fields trigger to your page:1 Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Advanced > Add Transaction Fields.

2 Complete the dialog box that pops-up, following the instructions below for each of the two tabs:

• The Basic tab



The Basic tabIn the first step of the dialog box you should select the fields to be added, and specify their type and value:


65

To set the dialog box options:1 In the Columns area specify the table columns you want to add to your HTML form from the insert page. You can add columns using the Plus (+) button. The Minus (-) button is used to remove fields from the form.

2 Specify the required settings for each added data-entry in the HTML form by selecting a row (single click) in the Columns area and entering the required information in the boxes below the grid. Read along for instructions.

3 In the Type drop-down menu select the data format accepted by your database table. All the options that you have are listed here: Text, Numeric, Double, Date.

4 In the Value text box specify the value for the selected table column. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build complex expressions.





These buttons are common to both tabs of the Add Transaction Fields trigger.



66

The Advanced tabThis step of the configuration requires the user to set the trigger's name and some transaction options:

To set the dialog box options:1 In the Trigger name text box enter an identifier (a name) for the trigger. Be careful when choosing it, because it has to be unique on each page since it is also the function name. By default, Developer Toolbox assigns unique names to each trigger, and this setting should not be changed, unless you really know what you are doing.

2 In the Transactions area, the transactions to which the trigger is registered are displayed. You can add new trans-actions manually, by using the Plus (+) button:


67

The Minus (-) button is used to remove transactions from the grid (select the transaction first, with a single click).

At least one transaction must be in the area at all times.

3 Specify the required settings for each transaction listed above by selecting a row (single click) in the Transactions area and entering the required information in the boxes below the grid. Read along for instructions.

4 In the Priority text box specify the trigger's priority to execute when working with the currently selected trans-action from the grid. The higher the value is, the later it will be executed.

5 In the Type drop-down menu you can read the trigger type. The drop-down menu appears disabled because it is a read-only field. The allowed trigger type in this situation is BEFORE, but all the possible trigger types are: STARTER, BEFORE, AFTER, END, ERROR.

6 In the Condition text box specify the condition that has to be fulfilled for the trigger to be executed (the start condition). To create the condition in a visual manner, click the Build condition button. It will open the Condition Builder dialog box.

7 After configuring the user interface, click OK to apply the trigger, or Cancel to dismiss it without making any changes to your page.

Auto-increment ColumnWhen working with Dynamic forms and with tables that contain ordered fields (order that is not established by the ID, but by entered values), you should use the Auto-increment Column server behavior. The order aspect is present in Dynamic Lists to display records as intended (their order can be changed both in browser and database). In Dynamic Forms, the order column must have unique values.

This server behavior is a trigger that registers itself to an Insert or a Custom transaction, automatically computing the value for the order column specified in its options. This value is computed by determining the maximum value already inserted, and adding 1 to it.

The server behavior is automatically added when using the Create Dynamic Form wizard, and setting a value in the Move up/down column drop-down menu in the wizard's last step.

If building a form manually, or if you haven't selected a Move up/down column in the wizard, you can access this server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Advanced > Auto-increment Column. The dialog box opens, containing two tabs.


68

• In the Basic tab, set the Table column containing the order values:


69

• In the Advanced tab, set the properties regarding the trigger:

To read all the explanations regarding the fields of this interface, see the Advanced tab.

Note: If you use the order field for a Dynamic list, but you neglect to select it in the corresponding form (either as a simple field or as the Move up/down column in the final wizard step), the newly inserted records will have NULL for the order column, which means that there will be multiple records with the same order.

Sort TriggersThis section provides information on how triggers can be sorted. Each transaction on a page can have multiple regis-tered triggers. Defining the correct order for all of these triggers (through the priority parameter in the Advanced tab of each trigger) can be a tricky task, as you must remember all priorities you've set for each one.

To ease this job, Developer Toolbox contains a tool allowing you to visually change the trigger's execution order for each transaction. It is the Sort Triggers command, that can be accessed from the Developer Toolbox tab of the Insert bar.


70


To set the dialog box options for the first tabs:1 In the Transaction drop-down menu, select the transaction for which to set the trigger order.

2 In the BEFORE triggers area, all triggers having the type BEFORE and registered for the currently selected trans-action are shown. You can modify the order of execution through the up and down buttons.

3 The same behavior is applied for the AFTER and END trigger areas.

4 Between the BEFORE and AFTER trigger areas, the transaction name and action is displayed.


• Click OK when you are done configuring the command.



These buttons are common to both tabs of the Sort Triggers interface.


71


To set the dialog box options for the second tab:1 In the STARTER triggers area, all the triggers that act as a starting condition for the transaction are listed, and you can change their order through the up and down buttons.

2 In the ERROR triggers area, all the triggers that start when the transaction fails are listed, and you can change their order through the up and down buttons.

3 When you are done, click OK to apply the command.

Advanced operations on dynamic formsThis section offers some insight upon the advanced operations that can be accomplished through dynamic forms and with the help of some specific Developer Toolbox features:

• “Create custom transactions in one operation” on page 72

• “Create custom transactions in multiple steps” on page 75

• “Set default values for form fields” on page 78

• “Perform roll back on the insert transaction” on page 79

• “Link Transactions” on page 80


72

Create custom transactions in one operationWhenever you want to build an insert page that contains specific fields which you can manually define, the Custom Form wizard is the right solution. The submitted information in the form can be saved in the database (by calling a stored procedure) or not. In the latter case, it could simply be sent as an e-mail to where it is needed to be known.

This wizard is divided into three compulsory steps, based on the type of data the user has to input. If Form Validation has been installed, aside from the regular steps required in completing the wizard, a new one will be displayed (as the third out of the four steps). It consists in defining the validation rules for all the fields included in the form generated by the wizard.

The Custom Form wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Custom Form Wizard.

You can also build the custom form gradually using the form tools and the Custom Transaction server behavior. For more information, see “Create custom transactions in multiple steps” on page 75.

To build the insert page with the Custom Form wizard:1 Open the page in Design view, and then apply the Custom Form wizard. A dialog box appears.

2 Complete the dialog box, following the instructions below for each of the four steps:

• Connection and redirect information

• Fields information


• SQL query

3 Click Finish when done


73

Connection and redirect informationThe first step into completing the dialog box requires the user to input basic information about the transaction, like the database connection and the page to which it will be redirected:


2 In the When finished, go to text box enter the page to be opened after the record is inserted into the table or click the Browse button to select the file page. You can also use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the file name.






These buttons appear on all three interfaces of the Custom Form wizard.



74

Fields informationThis dialog box allows you to add fields in your form. You can associate database fields with form controls:

To set the dialog box options:1 In the Form fields area specify the form objects you want to include on the HTML form of the insert page. You have to add the fields manually, using the Plus (+) button. The Minus (-) button is used to remove fields from the form.

You can change the order of the form objects on the HTML form by selecting a form object in the list and clicking the up and down arrows on the right top side of the dialog box.

2 Specify how each data-entry field should be displayed on the HTML form by selecting a row (single click) in the Form fields area and entering the required information in the boxes below the grid, as indicated below.

3 In the Label text box enter a descriptive label to display beside the data-entry field. By default, Dreamweaver displays the column’s name in the label field.


Set the form object’s properties. You have different options depending on how you want the form field to be displayed as.

5 You can use the Back button to alter the table and redirect information. If you do not wish to validate the user input, you can click on Finish to add the custom form elements to the page. If you want to continue configuring the wizard, click Next.


75

Form validation rulesThis step of the wizard configures the validation rules for each of the form input fields. You can define a rule for each form element, so that bad input will be avoided. For instructions on completing this step, see “Form Validation in wizards” on page 89.

SQL queryThis last step of the wizard offers you the possibility of editing your own SQL query, that would suit your needs the best:

To set the dialog box options:1 In the SQL query editable area you can write an SQL query for the current transaction (only if there is an active SQL connection). When putting together the query and choosing fields from the current ones, you can use the Developer Toolbox Dynamic Data (the lighting bolt icon).

2 After completing the user interface, click on the Finish button to apply the wizard, or Cancel to dismiss it without making any changes to your page.

Create custom transactions in multiple stepsIn order to gradually build an insert page containing specific fields, which you can manually define, you can use the form tools and the Server Behaviors panel. This procedure requires the adding of an HTML form that would allow users to enter data, and a Custom Transaction to insert records in a database table. The submitted information in the form can be saved in the database (by calling a stored procedure) or not. In the latter case, it could simply be sent as an e-mail to where it is needed to be known.

The form objects will be laid out in a basic table, which you can customize by using the Dreamweaver page design tools (make sure all the form objects remain within the form’s boundaries). To edit the server behavior, open the Server Behaviors tab of the Application panel (Window > Server Behaviors) and double-click the Custom Trans-action server behavior.

You can also build the custom form at once by using the Custom Form wizard. For more information, see“Create custom transactions in one operation” on page 72.

First of all, add an HTML form to the page. In order to get more information upon this, see “Insert Record Form wizard” on page 24.

To add the Custom Transaction server behavior to an insert page:1 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Forms > Advanced > Custom Transaction.


• The Basic tab

• The Fields tab



Dreamweaver adds a server behavior to the page that allows users to insert records in a database table or send the new information via e-mail by clicking the Submit button on the form.


76

The Basic tabThe first step into completing the dialog box requires the user to input basic information about the transaction, like the database connection and the page to which it will be redirected:


2 In the First check variable drop-down menu select which element should act as a starter condition for the insert operation (either URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value), and type its name in the associated text-box.

3 In the When finished, go to text box enter the page to be opened after the record is inserted into the table or click the Browse button to select the file page.





These buttons appear on all three interfaces of the Custom Transaction server behavior.



77

The Fields tabThis dialog box allows you to add fields in your form. You can associate database fields with form controls:

To set the dialog box options:1 In the Fields area specify the form objects you want to include on the HTML form of the insert page. You have to add the fields manually, using the Plus (+) button. The Minus (-) button is used to remove fields from the form.

You can change the order of the form objects on the HTML form by selecting a form object in the list and clicking the up and down arrows on the right top side of the dialog box.

2 Specify the required settings for each data-entry in the HTML form by selecting a row (single click) in the Fields area and entering the required information in the boxes below the grid, as indicated below.

3 In the Submit as drop-down menu select the data format accepted by your database table, or the one compatible with the further usage of this field content. For example, if the table column only accepts numeric data, select Numeric. All the options that you have are listed below: Text, Numeric, Double, Date, Check box: Y,N, Check box: 1,0, Check box:-1,0, File.

4 In the Get value from drop-down menu select the source from where the value is retrieved: URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value, Form in page, File field.

5 If the Variable name text box is displayed (it depends on the Get value from selection), enter the name for the variable. If the Value text box is displayed, enter a value, and if the Form field drop-down menu shows, select the suitable option.

6 In the Default value text box, when enabled, enter the default value for the currently selected form field.



78

The Advanced tabThis last step in configuring the server behavior requires the user to set some transaction options:

To set the dialog box options:1 In the Transaction name text box enter the desired name for the custom transaction. Be careful when choosing it, because it has to be unique on each page. By default, Developer Toolbox assigns unique names to each transaction, and this setting should not be changed, unless you really know what you are doing.

2 In the SQL query editable area you can write an SQL query for the current transaction (only if there is an active SQL connection). When putting together the query and choosing fields from the current ones, you can use the Developer Toolbox Dynamic Data (the lighting bolt icon).


Set default values for form fieldsWhen working with different fields, you can usually specify a default value to be displayed in the page, or even to be used when performing transactions. Both the Insert and Update transactions allow the user define a default value for each field involved in the transaction. And since Developer Toolbox is all about dynamic web development, it allows two ways of defining dynamic data as default values, depending on the user interface: you can add dynamic data by using the Developer Toolbox Dynamic Data blue lightning bolt (when displayed next to a field), or the Dreamweaver Dynamic Data yellow lightning bolt to use dynamic values as defaults.


79

Next to the default value text-box there is usually the lightning icon, that opens a dialog box allowing the developer select a dynamic value, either from an existing recordset, or a session variable. The dialog box that opens when pressing the lightning bolt is similar to the following image:

The number and names of the recordset and other variables, depend of the particular site page.

When you select a recordset field, or another variable through a Dynamic Data dialog, in the default Value text-box the actual code that will retrieve it is inserted, specific for the selected server model.

For the PHP_MySQL server model, when you select a recordset field as the default value of a form field, the user interface field is automatically populated with the corresponding PHP code:

Perform roll back on the insert transactionWhenever insert transactions have AFTER triggers closely connected to the transaction fields (e.g. a trigger that performs the file upload), the form data is first inserted into the table, and only then is the trigger executed. If the trigger fails for any reason, the data has already been inserted into the database, which may lead to corrupt or fake entries in your database.

For instance, an image file can get recorded in the database, but the actual file is not uploaded to the server, because the upload trigger failed. Consequently, the image will not be available in your application. A way to avoid this problem is implemented in Developer Toolbox, and is called a roll-back operation.

More exactly, a roll-back is an ERROR trigger that is executed when the AFTER trigger of an insert transaction has failed to execute correctly. The trigger receives the unique ID of the last inserted record. Its only function is to delete it from the database, thus providing a fail-safe mechanism against corrupted data.


80

As you can see in the next example, when the file upload trigger fails because of some wrong values, the next thing to be executed is the roll-back trigger:

Link TransactionsThis server behavior links together two transactions in page, automatically executing one of them after the other. It can be accessed from Server Behaviors > Developer Toolbox > Forms > Advanced > Link Transactions. The user interface has two easy-to-configure tabs.

To set the options for the first tab:1 In the Register to transaction drop-down menu select the transaction that you want to be executed first. It is called the master transaction.


81

2 In the Link to transaction drop-down menu select the transaction that should follow after the previous one. It is called the slave transaction.

3 In the Link column drop-down menu select the table field on which the linking transaction is based.

4 Click on the Advanced tab to continue configuring this server behavior.

In order to configure the Advanced tab of the server behavior, you can find instructions for each of the interface fields here:

After applying the server behavior, there are still some things you have to do in your Dreamweaver page (in case you haven't done any modifications on the buttons and form tags of the two transactions yet) so to obtain the expected functionality. These things are:

• delete the submit button from the first transaction.

• connect the two forms (corresponding to the two transactions) by deleting the closing form tag of the first form and the opening tag of the second form.

• make sure the first transaction is executed on the correct starting condition (since its submit button was deleted, it will now depend on the submit button of the second transaction).

Many-To-Many wizardThe Many-To-Many wizard is useful when you are working with many-to-many related tables. A typical example of a many-to-many relation is students registering to classes: a student can register to more classes, while a class is attended by more students.


82

When dealing with many-to-many relations, another database table must be used: a many-to-many table (linking table). Its role is to link students and classes (for our example). Thus, it stores records formed by associating one student to one class (that he/she registered to). This linking table has two columns, namely the primary keys of the two tables involved in the many-to-many relation. It also prevents duplicated records from occurring: the infor-mation about a student is only once stored, in the students table, and not for every class that he/she attends.

In order to better understand the role of the linking table (many-to-many table) when working with many-to-many related tables, let's consider the following example. Say we are working with the student_std and class_cls tables. If we stored the classes each student registered to in the same table as the students, the student_std table would have the following columns: id_std, name_std, classes_std.

1 In the classes_std column we could store the ID's of the classes that the student registered to. Now since there are more classes, the values will be stored as a string of values or text. For example, the next records could be found in the student_std table:

• 1; Ashley Crain; 1, 2, 3

• 2; Danny Morrison; 2, 4, 6, 8

• 3; Loni James; 1, 5

Since students do not attend the same number of classes and since attended classes are stored in one database column, there will clearly be difficulties in retrieving the classes that each student attends. So another storing method should be found.

2 In the classes_std column we could store the ID of a single class attended by the student. So for each class, we would have a corresponding record. Considering the example above, the student_std table would look like this:

• 1; Ashley Crain; 1



• 2; Danny Morrison; 2




• 3; Loni James; 1

• 3; Loni James; 5

Duplicated information inevitably occurs and this is not something that we want for our database.

3 By using a linking or many-to-many table that has two columns (the primary keys of the two main tables), all the inconveniences presented above will be gone. The stdtocls_stc table has three columns : : idstd_stc, idcls_stc and level_stc. Continuing with the example above, the records stored in this table will be the following:

• 1; 1;1

• 1; 2;1

• 1; 3;1

• 2; 2;2

• 2; 4;1

• 2; 6;0


83

• 2; 8;2

• 3; 1;2

• 3; 5;0

As you can see, this is with no doubt the best way to store data in your database when working with many-to-many related tables.

By using the Many-To-Many wizard, you can insert data in one of the main tables (the master table) taking into account the many-to-many relation to the other table (the detail table). Automatically, the needed records will be inserted in the linking table so that the database logic will not be affected.

The Many-To-Many wizard can be applied in a page where an Insert, Update or Dynamic form already exists. The wizard will generate the Many To Many Trigger and a Nested Repeat region:

• The trigger is not editable, so if you want to change any of the settings, undo the last action (if you just applied this wizard) and apply the wizard again. Since with Developer Toolbox you benefit from user interface persistence, there shouldn't be a problem when changing that one or few settings, while the rest remain unchanged:

The Many-To-Many wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Forms > Many-To-Many Wizard.

When using the PHp_MySQL server model, the Many-to-Many wizard in Developer Toolbox also allows you to have other fields in the many-to-many table as well. Considering the example above, this wizard will match the case where your linking table also has to store, say the level for each student for a particular class. This way you can differentiate between beginners, advanced or graduates.

The many to many wizard complies with its predecessor restrictions and can be accessed from the same places: the Insert bar > Developer Toolbox tab and the Server Behaviors tab > Plus (+) > Developer Toolbox > Forms.

To configure the first step options correctly:1 In the Master table drop-down menu select the table on which the Insert/Update/Dynamic form in page is based. This is the table that will have records inserted or updated, taking into account its many-to-many relation with another table.

2 In the Many to many table drop-down menu select the linking table between the two many-to-many related tables. The linking table should contain two columns that store the primary keys of the main tables.

3 In the Key to master table drop-down menu select the table column (of the many-to-many table) that makes reference to the primary key of the master table (the one used in the Insert/Update/Dynamic form).

4 In the Key to detail table drop-down menu select the table column (of the many-to-many table) that makes reference to the primary key of the detail table. This table's records will be displayed as checkboxes in the form in page. For the example considered, it offers the possibility to specify all the classes that a student registers to.


84

5 In the Detail table drop-down menu select the detail table, namely the one whose records will be displayed in the form (as checkboxes) and chosen from. The selection of one or more elements will be associated to the master record.

6 In the Primary key column drop-down menu select the primary key column of the detail table.

7 In the Get labels from drop-down menu select the column that stores the labels that you want displayed besides the checkboxes in browser.

8 In the Number of columns text box specify how many columns you want there to be when all the records from the detail table are displayed as checkboxes.

9 The buttons in the lower part of the interface offer the following functionalities:

• The < Back / Next > buttons are disabled, the wizard having only one step.




To configure the options for the PHP_MySQL server model:1 In the Form fields grid you can see the list of fields that will be added onto the page. You can add fields by clicking on the Plus (+) button and selecting the field from the list. Also, to remove a field simply select it and click the Minus (-) button. To configure a field select it in the grid and use the controls below the grid to change the options.

2 In the Label text box enter the text to be displayed as header for the field.


4 In the Submit as drop-down menu select the column type.

5 In the Default value text box enter the value that the column will use by default. You can either enter static data or use the Developer Toolbox Dynamic Data interface to select a dynamic value.


85

The wizard will add a looper area with checkboxes for selecting each student and for each the supplemental fields you have selected, as you can see in the preview below:

Build master-detail lists and forms with PHP_MySQL server modelsWhen dealing with data that is stored in different tables that are related to each other through a foreign key, you must link the lists and forms used to display and update information in order to ensure that the preservation of the data’s integrity. This set of commands for PHP_MySQL server models lets you convert a regular set of Dynamic lists and forms to a master detail set.

To obtain a master-detail set of pages:

1 Create the regular Dynamic Forms and Lists that are used to display and update information from the desired tables.

2 Open the page containing the Dynamic List for the master table and apply the Convert to Dynamic Master List command.

3 Open the page containing the Dynamic List for the slave table and apply the Convert to Dynamic Detail List command.

4 Finally, open the page with the Dynamic Form used to update information into the detail table and apply the Convert to Dynamic Detail Form command.

This sub-section describes the commands, server behaviors and browser behaviors associated to the Developer Toolbox master - detail features:

• “Convert to Master List” on page 86

• “Convert to Detail List” on page 86

• “Convert to Detail Form” on page 87


86

Convert to Master ListYou can use this command in order to complete the first step to create a Master-Detail set of Dynamic lists. Such a set of pages is mostly useful in order to display information stored in separate, yet related tables.

The Convert to Master List command is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Master Detail > Convert to Master List.

This wizard will add a link to the detail page, passing the right parameters, next to the edit and delete links on each row.

Before applying this command on the page:1 Create a Dynamic List on the master table.

2 Create at least the empty file which will store the detail list to which the master page will point.

To set the otions of the Convert to Master List dialog box: 1 In the Button label text field, enter the text to be displayed on the link / button pointing to the detail page.

2 In the Detail list page file field, click the Browse button and select the file containing the dynamic detail list in the site structure.

3 The three buttons in the top right corner of the interface offer you the next functionality:




4 When you are done setting these options click OK to apply the changes.

Convert to Detail ListYou can use this command in order to transform a regular Dynamic List into a detail list. The page will have to be used with a Master List, and will be accessible when clicking on the Details link. The detail list is automatically filtered by the value passed on from the master list, and displays only entries that belong to the selected master record.

Important: When creating the regular Dynamic List for the detail page, make sure you leave the foreign key to the master table as a field in the page. The Convert to Detail List server behavior will automatically transform it into a trans-parent field which takes the value passed by the master page.

The Convert to Detail List command is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Master Detail > Convert to Detail List.

This command will perform several changes to the list, as follows:

• A new title area is created, displaying the value of the master record that has been selected.

• A link to return to the master list is created

• The list recordset is changed to filter by the value passed by the master page.


87

Before applying this command on the page:1 Create a Dynamic List on the master table. Learn how to do so here.

2 Create the Dynamic List on the detail table.

To set the options of the Convert to Detail List dialog box:1 In the Connection drop-down menu select the database connection used for the list.

2 In the Table drop-down menu select the master table.

3 In the Primary key drop-down menu select the master table's primary key column.

4 In the Display column drop-down menu select the master table column that you wish to be displayed in the list title.

5 In the Configure Detail Table area set the options for the detail table to use.

6 In the Table drop-down menu select the detail table used to build the list upon.

7 In the Foreign key drop-down menu select the detail table column that stores the relation to the master table.





9 When you are done setting these options click OK to apply the changes.

If you want to test the page you have created a detail list on, you must first upload the master and detail pages to the testing server, and then access the master list page. By clicking on the Details link, the detail list will be loaded and display the corresponding records.

Convert to Detail FormYou can use this command in order to transform a regular Dynamic Form into a detail form. You need to perform this operation when using a set of master-detail pages, in order to ensure that records that are added from the detail form are actually related to the selected master record. You can apply this command on the Dynamic Form page that is associated to the detail Dynamic list.

The Convert to Detail Form command is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Master Detail > Convert to Detail Form.

This command will perform several changes to the form, as follows:

• A new title area is created, displaying the value of the master record for which changes are being made.

• The form field corresponding to the selected relation column is removed.

• The value of the master record that has been selected is entered automatically when adding new records.

Before applying this command on the page, follow these instructions:1 Create a Dynamic List on the master table. Learn how to do so here.

2 Create the Dynamic List on the detail table. Learn how to do so here.


88

3 Create the Dynamic Form for the detail list. Learn how to create a Dynamic form here.

To set the options of the Convert to Detail Form dialog box:1 In the Connection drop-down menu, select the database connection used for the list.

2 In the Table drop-down menu, select the master table.

3 In the Primary key drop-down menu, select the master table's primary key column.

4 In the Display column drop-down menu, select the master table column that you wish to be displayed in the list title.

5 In the Configure Detail Table area, set the options for the detail table to use.

6 In the Table drop-down menu, select the detail table used to build the list upon.

7 In the Foreign key drop-down menu, select the detail table column that stores the relation to the master table.


• Click OK when you are done configuring the settings.



9 When you are done setting these options, click OK to apply the changes.

If you want to test the page you have created a detail form on, you must first upload the master and detail list and form pages to the testing server, and then access the master list page. By clicking on the Details link, the detail list will be loaded and display the corresponding records. Then you can use the Insert or Update features to test out the master - detail relationship.

89

Chapter 4: Validate Form Input

This chapter presents a time-saving feature of Adobe® Dreamweaver® Developer Toolbox regarding the data validation. Aside from the standard server-side validation of the new data entered in a form and then submitted to the server, Developer Toolbox, through its form validation mechanisms, also allows the client-side data validation for the form elements. This client-side validation takes place at the moment when the user inputs the data in the form.

The standard form validation from Developer Toolbox comes with a broad range of validation templates, so it is easier to decide what type of data will be allowed in the form fields.

The validation process can be applied to both Transaction Engine generated forms and standard forms.


• “Form Validation in wizards” on page 89

• “Validate Form server behavior” on page 91

• “Advanced validation” on page 95

• “Check Multiple Unique Key (PHP_MySQL server model)” on page 108

• “Check Forbidden Words (PHP_MySQL server model)” on page 110

• “Secure forms with Captcha (PHP_MySQL server model)” on page 113

• “Convert to XHTML (PHP_MySQL server model)” on page 117

• “Compare Transaction Fields (PHP_MySQL server model)” on page 121

Form Validation in wizardsThere is a new step in the Insert Record/Update Record/Custom Form wizard is available. The purpose of this step is to offer you the possibility of defining a rule for each form element, so that bad input will be avoided.


90

Due to this integration, it is not needed to add a separate validation server behavior when using one of the three wizards. The interfaces for these wizards are almost identical, the only difference being the window's title:

To set the dialog box options:1 The Form fields area contains all the form fields in the current transaction. Specify the validation rules for each data-entry in the HTML form by selecting a row (single click) in the Form fields grid and entering the required infor-mation in the interface controls below the grid. Read along for instructions.

2 The Required checkbox defines whether or not the current field is mandatory when entering input in the form.

3 In the Validation format drop-down menu select the validation rule that will apply to the current form field. Depending on the selected format, different controls will appear on the interface. To learn more, see “Fields infor-mation” on page 26.

4 If the Custom message option is checked, you can define your own error message to be displayed when the data does not match the validation format.

5 In the Error message text box (enabled when the option above is checked) enter the custom message that users will see when entering data that does not conform with the defined rule. All form fields that require validation have a default error message. The custom error message overwrites the default one.

6 After completing the user interface, click Finish to apply the wizard, Cancel to dismiss it without making any changes, or Next (if the case) to move on to the next step.


91

Validate Form server behaviorThis server behavior allows adding validation rules to transaction form fields, in order to ensure that only correct data is entered.

To add a Validate Form trigger into the page:1 First create an Insert, Update, Custom or Login transaction. The server behavior is implemented as a trigger, therefore a transaction must exist on the page, so that the trigger can register to it. If more than one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Validate Form.

3 The user interface that opens is divided into two tabs. Configure these tabs as follows:

• The Basic tab, where options related to the actual validation must be set.

• The Advanced tab, where trigger specific options can be set.

4 Once you're done setting the options, click OK to apply the server behavior.


92

The Basic tabThe purpose of this user interface tab is to allow the developer set up the validation rules for each transaction field:

To set the dialog box options:1 The Form fields area displays all the transaction fields to which validation rules can be applied. The fields list is retrieved from the registered transactions. If registered to multiple transactions, the area will contain the reunion of the transaction fields.

The area displays the field name, how it is submitted, the required state and the associated validation format. After selecting a field from the grid, you can set its options, using the elements below.

2 The Required checkbox determines whether the selected field is mandatory or not. If checked, it will display a red * in the form, next to the field name.

3 In the Validation format drop-down menu select the validation rule to apply on input data. The following options are available:

If the field is submitted as text (you can see this in the second column of the Form fields grid), one of the following validation formats can be applied:

• No Validation – if you do not want to enforce any data validation on the form field.


93

• E-mail Address – checks if entered text is an e-mail address (such as [email protected]).

• Credit Card – checks if entered text is a credit card number.

• Credit Card Visa – checks if entered text is a 13 or 16-digit credit card number

• Credit Card Mastercard – checks if entered text is a 16-digit credit card number

• Credit Card American Express – checks if entered text is a 15-digit card number.

• Credit Card Discover – checks if entered text is a 16-digit card number.

• Credit Card Diners Club – checks if entered text is a 14-digit card number.

• ZIP Code – checks if entered text is a numeric postal code (several formats are accepted).

• ZIP Code US (5 digits) – checks if entered text is a 5-digit postal code (having the mask NNNNN).

• ZIP Code US (9 digits) – checks if entered text is a 9-digit postal code (having the mask NNNN-NNNNN).

• ZIP Code Canada – checks if the entered text conforms to the mask ANA NAN.

• ZIP Code UK – checks if the entered text conforms to one of the masks AN NAA, ANA NAA, ANN NAA, AAN NAA, AANA NAA, AANN NAA.

• Phone Number - allows - / . () + , and space as digit separators.

• Social Security Number

• URL

• IP Address

• Color (hexadecimal)

• Color (plain-language)

• Mask

• Regular Expression - allows you to define your own validation rule in the displayed text box. For more information on regular expressions, please visit http://www.regular-expressions.info/

Note: In the examples above, A represents a letter and N represents a digit.

Note: The Mask validation format provides an easy way to define your own rule for acceptable field input. The rule you write determines what type of input is allowed in each character position and the length of the entry. The following characters have special meanings: A - Allows an upper or lower-case character: A-Z and a-z. X - Allows an upper or lower-case character or number: A-Z, a-z, and 0-9. 9 - Allows a number: 0-9. ? - Allows any character. If you enter any other character (other than the above) it will be inserted into the field data.

Let's consider the following example for a Mask format: AAA?AAAA?AAAAA. The "Try this today" input is allowed, while the "Try this tomorrow" or "Try it 5 times" inputs are not allowed (the first one is too long, the second one contains characters not accepted by the mask).

Except for the Mask and Regular Expression formats, you can notice two text boxes in the interface, under the Validation format drop-down: Min char and Max char. Enter the minimum, respectively the maximum number of characters allowed for that form field.

If the field is submitted as numeric the following options are available:

• No Validation


94

• Numeric

• Positive Integer

• ZIP Code

• Mask

• Regular Expression

Except for the Mask and Regular Expression formats, you can notice two text boxes in the interface, under the Validation format drop-down: Greater than and Less than. Enter the minimum, respectively the maximum value accepted by the form field.

If the field is submitted as date or as timestamp the validation formats that can be applied are:

• No Validation

• Date

• Datetime

• Time

• Mask

• Regular Expression

Except for the Mask and Regular Expression formats, you can notice two text boxes in the interface, under the Validation format drop-down: Greater than and Less than. Enter the minimum, respectively the maximum date/time accepted by the form field. You can also notice a button labeled Change. By clicking it, you can change the date formats.

4 In the following text boxes you can choose a minimal and maximal value, depending on the validation type and format selected earlier.

• If the Custom message option is checked, you can define your own error message to be displayed when the data does not match the validation format.

• In the Error message text box (enabled when the option above is checked) enter the custom message that users will see when entering data that does not conform with the defined rule. All form fields that require validation have a default error message. The custom error message overwrites the default one.





These buttons appear on both interfaces of the Validate Form trigger.



95

The Advanced tabThe purpose of this user interface tab is to allow the developer to change the default trigger properties, to suit the particular situation. All trigger properties (name, type, priority, transactions) can be set from this dialog box:

For instructions on completing this step, see the Advanced tab. For the Validate Form trigger, by default the Priority is set to 10 and the Type is BEFORE, as it should execute before the transaction takes place.

The server behavior added this way can be edited later by double-clicking its name in the Server Behaviors tab of the Application panel.

Advanced validationThis sub-section provides information upon the Developer Toolbox tools that can perform complex validation actions:

• “Check Unique Key” on page 96

• “Check Detail Records” on page 98

• “Delete Detail Records” on page 100

• “Check Master Record” on page 104


96

• “Build complex conditions” on page 107

Check Unique KeyThe Check Unique Key server behavior allows the developer to check if a certain submitted value is unique before using it in a transaction. This means that you can check the table for another entry, to ensure no duplicates exist.

To add a Check Unique Key trigger into the page:1 First create an Insert, Update, Custom or Login transaction. The server behavior is implemented as a trigger, therefore a transaction must exist on the page, so that the trigger can register to it. If more then one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Check Unique Key.


• The Basic tab, where options regarding the field and value to check can be set.

• The Advanced tab, where you can set trigger properties.



97

The Basic tabIn this part of the user interface you can set options regarding what table field to check:

To set the dialog box options:1 In the Table drop-down menu, the table used in the transactions on page is automatically selected and the drop-down menu is disabled.

2 In the Column drop-down menu all fields belonging to the table selected above are displayed. Select the field to check for unique values.

3 In the Error message text area enter the text to be displayed if another entry has been found in the table. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the message.





These buttons are common to both tabs of the Check Unique Key interface.



98

The Advanced tabThis section of the dialog box allows setting the trigger properties:

For instructions on completing this step, see the Advanced tab. For the Check Unique Key trigger, by default the Priority is set to 30 and the Type is BEFORE, as it should execute before the transaction takes place.


Check Detail RecordsThe Check Detail Records server behavior allows the developer check if any detail records related to the master record that is being deleted exist. If detail records exist, the delete transaction is stopped, in order not to leave detail records that cannot be accessed.

To add a Check Detail Records trigger into the page:1 First create a Delete or Custom transaction. The server behavior is implemented as a trigger, therefore a trans-action must exist on the page, so that the trigger can register to it. If more then one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Check Detail Records.



99

• The Basic tab, where options related to the actual check can be set.



The Basic tabThe purpose of this user interface tab is to allow the developer set up the check operation options:

To set the dialog box options:1 In the Transaction table drop-down menu, the table used in the delete/custom transaction on page is automati-cally selected and the drop-down menu is disabled.

2 In the Primary key drop-down menu select the table column containing the primary key of the transaction table.

3 In the Detail table drop-down menu select the table which acts as a detail table for the transaction one. This means that its fields are related to the transaction table through a field.

4 In the Detail foreign key drop-down menu, select the detail table column that stores the relation to the master table.

5 In the Error message text area, enter the text to be displayed when the check returns one or more detail records that exist. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the message.




100



These buttons are common to both tabs of the Check Detail Records interface.



For instructions on completing this step, see the Advanced tab. For the Check Detail Records trigger, by default the Priority is set to 40 and the Type is BEFORE (because checking if any detail records exist must be done before the delete transaction, so that it can be stopped).


Delete Detail RecordsThe Delete Detail Records server behavior allows the developer delete all detail records depending on the one used in the transaction. This implements a cascaded delete of all detail records of the master record being used in the transaction's main operation.


101

To add a Delete Detail Records trigger into the page:1 First create a Delete or Custom transaction. The server behavior is implemented as a trigger, therefore a trans-action must exist on the page, so that the trigger can register to it. If more then one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Delete Detail Records.


• The Basic tab, where options related to the actual delete operation can be set.

• The Files tab (PHP_MySQL server models only) is where you can set options regarding the detail files to delete.

• The Folders tab (PHP_MySQL server models only) is where you can set options regarding the detail folders to delete.


4 Once you're done setting the options, click the OK button to apply the server behavior.

The Basic tabThe purpose of this user interface tab is to allow the developer set up the delete operation options:

To set the dialog box options:1 In the Transaction table drop-down menu, the table used in the delete/custom transaction on page is automati-cally selected and the drop-down menu is disabled.


102

2 In the Primary key drop-down menu the table column containing the primary key of the transaction table is automatically selected and the drop-down menu is disabled.

3 In the Detail table drop-down menu select the table which acts as a detail table for the transaction table. This means that its fields are related to the transaction table through a field.

4 In the Detail foreign key drop-down menu, select the detail table column that stores the relation to the master table.





These buttons are common to both tabs of the Delete Detail Records interface.


The Files tabThe purpose of this user interface tab is to allow the removal of files that are associated to the detail records. This means that if the master record has entries in the detail table, and those have files attached (e.g. departments > employees > employee portrait ) you can set the trigger to also delete the files.

Note: This tab is only available when using the PHP_MySQL server model.


103

To set the dialog box options:1 In the File folder field enter the name of the base folder where the file to be deleted exists. You can use the Browse button to pick the folder, and it will be added relative to the current page.

2 In the Table column drop-down menu select one of the detail table columns that stores the name of the file to remove, or if you have a custom naming, select the None: Rename Rule option.

3 In the Naming rule text field enter the rule to compute the file name on. You can also add other dynamic or static subfolders. To add dynamic data use the Developer Toolbox Dynamic Data icon to visually select it.

The Folders tabThe purpose of this user interface tab is to allow the removal of folders that are associated to the detail records. This means that if the master record has entries in the detail table, and those have folders attached (e.g. departments > employees > employee data in a certain folder ) you can set the trigger to also delete the entire folder associated with the detail record.

Note: This tab is only available for the PHP_MySQL server model.

To set the dialog box options:1 In the Folder(s) grid add rules for folders associated with the detail record that must be deleted. To add a new rule click the Plus (+) button and fill in the options below the grid. To remove a rule select it and then click the Minus (-) button.

2 In the Folder field enter the name of the base folder where the folder to be deleted exists. You can use the Browse button to pick the folder, and it will be added relative to the current page.


104

3 In the Subfolder drop-down menu select one of the transaction fields that gives the name of the folder to remove, or if you have a custom naming, select the None: Rename Rule option.

4 In the Naming rule text field enter the rule to compute the folder name on. You can also add other dynamic or static subfolders, as you can see in the image above. To add dynamic data use the Developer Toolbox Dynamic Data icon to visually select it.


For instructions on completing this step, see the Advanced tab. For the Delete Detail Records trigger, by default the Priority is set to 99 and the Type is BEFORE, as it should execute before the transaction takes place.


Check Master RecordThe Check Master Record server behavior allows the developer to add a check that ensures there is a master record corresponding to the current transaction record.


105

To add a Check Master Record trigger into the page:1 First create an Insert, Update, Custom or Login transaction. The server behavior is implemented as a trigger, therefore a transaction must exist on the page, so that the trigger can register to it. If more then one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Check Master Record.


• The Basic tab, where options related to the actual check can be set.


4 Once you're done setting the options, click the OK button to apply the server behavior.

The Basic tabThe purpose of this user interface tab is to allow the developer set up the fields to be checked in the master table:

To set the dialog box options:1 In the Transaction table drop-down menu, the table used in the insert/update/custom/login transaction on page is automatically selected and the drop-down menu is disabled.

2 In the Foreign key drop-down menu select the table column linking to the master table.

3 In the Master table drop-down menu select the table which acts as a master table for the transaction one. The drop-down menu is populated based on the connection used in the page.


106

4 In the Master primary key drop-down menu select the master table column that stores the primary key.

5 In the Error message text area enter the text to be displayed when the check fails, meaning that the master record does not exist. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the message.





These buttons are common to both tabs of the Check Master Record interface.



For instructions on completing this step, see the Advanced tab. For the Check Master Record trigger, by default the Priority is set to 40 and the Type is BEFORE (because checking if the master record exists must be done before the transaction).



107

Build complex conditionsTo have a trigger start its action only when a certain condition has been met, you can use the condition property found on the Advanced tab of all trigger user interfaces. To define the condition however, there are two ways:

1 Type the condition in the text-field.

2 Press the Build condition button to open the Condition Builder dialog box.

The Condition Builder allows building conditions from either static or dynamic data, using an intuitive interface and generating all the required code for you. If you need more complex conditions, simply switch to the Advanced tab, and you can enter it.

The dialog box is divided into two tabs:

• The Basic tab, where you can build relatively simple conditions easy.

• The Advanced tab, where you can type in more complex conditions.

The Basic tab

To set the dialog box options:1 In the Expression 1 text box enter the condition's first element. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build this expression.

2 From the Condition drop-down menu select the operator used to compare the two expressions.

3 In the Expression 2 text box, enter the second element of the condition. You can also use the Developer Toolbox Dynamic Data to build this expression.





These buttons are common to both tabs of the Condition Builder interface.

5 Click on the Advanced tab to build more complex conditions.


108

Note: If you prefer writing the code yourself in the Expression 1 and Expression 2 fields, please make sure the code is correct and appropriate for the server model you use (ColdFusion, PHP_MySQL, ASP_VBScript etc.).

The Advanced tab

To set the dialog box options:1 In the Expression text area you can see the condition set in the Basic tab. You can make it as complex as you want by using other variables, constants, operators.

2 Click OK when you are done building the condition.

Note: When switching from the Advanced tab to the Basic one, if the condition is simple enough, it will be recognized, and the respective fields will be filled in automatically.

Check Multiple Unique Key (PHP_MySQL server model)The Check Unique Key server behavior for the PHP_MySQL server model allows the developer to check if certain values submitted by a form are unique before using them in a transaction. This means that you can check the table for another entry, based on multiple criteria to ensure no duplicates exist.

To add a Check Unique Key trigger into the page:1 First create an Insert, Update, Custom or Login transaction. The server behavior is implemented as a trigger, therefore a transaction must exist on the page, so that the trigger can register to it. If more then one transaction exists, the trigger will register to all of them.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Check Unique Key.


• The Basic tab, where options regarding the field and value to check can be set.




109

The Basic tabIn this part of the user interface you can set options regarding what table field to check:

To set the dialog box options:1 In the Table drop-down menu, the table used in the transactions on page is automatically selected and the drop-down menu is disabled.

2 In the Column(s) grid add the fields to check. You can add fields by clicking on the Plus (+) button and remove them by selecting and clicking the Minus (-) button.

3 In the Error message text area enter the text to be displayed if another entry has been found in the table. You can use the Developer Toolbox Dynamic Data (the lighting bolt icon) to build the message.





These buttons are common to both tabs of the Check Unique Key interface.



110


For instructions on completing this step, see the Advanced tab. For the Check Unique Key trigger, by default the Priority is set to 30 and the Type is BEFORE, as it should execute before the transaction takes place.


Check Forbidden Words (PHP_MySQL server model)The Check Forbidden Words server behavior allows the developer to check if certain words exist in the fields of the form that is validated. This means that you can check all the fields in a form against a list of defined forbidden words to ensure that no offensive or forbidden content is submitted. You can define the word list in a table, or enter it directly into the user interface.

To add a Check Forbidden Words trigger into the page:1 First create an Insert, Update, Custom or User Registration transaction. The server behavior is implemented as a trigger, therefore a transaction must exist on the page, so that the trigger can register to it. If more then one trans-action exists, the trigger will register to all of them.


111

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Form Validation > Check Forbidden Words.


• The Basic tab, where options regarding the word list and the action to take can be set.



The Basic tabIn this part of the user interface you can set options regarding where to retrieve the list from and what action to take when a word on the blacklist is found:

To set the dialog box options:1 In the Build list from drop-down menu you can select between Table and Text. If you choose Table, the word list will be retrieved from a database table. If you select Text, a text area control is displayed and you can enter the forbidden words.

2 The Table drop-down menu is displayed only when the Build list from is set to Table and allows selecting the database table to use to retrieve the word list.

3 The Field drop-down menu is displayed when retrieving the bad words from the database, and allows selecting the table column which stores the bad word.


112

4 If you have decided to enter the bad words (the Text option), the Word list text area is displayed. This is where you can enter each bad word either as a comma - separated list, or one on each line.

5 In the Action drop-down menu select the action to take when a word on the list is found in one of the fields. You have three options:

• Replace bad word with '*' - when the word is found in a form field, each letter is replaced with the * character. Then content is then passed along to the transaction in the changed form.

• Remove the word - the word is deleted entirely from the content. Then the transaction moves on and saves / performs the requested operation on the content without the word in place.

• Display error message - this is the only action that requires user intervention. When a bad word is found, an error message is displayed and the user must manually remove the bad words from the form fields. A second error message is displayed next to each field that contains bad words.

6 In the Error message area enter the message to display when bad words are encountered. This area is enabled and taken into account when the Display error message action is selected. For the error message you can enter static text, or if you want to display the form fields values you can do so by using the Developer Toolbox Dynamic Data button.





These buttons are common to both tabs of the Check Forbidden Words interface.



113


For instructions on completing this step, see the Advanced tab. For the Check Forbidden Words trigger, by default the Priority is set to 20 and the Type is BEFORE, as it should execute before the transaction takes place.


Note: When using a database table to store the list of bad words, make sure that each record contains only one entity - be it a word or a combination of words. When entering the words in the interface text area you can have both a comma separated list of words or one word on each line (separate them with the new line character—Enter on the keyboard).

Secure forms with Captcha (PHP_MySQL server model)To protect the input forms from unsolicited entries by spammers - be they humans or automatic programs - you can use CAPTCHA to force users enter a specific word. CAPTCHA is an acronym for Completely Automated Public Turing Test to Tell Computers and Humans Apart.

The principles behind CAPTCHA are as follows:

• The user is presented with a garbled image on which some text is displayed. This image is generated by the server using random text.


114

• The user must enter the same letters in the text into a text field that is displayed on the form to protect.

• When the form is submitted, the server checks if the text entered by the user matches the initial generated text. If it does, the transaction continues. Otherwise, an error message is displayed and the user has to enter a new code.

You can add such a verification to an already created input form. To add it you can use the wizard or the server behavior.

• The Captcha wizard

• The Check Captcha server behavior.

In order to use CAPTCHA, you must meet the minimum requirements for Developer Toolbox, and have a working Image processing library installed on the server. To learn more, see “Minimum requirements” on page 2.

Add Captcha using the wizard (PHP_MySQL server model)You can add all blocks of a secure form at once by using the Captcha wizard with PHP_mySQL server models. The wizard can be found in the Developer Toolbox tab of the Insert bar. Before using this wizard you must have already created a form on the page that performs one of the following actions:

• Insert a record (this includes the User Registration transaction from Developer Toolbox).

• Update a record.

• A form created with the Custom Form wizard or which uses the Custom Transaction from Developer Toolbox.

The wizard will add the following elements to the page:

• A text field and the dynamic image placeholder for the server generated security code.

• A Custom Trigger that is registered to the transaction, executes before it and checks if the user entered security code matches the one displayed on the image.

To secure a form using the Insert Captcha Image wizard:1 Create the form on the page using one of Developer Toolbox's wizards, or create a custom form.

2 Place the cursor inside the form and add a new row. Enter a label—e.g. Security code.

3 Start the wizard by clicking on its icon. Fill in the user interface options as shown below.

4 Click OK to apply the changes.

To configure the wizard options:The wizard has only one step, where you can define the available options for captcha.

1 In the Error message text field enter the message that will be displayed when the user mistypes the captcha code. You can use the Developer Toolbox Dynamic Data to add dynamic values to the message.

Make the message as suggestive as possible, so the user will understand the problem and correct it for the next submit.

2 Click OK when done to close the user interface and apply the changes.


115

The wizard adds at the cursor location a text field and a dynamic image placeholder. This is where the security image that the user must enter in the text field is displayed.

The wizard also adds a server behavior named Check Captcha which you can use in order to edit the previously entered error message and options.

When the page is viewed in a browser and the correct code is not entered, the error massage that was defined in the user interface gets displayed, and a new code is generated.

Note: The code uses a temporary folder to store images that are displayed in the browser. The folder is: <site_root>/includes/common/_temp/ . Automatic clean-up is performed on this folder, removing used images. In order for the Captcha behavior to work correctly, you must set the the user permissions that the web server runs on read and write permissions for this folder.

Note: Inside the _temp folder there is an empty.txt file. This file is required by Dreamweaver to automatically generate the folder. You should not remove this file.

Configure the Captcha Server Behavior (PHP_MySQL server model)The Captcha wizard adds a server behavior on the page, the text field, and the dynamic image. Its name is Check Captcha and allows changing the error message that is displayed when users enter the wrong code.

Its user interface is divided into two tabs:

• The Basic tab—where you can check the captcha field ID and change the error message.

• The Advanced tab—where you can configure trigger options: type, priority, transaction to which it is attached to.

Instructions for setting the options on these two user interface tabs can be found below.

The Basic tabOn the Basic tab you can check the ID of the captcha field, the method it uses and the Error message:


116

• The Captcha field text field displays the ID of the generated captcha text field. The field is disabled, so you cannot change the ID.

• In the Submit method text field you can see what method of passing the data from the page to the Captcha check function is used.

• In the Error message text area you can enter a message to be displayed when the users enter a code that does not match the one displayed.

When you are done configuring the options click OK to apply the changes, or Advanced to move on to the second tab.


117


For instructions on completing this step, see the Advanced tab. For the Check Captcha trigger, by default the Priority is set to 10 and the Type is BEFORE (because checking if the code is correct must be done before the transaction).


Convert to XHTML (PHP_MySQL server model)To make sure form fields containing HTML code contain only the tags you want, or to ensure that the HTML is valid, use the Convert to XHTML server behavior. This server behavior allows you to check the HTML validity in user submitted fields so that they are XHTML complaint. It also lets you allow or deny certain tags from within the submitted content of the page's form the fields.

Before applying the server behavior onto a page, you must have gone through these steps:1 You have an Insert, Update or Custom transaction on page, with at least one field - be it text field, text area or hidden field.


118

2 Configure the path to the HTML Tidy utility. This external program is used to convert existing content to XHTML compliant content.

To set up Tidy, follow these instructions:

a Download HTML Tidy from the project web site. You should make sure you have the latest version.

b Extract the binary file (or executable if on Windows) to a folder you can access.

c Open the <site_root>\includes\common\KT_config.inc.php file in Dreamweaver.

d Edit the KT_preferred_tidy_path variable and enter the path to the extracted executable files. Omit the name of the file and the trailing \ if any.

e Save the KT_config.inc.php file and upload it to the server.

f As a last check make sure your server is configured to allow the execution of the HTML Tidy external program. On Microsoft Windows you must allow the user as which the web server is running execution rights on the cmd.exe file.

3 On the page containing the form in Dreamweaver apply the Convert to XHTML server behavior. You can access it from the Application panel > Server Behaviors tab > Developer Toolbox > Form Validation.

4 The user interface is divided into two tabs. Configure each of them as described below:

• The Basic tab

• The Advanced tab.


The server behavior will add logic into the page that invokes the Tidy external program on the field content and cleans it up. The transaction will continue with the correct content.

The Basic tabOn this tab of the user interface you can define tag restrictions and the fields whose content you wish to have converted to XHTML. The controls on this tab should be used as follows:

1 In the Tag policy drop-down menu define how to restrict entered tags. You have three options:

• Allow all tags - all HTML tags that the user has entered are accepted by the system.

• Allow following tags only - only the tags defined in the Tags list text box will be accepted by the system. All other tags will be removed before parsing content with HTML Tidy.

• Deny following tags only - tags that are entered in the Tags list text box will be stripped from the content. All other tags are left as is.

2 The Tags list text box is enabled only when the Tag policy is set to allow or deny certain tags.


119

3 In the Fields grid define the form fields whose content will be converted to XHTML. To add a new field to the check, click the Plus (+) button on top of the grid and then select the appropriate field in the pop-up dialog. To remove a field, select it in the grid and click the Minus (-) button.

4 Click on the Advanced tab if you need to define additional trigger properties, or click OK to apply the trigger with the default execution priority.


120


For instructions on completing this step, see the Advanced tab. For the Convert to XHTML trigger, by default the Priority is set to 12 and the Type is BEFORE, as it should execute before the transaction takes place.


Note: The code uses a temporary folder to store the text being converted in a temporary file. The folder is: <site_root>/includes/common/_temp/ . In order for the Convert to XHTML behavior to work correctly you must allow the user as which the web server runs read and write permissions on this folder.

Note: Inside the _temp folder there is an empty.txt file. This file is required by Dreamweaver to automatically generate the folder. You should not remove this file.


121

Compare Transaction Fields (PHP_MySQL server model)To validate form fields between them—e.g. compare two form fields to make sure their values are not the same—you can use the Compare Transaction Fields server behavior. This server behavior allows you to define pairs of fields that are compared, and the condition to compare them on. You can also set a custom error message for each check that is performed.

Before applying the server behavior onto a page, you must have gone through these steps:1 You have an Insert, Update or Custom transaction on page, with at least two fields

2 On the page containing the form in Dreamweaver apply the Compare Transaction Fields server behavior. You can access it from the Application panel > Server Behaviors tab > Developer Toolbox > Form Validation.

3 The user interface is divided into two tabs. Configure each of them as described below:

• The Basic tab

• The Advanced tab.


The server behavior will add logic into the page that compares each of the field paires that were configured in the user interface.

The Basic tabOn this tab of the user interface you can define the fields to compare and how to compare them.

Fill in the user interface as follows:1 In the Fields grid you can see all of the already added comparison conditions, with all of the pertinent information. To add a new comparison click the Plus (+) button and then define the properties in the controls below the grid. To remove a comparison, select it in the grid and click the Minus (-) button to remove it.

2 In the Field drop-down menu select the first transaction field for the comparison.

3 In the Condition drop-down menu select the type of comparison to make.

4 In the Compare to field select the other transaction field to compare the first with. Either enter a value or use the Developer Toolbox Dynamic Data to select it.


122

5 In the Error message text box enter the message to display when the comparison fails.

6 Click the Advanced tab to continue configuring the trigger, or OK to accept the default trigger and transaction binding properties.

The Advanced tabThe purpose of this user interface tab is to allow the developer to change the default trigger properties, to suit the particular situation. All trigger properties (name, type, priority, transactions) can be set from this dialog box:.

For instructions on completing this step, see the Advanced tab. For the Compare Transaction Fields trigger, by default the Priority is set to 11 and the Type is BEFORE, as it should execute before the transaction takes place.


123

Chapter 5: Form Controls

This chapter describes the Form Controls features which are designed to improve usability by adding dynamic elements to HTML forms. These features are included in Adobe® Dreamweaver® Developer Toolbox and will be useful to any web programmer.

These form controls (also called widgets)improve the appearance of user interfaces, allow complex behaviors, and make the process of filling in certain forms faster.

Note: The Form Controls use JavaScript to achieve their functions, and as such, they will not work on browsers with no Java / JavaScript support, or with support disabled. Also, the controls do not function properly with the Opera 7.5 browser.

There are 13 widgets included in the bundle, and each one of them will be presented in detail in the following sections.


• “Masked Text Field” on page 123

• “Numeric Text Field” on page 126

• “Smart Date” on page 128

• “Autocomplete Text Field” on page 130

• “Date Picker” on page 132

• “Restricted Textarea” on page 134

• “Editable Drop-down” on page 136

• “Dependent Drop-down” on page 138

• “Multi-field Drop-down” on page 142

• “Comma-separated Checkboxes” on page 145

• “Comma-separated Menu” on page 147

• “Comma-separated Selector” on page 149

• “List Sorter” on page 151

Masked Text FieldThe Masked Text Field widget is an improved text-field that reinforces a certain format for the values to be entered.

You can use the Masked Text Field when you need the site visitors to enter data that must comply with a predefined format (social security numbers, license plates etc).

This section presents details on:

• “Configure Masked Text Field” on page 124

• “View Masked Text Field in browser” on page 125


124

Configure Masked Text FieldThe Masked Text Field server behavior allows the web developers to include a masked text field in their site pages. Before applying it, there must be a text field added in your Dreamweaver page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Masked Text Field.

The user interface has only one tab. Directions about its correct configuration are given below.

To set the dialog box options:1 In the Apply to field drop-down menu select the text field on which to apply the server behavior.

2 In the Mask drop-down menu select one of the predefined masks or create your own custom mask. To learn more about this, read the note below.

3 The Restrict to mask checkbox enables the option of limiting the text field input to the mask type. If you do not check it, you can enter at most as many characters as the mask has (so less, but not more).

4 In the Default value text box enter a starting value for the masked text field. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.





A mask is a validation format that provides an easy way to define your own rule for acceptable field input. The rule you write determines what type of input is allowed in each character position and the length of the entry. For the Masked Text Field widget, the following characters have special meanings:

A - Allows only the UNICODE alphabetic characters (upper or lower-case) inside the following ranges:

• \u0040-\u005A


125

• \u0061-\u007A

• \u0100-\u017E

• \u0180-\u0233

• \u0391-\u03CE

• \u0410-\u044F

• \u05D0-\u05EA

• \u0621-\u063A

• \u0641-\u064A

• \u0661-\u06D3

• \u06F1-\u06FE

These are UTF8 character codes from the following UNICODE blocks:

• Basic Latin

• Latin Extended-A

• Latin Extended-B

• Greek

• Cyrillic

• Hebrew

• Arabic

X - Allows all the characters that A replaces, plus all the digits (0-9).

9 - Allows a number: 0-9.

? - Allows any character.

If you enter any other character (other than the above) it will be inserted into the field data.

Let's consider the following example for a Mask format: AAA?AAAA?AAAAA. The "Try this today" input is allowed, while the "Try this tomorrow" or "Try it 5 times" inputs are not allowed (the first one is too long, the second one contains characters not accepted by the mask).

View Masked Text Field in browserThe Masked Text Field replaces a regular text field in a form, and allows the developer enforce a specific format for the entered data. When displayed in the browser, the text field looks no different from a regular one, the difference being related to te behavior only:


126

In the example above, the masked text field has been configured to accept only input conforming to the PIN format (e.g. 1234). If you enter anything other than a character matching the mask, (e.g. for this example, a letter, or another sign), the character will be automatically deleted; if you enter a wrong character three times in a row, a visual display of the format you must enter will be displayed beside the text field:

This text will automatically disappear when the correct format is entered.

Also, if in the defined mask, separating characters exist, they will be automatically entered by the script.

The controls are created using Java Script, and thus, they work only if a browser with Java Script support is used. If the browser does not have Java Script, the text field will behave like a normal one, with no enhancements at all.

Numeric Text FieldThe Numeric Text Field is an improved text-field that restricts user input to numeric data only, and allows the use of increment/decrement buttons and keys.

You can use the Numeric Text Field in an online shop, on forms that require numbers only (such as price, weight, quantity or size).


• “Configure Numeric Text Field” on page 126

• “View Numeric Text Field in browser” on page 128

Configure Numeric Text FieldThe Numeric Text Field server behavior allows the web developers to include a numeric text field (the input can only consist of digits) in their site pages. Before applying it, there must be a text field added in the Dreamweaver page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Numeric Text Field.


127



2 The Allow negative checkbox enables the option of entering negative numbers. The minus ("-") character will be accepted at the beginning of the text field, when needed.

3 The Allow float checkbox enables the option of entering rational numbers. The period (".") character will be accepted once in the text field.

4 The Display spin control checkbox allows the appearance of the increment/decrement controls when the widget is loaded in the browser.

5 The Use min/max value checkbox enables the two text boxes below it, when checked.

6 In the Greater than text box enter the minimum value for the numeric input. When a number lower than the minimum value is entered, it will be replaced with the minimum value.

7 In the Less than text box enter the maximum value for the numeric input. When a number greater than the maximum value is entered, it will be replaced with maximum value.

8 In the Default value text box enter a starting value for the numeric text field. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.






128

View Numeric Text Field in browserWhen the Numeric Text Field widget is applied on a form text field element, it will change its behavior and the way it looks, as follows:

If the browser supports Java Script, two buttons will be displayed next to the text field, allowing you to increment or decrement the value displayed.

• The text field allows only numeric input; if you enter a character that isn't numeric, or the decimal and negative signs, it will be ignored.

• The negative sign can only be entered as the first character. If it is placed anywhere else, it will be treated as any other bad input.

• The decimal separator can only be placed once. If you try entering it a second time, it will be treated as bad input, and ignored.

• The increment and decrement buttons have different behavior, based on how long they have been pressed: in the first 5 seconds, the buttons will increment or decrement the value in the text field by one. If they are held for more than 5 seconds, they will automatically add or subtract 10 to the value in the text field. The same behavior is achieved when pressing the + and - buttons on your keyboard.

• If the browser does not support Java Script, or has it disabled, the text field will behave as a regular one.

Smart DateThe Smart Date Widget is a improved text field that allows you to enforce a date format, while easing the input method.

You can use the Smart Date Widget in registration forms, where users have to enter birthdays, or in order forms, for the delivery dates.


• “Configure Smart Date” on page 128

• “View Smart Date in browser” on page 129

Configure Smart DateThe Smart Date server behavior allows the web developers to include a smart date text field in their site pages. Before applying it, there must be a text field added in the Dreamweaver page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Smart Date.


129



2 The Date format used in your site is displayed in bold text. You can change it by clicking on the button next to it, Change. For more details, read Date formats.

Note: If the entered information is to be inserted in your database, make sure the database date format set up in Date Formats panel is according to the one used by your database server.

3 The Use spin control checkbox allows the appearance of the increment/decrement controls when the widget is loaded in the browser.

4 The Use default now checkbox enables the smart date text field to automatically display the current date when the site page is loaded, in case there is no other default value.

5 The Restrict to mask checkbox limits the number of characters typed to the mask length.

6 In the Default value text box enter a starting value for the smart date text field. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.





View Smart Date in browserThe Smart Date widget is designed to help prevent incorrectly formatted dates when submitting forms. It is applied on a regular text field, and alters its behavior as follows:


130

If the browser on which the page is viewed supports Java Script, two buttons will be displayed next to the regular text field, allowing you to increment or decrement the value of the currently selected group (date, month or year).

• The increment and decrement operation can be performed with the help of the + and - keys. Just select the date group (e.g. month/day/year) to change, and either press the keys, or buttons. If you hold the key/button pressed for more than 5 seconds, instead of one unit, it will change the value for the group by 10.

• When using the increment/decrement feature, when the current group has reached its limit (e.g. end of the day or month), the next affected group will be changed.

• The existence of the increment and decrement buttons is determined by the way the widget has been configured.

• When you enter the date in the text field, if you do not respect the format, it will automatically convert the input into a valid format.

Autocomplete Text FieldThe Autocomplete Text Field is an enhanced text field that dynamically completes what you type with matching values from a table. You can also select the values from a list.

You can use the Autocomplete Text Field in user registration forms, such as allowing users to select their country or city easier.


• “Configure Autocomplete Text Field” on page 130

• “View Autocomplete Text Field in browser” on page 131

Configure Autocomplete Text FieldThe Autocomplete Text Field server behavior allows the web developers to include an autocomplete text field in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also a text field added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Autocomplete Text Field.


131



2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the autocomplete text field.

3 In the Get labels from drop-down menu select the table field that stores the information you need to use.

4 In the Records to display text box enter the number of records that you want to be displayed in the drop-down menu at a time. This drop-down menu pops up when pressing the control on the right of the widget, or when pressing the down arrow (the cursor being placed in the text field).

5 If you check the Default option checkbox, then in the drop-down menu in browser, the "Please Select" text will be displayed first. If you leave it unchecked, the default option will be blank.

6 In the Default value text box enter a starting value for the autocomplete text field. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.





View Autocomplete Text Field in browserThe Autocomplete Text Field replaces a regular text field in a form, and adds the autocomplete feature. Its behavior and look in a browser (with Java Script support) are as follows:


132

A button is displayed beside the normal text field section, allowing the user open a drop-down list with the elements that can be entered.

When the user enters text, and it matches something in the list, the field will be completed with the remaining characters displayed in blue.

When more than one entry has been found to match the user input, the first one will be displayed for completion. The rest can be accessed by pressing the down arrow key, or the drop-down button.

If the page containing an autocomplete text field is opened in a browser that does not support Java Script, the widget will be displayed as a regular text field.

Date PickerThe Date Picker is an improved text field that lets you visually select a date from a calendar.

You can use the Date Picker text field on forms that require users to enter a date, in order to make sure that no errors are committed, and to ease input.


• “Configure Date Picker” on page 132

• “View Date Picker in browser” on page 134

Configure Date PickerThe Date Picker server behavior allows the web developers to include a date picker text field in their site pages. Before applying it, there must be a text field added in the Dreamweaver page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Date Picker.


133



2 In the Date type drop-down menu select one of the two options:

• Date - if you want to display on the date (day, month, year).

• Datetime - if you want to display the date and the time (day, month, year, hour, minute, second, am/pm).

3 The Date format used in your site is displayed in bold text. You can change it by clicking on the button next to it, Change. For more details, see “Configure Date Picker” on page 132.

Note: If the entered information is to be inserted in your database, select the date format that is compatible with the table field that stores the date-type data.

4 The Monday first day of the week checkbox makes Monday appear as the first day of the week in the calendar. If unchecked, Sunday will appear as the first day.

5 The Single click activation checkbox will insert the clicked calendar date in the text box and then close the calendar. If unchecked, the calendar will be closed by the user (either by clicking the "x" icon, or by clicking somewhere else in the page).

6 The Allow keyboard input checkbox allows you to manually enter the date in the text field, and not only select it from the calendar.

7 The Restrict to mask checkbox limits the number of characters typed to the date format length.

8 In the Default value text box enter a starting value for the date picker text field. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.



134




View Date Picker in browserThe Date Picker allows the user to select the date from a calendar, rather than manually entering the date. It enhances the regular text field, by providing a supplemental button that opens a calendar. As it is created in Java Script, only compliant browsers will be able to use its features.

The Date Picker behavior and look in the browser are as follows:

• In a Java Script compliant browser, a button appears beside the text field. When the button is pressed, it will display the calendar:

• When a date is selected from the calendar, it will be inserted in the text field, and the calendar will close. You can manually alter the date, or re-open the calendar to choose another one.

• If the user decides to manually enter the date in the text field, then it will allow and enforce only the date format specified in the configuration.

Restricted TextareaThe Restricted Text Area is an improved text area that allows the user to enter only a fixed number of characters. It displays the remaining number of characters next to the actual text area.

You can use the Restricted Text Area in forms where users can only enter a maximum number of characters (e.g. an SMS composer).


• “Configure Restricted Textarea” on page 134

• “View Restricted Textarea in browser” on page 135

Configure Restricted TextareaThe Restricted Textarea server behavior allows the web developers to include a restricted text area in their site pages. Before applying it, there must be a text area added in the Dreamweaver page.


135

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Restricted Textarea.


To set the dialog box options:1 In the Apply to field drop-down menu select the textarea field on which to apply the server behavior.

2 In the Max chars text box enter the maximum number of characters allowed in the text area. The default value is 255.

3 The Show character count checkbox displays the number of characters that can still be typed.

4 The Show message if limit reached checkbox notifies you that you reached the maximum number of characters, and that you cannot type any more text.





View Restricted Textarea in browserDepending on how the Restricted Textarea has been configured, it may or may not impact the user visually. However, the behavior is altered from the normal HTML text area in all cases.

If the Show character count option has been enabled in the control's user interface, the number of characters left to enter in the text area will be displayed next to the element:

The behavior of the control is as follows:


136

• Each time a new character is typed, the character counter is decreased. When an existing character is deleted, the counter will increase its value.

• When the maximum number of characters has been reached, the character counter turns its border blue, and optionally, if set in the configuration dialog, a message is displayed.

• If the user copies & pastes to enter content, and its number of characters is bigger than the allowed limit, the content will be truncated to fit the text area, and the limit reached message is displayed.

Editable Drop-downThe Editable Drop-down widget is an improved drop-down that allows you not only to see the items already stored in the database but also to add new ones by typing them in and clicking on the add button.

You can use the Editable Drop-down to select the departments of a company and easily add new ones when the company develops.

• “Configure Editable Drop-down” on page 136

• “View Editable Drop-down in browser” on page 138

Configure Editable Drop-downThe Editable Drop-down server behavior allows the web developers to include an editable drop-down in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also a list/menu item added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Editable Drop-down.


137


To set the dialog box options:1 In the Apply to field drop-down menu select the list/menu field on which to apply the server behavior.

2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the editable drop-down.

3 In the Get labels from drop-down menu select the table field that stores the names you want to be shown in the menu.

4 In the Get values from drop-down menu select the table field that stores the value for the menu elements.

5 In the Number of records to display drop-down menu enter the number of records to be displayed.

6 The Single click select checkbox enables the selecting of an element and then the closing of the menu with only one click.

7 If you check the Default option checkbox, then in the editable drop-down menu in browser, the "Please Select" text will be displayed at first. If you leave it unchecked, the default option will be blank.

8 In the Restrict to list elements drop-down menu select "No" if you want to allow adding new elements, or "Yes" otherwise.

9 In the Default value text box enter a starting value for the editable drop-down. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.


138





Note: If you use this server behavior on the ColdFusion server model, a file named Application.cfm will be automatically generated in the site root folder. Do not delete this file, as it contains settings related to session variables used by the server behavior and the current application. If you remove this file or modify it, application pages that use sessions will not function properly.

View Editable Drop-down in browserWhen placing an Editable Drop-down widget in a page it changes the default behavior of a list/menu field in the following way:

While typing, the text field displays the closest match found in the database. As long as it finds a closest match the "Add this" button is not active.

By clicking the arrow you can open the drop-down to see all elements in the database.

When your text no longer matches an entry in the database the Add this button will become active and you can add the new option to the already existing ones.

Dependent Drop-downThe Dependent Drop-down widget lets you to include two related drop-down menus in the same page.

You can use the dependent Drop-down widget to manage a state-city relationship. For example, on registration you can ask your users to enter both state and city. The drop-down for cities is modified according to their selection from the state drop-down.

• “Configure Dependent Drop-down” on page 139

• “Dependent Drop-down wizard” on page 140

• “View Dependent Drop-down in browser” on page 144


139

Configure Dependent Drop-downThe Dependent Drop-down server behavior allows the web developers to include dependent drop-downs in their site pages. Before applying it, there must be at least one recordset (for the detail form item) created in the Dream-weaver page, and two list/menu items inserted.

Also, the master form item must have values associated to it (either dynamically, through another recordset, or stati-cally). To do this, select the master list/menu item in your Dreamweaver page and use the Property Inspector to associate values to it:

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Dependent Drop-down.


To set the dialog box options for the first tab:1 In the Master field drop-down menu select the form element that has the master role.

2 In the Detail field drop-down menu select the form element that has the detail role. The content of this drop-down menu depends on the selection you made in the master drop-down menu.





These buttons are common to both tabs of the Dependent Drop-downs server behavior interface.


140

4 Click on the Dynamic tab to continue with configuring the server behavior.

To set the dialog box options for the second tab:1 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed in the detail drop-down.

2 In the Primary key drop-down menu specify the primary key field of the current table. This will also be the field that contains the values to be submitted from the dependent menu.

3 In the Foreign key drop-down menu specify the foreign key field that will be the link to the master recordset.


5 In the Default value text box enter a starting value for the dependent drop-down. You can also select it from one of the available recordsets in your page by using the lightning icon on the right.

6 Click OK when you are done configuring the server behavior.

Dependent Drop-down wizardThe Dependent Drop-down wizard automatically creates two select form elements that are linked together. This is an easier way to implement a dependent drop-down when compared to manually adding the dependent drop-down widget, because it generates all necessary elements. Plus, you can select the desired tables both for the master, and dependent menu in a single interface. This gives you a better view on the tables involved in the relation.

The Dependent Drop-down wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Dependent Drop-down Wizard.


141

To set the Step 1 dialog box options:1 In the Connection drop-down menu, select the database connection used for your site, and through which to retrieve the menus data.

2 In the Master table drop-down menu, select the data source for the main menu - the master one.

3 In the Primary key drop-down menu, select the master table's field that contains the unique identifier.

4 In the Detail table drop-down menu select the second menu's data source. This will be displayed in the dependent drop-down menu, and it must contain a link to the master table (as a foreign key).

5 In the Primary key drop-down menu, select the detail table's field that contains the unique identifier. This will also be the field that contains the values to be submitted from the dependent menu.

6 In the Foreign key drop-down menu select the detail table's field containing the link to the master table.






These buttons appear on all three interfaces of the Insert Record Form wizard, so their role will not be explained again in the next two steps.


To set the Step 2 dialog box options:1 In the Get labels from drop-down menu of the master section, select the master table's field containing the names to be displayed in the master menu for each element. A field for the value doesn't need to be selected, as the primary key will be used (it was defined in the first step).

2 In the Get labels from drop-down menu of the detail section, select the detail table's field containing the names to be displayed in the dependent menu, for each element.

3 In the Default value text-box you can enter a value that will be initially displayed/selected in the detail menu. You can use an entered, static value, as well as dynamic data, by pressing the lightning icon next to the field.

4 When you are done configuring the wizard, click the Finish button to apply it to the page.

It will insert two drop-down HTML form elements configured as dynamic fields, the master and detail table's recordsets. Also, the second drop-down menu (the dependent one), will have its type changed to the corresponding widget.

The contextual help provides insight on each of the dialog box's elements. To see help for a particular item, select the item, and some hints on what it should be set to will be shown.

View Dependent Drop-down in browserThe Dependent Drop-down widget will implement two areas:

• In the first area you have the main categories to be selected - in our example the continents

• The second area contains the subcategories - in our example the countries


142

When selecting a continent from the first drop-down menu in the second possible countries to choose from change according to our selection. Take a look at the pictures below to better understand the behavior.

Multi-field Drop-downThe Multi-field Drop-down widget lets users pre-fill form fields with information related to a selected value.

For example, upon selecting a country from a drop-down you can pre-fill the values of the phone prefix, currency and expedition fee in the other text fields in the page.

• “Configure Multi-field Drop-down” on page 142

• “View Dependent Drop-down in browser” on page 144

Configure Multi-field Drop-downThe Multi-field Drop-down server behavior allows the web developers to include a multi-field drop-down in their site pages. Before applying it, there must be two recordsets created in the Dreamweaver page, a list/menu item and at least an input item inserted.

Also, the list/menu item must have values associated to it. Do this dynamically, using one the two recordsets previ-ously created, namely the one that contains the foreign key table column. To do this, select the list/menu item in your Dreamweaver page and use the Property Inspector to associate values to it:


143

Hit the Dynamic button and configure the dialog box that opens similarly to the following example:

Select the recordset retrieved from the 'detail' table (the one that contains the foreign key). As values, select the foreign key, and as labels, select the field that will display the information you want to be shown.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Multi-field Drop-down.


144


To set the dialog box options:1 In the Master field drop-down menu select the form element that has the master role, namely the list/menu item.

2 In the Detail field drop-down menu select the form element that has the detail role (an input tag).

3 In the Recordset drop-down menu select the recordset to be used for the detail field. The selected recordset should contain the data that you want displayed in the input field when using the multi-field drop-down.

4 In the Primary key drop-down menu specify the primary key field for the current recordset.

5 In the Get labels from drop-down menu select the table field that stores the names you want to be shown in the detail field.





View Dependent Drop-down in browserWhen working with a Multi-field Drop-down the browser will display one Drop down and a number of dependent text fields. The entries of the text fields will change according to the user selection from the drop down.


145

Take a look at the pictures below to better understand the way this widget works:

Comma-separated CheckboxesThe Comma-separated Checkboxes widget allows the user to render a comma separated string of values as a list of checkboxes.

You can use the widget to designate an employee several assignments in a task assignment application.

• “Configure Comma-separated Checkboxes” on page 145

• “View Comma-separated Checkboxes in browser” on page 146

Configure Comma-separated CheckboxesThe Comma-separated Checkboxes server behavior allows the web developers to include comma-separated check-boxes in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also an input item added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Comma-separated Checkboxes.


146



2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the comma-separated checkboxes.

3 In the Get labels from drop-down menu select the table field that stores the names you want to be shown besides the checkboxes.

4 In the Get values from drop-down menu select the table field that stores the values for the widget elements.

5 In the Display columns text box insert the number of checkboxes that will be displayed in the browser (to allow horizontal looping for the checkboxes).





View Comma-separated Checkboxes in browserThe Comma-separated Checkboxes widget allows the user to render the records from a database table as checkboxes. Each entry in the database table passes its label to the checkbox's label, and the ID (or a value of choice) to the checkbox value. When the form is submitted, all of the checked records (shown as checkboxes) will be passed as a single string, containing the checkbox's values separated by commas.

An use of this widget is when having to subscribe to several magazines in a registration form, and the database only uses one field to store the subscriptions for each user, using the comma separated magazine's ID.


147

When viewed in a browser, the widget is rendered as a set of checkboxes, but they will submit a single string made up from comma separated values. Please see the following image to better understand the behavior:

Comma-separated MenuThe Comma-separated Menu widgets allow the user to render a comma separated string of values as a multiple select.

You can use the widget in a task assignment application that allows the manager to assign several tasks to a single employee, by selecting them form the menu.

• “Configure Comma-separated Menu” on page 147

• “View Comma-separated Menu in browser” on page 149

Configure Comma-separated MenuThe Comma-separated Menu server behavior allows the web developers to include a comma-separated menu in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also an input item added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Comma-separated Menu.


148



2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the comma-separated menu.


4 In the Get values from drop-down menu select the table field that stores the value for the widget elements.

5 In the Size text box insert the number of options that will be displayed in the menu at one time.






149

View Comma-separated Menu in browserThe Comma-separated Menu widget allows the user to render a comma separated string of values as a multiple select. This way, to a value inserted in a text field you can associate one or more entries by picking them out of the multiple select. Please see the picture below to better understand the behavior.

Comma-separated SelectorThe Comma-separated widget lets the user render a comma separated string of values as two select fields: one with "remaining values", and one with the "selected values."

You can use the widget in a task assignment application. The manager can not only assign an employee several tasks, but can also order them according to importance.

• “Configure Comma-separated Selector” on page 149

• “View Comma-separated Selector in browser” on page 150

Configure Comma-separated SelectorThe Comma-separated Selector server behavior allows the web developers to include a comma-separated selector in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also an input item added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > Comma-separated Selector.


150



2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the comma-separated selector.

3 In the Get labels from drop-down menu select the table field that stores the names you want to be shown in the widget.


5 The Sort selected elements checkbox enables the option of manually sorting the selected elements (two controls are displayed to the right of the widget when the page is loaded in the browser).

6 In the Size text box insert the number of options that will be displayed in the selector at one time.





View Comma-separated Selector in browserThe Comma-separated Selector widget allow the user to render a comma separated string of values as two select fields: one with "remaining values", and one with the "selected values".

• The widget inserts buttons to allow you to select all elements and to move the selection from one field to the other.

• The "Selected Values" field has buttons for ordering the selection. The user selects an entry and can then move it up or down one place simply by clicking on the right hand arrows.


151

Please see the below picture to better understand the behavior.

List SorterThe List Sorter widget lets you sort a list of entities. The widget includes a multiple select input with two buttons v, ^. The arbitrary selected elements are moved up down, by clicking on the buttons. The new elements order is then saved in the database as a comma separated string.

You can use the List Sorter to arrange the task list of your employee according to the importance of each assignment.

• “Configure List Sorter” on page 151

• “View List Sorter in browser” on page 152

Configure List SorterThe List Sorter server behavior allows the web developers to include a list sorter in their site pages. Before applying it, there must be a recordset created in the Dreamweaver page, and also list/menu item added.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Form Controls > List Sorter.



152

To set the dialog box options1 In the Apply to field drop-down menu select the list/menu field on which to apply the server behavior.

2 In the Recordset drop-down menu select one of the recordsets defined in your page. The selected recordset should contain the data that you want displayed when using the list sorter.

3 In the Get labels from drop-down menu select the table field that stores the names you want to be shown in the widget.


5 In the Order field drop-down menu select the table field that stores the order logic for the elements in the list.





If you want to modify the size of the list (the number of entries it displays at one time), select the list/menu item in your Dreamweaver page and then use the Height property in the Property Inspector:

View List Sorter in browserThe List Sorter widget is an "out of the box" way to sort a list of entities. The widget includes a multiple select input with two buttons: v and ^. The arbitrary selected elements are moved up or down, by clicking on the buttons. The new elements order is then saved in the database as a comma separated string.

Please see the below picture to better understand the behavior.

153

Chapter 6: File Manipulation

File manipulation is used on the web to allow site visitors to download an offline version of the information presented, for effective document management or just to offer some files to others. Dynamic sites cover file manip-ulation quite nicely, allowing file uploading and changing on the fly, as well as a better control over downloaded / uploaded files.

Downloading files is the easy part, you just need to add a link to your page pointing to the file's location on the server, and when any visitor clicks that link, he can download the file.

Uploading is a little trickier. To upload a file directly from the browser to a server, you must use a form containing a file field. Also, the form must have the enctype attribute set to "multipart/form-data", in order to instruct the web server to download the submitted file to the server. When the page is submitted, the browser will read the file contents along with the other form fields and post it to the server.

The page to which the form submits will initialize some variables containing the file name, size and the remote upload folder. These variables have different names, depending on the web server you use, but their function is similar. To find what the specific names for this variables are for your particular configuration, consult the manual of the server, the file manipulation section.

Once the browser sent the file and the page initialized the variables, it is up to the programmer's code to handle how and where to store the file, to decide if it will be saved or discarded, inserted into a database or not.

When you work with files, you should take into account the following issues:

• Maximum file size. This determines how large uploaded files can be. This option depends on each server's config-uration and if exceeded, the file will automatically be discarded.

• File access rights. To be able to upload files to a server directly from your web application, you must set the right to save files to the specified folder, otherwise an error occurs.

• Proxy and cache settings. Certain proxy and cache configurations can limit the maximum allowed file size. Therefore, when you attempt to upload a large file, you might get an error, even if your web server is configured to accept the file. These settings can be changed in the proxy/cache configuration files.

Another issue regarding file upload is recording the file into a database. Most dynamic web applications not only upload the file, but also record each file in a database (the file's name/path, not the file content). When the file record is deleted from the database, the corresponding file must also be physically removed from the server. Otherwise, old files will just pile up on your server, taking up valuable space.

Adobe® Dreamweaver® Developer Toolbox solves all of these problems in a simple, yet effective way, providing visual solutions to add code for file upload, download and delete.


• “Upload Files” on page 154

• “Configure Upload File interface” on page 154

• “Download Files” on page 157

• “Delete Files” on page 159

• “Download Files (PHP_MySQL server model)” on page 161

• “Delete Folder (PHP_MySQL server model)” on page 166


154

• “Multiple File Upload (PHP_MySQL server model)” on page 168

Upload FilesWith Developer Toolbox you will be able to add file upload capabilities without any hand coding. The Transaction Engine handles both the insert of the file name to database table as well as saving to a specified folder on the server.

To use the file upload feature of the Developer Toolbox:1 Create an Insert/Update operation on your page. You can do this by using the Insert/Update Record Form Wizard, or by manually creating the form and adding the desired server behaviors. If you create the form manually, make sure that a file type form field is added and related to the table field that will store the file name, and that the form's enctype attribute is set to "multipart/form-data".

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Upload File.

3 Configure the user interface to suit your particular needs.

4 Save the page and test it into the browser by selecting a file to upload.

When submitting a page that has file upload capabilities added through Developer Toolbox, the Transaction Engine handles it in the following way:

• The Insert/Update transaction is executed first in order to add into the database all other fields, including the file name field.

• The file upload is executed only after the insert or update operation ended successfully. If the transaction failed due to any reason, the file upload will not take place.

• When attempting to move the uploaded file to the folder specified in the File Upload configuration, the Trans-action Engine will also handle the following errors: (a) the possibility that a file with the same name has already been uploaded, by performing the Block or Rename action specified in the user interface, (b) the file size is bigger than the maximum specified in the user interface, by stopping the file upload, or (c) the file extension does not match any of those in the list of allowed extensions, in which case the upload fails.

If no other errors were raised when uploading the file, everything ends here. Otherwise, if the file upload fails, a rollback will be performed on the transaction, so that no invalid data will be stored in the table.

Configure Upload File interfaceAfter creating a transaction for inserting or updating records in your tables, you can easily add upload capabilities to a form with Developer Toolbox.

The following prerequisites must be met before attempting to use the File Upload trigger:

• Have a form element of the FILE field type, correctly bound to the table field.

• Have a transaction on page, either Insert or Update.

• Have proper access to the folder where you want to upload files (you must have user permissions on file and folders).

Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Upload File. The user interface that opens is divided into three tabs. Configure them as shown below.

• “The Basic tab” on page 155


155

• “The File tab” on page 156

• “The Advanced tab” on page 157

The Basic tabThis tab contains options regarding the form binding and the file upload folder:

To set the dialog box options:1 In the Form field drop-down menu select the form element to which the file upload trigger gets binded to. If you have multiple file field elements, select the right one in the list, or the files will not upload correctly.

2 In the Table column drop-down menu, select the column in the table which will store the filename.

3 In the Upload folder text box enter the folder on the server where you need to store your files or use the Browse button to select it from one of the site's folders. You can also use the Developer Toolbox Dynamic Data lightning icon to insert dynamic placeholders into the text box. They will be replaced with their values at runtime. The mark-up is inserted into the text field relatively to the mouse cursor, or if the cursor is not in the text field, it will be inserted at the beginning.

4 Whenever in trouble, you can consult the Contextual help displayed on bottom of the user interface.






156

These buttons are common to all three tabs of the Upload File interface.

6 Click on the File tab to continue with configuring the trigger.

The File tabThis tab contains options regarding file related settings:

To set the dialog box options:1 In the Maximum file size text box define up to what size files will be allowed to upload on site in kB. Default value is 200 kB.

2 The Allowed extensions list displays all extensions considered trusted, and therefore allowed to be uploaded. You can add a new extension by clicking the Plus (+) button and entering the extension format in the new dialog box. Similarly, you can remove an already entered extension, by selecting it in the list and then pressing the Minus (-) button.

3 In the File rename drop-down menu select the action to take when a name conflict arises on upload. Available options are:

• Automatic renaming - this option allows preserving the new file by assigning it a different name.

• Block upload - choosing this option will block the upload attempt without affecting in any way the existing file.

• Custom renaming - choosing this option allows the user specify a format to be used when doing renames. The format will be entered in the Renaming rule text-box, and can contain user-text and dynamic data. To select dynamic data to use, click the Developer Toolbox Dynamic Data lightning icon.


157

4 Click on the Advanced tab to continue with configuring the trigger or you can click OK to apply the trigger. The last tab is used only when the automatic assignment of the trigger to a transaction does not match your intentions or when you need more control over the trigger.

The Advanced tabThis tab allows advanced configuration of the trigger's behavior and its association to one (or multiple) trans-action(s):

For instructions on completing this step, see the Advanced tab. For the Upload File trigger, by default the Priority is set to 98 (since the trigger works with files, it should be among the last ones on page, so a high priority number is recommended) and the Type is AFTER, as it should execute after the transaction was completed.


Download FilesTo allow users to download files stored either in a dynamic manner through the File Upload trigger, or files that just exist on the server, Developer Toolbox offers another server behavior you can use: Download File.


158

To use this server behavior on one of your pages:1 Locate the folder storing your files on the server; remember its name, as you will need it later on.

2 Open the page that will offer the file for download. If you wish to use the default generated Download link, skip this step, else create the link (button, text, image) that will start the file download and select it.

3 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Download File.

4 Configure the user interface so that the correct files will be offered for download.

5 Save the page and test it into the browser, by attempting to download one of the stored files.

In order for the download operation to work, the folder storing the files must be visible to the web-server, or it should have read permissions on the folder and files.

If you decide to change any settings, you can do so by double-clicking the Download File server behavior displayed in the Server Behaviors tab.

If you are working with a PHP_MySQL server model, you can further enhance the download by adding a maximum number of download attempts (a limit) and a download counter. You can set these options in the corresponding tabs of the user interface. In order to use the download counter feature you must have a column in your database table where to store the count value. In order to limit the number of downloads per user or per page, you must have configured a many-to-many table which stores the file-user associations and the maximum number of tries allowed for each.

Configure Download File interfaceBefore using the Download File server behavior, if you do not wish it to generate the default download link, you have to create your own page element that will start the download operation (a button, text section or image).

Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Download File. The user interface that opens has one tab. Configure it as shown below.


159

To set the dialog box options:1 In the File folder text-box enter the folder where the files are stored. You can either type in the name or use the Browse button to select it from one of the site's folders. If you want to create the file name from dynamic and static data, use the Developer Toolbox Dynamic Data lightning bolt icon to insert dynamic placeholders that will be replaced at run-time.

2 In the Recordset drop-down menu select the recordset containing the field with the filename. This menu will display all recordsets found on the page.

3 In the Field drop-down menu select the table (recordset) column storing the filename. If the filename is not stored in a table, select either None: Rename rule. In the last case, the Renaming rule text-box enables.

4 In the Renaming rule text box, when enabled (when the filename is not stored in a table column), enter the file name format. You can use both static text and dynamic data, by pressing the Developer Toolbox Dynamic Data lightning bolt icon. This will allow selection of dynamic variables that will be inserted in the text box as placeholders that will be replaced at runtime.

5 The Contextual help displayed on the bottom of the dialog box offers information regarding each field.





Delete FilesWhen removing items from the database that have associated files stored on disk, you must implement logic that allows the related files to be deleted simultaneously.

In order to create such a page:1 Create a page on which you add a delete transaction that removes a record from the table. This table should be the one which has a field related to files on disk.

2 Add the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Delete File. This action will only take place after the delete operation on the table. If the delete operation is not successful, the file will not be deleted either.

3 The Transaction Engine will attempt to remove the file; if an error occurs, a rollback will be executed on the delete operation, so that no data will be lost.

Configure Delete File interfaceThe purpose of this user interface is to add application logic that deletes files related to a database record.

To delete a file, you must first have a page that uploads files to the server when inserting fields into the database. To learn how to add such functionality, see “Upload Files” on page 154.


160

Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Delete File. The user interface that opens is divided into two tabs. Configure them as shown below.

To set the dialog box options for the first tab: 1 In the Table column drop-down menu select the table field that contains reference to the files on disk.

2 The Renaming rule text box enables when in the Table column drop-down menu you selected None: Rename rule. You can use the Developer Toolbox Dynamic Data to compose the rule.

3 In the File folder file field, select the folder on the server where files are stored. You can use the Browse button to select it from one of the site's folders or you can use the Developer Toolbox Dynamic Data to insert dynamic place-holders into the text box (which will be replaced with their values at runtime).





These buttons are common to both tabs of the Delete File interface.


161


For instructions on completing this step, see the Advanced tab. For the Delete File trigger, by default the Priority is set to 98 (since the trigger works with files, it should execute among the last) and the Type is AFTER, as it should execute after the transaction was completed.


If the file to delete is actually an image, the program tries to locate any existing thumbnails, and if any are found, it also deletes them.

Download Files (PHP_MySQL server model)To allow users to download files stored either in a dynamic manner through the File Upload trigger, or files that just exist on the server, Developer Toolbox offers another server behavior you can use: Download File. When using the PHP_MySQL server model there is an enhanced version of the Download File server behavior that allows counting the number of downloads for a file and/or block the download when a limit has been reached.

To use this server behavior on one of your pages:

1 Locate the folder storing your files on the server; remember its name, as you will need it later on.


162

2 Open the page that will offer the file for download. If you wish to use the default generated Download link, skip this step, else create the link (button, text, image) that will start the file download and select it.

3 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Download File.

4 Configure the user interface so that the correct files will be offered for download. Also decide if you want to use a download counter and block the download when a limit has been reached.

5 Save the page and test it into the browser, by attempting to download one of the stored files.

In order for the download operation to work, the folder storing the files must be visible to the web-server, or it should have read permissions on the folder and files.

If you decide to change any settings, you can do so by double-clicking the Download File server behavior displayed in the Server Behaviors tab.

Configure Download File interfaceThe PHP_MySQL server model offers an improved version of the Download File server behavior that allows you to add extra functions - keep track of how many downloads took place and limit downloads per user to a certain number.

Before using the Download File server behavior, if you do not wish it to generate the default download link, you have to create your own page element that will start the download operation (a button, text section or image).

Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Download File. The user interface is divided into three tabs, which you should fill in as shown below:

• The Basic tab - with the options on this tab define where to get the name of the file to download and its location. You can use names stored in a recordset, or a rename rule.

• The Counter tab - set the table column where to store the number of downloads for a file and whether to use this feature or not.

• The Limit tab - set options in order to block the file download on certain condition.


163

The Basic tabThe Basic tab allows defining the file to offer for download. You can specify the location and where to get its name from.

To set the dialog box options:1 In the File folder text-box enter the folder where the files are stored. You can either type in the name or use the Browse button to select it from one of the site's folders. If you want to create the file name from dynamic and static data, use the Developer Toolbox Dynamic Data lightning bolt icon to insert dynamic placeholders that will be replaced at run-time.

2 In the Recordset drop-down menu select the recordset containing the field with the filename. This menu will display all recordsets found on the page.

3 In the Field drop-down menu select the table (recordset) column storing the filename. If the filename is not stored in a table, select None: Rename rule. In the last case, the Renaming rule text-box enables.

4 In the Renaming rule text box, when enabled (when the filename is not stored in a table column), enter the file name format. You can use both static text and dynamic data, by pressing the Developer Toolbox Dynamic Data lightning bolt icon. This will allow selection of dynamic variables that will be inserted in the text box as placeholders that will be replaced at runtime.

5 The Contextual help displayed on the bottom of the dialog box offers information regarding each field.




164



The Counter tab The Counter tab allows setting up the table column which will keep track of the number of downloads for a certain file.

To set the dialog box options:1 To enable the user interface options, tick the Enable download counter checkbox.

2 In the File table drop-down menu select the database table storing file information.

3 In the Primary key drop-down menu select the table column which stores the unique identifier for files.

4 In the Primary key equals set the value which the column in the files table must match. You can use the Developer Toolbox Dynamic Data icon to pick the recordset field with the primary key. This way you will update the counter for the file that is offered for download.

5 In the Download counter field drop-down menu select the table column which stores the number of downloads for a file.

6 When done setting the options, click OK to apply the changes.


165

The Limit tabThe limit tab allows setting up options to block a file download if it has been already downloaded a certain number of times. The options allow blocking the download based on the number of page uses or per user.

To set the dialog box options:1 To enable the download limiter feature, tick the Limit downloads checkbox. This will also enable all of the other interface fields.

2 In the Many-to-many table drop-down menu select the table that stores the association between users and files, as well as the allowed number of downloads for each user.

3 In the Primary key drop-down menu select the table column that stores the unique identifier for each pair of user - file - limit setting.

4 In the Key to file table select the table column which stores the foreign key to the table storing information on files.

5 In the Key to file table equals field enter the value which the table field must match. You can use the Developer Toolbox Dynamic Data interface to add dynamic values.

6 In the Key to user table drop-down menu select the table column storing the foreign key to the table storing the users.

7 In the Download counter field drop-down menu select the table column storing the download attempts counter allowed for each user.

8 In the Get max downloads for drop-down menu select how you want to limit the downloads. You have two options:

• Table - the limit is retrieved from a table column which will be specified in the menu that is displayed.

• Entered value - the limit is manually entered in a text field.

9 In the Max downloads text field enter the maximum number of downloads that is allowed. The text field is displayed when the method is set to Entered value.


166

10 The Table column drop-down menu is displayed when the limit is retrieved from a table and allows selecting the table column storing the maximum allowed number of downloads.

Delete Folder (PHP_MySQL server model)When removing items from the database that have associated folders created on disk, you must implement logic that allows the related folders to be deleted simultaneously.

In order to create such a page:1 Create a page on which you add a delete transaction that removes a record from the table. This table should be the one which has a folder related on the disk.

2 Add the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Delete Folder. This action will only take place after the delete operation on the table. If the delete operation is not successful, the folder will not be deleted either.

3 The Transaction Engine will attempt to remove the folder; if an error occurs, a rollback will be executed on the delete operation, so that no data will be lost.

Configure Delete Folder interfaceThe purpose of this user interface is to add application logic that deletes folders related to a database record.


167

To delete a folder, you must first have logic that creates the folder when inserting fields into the database. The folder name is made up from the primary key field of the transaction table or from a rename rule

Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Delete File. The user interface that opens is divided into two tabs. Configure them as shown below.

The Basic tab

To set the dialog box options for the first tab: 1 In the Folder field enter the name of the parent folder, where the folder to be deleted can be found. You can use the Browse button to navigate through the site structure and pick the right folder.

2 In the Subfolder drop-down menu pick the primary key transaction field to build the folder name from or use the None: Rename rule for custom naming.

3 In the Naming rule enter the rule used to define the folder name. You can use the Developer Toolbox Dynamic Data to pick dynamic values from the current record, a recordset on the page or other parameters.





These buttons are common to both tabs of the Delete File interface.



168

The Advanced tab For instructions on completing this step, see the Advanced tab. For the Delete File trigger, by default the Priority is set to 98 (since the trigger works with files, it should execute among the last) and the Type is AFTER, as it should execute after the transaction was completed.


Multiple File Upload (PHP_MySQL server model)With the PHP_MySQL server model you will be able to add multiple file upload capabilities without any hand coding. with the File Upload server behavior you could upload a single file to the server, and save its name in the database, or rename the file using a rename rule. With the Multiple File Upload, the record specifies the dynamic name of the folder where to store the files.

To use the multiple file upload feature:

1 Create an Insert/Update operation on your page. You can do this by using the Insert/Update Record Form wizard, or by manually creating the form and adding the desired server behaviors.

2 Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Multiple File Upload.

3 Configure the user interface to suit your particular needs.


169

4 Save the page and test it into the browser by selecting a file to upload.

When submitting a page that has file upload capabilities added by Multiple File Upload, the Transaction Engine handles it in the following way:

• Each of the files is uploaded to the server in a temporary folder as it is selected.

• The Insert/Update transaction is executed first in order to add all fields into the database.

• After the insert or update operation ended successfully, the subfolder to store the files is created using the specified rename rule, and the files are moved to the specific folder. If the transaction failed due to any reason, the folder is not created and the files are not copied.

• If no other errors were raised when working with the files and folders, everything ends here. Otherwise a rollback will be performed on the transaction, so that no invalid data will be stored in the table.

Configure the Multiple File Upload interfaceAfter creating a transaction for inserting or updating records in your tables, you can easily add multiple file upload capabilities to a form.

The following prerequisites must be met before attempting to use the Multiple File Upload trigger:

• Have a transaction on page, either Insert or Update.

• Have proper access to the folder where you want to upload files (you must have user permissions on file and folders).

Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Multiple Upload File. The user interface that opens is divided into three tabs. Configure them as shown below.





170

The Basic tabThis tab contains options regarding the base folder where to store files, and the naming rule for the subfolder to create:

To set the dialog box options:1 In the Upload folder field select the base folder where to store the dynamic subfolders and files.

2 In the Subfolder drop-down menu select the primary key transaction field to use as rename rule, or select None: Rename rule to enter your custom option.

3 In the Naming rule text box enter the name for the folder on the server where you want to store your files. You can also use the Developer Toolbox Dynamic Data lightning icon to insert dynamic placeholders into the text box. They will be replaced with their values at runtime. The mark-up is inserted into the text field relatively to the mouse cursor, or if the cursor is not in the text field, it will be inserted at the beginning.






These buttons are common to all three tabs of the Upload File interface.



171


To set the dialog box options:1 In the Maximum file size text box, specify the maximum file size in kilobytes (kb) that users can upload to the site. Default value is 200 kB.

2 In the Maximum number of files text box enter the maximum number of files that the user is allowed to upload.

3 The Allowed extensions list displays all extensions considered trusted, and therefore allowed to be uploaded.

You can add a new extension by clicking the Plus (+) button and entering the extension format in the new dialog box. Similarly, you can remove an already entered extension, by selecting it in the list and then pressing the Minus (-) button.



172


For instructions on completing this step, see the Advanced tab. For the Multiple File Upload trigger, by default the Priority is set to 90 (since the trigger works with files, it should be among the last ones on page, so a high priority number is recommended) and the Type is AFTER, as it should execute after the transaction was completed.


173

Chapter 7: Image Manipulation

This chapter provides information for uploading and manipulating images on your site. Adobe® Dreamweaver® Developer Toolbox smoothes out the process by allowing the uploading of images along with the items being inserted and/or updated in a database. This way, the whole process is simplified. When uploading images, you can also resize them so that they will fit nicely with the design.

Displaying dynamic images is easy when using Developer Toolbox. The File Upload component checks that only the correct images will be shown. Another great advantage is the simplified process of building a photo gallery thanks to the automatically generated thumbnails and the image resizing.

One known limitation when using the image manipulation server behaviors in Developer Toolbox is that you cannot resize / create a thumbnail of an animated gif. Only the first frame will be resized and the rest will be destroyed.

If you use the PHP_MySQL server model, you can also add protection to the thumbnails displayed on your site by adding a custom watermark.


• “Upload and resize images” on page 173

• “Display dynamic images” on page 177

• “Display dynamic thumbnails” on page 179

• “Display dynamic thumbnails” on page 179

• “Multiple Image Upload (PHP_MySQL server model)” on page 182

• “Show Media Object (PHP_MySQL server model)” on page 186

• “Multiple Image Upload with Save to Database wizard (PHP_MySQL server model)” on page 188

Upload and resize imagesThis feature is designed to allow the web developer to easily upload images in their dynamic sites. The advantage of this trigger is the ability to resize the pictures used in the site design. The Upload and Resize Image server behavior must be associated with an insert or an update transaction, and before applying it, there must be a file field in your Dreamweaver page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Upload and Resize Image.


174

The user interface has three tabs. Directions about the correct configuration of each one is given below.

To set the dialog box options for the first tab:1 In the Form field drop-down menu select one of the current FILE fields of the form included on your Dream-weaver page.

2 In the Table column drop-down menu select the database table field where you want to upload the image. You can also select None, which means that the image file name will not be saved in the database.

3 In the Upload folder text box enter the name of the folder where the images will be uploaded. You can use the Browse button to select a static folder and then you can append to it a dynamic value by using the Developer Toolbox Dynamic Data selector.

4 The Resize image checkbox enables the option of resizing the uploaded image. When checked, the next three controls are activated.

5 In the Resize method drop-down menu select one of the five available options:

• Auto Both the Width and Height text boxes below this drop-down menu are enabled. You can fill in the Width Text box, the Height text box, or both. If you fill in only one of them (for example, if you only specify a width), the image’s other dimension resizes proportionally.

• Proportional - Fit to box Both the Width and Height text boxes below this drop-down menu are enabled. The image will be resized so as to keep its original aspect ratio, but at the same time fit inside a rectangle having the specified dimensions.


175

Note: If Proportional - Fit to box is selected, images will be resized only if one of their dimensions exceeds the ones specified. Otherwise, images will be left at their original dimensions.

• Proportional - Fixed width Only the Width text box below is enabled. The image height is dynamically calculated, proportionally with the entered width.

• Proportional - Fixed height Only the Height text box below is enabled. The image width is dynamically calcu-lated, proportionally with the entered height.

• Fixed width and height Both the Width and Height text boxes below this drop-down menu are enabled. The image is resized to the specified dimensions, but the original aspect ratio will be lost.

6 In the Width text box, when enabled, enter the number of pixels corresponding to the image width.

7 In the Height text box, when enabled, enter the number of pixels corresponding to the image height.





These buttons are common to all three tabs of the Image Upload and Resize trigger interface.



176

To set the dialog box options for the second tab:1 In the Maximum file size text box enter the maximum size that the uploaded image files can have. The measurement unit is the kilo byte (kB). If the entered size is 0 (zero), then the maximum file size allowed will be the one accepted by the server.

2 In the Allowed extensions area specify the list of extensions that the image files to be uploaded can have. You can add new ones manually, by using the Plus (+) button:

The Minus (-) button is used to remove extensions from the grid.

3 In the File renaming drop-down menu select one of the three available options to apply if an existing uploaded file has the same name as the current one:

• Automatic renaming - the file is given a new, unique name (by adding a number at the end, before the file extension).

• Block upload - the file is not renamed, and the transaction is not executed if a file with the same name exists.

• Custom renaming - this options enables the last control of this interface, namely the text box below.

Note: If in the first tab, you chose None: rename rule Table colum. The Automatic renaming option is automatically selected and then the drop-down made disabled.

4 In the Renaming rule text box, when enabled, enter a custom name for the image files, using dynamic values, prefixes and suffixes. No spaces are allowed in the custom name. You can input dynamic data in the corresponding field by using the Developer Toolbox Dynamic Data selector.

Note: If you chose not to save the image name in a transaction field, then the custom name can only contain the available transaction field names (as dynamic values) and a defined extension.


177


For instructions on completing this interface, see the Advanced tab.

When uploading a new image through an update transaction (e.g. to replace a photo), the program will remove all thumbnails of the previous image. They will be re-created when a page containing the Show thumbnail server behavior is displayed in a browser.

Display dynamic imagesThe Show Image server behavior allows the web developers to display dynamic images in their site pages. Make sure you have a recordset in your page. Before applying the server behavior, you could select an image tag in your Dream-weaver page, or simply make no selection.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Show Image.


178


To set the dialog box options:1 In the File folder text box enter the name of the folder from where the images will be retrieved. You can use the Browse button to select a static folder and then you can append to it a dynamic value by using the Developer Toolbox Dynamic Data selector.

2 In the Recordset drop-down menu select one of the recordsets defined in your page.

3 In the Field drop-down menu select the table column that stores the names for the images to be shown. You can also select None: Rename rule. Only in the latter case, the text box below will be enabled.

4 In the Renaming rule text box, when enabled, enter a custom name rule used to save the image. The name can only contain constant expressions and the current recordset fields. The Developer Toolbox Dynamic Data selector allows you to input dynamic data in the corresponding field.





After applying this server behavior, a translator will be shown in your Dreamweaver page:


179

Display dynamic thumbnailsThe Show Thumbnail server behavior allows you to display dynamic thumbnail images in your site pages. Before applying it, a recordset must be created in your Dreamweaver page. This recordset should contain the image/thumbnail names in one of its fields.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Show Thumbnail.

No image thumbnail is actually created until the page containing a Show Thumbnail server behavior is requested in the browser for the first time. When a thumbnail is created on the server, it is saved in a folder called thumbnails, created inside the image upload folder (either statically or dynamically). In the example below, the image upload folder is called “images.”

The name of the thumbnail is generated automatically. If the original image is called filename.ext, the corresponding thumbnail will be called filename_WxH.ext, W representing the width and H representing the height of the thumbnail.

Depending on the website server model used, the user interface can contain one tab or more. The user interface tabs are:

• The Basic tab - available in all supported server models. It allows defining basic thumbnails options, like the location, recordset field and size.

• The Popup tab - (PHP_MySQL server model only) Lets you define options for previewing one or more related thumbnails in a pop-up window.

• The Watermark tab - (PHP_MySQL server model only) With the options on this tab you can select a watermark image to apply over the thumbnail. This ensures that no other party can use your images.

The Basic tabDirections about how to configure the options on this user interface tab are given below:

To set the dialog box options:1 In the File folder text box enter the name of the folder from where the thumbnail images will be retrieved. You can use the Browse button to select a static folder and then you can append to it a dynamic value by using the Developer Toolbox Dynamic Data selector.


3 In the Field drop-down menu select the table column that stores the names for the uploaded files that will generate thumbnails from. You can also select None: Rename rule. Only in the latter case, the text box below will be enabled.

4 In the Renaming rule text box, when enabled, enter a custom name rule used to save the thumbnail. The name can only contain constant expressions and the current recordset fields. The Developer Toolbox Dynamic Data selector allows you to input dynamic data in the corresponding field.

5 In the Resize method drop-down menu select one of the available options.






180



The Popup tabThis user interface tab is only available for PHP_MySQL server models and allows defining popup viewing options: whether to display in another window and whether to use navigation.

To set the options on this user interface tab:1 Tick the Display image popup in new windows to enable the use of a pop-up window to display the image.

2 Tick the Allow navigation checkbox if you want to add a navigation bar in the pop-up window to browse through the images.

3 In the Width text field enter the width in pixels for the pop-up window with the image preview.

4 In the Height text field enter the height in pixels for the pop-up window with the image preview.


181

5 Tick the Fit to window checkbox in order to force the image displayed in the pop-up to have the same size as the window.

The Watermark tabThis user interface tab is only available for PHP_MySQL server models and allows applying a watermark on the thumbnail to be displayed.

To set the options on this user interface tab:1 Tick the Apply Image Watermark checkbox to enable adding a watermark over the thumbnail that is created and displayed.

2 Tick the Apply popup Watermark checkbox to enable adding a watermark over the thumbnail that is displayed in a popup window. This checkbox is enabled only if you have decided to display thumbnails in a pop-up.

3 In the Transparency text field enter a value between 0 and 100 which will be the value of the watermark trans-parency. The higher the value, the more opaque the watermark will be.

4 In the Select Watermark Image file field click the Browse button to select a file from the local site structure.

5 In the Vertical drop-down menu select where to position the watermark image over the thumbnail on the vertical axis. You can choose between top, center and bottom.

6 In the Horizontal drop-down menu select where to position the watermark image over the thumbnail on the horizontal axis. You can choose between left, center and right.


182

7 In the Resize method drop-down you can decide whether to modify the watermark to better fit the image. Available options are:

• Do not resize - the watermark stays at the initial size and is applied as such over the image, in the desired position

• Stretch - the watermark is resized to the thumbnail to be applied on size. The positioning does not matter any longer.

• Resize - specify a fixed width and height to resize the watermark to.

8 In the Width and Height fields which are enabled if you select the resize option enter the value in pixels for the watermark image.

After applying this server behavior, a translator will be shown in your Dreamweaver page:

Multiple Image Upload (PHP_MySQL server model)The Multiple Image Upload server behavior is available when using the PHP_MySQL server model, and allows the user to upload and resize more than one image at a time.

The Multiple Image Upload server behavior must be associated to an insert or an update transaction.


183

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Multiple Image Upload.

The user interface that opens is divided into three tabs. Configure them as shown below.




The Basic tabThis tab contains options regarding the base folder where to store files, the naming rule for the folder to create and resizing options:

To set the dialog box options:1 In the Upload folder field select the base folder where to store the dynamic subfolders and files.

2 In the Subfolder drop-down menu select the primary key transaction field to use as rename rule, or select None: Rename rule to enter your custom option.

3 In the Naming rule text box enter the name for the folder on the server where you want to store your files. You can also use the Developer Toolbox Dynamic Data lightning icon to insert dynamic placeholders into the text box. They will be replaced with their values at runtime. The mark-up is inserted into the text field relatively to the mouse cursor, or if the cursor is not in the text field, it will be inserted at the beginning.


184



• Auto when both the Width and Height text boxes below this drop-down menu are enabled. Depending on which of the two you fill in, the resize will be made either proportionally or fixed.

• Proportional - Fit to box when both the Width and Height text boxes below this drop-down menu are enabled. The image will be resized so as to keep its original aspect ratio, but at the same time fit inside a rectangle having the specified dimensions.

• Proportional - Fixed width when only the Width text box below is enabled. The image height is dynamically calcu-lated, proportionally with the entered width.

• Proportional - Fixed height when only the Height text box below is enabled. The image width is dynamically calculated, proportionally with the entered height.

• Fixed width and height when both the Width and Height text boxes below this drop-down menu are enabled. The image is resized to the entered dimensions, but the original aspect ratio will be lost.

If "Proportional - Fit to box" resize method is chosen, Images will be resized only if the one of their dimensions exceeds the specified ones. Otherwise, images will be left at their original dimensions.










185


To set the dialog box options:1 In the Maximum file size text box define up to what size files will be allowed to upload on site in kB. Default value is 200 kB.

2 In the Maximum number of files text box enter the maximum number of files that the user is allowed to upload.

3 The Allowed extensions list displays all extensions considered trusted, and therefore allowed to be uploaded.

You can add a new extension by clicking the Plus (+) button and entering the extension format in the new dialog box. Similarly, you can remove an already entered extension, by selecting it in the list and then pressing the Minus (-) button.



186


For instructions on completing this step, see the Advanced tab. For the Multiple File Upload trigger, by default the Priority is set to 90 (since the trigger works with files, it should be among the last ones on page, so a high priority number is recommended) and the Type is AFTER, as it should execute after the transaction was completed.


Show Media Object (PHP_MySQL server model)The Show Media Object server behavior allows the web developers to display dynamic media elements images in their site pages. This server behavior allows you to add flash movies, quictime movies and windows media elements into the page. Before applying the server behavior, make sure you have a recordset in your page.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > File Upload > Show Media Object.


187


To set the dialog box options:1 In the File folder text box enter the name of the folder from where the media files will be retrieved. You can use the Browse button to select a static folder .


3 In the Field drop-down menu select the table column that stores the names for the images to be shown. You can also select the None: Rename rule. Only in the latter case, the text box below will be enabled.

4 In the Renaming rule text box, when enabled, enter a custom name rule used to save the image. The name can only contain constant expressions and the current recordset fields. The Developer Toolbox Dynamic Data selector allows you to input dynamic data in the corresponding field.

5 In the Type drop-down menu select the type of media object to create based on the dynamic rule. You have three options: Flash Movie, Windows Media and QuickTime Movie. After defining the type, the code added in the page will allow you to use the Dreamweaver bar to define additional settings.

6 In the Width and Height text boxes enter the size of the inserted media object.






188

After applying this server behavior, a translator will be shown in your Dreamweaver page, depending on the type of media you have chosen. You can then select it and use the Property Inspector to change its options.

Multiple Image Upload with Save to Database wizard (PHP_MySQL server model)The Multiple Image Upload with Save to Database wizard server behavior is available for PHP_MySQL server models and allows the user to upload and resize more than one image at a time and also to save the file name and any other fields with a default value to the database.

The Multiple Image Upload server behavior adds an insert transaction on the page, as well as the upload component. If you have JavaScript enabled and Flash 8 or higher installed you will be able to use a flash uploader. Otherwise you can upload one file at a time and, if JavaScript is enabled the progress bar will be displayed.

This wizard is accessible from the Insert bar > Developer Toolbox tab.

The wizard is divided into four (4) steps, each with different options that can be set. You can learn how to configure these steps in the sections below:

• Step 1 - define the database table to use.

• Step 2 - define where to save the image and whether to resize images or not.

• Step 3 - define file options: maximum size, allowed extensions and renaming if needed.

• Step 4 - define additional fields and their default values.

Step 1 - Database informationIn this step of the wizard define the database information - table and primary key.

Configure the options as follows:1 In the Connection drop-down menu select the database connection pointing to the files table.

2 In the Insert into table drop-down menu select the table which will store the file names, or the additional field values.

3 In the Primary Key column drop-down menu select the table column which is the unique key. Also tick the Numeric checkbox if the field type requires it.






These buttons appear on all three interfaces of the wizard.



189

Step 2 - Set storage options

In this step of the wizard define options regarding the file location and resizing:1 In the Table column drop-down menu select the table column where to save the file names.

2 In the Upload folder select the site folder where to save files. You can enter both static and dynamic values through the Developer Toolbox Dynamic Data.



• Auto when both the Width and Height text boxes below this drop-down menu are enabled. Depending on which of the two you fill in, the resize will be made either proportionally or fixed.

• Proportional - Fit to box when both the Width and Height text boxes below this drop-down menu are enabled. The image will be resized so as to keep its original aspect ratio, but at the same time fit inside a rectangle having the specified dimensions.

• Proportional - Fixed width when only the Width text box below is enabled. The image height is dynamically calculated, proportionally with the entered width.

• Proportional - Fixed height when only the Height text box below is enabled. The image width is dynamically calculated, proportionally with the entered height.

• Fixed width and height when both the Width and Height text boxes below this drop-down menu are enabled. The image is resized to the entered dimensions, but the original aspect ratio will be lost.

If "Proportional - Fit to box" resize method is chosen, images will be resized only if the one of their dimensions exceeds the specified ones. Otherwise, images will be left at their original dimensions.




Step 3 - File properties

In the third step define restrictions for the uploaded files - extensions and size:1 In the Maximum file size text box enter the maximum size that the uploaded image files can have. The measurement unit is the kilo byte (kB). If the entered size is 0 (zero), then the maximum file size allowed will be the one accepted by the server.

2 In the Allowed extensions area specify the list of extensions that the image files to be uploaded can have. You can add new ones manually, by using the Plus (+) button:


190

The Minus (-) button is used to remove extensions from the grid.

3 In the File renaming drop-down menu select one of the three available options:

• Automatic renaming - the file is given a new, unique name (by adding a number at the end, before the file extension).

• Block upload - the file is not renamed, and the transaction is not executed if a file with the same name exists.

• Custom renaming - this options enables the last control of this interface, namely the text box below.

4 In the Renaming rule text box, when enabled, enter a custom name for the image files, using dynamic values, prefixes and suffixes. No spaces are allowed in the custom name. You can input dynamic data in the corresponding field by using the Developer Toolbox Dynamic Data selector.

Note: If you chose not to save the image name in a transaction field, then the custom name can only contain the available transaction field names (as dynamic values) and a defined extension.


Step 4 - Additional fields

In the last step of the wizard define what other table columns will receive a value, and which, with the file upload:1 In the Form fields area specify the table columns that a value will be inserted into. Use the Plus (+) button to add form fields to the current transaction. Use the Minus (-) button to remove fields.

2 To configure the properties for each field you must first select it in the grid and then use the control below the grid to set it:

• In the Submit as drop-down menu select the type of the database column.

• In the Default value text field enter the value that the column will receive. You can use both static and dynamic data by using the Developer Toolbox Dynamic Data to chose the value.

3 Click Finish to close the wizard and apply the changes.

The wizard will add an Insert Transaction and a Upload Image trigger onto the page. It will also generate an Upload button when viewed in the browser. Then, depending on what plugins you have enabled in the browser - e.g. JavaS-cript and / or Flash the upload indicators and operation will slightly differ:

• The Flash version allows selecting multiple files at once and uploading them. Individual and batch progress bars accurately display the upload progress. With the upload, the insert takes place as well.


191

• The HTML and JavaScript version only allow selecting one file at a time, but still display a progress bar when uploading. The record is inserted with the upload as well.

• If neither JavaScript and Flash cannot be used, the default HTML file upload takes place. No upload progress bar is displayed.

192

Chapter 8: Retrieve Dynamic Data

This chapter shows you how to use Adobe® Dreamweaver® Developer Toolbox to extract data stored in your database.

This chapter contains the following sections.

• “Retrieve data from databases” on page 192

• “Developer Toolbox Dynamic Data” on page 211

• “Transaction Engine generated variables” on page 214

Retrieve data from databasesThis section presents basic concepts about working with databases and teaches you how to retrieve and use data memorized there with the help of the Developer Toolbox extension. The module that will be presented in detail in this section is Query Builder (QuB).

Note: In the following pages Query Builder is sometimes referred as QuB.

• “Build advanced recordsets from Dreamweaver” on page 192

• “Configure a Query Builder recordset” on page 193

• “Configure Query Builder” on page 194

• “Query Builder orientation” on page 195

• “Manage queries” on page 198

• “Work with database tables” on page 201

• “Change table alias” on page 202

• “Manage table relations” on page 202

• “Work with table columns” on page 204

• “View the generated SQL code” on page 208

• “View query results” on page 209

• “Print database diagrams” on page 210

• “Advanced database operations” on page 211

Build advanced recordsets from DreamweaverFrom this section, you will learn how to open the Query Builder interface from Dreamweaver and how the two products work together.


193

Query Builder is an intelligent and user-friendly alternative to the standard Dreamweaver advanced recordset, in that the SQL code can be generated from a visual interface rather than hand-coded. The purpose of Query Builder is to help you define recordsets that you can use in your site pages as any other data source.

On the right side of the Dreamweaver recordset window, there is a QuB button from which you can reach the Query Builder interface.

In the next topic, the exact steps involved in opening the interface will be described.

Note: Note: In order for Query Builder to open, you must have pop-up blocking disabled on your browser. Query Builder opens in a web browser and can sometimes be prevented from opening when pop-up blocking software is installed and activated. For details, see Pop-up blocker conflicts.

Configure a Query Builder recordsetAfter clicking the QuB button, a window similar to the Dreamweaver Recordset will open. You can open an existing query for editing or create one from scratch.

• To create a query, click the New Query button as shown below.

• To edit a query, select it from the Query name drop-down menu and click the Edit Query button.


194

Note: If you cannot see all your queries in the menu, click the Refresh button.

If you chose to create a new query, you will be prompted to enter a name:

Click OK and Query Builder will open. With the Query Builder interface now on your screen, you're ready to move on, making sure that the proper configuration is set on your computer.

Configure Query BuilderDepending on your database management system (DBMS), there are some Query Builder settings which may need to be modified. For example, some database management systems use "!=" for a "not equals" comparison, others use "<>".

To reach the settings interface, open the Query Builder menu and select the Settings option:

The QuB Settings dialog box will appear.


195

To configure Query Builder:1 In the Enclose date between text box enter the character that will delimit a date. For example, '04-03-2004' using single quotes, or "04-03-2004" with double quotes.

2 In the Not equals drop-down menu select the symbol that your DBMS is using for the "not equals" comparison. The query builder default is "!=", but you can change this depending on your configuration to "<>".

3 Check the Use AS in order by checkbox if your DBMS syntax allows it.

4 Click OK when you are done.

By using Query Builder, a folder named qub will be created in your includes folder. Do not forget to upload this folder on the server. Query Builder also creates 3 tables in your database.

Query Builder orientationThis sub-section introduces you to the Query Builder interface. When opening Query Builder for the first time it could seem confusing. The purpose of this chapter is to provide explanations to better understand the product.

Query Builder can be accessed from within Dreamweaver, and the generated SQL can be used back in Dreamweaver as any other recordset. It is not designed to be used as a database administration tool (like PHPMyAdmin) but as a tool for quickly generating complex recordsets for use within a site.

• “Workspace orientation” on page 196

• “Database Diagram” on page 197

• “Shortcut keys in Query Builder” on page 197


196

Workspace orientationQuery Builder simplifies the creation of SQL queries through a visual editor. At first glance the editor may appear complicated, but taken piece by piece it is simple to understand and use. Take a look at its visual components:

1 Query List Panel - this panel contains a list of all previously stored queries. Here you can add, edit, or delete any saved queries, or search the list by name.

2 Tables panel - this panel displays a list of all the tables stored in the database you are currently connected to in Dreamweaver. The checkboxes are used for adding or removing the table from the Database Diagram.

3 Database Diagram - this diagram is a tool for representing your tables and the relationships between them visually. The checkboxes next to each table column allow fields to be added to the Query Management Panel.

4 Query Management Panel - the query management panel is where you will define the output of your query: columns to include, sorting, and group functions, such as SUM, AVG etc.

5 SQL/Results Preview Panel - this panel contains two tabs, one labeled SQL Query, and another labeled Results. These tabs let you see the SQL code, and its result, respectively.

6 Query Builder toolbar - the toolbar contains buttons for zooming in and out of the database diagram. This is useful when using a complex database structure with lots of tables and relationships between those tables. You can zoom out to see all the tables at once, or zoom back in to view specific details.

7 Query Builder menus - there are two menus: one labeled Query and one labeled Help. The Query menu has options for saving queries, editing basic Query Builder settings, printing the diagram, and closing the application. The Help heading automatically opens a help file where you can search for any topic regarding Query Builder.

In the next topic, you will learn how to work with the Database Diagram panel.


197

Database DiagramThe Database Diagram allows you to:

1 Visually edit your SQL query.

2 View and better understand the logical structure of your database.

A typical query diagram contains the following elements:

• database tables.

• relations between tables.

After clicking a checkbox from the Tables panel, the corresponding table will appear in the database diagram.

Once multiple tables are displayed in the diagram, relations can be added between them.

When a relation is added, a line appears between the two tables, with an arrow pointing to the direction of the JOIN SQL statement. This means a LEFT JOIN will point to the left table, and a RIGHT JOIN will point to the right table. To help define relations, and query parameters, the primary keys of each table are automatically identified and marked with a key icon.

The positions of each table in the diagram can be changed by using the mouse to drag and drop a table anywhere in the diagram. The line representing the relation will stay attached to the table wherever it is moved.

Shortcut keys in Query BuilderThe following table contains a list of keyboard shortcuts in Query Builder. They work only when the Database Diagram area has the focus (you must click on it).

Shortcut keys Action

A Select all tables.

Arrow keys Move the selected tables (you can select more tables by pressing CTRL and mouse clicking them).

L Edit a selected relation between two tables.

S Save the current query in the query repository.

+ (in the numeric pad) Zoom in the Database Diagram.

- (in the numeric pad) Zoom out of the Database Diagram.

(CTRL +) Z Undo operation.

(CTRL +) Y Redo operation.

Delete Remove the selected object (table or relation) from the diagram.


198

The keyboard shortcuts listed above help speeding up the development process by saving precious seconds of your time.

Manage queriesThis sub-section shows you how Query Builder makes it possible to manage a large number of queries from one location. The Query List Panel displays a list of all previously saved queries:

Immediately below the row of buttons, there is a text box from which you can search the list of queries. Below the list there are four buttons for managing the list. From left to right, the buttons can create a new query, save the current query, save as a new query, delete the query selected in the panel.

• “Create query” on page 199

• “Open query” on page 200

• “Search queries” on page 201

Q, X Save the current query and close the Query Builder window.

ESC Close all opened menus or context menus.


199

Create query

To create a query:1 Click the New Query button. (For instructions on getting to the QuB Recordset window in Dreamweaver, see “Build advanced recordsets from Dreamweaver” on page 192.)

2 You will be prompted to give the query a name:

3 The new query will appear in the Query List Panel, along with any other saved queries you may have.

The next topic will show you how to open an existing query from Dreamweaver.


200

Open queryTo open a query you've already saved, get to the Query Builder recordset window and you'll find a list of your queries in the Query Name drop-down menu.

Click Edit Query, and the Query Builder window will open with the selected query loaded.


201

In the next topic you will see how to use the Query List Panel to search through your queries.

Search queriesIn the Query List Panel, just below the four buttons, there is a text box where you can search for a query by name. As you type in the text box, the query list is filtered based on the entered characters.

As you enter characters, the list is automatically narrowed down to those matching the search text. In the next topic, you will move on to working with database tables in Query Builder.

Work with database tablesOn the left side of the Query Builder interface you'll find the Tables panel where you can find the tables from your database connection.

By clicking on the checkboxes associated with each table, you can bring them into the Database Diagram:

You can move the tables around by clicking on them and dragging the mouse. Other elements of the database diagram are:


202

1 Table name: the table name appears in a gray box across the top of each box representing a table. This way each table can be easily identified within the diagram.

2 Table columns: a list of the table columns appears beneath the table name as well as an option to select all the columns. The column name appears exactly as it does in the database.

3 Checkboxes: next to each table column is a checkbox. The checkbox lets you add the column to your recordset. Upon checking the checkbox, the column name will appear in the Query Management Panel.

4 Data type: to the right of each table column there is the variable type for the column, useful for determining the type of comparisons to use in the Query Management Panel.

Change table aliasThe Change Table Alias option can be used to make the table names more readable in the Database Diagram. It is especially useful when dealing with lots of tables, or copies of tables using self foreign keys. To use this option, put the cursor inside a table, and right click - the following menu will appear:

Enter a new name for the table, and click Change. Now in the diagram, the table will have a new heading:

Keep in mind, that changing the alias does not change the actual table name, just it's header in the Database Diagram. To change the table's name in the database, you must use your database management software (MySQL, MS Access, etc.).

The diagram also allows you to manage table relations. In the next section, you'll learn more about working with table relations in Query Builder.

Manage table relationsThis sub-section shows you how relations between tables can be managed in the Database Diagram.

The Database Diagram allows you to represent table relations in a visual manner. You can use the Database Diagram to add, edit and remove relations on your database tables.

• “Define relation between tables” on page 203

• “Edit relation between tables” on page 203

• “Delete relation between tables” on page 204


203

Define relation between tablesRelations between tables can by dragging the field of one table, and dropping it on the corresponding field in the related table. For example, in the departments and employees tables, you would click on the foreign key column, drag it to the departments table, and drop it on top of the id_dep. See the following image for details:

Afterwards, the relation should look similar to the image below

:

When the relation is created a line and an arrow will appear between the two tables. The arrow represents the direction of the JOIN SQL statement - LEFT JOIN, RIGHT JOIN, or INNER JOIN (no arrow).

There is also the possibility to create a relation between a table and a copy of itself (self-foreign key). To create a self-foreign key relationship, just right click on the table and select the Duplicate option. Once the copy is created, use the same drag and drop process between the table and it's duplicate copy. For a definition of the self-foreign key principle, check out the Glossary tab.

Edit relation between tablesTo edit a relation, select the line connecting the tables and right click; the Edit Relation window will then appear,

1 The Left Table Name, Left Field Name, Right Table Name, Right Field Name cannot be edited in the dialog box. These contain the tables and fields you selected in the Database Diagram.


204

2 Check one of the Relation Type radio buttons:

• Only include rows where joined fields are equal - this option grabs records from both tables only where there is a match between the id_dep and iddep_emp table fields.

• Include all records from the A table (employees) and only those from the B table (departments) where joined fields are equal - with this option, all employee records will be selected, and only departments with an ID that matches the iddep_emp field from the employees_emp table.

• Include all records from the B table and only those from the A table where joined fields are equal - here, all department records are listed, and only those employees whose iddep_emp matches one of the department ID's.

Delete relation between tablesTo delete a relation between two tables, right click on the line connecting the tables; a dialog box will display, asking you to confirm the deletion.

When a relation is removed, several things happen. Here are some things to notice:

1 The line connecting the two tables is removed.

2 The JOIN statement is removed from the SQL Query.

3 If table is no longer linked to anything, an error message appears in the SQL/Results Preview Panel.

4 Foreign Key icon is removed.

The next section will describe using the Query Management Panel to retrieve exactly the data you want.

Work with table columnsThis sub-section shows you how the Query Management Panel allows you to control the output of the SQL query by letting you add table columns from the Database Diagram. You can select which fields you will need, and set grouping and sorting properties. The topics in this section are:

• “Add and remove columns in your query” on page 205

• “Define aliases” on page 205

• “Sort data” on page 206


205

• “Group data” on page 207

• Define query conditions

Add and remove columns in your queryThe checkboxes in the database diagram can be used to add or remove columns from the Query Management Panel.

Once a column has been added, you can create an Alias, and use the sorting and grouping features. The Alias option is described in the next section.

Define aliasesThe Alias field is generally used when a variable needs to be created in the query. For example, if your query takes a sum of all the department budgets, a default alias (variable) will be created to store that number.

An alias is not required unless a Grouping option is chosen. When a Grouping option is selected, then Query Builder generates one by default. If you would prefer to have your own alias name, just delete the default and type the new name instead.

The Output checkbox indicates if a tables column will be included in the final recordset or not. You could use a certain table column just to define a query condition, but not include that column in the query results. For instance, you may want to display the names of the employees that have a salary greater than $1,000. In this query, the salary_emp column would be used just to define a condition, but would not be included in the output of the recordset.

The generated query looks like this:

SELECT employees_emp.name_emp

FROM employees_emp

WHERE employees_emp.salary_emp>1000

Please notice that the salary_emp column is not included in the SELECT clause, but only appears in the WHERE clause.


206

The Results tab confirms this:

In the next topic you will see how to use the Sort option.

Sort dataThe sort option is a simple tool which lets you arrange numeric values in ascending or descending order. The example below shows the query results when department budget is selected and a descending sort is applied.

In the next topic you'll see how to use the Grouping option on your recordset data.


207

Group dataThe Query Management Panel contains an option for grouping the selected column. Sometimes you may not want just raw data, but rather some specific information from the table. The Grouping drop-down menu lets you get sums, minimum and maximum values, averages, and row counts (ex: how many departments in the company). The following image shows how the options are displayed:

Here you can see the query results when a sum grouping is applied to the department budget column:

The grouping functions (also known as aggregate functions) are used for retrieving information about a group of records from the database. Examples include the sum of all salaries of the employees in a department, the average price of TV sets in a country or the number of clients that have bought a certain product. The next topic goes a step further by describing how to create conditions in your query.


208

Define query conditionsSometimes there are specific conditions that need to be set in the query , such as searching for a specific element, or comparing numeric or alphabetical values. To set a condition, click the button next to the condition text box; the Edit SQL Condition dialog box will appear.

To set the dialog box options:1 The Table Column text box is disabled and it displays the alias and the name of the table column for which you are writing the condition.

2 In the Condition drop-down menu select the type of comparison. There are options for comparisons of numeric fields and character strings: =, >, >=, <, <=, !=, begins with, contains, ends with, is null, is not null.

3 In the Variable Type drop-down menu select the type for the dynamic variable to be compared with the database value. The available options are: Form Variable, URL Variable, Session Variable, Cookie Variable, Entered Variable.

4 In the Run-time Value text box enter the value that will be considered at run-time.

5 In the Default Value text box enter the default value.

6 Click OK when you are done.

The next topic will explain how to use the SQL/Query Preview Panel for checking the accuracy of the generated query.

View the generated SQL codeThe SQL/Results Preview Panel has a tab labeled SQL Query where you can see the SQL code generated by your query.


209

Let's consider the following example:

If your Database Diagram and Query Management Panel look like in the image above, then the generated SQL query is:

As you make changes in Query Builder, the generated code is updated to reflect the changes.

The code itself cannot be edited directly in Query Builder. However, it is possible to open the query in Dreamweaver and modify the query using the Advanced Recordset tool.

In the next topic, you will see how to preview the results of your query.

View query resultsThe SQL/Results Preview Panel also lets you see the results of your query before you save it. This way, you can be sure the query obtains exactly what you want before testing it in Dreamweaver.


210

The results of the query considered in the previous topic are:

Immediately above the results table, you can see the number of rows that are listed in the results. Above that, you can notice the Show All button. When clicking on it, all the records selected from your database will be displayed. If you want to see again only 10 records, click on the Results tab.

In the top-right corner of the SQL/Results Preview Panel, you can notice a black-arrow button. It has the role to collapse/expand this panel.

Print database diagramsThe Query menu contains a Print option, where you can print the contents of the database diagram. At this point, the Print function only applies to the database diagram. Other panels cannot be printed from within Query Builder. To reach the Print option, first go the Query menu in the top left corner of the Query Builder interface. From there, select the Print option as shown below:

After selecting Print, a preview will open, as well as the print screen from your browser:


211

The preview just lets you see what will be printed before sending it to the printer. If everything looks alright, just use the already opened print window from your browser to send the document to the printer.

This concludes the description of Query Builder's basic functionality. The remaining topics address advanced features.

Advanced database operationsThis sub-section presents some finer database concepts for those who are interested in knowing more.

What is Query Builder repository?When creating and saving queries with Query Builder, the application needs a place to store your settings, queries, and database table relations. By saving your settings, each time Query Builder is opened it will already have the queries and database diagram set as you left them.

There are three extra tables added to your current database:

1 qub3_queries_que - the queries table stores info for each saved query: the name, SQL code, and information on which field.

2 qub3_relations_rel - the relations table stores information regarding your table relationships set up in the database diagram.

3 qub3_settings_set - the settings table stores the general Query Builder settings chosen in the Query Menu > Settings option.

Note: Note: To keep Query Builder running smoothly, it is best not to edit the contents of these tables.

Developer Toolbox Dynamic DataThe Developer Toolbox Dynamic Data tool is a replacement for the standard dynamic data dialog. It is used in Developer Toolbox, to provide a unified way of building mark-ups, or place holders. These are recordset fields, server or session variables, and other types of dynamic data that are replaced at runtime by their corresponding values.

The Developer Toolbox Dynamic Data has an associated blue lightning icon that is displayed next to the interface field that can use it:

When used, it provides a user interface that allows selecting from one of the existing variable sources in page and automatically creates the mark-up code.

To set the dialog box options:1 In the Get values from drop-down menu select the variable source. Available options are:

• Transaction field

• Recordset field

• URL parameter

• Form variable


212

• Cookie

• Session variable

• Server variable

2 Depending on the selection made in the Get values from drop-down menu, different options will be displayed for the other fields, as follows:

• For Transaction field, a drop-down with all fields involved in the transaction is displayed.

• For Recordset field, two drop-downs are shown: one listing the available recordsets, and another one listing the recordset fields.

• For URL parameter, Form variable, Cookie, Session variable and Server variable, the Variable drop-down is shown, listing the available variables in the current category.

3 In the Mark-up code text-box, the generated placeholder is displayed. This code will also be inserted into the page.





Use Developer Toolbox mark-up languageThe Developer Toolbox Dynamic Data provides automatically generated mark-ups for dynamic data, from the source you specify. These mark-ups are replaced at runtime by the actual value, and are taken into account when doing the operations they are involved in. It is used in Developer Toolbox to provide a unified mark-up language for dynamic values on all server models.

There are several types of dynamic data that can be replaced by these mark-ups, starting with the data used in a trans-action, to more specific variables (e.g. the current date). The mark-up is made up of the variable identifier, enclosed between braces (e.g. {dynamic}). Depending on the identifier format, the dynamic value to be replaced is taken from a different place, and the generated code differs. As you can see in the Developer Toolbox Dynamic Data presen-tation, the dialog box can be accessed through the blue lightning icon, and it will generate the correct code, depending on the decisions you make in the drop-down menus.

You can also manually enter mark-ups, and they will be treated correctly at runtime, being replaced with their corre-sponding values. When entering the mark-ups by hand, you must pay attention at the identifier format, as it can only be one of the following list:

• {variable_name} - this is equivalent to the field value of the current transaction; if used as a trigger option, it will be replaced with the field value of the transaction the trigger is registered to. It can be used when trying to access a transaction field value before or right after a transaction executes. The code that gets generated in order to replace it with the correct value is:

• $this>getColumnValue('name_ctg') - for the name_ctg field value of the current transaction, PHP model.

• $this>tNG>getColumnValue('name_ctg') - for the name_ctg field value of the transaction to which the trigger is registered, also PHP model.

• {rsRecordset.myColumn} - it is equivalent to the value of the column myColumn of the rsRecordset recordset. Useful when trying to access a recordset column in an easy way. The equivalent code is:

• $row_categoriesRs['name_ctg'] - for the name_ctg column, PHP_MySQL server model.


213

• {GET.variable_name} - equivalent to the value of a GET passed variable. Use this mark-up to access variables that are passed to the page through the GET method, usually URL parameters. The equivalent code is: $_GET['id'] - for the id URL parameter, PHP model.

• {POST.variable_name} - equivalent to the value of a form variable passed through the POST method. Use this mark-up to work with submitted form variables. The equivalent code is: $_POST['id'] - for the id form variable, PHP model.

• {COOKIE.variable_name} - equivalent to the value of an HTTP cookie stored variable. It can be used when working with authentication variables stored in cookies. The equivalent code is: $_COOKIE['PHPSESSID'] - for the PHPSESSID variable, PHP model.

• {SESSION.variable_name} - equivalent to a session variable. A simple use is when trying to display the currently logged in user's name on the page. The equivalent code is: $_SESSION['user_name'] - the user_name session variable.

• {GLOBALS.variable_name} - this mark-up is valid for the PHP model only. It is equivalent to a global available variable, and it can be used to pass data across functions. The equivalent code is: $GLOBALS['user_name'] - the user_name global variable, PHP model.

• {REQUEST.variable_name} - this mark-up is valid for the ColdFusion server model only. It is the equivalent for a global variable, with the same use as it's PHP correspondent above. The equivalent code is: #Request['user_name']# - for the user_name variable.

• {APPLICATION.variable_name} - only available for the ColdFusion server model, it is the mark-up to access an application variable. Usable when you need to invoke an application variable for your page. The equivalent code is: #Application['user_name']# - for the user_name variable.

• {NOW}, {NOW()}, {now}, or {now()}- this mark-up is replaced with the current date. Its value is represented in the screen date format specified in Control Panel > Date formats. Use it when you need to assign the current date to a field in a transaction. For instance, when posting an online article, you might want the date to be automatically set to the current one, instead of having the user manually entering the date when the article was created.

Note: You can use both the lower case and upper case versions with the same result.

• {NOW_T}, {NOW_T()}, {now_t}, or {now_t()} – this mark-up is replaced with the current time. Its value is repre-sented in the screen time format specified in Control Panel > Date formats. Use this mark-up when you need to set the value of a transaction field to the current time.


• {NOW_DT}, {NOW_DT()}, {now_dt}, or {now_dt()} – this mark-up is replaced with the current date and time. Its value is represented in the screen date and time formats specified in Control Panel > Date formats.


• {KT_defaultSender} - this mark-up is replaced with the value you set in the E-mail settings entry of the Control Panel for the Default sender. The initial value is [email protected].

Using this simple mark-up language, you do not have to write the code for retrieving data yourself. It is easier and faster to work with dynamic data this way. Also, when using dynamic data in various Developer Toolbox interfaces, the same type of mark-ups are added in the page code.


214

Transaction Engine generated variablesThe Transaction Engine which constitutes the core of Developer Toolbox uses a set of variables to accomplish certain tasks, and to store data (e.g. session or URL variables) that can also be used when hand-coding portions of a page, or writing custom triggers. However, not all variables exist at all times, some of them being created only when certain events or settings exist.

The names of these variables always use the "kt_" prefix. A list of variables, and their existence case follows:

1 Variables that appear as results of transaction fields:

• kt_login_id - stores the ID of the currently logged in user. It is initialized and can be used after the user logs in. It corresponds to the $tNG_login_config["pk_field"] field in tNG_config.inc.php.

• kt_login_user - stores the user name for the currently logged in user. It is initializaed and can be used after the user logs in. It corresponds to the $tNG_login_config["user_field"] field in tNG_config.inc.php.

• kt_login_password - stores the password for the currently logged in user. It is used for the forgot password page, and the welcome e-mail page. It is stored in un-encrypted form, in order to be visible in the e-mail message to send. It can only be used after a registration process, and it corresponds to the $tNG_login_config["password_field"] field in tNG_config.inc.php.

• kt_login_level - stores the access level for the currently logged in user. It is available only if using user authenti-cation based on username, password and user level, and only after the user logs in. It corresponds to the $tNG_login_config["level_field"] field in tNG_config.inc.php.

• kt_login_page - stores the URL to the login page specified in the Control Panel > User Authentication. It is used by the Transaction Engine to fill in the links in the welcome and activation e-mail, and to provide the redirect for the restrict access to page server behavior. It corresponds to the $tNG_login_config["login_page"] field in tNG_config.inc.php.

• kt_activation_page - stores the URL to the activation page. It is used after user registration to provide the activation link in the welcome / activation e-mail message. It is obtained from the kt_login_page variable, by replacing the login.ext section with activate.ext (ext = current extension required by the server-model).

• kt_login_rememberme - stores the state of the remember me checkbox. Used for the auto-login feature.

2 URL variables, used on the account activation page:

• kt_login_random - stores the random key generated upon registration. It is available only when using account activation with random key.

• kt_login_email - the e-mail address of the user whose account is being activated.

215

Chapter 9: Display Dynamic Data

This chapter explains how to display data extracted from your database (or from other data sources) in your web application, by using Adobe® Dreamweaver® Developer Toolbox.

This chapter contains information on:

• “Front-end dynamic lists” on page 215

• “Back-end dynamic lists” on page 226

• “Developer Toolbox formats in the Bindings tab” on page 241

Front-end dynamic listsThis section describes the facilities that Developer Toolbox offers when building front-end dynamic lists:

• “Looper wizard” on page 215

• “Nested Repeat Region wizard” on page 216

• “Advanced operations on front-end lists” on page 217

Looper wizardThe purpose of the Looper wizard is to create looped representations of recordset content in a single operation. If you wish to create the list by putting together the separate pieces, see “Horizontal Looper” on page 218. Before applying it, make a selection in page.

The Looper wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Looper Wizard.

In order to add a horizontal looper into the page:1 Create a recordset containing the data that you want listed.

2 Drag and drop the recordset field you wish to display from the Bindings panel to the design area.

3 Select the field and apply the Looper wizard.


216

To set the Looper wizard options:1 The Looper type drop-down menu lets you select the order in which the records will be displayed (horizontally or vertically):

2 In the Recordset drop-down menu select the recordset you've already created and that contains the data you want to list. If you have no recordset yet, you can use the Add recordset button and create one now.

3 The Show radio group offers two possibilities:

• The first option allows you to set the number of table rows and table columns that will be used to list the data contained in the recordset (the number of records displayed is the result of the multiplication between the two numbers entered).

• The second option leads to the display of all the records. Depending on the looper type, only one of the text boxes above (rows, columns) will be enabled.


• The < Back / Next > buttons are disabled as this wizard only has one step and you cannot navigate back and forth.




Nested Repeat Region wizardThe Nested Repeat Region wizard can display records from two related tables (master and detail tables) in an organized manner. The wizard uses the foreign key to determine which detail record belongs to which master record, and lists them accordingly.

It will add all the required elements into the page, like tables, recordsets and server behaviors. You can also create these elements by hand, and then use the Nested Repeat Region server behavior to achieve the same result.

The Nested Repeat Region wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Nested Repeat Region Wizard.

To set the dialog box options for the first step of the wizard:1 In the Connection drop-down menu select the database connection defined for your site; if you don't have a connection yet, you can use the Define button and create one now.

2 In the Master table drop-down menu select the table containing the master records. This drop-down menu displays all the tables retrieved from the connection you selected at the first step.


217

3 In the Primary key drop-down menu you must select which field contains the primary key in the master table. It automatically selects the first field.

4 In the Display Value drop-down menu select the field that stores the names you want to be displayed.

5 In the Detail table drop-down menu select the table that contains the records linked to the ones in the master table.

6 In the Foreign key drop-down menu select the detail table field which contains the relation to the master table.

7 The Display value drop-down menu allows the choosing of a suitable field for display instead of the foreign key.






These buttons appear on all three interfaces of the Nested Repeat Region wizard.


To set the dialog box options for the second step of the wizard:1 In the Repeat style radio group select the method by which the detail records will be displayed: List (comma-separated list) or Sub-table (tree-like structure).

2 The image below this radio group gives a preview of how the list will look.

3 Click Finish when you are done configuring the wizard. In the Dreamweaver page, the result should look something like this:

Note: If two nested repeat regions are used on the same page, you must create a separate recordset for each one. If you try to use the same recordset for both you will be prompted with an error message.

Advanced operations on front-end listsThis sub-section presents features of the Advance Repeated Regions server behavior, which is included in Developer Toolbox. These advanced features are practical for giving users easy to read front-end dynamic lists. The dynamic lists make it possible to organize complex recordset results from single tables, as well as tables with a master / detail relationship. This section will specifically deal with the following server behaviors:

• “Horizontal Looper” on page 218

• “Vertical Looper” on page 219

• “Nested Repeat Region” on page 219

• “Nested Show If Not First” on page 220


218

Horizontal LooperAfter applying the Looper wizard and choosing the Horizontal type, you can notice in the Server Behaviors tab the server behavior that is added, namely the Horizontal Looper one. You cannot find it in the Developer Toolbox menu as it can only be accessed and edited after applying the Looper wizard, which adds it to the server behaviors list of the page.

You can use the Horizontal Looper server behavior (by double-clicking on it) to alter the Looper list properties at a later time.

The server behavior contains only one tab and it looks similar to the image below:

To set the dialog box options:1 In the Recordset drop-down menu select the recordset containing the data you want to list.


• the first option allows you to set the number of table rows and table columns that will be used to list the data contained in the recordset (the number of records displayed is the result of the multiplication between the two numbers entered).

• the second option leads to the display of all the records. For the Horizontal type, the Columns text box above is enabled.

3 In the Row separator read-only text box you can see the HTML tag that is used to separate data rows.






219

Vertical LooperAfter applying the Looper wizard and choosing the Vertical type, you can notice in the Server Behaviors tab the server behavior that is added, namely the Vertical Looper one. You cannot find it in the Developer Toolbox menu as it can only be accessed and edited after applying the Looper wizard, which adds it to the server behaviors list of the page.

You can use the Vertical Looper server behavior (by double-clicking on it) to alter the Looper list properties at a later time.

The server behavior contains only one tab and it looks similar to the image below:

To set the dialog box options:1 In the Recordset drop-down menu select the recordset containing the data you want to list.


• the first option allows you to set the number of table rows and table columns that will be used to list the data contained in the recordset (the number of records displayed is the result of the multiplication between the two numbers entered).

• the second option leads to the display of all the records. For the Vertical type, the Rows text box above is enabled.





Nested Repeat RegionIf you want to add the nested repeat region functionality for already created elements, without using the Nested Repeat Region wizard, you can use the server behavior instead. Before using the Nested Repeat Region server behavior, create a simple recordset for the master table and create a more complex recordset for the detail table (a filter must be applied on the foreign key column, ensuring that it is equal to the entered value). Also, make a selection in page.


220

The Nested Repeat Region is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Advanced > Nested Repeat Region.

The server behavior has one tab. Instructions about its correct configuration are given below.

1 In the Master recordset drop-down menu select the previously created recordset with the main data. The first recordset is selected by default.

2 In the Primary key drop-down menu specify the primary key column for the master table. The content of this drop-down menu is refreshed each time the user selects another master table. By default, the first element is selected.

3 In the Detail Recordset drop-down menu select the recordset created earlier that contains the data related to the master table.





Nested Show If Not FirstThe Nested Show If Not First server behavior is used to control the separator display, more exactly to avoid the separator display before the first element in the list. Before applying it, make a selection in page.

The Nested Show If Not First is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists > Advanced > Nested Show If Not First.


221

The server behavior has one tab. Instructions about its correct configuration are given below.

To set the dialog box options:1 In the Recordset drop-down menu select the recordset that will be used for the first row verifications.





File List Recordset (PHP_MySQL server model)When using the PHP_MySQL server model, a feature for working with server files in a dynamic manner is available. Given a folder with files you can use the File List Recordset to retrieve and manipulate the files as any other database stored dynamic data.

The file list recordset is a special type of recordset that retrieves files from a specified folder instead of database records. Then you can use the recordset in the same manner as any regular recordset.

To create a File List Interface:1 From the Application tab > Server Behaviors tab > Plus (+) > Developer Toolbox > File Upload click the File List Recordset entry.

2 Fill in the user interface settings as shown below. Click OK to apply the changes.

3 The new recordset is displayed on the Bindings tab. It retrieves and allows using the following file information:

• The full file name, including the path to the base folder selected in the user interface. This folder is the main folder where subfolders and images are uploaded.

• The file name - only the name of the file, without any folder or path information

• The creation date.


222

• The file size

• The file extension

4 Use the recordset just as you would use a regular one; you can drag and drop fields onto the page or use other server behaviors.

The user interface for this special recordset is divided into two tabs:

• The Basic tab - define basic recordset options: name, connection, location and naming rule for files.

• The Advanced tab - define recordset sorting and type of the files to retrieve.

Fill in each of these user interface tabs as instructed below.

The Basic tabWith the options on this tab you can define the recordset name, connection and file information.

Fill in the interface fields as shown below:1 In the Recordset name field enter a name for the recordset that is created. Use a unique name on the page.

2 In the Connection drop-down menu select the database connection to use.

3 In the File folder field enter the path to the folder storing the images. The path is relative to the current document. You can also use the Browse button to select the folder from the site structure. This is the base folder for the file upload and subfolder creation.

4 In the Recordset drop-down menu select one of the page recordset that you would like to use to provide the subfolder name. Select a Recordset here even if you don't want to retrieve the subfolder name from database.

5 In the Field drop-down menu select the recordset field that stores the subfolder name, or select None: Rename Rule to enable the Renaming rule text field (if the subfolder name is not to be retrieved from database).


223

6 In the Renaming rule enter the expression that determines the name of the subfolder containing the files. You can use the Developer Toolbox Dynamic Data to build dynamic expressions.

The Advanced tabOn this tab you can configure the value by which to order the recordset, the method and the file types:

1 In the Order drop-down menu select one of the file properties to order the recordset by. Available options are:

• Name - the file name

• Size - the file size

• Date - the creation date

• Extension - the file extension

2 In the Method drop-down select how to order the recordset: Ascending or Descending.

3 In the File types drop-down menu select the type of files to retrieve. Available options are:

• Documents - a predefined category with several document - type extensions.

• Images - predefined category with image file type extensions

• Custom - define your own extensions to load.


224

4 In the Allowed extensions grid you can see the list of extensions corresponding to the selected File type category. You can add or remove extensions from the grid by using the Plus (+) and Minus (-) buttons

When done setting all the options, click the OK button to create the recordset. It will be displayed in the Bindings tab as a File List Recordset and can be expanded to display the fields it retrieves:

Alternate Row Color (PHP_MySQL server model)The Alternate Row Color functionality has two server behaviors that accomplish the goal: to set two different background colors for a table/list rows and alternate them for consecutive rows. This contributes to a clearer reading and consulting of the table information (especially if it has many columns).

This section contains the following:

• “Alternate colors” on page 225

• “Alternate Colors CSS” on page 225


225

Alternate colorsBefore applying the Alternate Colors server behavior to a page, you need to have previously created a recordset and a dynamic table, or a Dynamic List.

1 Apply the Alternate Colors server behavior, accessing it from the Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists. Configure it by following the next instructions.

2 In the Even row color text box enter the hexadecimal code for the color that you want displayed as the background for the even rows. You can use the Color Picker button displayed beside the text box.

3 In the Odd row color text box enter the hexadecimal code for the color that you want displayed as the background for the odd rows. You can also use the Color Picker button. If none of the colors displayed there are convenient to you, you can choose another one by pressing the second button from the right (in the top bar of the Color Picker window).

4 Check the Highlight option if you want the row above which the mouse is to be highlighted.

5 The Highlight color text box is only enabled if the checkbox above it is checked. In identical ways as mentioned above, set the color that you want to be used for the mouse-over rows.





Alternate Colors CSSSimilarly to the Alternate Colors server behavior, before applying the Alternate Colors CSS server behavior to a page, you need to have previously created a recordset and a dynamic table, or a Dynamic list, but NOT only these elements. You also have to define two or three CSS classes (if you want to use a highlight color as well) that will be used to retrieve the needed background colors.

Apply the Alternate Colors CSS server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Dynamic Lists. To configure it correctly, follow the instructions below:

1 In the Even row class drop-down menu select the class that you previously defined to set the background color for the even rows:

2 In the Odd row class drop-down menu select the class you defined for the odd rows background color.

3 Check the Highlight option if you want the row above which the mouse is to be highlighted.


226

4 The Highlight class drop-down menu is only enabled if the checkbox above it is checked. Here, you should select the class you defined for the highlight color:





Back-end dynamic listsThis section describes the facilities that Developer Toolbox offers when building back-end dynamic lists:

• “Create Dynamic List wizard” on page 226

• “Dynamic List layout” on page 231

• “Manage Dynamic List wizard” on page 232

• “Dynamic List browser behavior” on page 233

• “Filter dynamic data: Dynamic list filters” on page 238

Create Dynamic List wizardIn order to quickly retrieve and display data from a table as a list with advanced capabilities, you can use the Create Dynamic List wizard. What this list offers above a standard dynamic table, is the possibility to filter and order the content, as well as automatically generated links to the corresponding Dynamic form, allowing you to add a new record, update or delete an existing one much more easier. Ordering the list can be done after any of the fields that are displayed, simply by clicking on the column title. An arrow, pointing either up or down indicates the sort manner: ascending or descending.


227

The Create Dynamic List wizard is accessible from two locations:


• The Application panel, Server Behaviors > Developer Toolbox > Dynamic Lists > Create Dynamic List wizard.

This wizard will create several elements for you (for a complete list, check out below, at the end of the topic):

• The recordset that retrieves the data you specify.

• The HTML elements to display the data, as well as the additional elements (links, buttons, navigation).

• The Dynamic List Layout server behavior, letting you modify some of the list's properties afterwards.

Before using the Create Dynamic List wizard, you should have a correctly configured testing site, as it will be required for the database connection setup step.

The wizard contains 4 steps, each of them addressing some settings:

1 In the first step define the data that will be displayed.

2 In the second step define which fields are to be displayed in the list's column.

3 In the third step define the filter for each column.

4 In the fourth step set some specific list properties.

Note: You can only create one Dynamic list per page.

Step 1 - Select a table to work withTo set the dialog box options for the first step of the wizard, follow the instructions below:

1 In the Get data from drop-down menu select one of the 2 possibilities:

• Table - if you want to retrieve data from a database table.

• Recordset - if you want to retrieve data from a recordset.

Depending on your choice, the interface will display different fields.

2 If you selected Recordset in the first drop-down menu, configure the following interface field:

In the Recordset name drop-down menu select one of the recordsets defined in your page. If you don't have a recordset yet, you can use the Add Recordset button and create one now.

Note: Say your recordset is retrieving data from more than one table and that you set the primary key column as being from table A. Make sure that in the corresponding form, in the first step of the Create Dynamic Form wizard, you select table A and the same primary key as the one selected in the list.

When from the Dynamic list in browser, you call the Dynamic form (for either updating or inserting), the form will only display the fields corresponding to table A although the list uses a recordset with more fields.

3 If you selected Table in the first drop-down menu, configure the following two interface fields:

• In the Connection drop-down menu select the database connection defined for your site. If you don't have a connection yet, you can use the Define button and create one now.

• In the Table drop-down menu select the database table retrieved through the selected connection, table that contains the data to display in the list.

4 In the Primary key column drop-down menu, select the table field which is set to be the primary key. This field contains unique data, and is used by default to pass parameters regarding the record to retrieve between the list and the form.


228

5 The Numeric check-box sets the primary key type. It is automatically refreshed when a new field is selected in the Primary key column drop-down menu.

6 In the Detail page text field, enter the name of the page that displays the details (all fields) for a selected record, as well as allowing the insert and update actions. You can type a file name (file that does not exist) and the wizard will create it for you. Or you can use the Browse button to select the page from your local site folder. The default value is form.php and in case it does not exist in your site structure, it will be physically created.

7 In the Number of records text field specify how many records will be displayed in the list at a time. This translates in how many rows will be in the list. The default value is 10.






These buttons are common to all steps of the Dynamic List wizard interface.


Step 2 - Configure the displayed fieldsTo set the dialog box options for the second step of the wizard:

1 If in the Get data from drop-down menu of the first wizard step, you selected Recordset, the interface for the second step looks like this:

Note: If you selected Table, the interface for the second step has some extra fields. Details upon these additional fields and the interface itself are presented starting with step 4. But read along for the common interface fields.

2 In the List columns grid, you can define what table columns will appear in the list. You can add or remove elements by clicking on the Plus (+) and Minus (-) buttons on top of the grid. Also, you can change the order columns are displayed in, by pressing the Up (^) and Down (v) buttons.

3 For each column there are some properties that can be set. In order to access them, you have to select the list field for which to set the properties from the grid. The available properties are:

• Header - this will be reflected in the list column title for the corresponding field.

• Char width - the maximum number of characters displayed is by default 20 (no matter the column type). You can set it as large as you want, but the content of the respective fields cannot spread on multiple rows. So if you set a large length, you will have to use the horizontal page scroll to view all the information listed.

4 If in the Get data from drop-down menu of the first wizard step, you selected Table, the interface looks like this:

5 Another property that can be set for each field (if you selected Table in the first step of the wizard) lays in the Get value from radio group. Select one of the radio buttons:

• Current table - the value will be retrieved from the current table (the one that contains the respective column). The three drop-down menus in the lower part of the interface will be disabled.

• Look-up table - by choosing this button, the value of the selected list column will be retrieved from a related database table. If you choose to use filters in the next wizard step, then the list columns that retrieve their values from look-up tables have the Display as property automatically set on Menu (but you can change it if you want to). In this step, the following three interface fields will be enabled. Read about their configuration below.

6 In the Database table drop-down menu select the table that contains the values you want to retrieve.


229

7 In the Label column drop-down menu select the column that stores the content you want to be displayed in the list.

8 In the Value column drop-down menu select the column that stores the value of the selected list field.


Step 3 - Define the filterTo set the dialog box options for the third step of the wizard:

1 In the Use filter drop-down menu select whether or not you want to use filters in the Dynamic list. If you choose No, the two drop-down menus under the grid will become disabled and no filter will be used in the list.

2 In the List columns grid, there are enumerated the table columns that appear in the list. You can set filter properties for each one of them.

3 If you chose to set filters for the list columns, in the Display as drop-down menu select one of the four possibilities of displaying the filter:

• Text field - you must enter the text to filter the list column by.

• Menu - the filtering options are displayed in a drop-down menu, allowing users to select only certain values.

• Checkbox - this option is suitable only for the columns with two possible values: 1/0, -1/0, or y/n. In browser, if this filter is unchecked, all the rows are listed. If checked, only some rows are listed, namely the ones that have a certain value (1, -1, y) in the respective column.

• None - select this option if you don't want a filter to be displayed for the current column in the grid.

Note: when selecting a filter to be displayed as a menu (after in step 1 you had chosen to get data from a Table, and in step 2 to get values from a Look-up table), a recordset will be automatically created (named Recordset1 if there isn't any other recordset with this name. If there is, it will be named Recordset2 etc). From this recordset, the menu will retrieve the values it displays.

If in step 2 you selected to get values from the Current table and you want to display the filter as a menu, under the Max chars text box there will be two buttons that you can use to associate values to the menu filter: Menu Properties and Add Recordset. Add the recordset first.

4 In the Field type drop-down menu select one of the available options. It shows the way filter form fields are submitted. The available values depend on the element chosen in the Display as field.

5 The Max chars text box is only enabled for filters displayed as text fields. Enter the maximum number of characters accepted in the filter.


Step 4 - Dynamic List propertiesTo set the dialog box options for the fourth step of the wizard,:

1 In the Default order drop-down menu on the left select the column by which the list will be ordered. In the drop-down menu on the right select the manner in which the ordering is to be made: Ascending or Descending.

2 In the Move up/down column drop-down menu leave the default None option if you are not using an ordering column. This will leave the settings for the previous two drop-down menus enabled.

By selecting a table column (that should store the records order), the drop-down menus above (Default order) will be disabled. The selected column must store numeric values and must have the unique attribute (there cannot be two identical values).


230

Corresponding to the Move up/down column, the list will display in browser 2 buttons on each row, namely the up and down arrows. It will not display the values kept in the database (even if this table column was listed in the List columns grid on step 2).

By moving rows up and down in the Dynamic list, the values stored in this table column will be modified / switched between them (after saving the changes).

Note: For technical details about selecting the Move up/down column when creating a Dynamic list, as well as a Dynamic form, see “Dynamic Form Layout” on page 53.

Note: If you selected a Move up/down column in your list and later on you want to remove it, you can do this by right-clicking on that column (in Design View in Dreamweaver) and then selecting Table > Delete Column. You cannot remove this column using one of the server behaviors.

3 The Current skin used in your site (in all the pages included, not only the current one) has its name displayed in bold text. The Change skin button offers the possibility of choosing another skin out of the available ones (aqua, kollection, arktic, formal) or None, if you don't want to use any skin.

You can preview the chosen skin in the image provided along with the selected skin. For more details, see “CSS Skins” on page 294.

4 In the Duplicate buttons drop-down menu select whether or not you want the list buttons to be displayed both in the list's footer and header (the Yes option), or only in the list's footer (the No option).

5 In the Duplicate navigation drop-down menu select if the navigation elements will be displayed both in the footer and header (the Yes option), or only in the list header (the No option).

6 In the Table row effects drop-down menu select whether or not you want rows to be highlighted when the mouse is over them.

7 In the Show links as buttons drop-down menu select whether or not you want the links to be shown as buttons.

8 In the Has row counter drop-down menu select Yes if you want to display a counter in the list's first column, and No otherwise. It is not related to the columns in the database, but to the list row on which they are displayed.

9 When you are done configuring the wizard, click the Finish button.


231

The page in Dreamweaver should look like this (if data was retrieved from a table, and not a recordset):

As you can see, the list uses some translators in Dreamweaver Design View to display code blocks (e.g. the numbers used in the page header, or the show if conditional region for the filter). Translators are not visible on the final generated page, in the browser. They are just visual aids in Dreamweaver, in order to help you identify the different generated server behaviors and code blocks.

Once applied in a Dreamweaver page, the Create Dynamic List wizard will add the following elements in the Server Behaviors tab of the Application panel:

• a recordset corresponding to the Dynamic list.

• a recordset corresponding to each menu filter, if you set any. See the note above to understand better how this works.

• conditional and repeated regions.

• dynamic attributes for the HTML form elements.

• the Dynamic List Layout server behavior.

To change any of the list properties at a later time, you can double-click the Dynamic List Layout server behavior (inserted by the wizard) or apply the Manage Dynamic List wizard command, accessed from the Insert bar > Developer Toolbox tab.

To learn about the list's behavior in the browser, see “Dynamic List browser behavior” on page 233.

Dynamic List layoutAfter applying the Create Dynamic List wizard, you can notice in the Server Behaviors tab the server behavior that is added, namely the Dynamic List Layout. You cannot find it in the Developer Toolbox menu as it can only be used after applying the Create Dynamic List wizard, which adds it to the server behaviors list of the page.

You can use the Dynamic List Layout server behavior (by double-clicking on it) to alter the Dynamic list properties (mainly the visual elements like the skin and the buttons) at a later time. The server behavior contains two tabs.

To set the dialog box options for the Basic tab, follow these steps:

1 In the Number of records text field specify how many records will be displayed in the list at a time.

2 In the Default order drop-down menu on the left (if enabled) select the column by which the list will be sorted. In the drop-down menu on the right select the manner in which the sorting is to be made: Ascending or Descending.

3 In the Move up/down column read-only drop-down menu you can view what table column was selected previ-ously (in the Create Dynamic List wizard) for the records order.


232

Note: If you selected a Move up/down column in your list when using the Create Dynamic List wizard and later on you want to remove it, you can do this by right-clicking on that column (in Design View in Dreamweaver) and then selecting Table > Delete Column. You cannot remove this column using one of the server behaviors.

4 The Current skin used in your site (in all the pages included, not only the current one) has its name displayed in bold text. The Change skin button offers the possibility of choosing another skin or None, if you don't want to use any skin. For more details, see “CSS Skins” on page 294.

5 In the Duplicate buttons drop-down menu select whether or not you want the list buttons to be displayed both in the list's footer and header, or only in the list's footer.

6 In the Duplicate navigation drop-down menu select if the navigation elements will be displayed both in the footer and header, or only in the list header.

7 In the Table row effects drop-down menu select whether or not you want rows to be highlighted when the mouse is over them.

8 In the Show links as buttons drop-down menu select whether or not you want the links to be shown as buttons.

9 In the Has row counter drop-down menu select Yes if you want to display a counter in the list's first column, and No otherwise. It is not related to the columns in the database, but to the list row on which they are displayed.

10 Click on the Advanced tab to continue configuring the server behavior.

To set the dialog box options for the Advanced tab:1 In the List name read-only text box you can read the name of the Dynamic list. It is formed by putting together the word 'list', the name of the database table, and a unique number per site.

2 In the Detail page text box you can enter another file than the one already there, file in relation with the Dynamic list. This file should contain a Dynamic form (that will display all the record details). You can either type its name or use the Browse button to locate it on your computer.

3 Click OK when you are done configuring the Dynamic List Layout server behavior.

Manage Dynamic List wizardAfter applying the Create Dynamic List wizard, you can alter the properties of the Dynamic list fields by using the Manage Dynamic List wizard. It is accessible from two locations:


• The Application panel, Server Behaviors > Developer Toolbox > Dynamic Lists > Manage Dynamic List wizard.

Important: Before applying this command or the server behavior, make sure that you click on the Server Behaviors tab inside the Application panel in order to display the list of existing Server Behaviors on page. This is mandatory, and if you skip this step you will not be able to use the wizard.

This command has three steps and it can be applied any time you want to make changes in a Dynamic list. These changes regard the three operations: insert, update and delete that can be performed on the Dynamic list fields. So you can add or remove fields from the list, or you can update the existing ones (header, char width).

Note: Since there can only be one Dynamic list in the page, the wizard automatically opens with the second step. If you want to know the list name, you can hit the < Back button in that second step and check out the list name in the first step.

To set the options for the first and second steps of the wizard:1 In the List name drop-down menu, the name of the Dynamic list in page is already selected.



233

3 The List columns grid lists the current table columns that appear in the list. You can add or remove elements by clicking on the Plus (+) and Minus (-) buttons on top of the grid. Also, you can change the order columns are displayed in, by pressing the Up (^) and Down (v) buttons.

Note: If in the second step of the Create Dynamic List wizard you removed some table columns and now you want to add them to the list, you will notice that they are not available in the Add window. To make them available, you should first edit the list recordset (double-click it in the Server Behaviors tab) and add the wanted table columns. Do this by either using the Select button in the window that opens or the QuB3 button (Query Builder).

4 For each column there are some properties that can be modified. To access them, select a list column from the grid in order to modify its properties. The available properties are detailed below.

5 In the Header text box you can modify the list column title (header).

6 In the Char width text box you can modify the maximum number of characters accepted by the current list column.


To set the options for the third step of the wizard:1 The Use filter drop-down menu is read-only, reminding you if you chose to use filters or not in the Create Dynamic List wizard.

2 In the List columns grid, there are enumerated the table columns that appear in the list. You can set filter properties for each one of them.

3 If you chose to set filters for the list columns, in the Display as drop-down menu select one of the four possibilities: Text field, Menu, Checkbox, None. The latter one assures that no filter is displayed corresponding to the current column. Read more about these options here.

4 In the Field type drop-down menu select one of the available options. It shows the way filter form fields are submitted. The available values depend on the element chosen in the Display as field.

5 Depending on the Display as option, some more buttons may become available. For the menu option, two new buttons, Menu properties and Add recordset are available, allowing you to create a new recordset, and to change the menu items properties.


Dynamic List browser behaviorWhen using a Dynamic list to display records from the database, you should completely understand all of the elements that are generated along with it and how they help ease navigation, as well as some of the most common operations.


234

As a basic example of a simple Dynamic list, consider the following image:

The elements that compose the Dynamic list are:

1 The list title displays:

• the generic name of the elements listed. This is taken from the table name (eliminating the underscore "_" and what follows after it) or, when data is retrieved from a recordset, the displayed list title is the name of the recordset (in Title case)

• the counting order of the first and last elements on the current list page out of the total number of elements.

2 The list header and footer contain buttons that can add an element (or more) and modify or delete the selected elements. They are displayed both in the header and footer only if in the Duplicate buttons drop-down menu you selected Yes when creating the list. The available buttons are:

• edit - modify the selected records (multiple update). By selecting certain records and then hitting the Edit button in the footer (or header), you can edit multiple records at the same time.

• delete - delete the selected records (multiple delete).

• add new - insert one or more new records in a database table at the same time (multiple insert). The drop-down menu besides this button has 3 default options: 1, 3 and 6. They represent the number of records that you can choose to insert in one operation. If none of the 3 options in the add new drop-down menu are convenient to you, you can add another one. To learn how to do this, see How to Edit the Number of Records in a Multiple Insert.

Note: Both the single and multiple delete operations, although they appear to take place the in list page, they are actually executed in the form page, where the Insert/Update/Delete transactions are included.

3 The navigation bar allows you to move through the list pages: first, previous, next and last.

This bar is displayed both in the header and footer only if in the Duplicate Navigation drop-down menu you selected Yes when creating the list.


235

4 There are 2 links displayed near the navigation bar, on the right:

• The Show all records link displays in one list page all the records retrieved. After clicking on it, it becomes Show n records, n being the number of records you chose to be displayed per page.

• The Show filter link displays in a table row the filters set for each of the list columns. After clicking on it, it becomes Reset filter, which has 2 roles: when pressed, it resets the filter and at the same time, it hides it.

5 The list table header contains:

• the labels specified in the Create Dynamic List wizard for each table column;

• a checkbox element (on the very left) that allows selecting all the records currently displayed, in order to edit or delete them;

• an additional column, No., that lists the current number of a table row which displays list elements (it simply counts the elements starting with 1). This order is not the order from the database table, but one that is created when the elements are displayed. This column does not appear if the Has row counter checkbox was not selected in the Create Dynamic List wizard.

6 By using the filter, you can select elements with certain characteristics out of the list. Filters can be set for none, all or just some of the list columns (set in step 3 of the Create Dynamic List wizard)

• In a drop-down menu filter, select one of the available options and all the records that qualify will be listed.

• In a text field filter, enter a sub-string, and all the records that, in that specific table column, include in their values the typed sub-string, will be listed.

Note: Filters for date-type columns and for numeric columns have some particular characteristics.

7 Click the Filter button on the right of the filter row in order to make the records selection. The button is absolutely needed when the filter is a menu (or when at least one of the filters is a menu). When all the filters are displayed as text fields, you can simply hit Enter after typing in the filtering text.

8 An actual list table row contains the following:


236

• a checkbox in the first table column that allows selecting that row;

• the number that identifies that row in the list table;

• the actual data in that record;

• the edit button that allows updating the record corresponding to that row;

• the delete button that allows removing the record corresponding to that row.

Notice that when the mouse is over a row, if in the Table row effects drop-down menu of the Create Dynamic List wizard you selected Yes, the row is highlighted (in green here, for the Kollection skin). For the same skin, when a row is selected, it is highlighted in purple.

Note: When deleting a row, the Dynamic list will continue to display the page from which that row was removed, and will not redirect the view to the first page. The only exception is when the row deleted is the only one on the last page. After removing it, the list will display the new last page, namely the one that used to be second to last (so that an empty page will not be shown after the deletion).

9 If in the Move up/down column drop-down menu you selected one of the numeric and unique table columns available, you will notice a new column in the table list that contains 2 buttons on each row (except for the first and last rows), namely the up and down arrows (the Order column in the example given here). The first and last rows on a list page display only one of the two buttons: the down arrow, respectively the up arrow.

The title of this column is shown as a link, and there is a little black arrow next to the title (see the image above, at step 6). By pressing this link, the records are displayed in the list table ascending or descending (the black arrow indicates the ordering direction), in relation to that field. The other column titles are not showed as links so you cannot order the list items by other criteria since they are already displayed in a specific order (given by the order column).

Note: When in the Move up/down column drop-down menu you selected None and in the Default order drop-down menu you selected one of the available columns (set in step 4 of the Create Dynamic List wizard), all the column titles in the Dynamic list are displayed as links. You can click on any of them if you want to order the records according to that table column. The black arrow will show you by which column the current order is made, and it will also imply the direction:

10 Back to the up and down arrow buttons: not only do they change the records order in the list table (by moving them up and down in the list), but also in the database.


237

Let's say that in the first list page (the first image in this topic, before step 1), you want to switch between them the records currently on the second and third row. You can simply click on the up button on the third row. The row that is moved is being highlighted (in green here):

As you can notice, the two rows switched between them. Also, notice that the list rows are not correctly numbered now (1, 3, 2, 4) and that the column with the up and down arrows had its title replaced by the Save button. This button appears after the first move.

This phase in the ordering process (the rows switching in the list) is the client-side part of the operation. The changes are not updated in the database at this moment so that the page will not be loaded for each and every order move you make.

11 After reaching a final order, you can press the Save button and the change will be saved in the database (the actual values of the order_prd column will be changed). This is the server-side part of the operation. Also, the rows numbering will be corrected, and the Save button will be replaced by the column title:

Note: If you want to switch two records between them, one being the last on a page and the other being the first on the next page, you can do this only when all the records are displayed.


238

12 If you attempt to do anything before saving the rows/records moving, a message window will pop-up reminding you to save or discard the changes:

13 The list elements that are displayed can be retrieved from more than one table. Simply change its filter element to menu and define a recordset. The list's query will automatically create a join with the respective table. This allows displaying actual names for foreign key fields, without the need of writing complicated queries by hand.

Filter dynamic data: Dynamic list filtersThere are some specific characteristics about filtering date-type columns and numeric columns, characteristics that will be described in what follows. Before checking them out, get familiar with the date formats allowed by Developer Toolbox and set through the Developer Toolbox Control Panel.

The skin used this time will be the arktic one, and the buttons and navigation bar are not duplicated. Let's consider the Dynamic list below. The rows are ordered ascending by name:

In the text field filter corresponding to the Hire date list column, you can type different sub-strings in order to select certain rows from the list. Any input you may enter, it is handled as having your date format. All the existing possi-bilities for date filtering will be described below, after the following note.

Note: Besides using the slash (/) as a date separator, you can also use a dash (-) or a dot (.).


239

1 If you want to retrieve all the employees that were hired in year YYYY (between January, 1 and December, 31), you can type YYYY in the date filter, click the Filter button on the right, and those employees will be listed:

2 If you want to retrieve all the employees that were hired in month MM of year YYYY (between the first and the last day of that month), you can type either YYYY/MM or MM/YYYY in the date filter (no matter your date format), and those employees will be listed:

3 If you want to retrieve all the employees that were hired in a certain year (between January, 1 and December, 31), you can also type YY in the date filter, and those employees will be listed.

• If you enter a value lower than 70, the filter will retrieve the rows that have the hire date between January 1, 20YY and December 31, 20YY:


240

• If you enter a value greater than 70, the filter will retrieve the rows that have the hire date between January 1, 19YY and December 31, 19YY.

4 If you want to retrieve the employees hired on a certain day, type that date (in your specific screen date format) in the filter text field. All the employees hired on that day, between 00:00:00 and 23:59:59 will be listed.

In the current example, the date format is MM/DD/YYYY. Let's use the dash (-)as a date separator.

Note: for the same result, you could have typed YY (05-14-98) instead of YYYY (05-14-1998), but make sure that your input is aligned to the date format.

5 When the date is explicitly typed (day, month, year), like in the previous step, you can filter deeper by the time (hour:minute:second). Do this by typing space after the date and then go as detailed as you want by mentioning the hour, minute, second. If you haven't stored the time in the database, then this part of the filter will be ignored and only the date part will be in action.

• If after the space you type nothing else, then the time interval considered is: 00:00:00 to 23:59:59.

• If you type MM/DD/YYYY HH, this input will be actually seen as the interval between MM/DD/YYYY HH:00:00 and MM/DD/YYYY HH:59:59.

• Similarly, if you type MM/DD/YYYY HH:II, the filtered time interval will be: MM/DD/YYYY HH:II:00 - MM/DD/YYYY HH:II:59.

6 The following operators: <, >, <=, >=, =, <>, != (identical with <>) can be used when filtering by a date-type field. The operators actions are obvious (according to their mathematical meaning).

Here is the list of sub-strings you can type after one of these operators in the filter. For exemplification, we'll use the ">" operator:

• >YYYY or >YY (no matter your date format)

• >YYYY/MM or >MM/YYYY (no matter your date format)


241

• depending on your date format, only one of these two will work for you: >YY/MM or >MM/YY

• >MM/DD/YYYY (a certain date written in your date format). You can retrieve the wanted rows even when typing YY.

Since the Salary list column is a numeric one, in the text field filter corresponding to it, you can also use these operators: <, >, <=, >=, =, <>, != (identical with <>):

Note: The entered expressions that don't match the rules above will be ignored and no error will be thrown.

Developer Toolbox formats in the Bindings tabThis section describes the formatting facilities offered by Developer Toolbox when working with dynamic data from the Bindings tab (recordsets or variables):

• “Format date” on page 242

• “Escape special characters” on page 242

• “Format for list” on page 243


242

These formats can be applied for any field what is placed on page from the Bindings tab. Once a field is placed on page, the Format drop-down menu is available. The Developer Toolbox added options are under the Developer Toolbox menu item:

Format dateThis format will apply the KT_formatDate function on the selected field. This function will convert from database date formats to the selected screen format, according to the options set in the Developer Toolbox Control Panel > Date formats.

This format should be used on fields that contain dates, and if retrieved from a database, their format must match the one set for the Database date format in the Developer Toolbox Control Panel. Otherwise, the conversion may not work as expected.

When applied on a field (e.g. name_emp), it will become a parameter for the function.

• For the PHP server model, the code is like the following:

KT_formatDate($row_rsRecordset['name_emp']).

• For the ColdFusion server model, the code is:

#Request.KT_formatDate(rsRecordset.name_emp)#

• For ASPVBScript, the code is:

KT_formatDate((rsRecordset.Fields.Item("name_emp").Value))

Escape special charactersThis format will apply the KT_escapeAttribute on the selected field. This function will replace all special characters (double quotes, the less then and greater then signs - " , > and <) with their corresponding HTML codes, in order to avoid breaking the page code. This will also make sure that no code can be entered in a field, and ran when displayed.

When applied on a field, it becomes a parameter for the function, and the result is the function output.

• For the PHP server model, the code is like the following: KT_escapeAttribute($row_rsRecordset['name_emp']).


243

• For the ColdFusion server model, the code is: #Request.KT_escapeAttribute(rsRecordset.name_emp)#

• For ASPVBScript, the code is: KT_escapeAttribute((rsRecordset.Fields.Item("name_emp").Value))

Format for listThis format will apply the KT_FormatForList function on the selected field. This functions prepares the field content to be viewable in a list (e.g. a Dynamic list), and it performs the following operations on the field:

1 First, it removes all <head>, <link>, <style> and <script> opening and closing tags.

2 Next, the less then and greater then ( < and >) characters are converted to their HTML codes (< >).

3 Then the function checks the length of the field. If it is greater than a maximum number of characters, only a section will be kept (from the beginning, up to the maximum number of characters set).

4 The last thing is to add a trailing "..." section, if the field's length is bigger than the maximum allowed number of characters.

When applied on a field, it becomes a parameter for the function. The result is no longer the exact field value, but the value returned by the function.

• For the PHP server model, the code is like the following:KT_FormatForList($row_rsRecordset['name_emp'],$maxChars).

• For the ColdFusion server model, the code is: #Request.KT_FormatForList(rsRecordset.name_emp,maxChars)#

• For ASPVBScript, the code is: KT_FormatForList((rsRecordset.Fields.Item("name_emp").Value),maxChars)

244

Chapter 10: User Authentication

This chapter provides information about a great feature in Adobe® Dreamweaver® Developer Toolbox, namely user authentication. The improvements and novelty brought along with these features significantly increase the security level of your site.

• “Build a user registration page” on page 244

• “Build a login form” on page 246

• “Restrict access” on page 249

• “Logout the user” on page 252

• “Advanced user login actions” on page 253

Build a user registration pageWhen you decide to implement a user authentication system for your site, the first step to take is to create a way for users to create accounts. This is the user registration process, which usually contains an insert transaction (to add the user data into a table) together with some checks to make sure the user name is not taken, and that the confirmed password matches the entered passwords. User Login module gives you the possibility of doing all of these actions in a single place, with the User Registration wizard.

The User Registration wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > User Login > User Registration Wizard.

To set the options for the first step of the wizard:1 The Connection, Table and Primary key column interface fields display the settings established in the login settings of the Control Panel. All login options are set globally.

2 If you want to change any of these settings, click the Change Login Settings button and the control panel entry mentioned above will be displayed.

• The five buttons in the lower part of the interface offer the following functionalities:





These buttons appear in all the User Registration wizard steps.


In the second step of the wizard, you will associate for each table column the form element to be displayed.


245

To set the options of the second and third steps of the wizard:1 In the Form fields grid, all table columns that are used in the transaction are displayed, with their associated properties: label, form element, submit type, and default value (where needed). You can add or remove columns to/from the transaction, with the + and - buttons placed on top of the grid, and you can change fields order with the up and down arrows above the grid.

2 Specify how each item should be displayed in the HTML form by selecting a row (single click) in the Form fields area and entering information in the boxes below the grid as indicated below.

3 In the Label text-box enter the text to be displayed next to the form element.

4 In the Display as drop-down menu select the form element to use for the table column. For the password field, you must select Password field, in order for the confirm password automatic generation and check. To read the detailed description for each of the available options, click here.

5 In the Submit as drop-down menu, select the data type to use when submitting information to the database.

6 In the Default value text-box enter a value that will be displayed by default in the form element, when the page loads.


Note: If you remove the password field from the grid, by clicking on the Minus (-) button, a password will be automati-cally generated by Developer Toolbox, and will be sent by e-mail to the user (if the Send welcome e-mail option is checked). If no e-mail message is to be sent to the user, the account is blocked (there is no way to discover the password).

Note: If you use the PHP_MySQL server model and have defined in your database columns for storing the maximum number of login attempts, the account disable date, registration date and expiration date you should leave those columns out of the registration form. They receive the right values behind the scenes, in a transparent manner: the registration date field gets the current date, the expiration gets the current date plus the expiration period defined in the control panel. If for any reason you want to have some of the fields initialised with your custom value, make sure you set them to be displayed as Text and remove them from the page form (in generated code) so that the users cannot alter it.

In the third step, you can set validation rules for the form elements. For instructions on completing this step, see “Form Validation in wizards” on page 89.

In the fourth and last step of the wizard, you can set some registration options.

To set the options for the fourth step of the wizard:1 If you want to send welcome e-mail messages and if you want to use account activation, check the corresponding checkboxes.

Note: The Use account activation checkbox is disabled if in the login settings of the Control Panel there is no table column specified that stores the account active state.


When you finish with the wizard configuration, it will add the HTML form, a Send E-mail trigger and a Throw error trigger. When you open the page in the browser, and try to register, the wizard will perform several actions:

• Check if the user name is unique.

• Compare the password field versus the confirm password field (if any).

• If everything went fine, insert the data into the table.

• As last action, send a welcome e-mail.


246


Build a login formThis section explains how to create user login forms:

• “Login Form wizard” on page 246

• “Login Transaction” on page 246

• “Show Login Message” on page 249

Login Form wizardIn order for a user to be recognized by your site, they have to login using their username and password. All settings for the login process are configured through the login settings entry of the Control Panel: how to login users, what database table stores the user details, user levels and redirects.

You must provide a way for the users to enter the data that will allow the site to recognize them. This is done via a login form generated automatically by the Login Form wizard.

The Login Form wizard is accessible from two locations:


• The Application panel, Server Behaviors > + > Developer Toolbox > User Login > Login Form Wizard.

Once you've accessed the wizard, its user interface will be displayed at the first step. The dialog box is identical to the one from the first step in the User Registration wizard. For instructions, see “Build a user registration page” on page 244.

To set the dialog box options for the second step of the wizard:1 If Use "Remember me" checkbox is checked, the wizard will generate a "Remember me" option in the form, allowing the user to be automatically logged in.

2 If Create "Forgot password" page is checked, the wizard will generate a page in Dreamweaver named forgot_password. This page contains a form, a Send E-mail trigger, an Update Transaction.


Once the wizard is completed, it will add an HTML form and a login server behavior.


Login TransactionIn order to build the login page, you can either use the wizard and do all operations in one place, or construct the page from pieces.


247

To build the login page from pieces, you must follow the next steps:

• Add the HTML elements that will constitute the login form: the text-fields and buttons.

• Make sure the login settings of the Control Panel are correctly configured.

• Apply the Login Transaction. Configure it to use the form elements you've created.

• Save the page and preview it in the browser. Try to login.

Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Login Transaction.

The user interface has three tabs. Directions about their correct configuration are given below.

To set the dialog box options for the first tab:1 The Connection, Table and Primary key column interface fields display the settings established in the login settings of the Control Panel. All login options are set globally.

2 If you want to change any of these settings, click the Change Login Settings button and the control panel entry mentioned above will be displayed.

3 In the First check variable drop-down menu select the variable type to use as a starter: URL Parameter, Form Variable, Cookie, Session Variable, Server Variable, Entered Value. In the associated text box enter the variable's name.

4 The three buttons in the top right corner of the interface offer you the next functionalities




These buttons appear on all three interfaces of the Login Transaction server behavior.


248


To set the dialog box options for the second tab: 1 The Username drop-down allows you to select the field containing the user name among all the text field elements in the page.

2 The Password drop-down menu lists only the password type fields in the page's form.

3 The Remember me drop-down menu lists all fields of type checkbox.


To set the dialog box options for the third tab:1 In the Transaction name text box enter an appropriate name for the transaction making sure it is unique on the page. By default, Developer Toolbox assigns unique names to each transaction, and this setting should not be changed, unless you really know what you are doing.

2 Click on the OK button to add the server behavior into the page.


249


Show Login MessageThe Show Login Message server behavior gives the user information regarding their access to a page.

Access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Show Login Message.

For example, a page with restricted access will give the following message:

The user is redirected to the login page, and given a message like the one above. The Show Login Message behavior is automatically added with the Login Form wizard. Messages are also generated for users who have not activated their account, and also for users who have just completed the forgot password page and have been returned to the login page.

Restrict accessThis section shows you how to restrict access to pages and folders:

• “Restrict Access To Page” on page 249

• “Restrict Access To Folder” on page 250

Restrict Access To PageThe goal of having users login onto your site is to allow them to access information that others cannot. In order to do so, you must protect the private pages by restricting access for the users that haven't logged in. When using User Login module, you can implement this through the Restrict Access To Page server behavior.

You can access the server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Restrict Access To Page. The user interface has only one tab.


250

Configure the dialog box that opens so that only the users that you want will get access, while others will get redirected to a specified page. Set the criteria to use when blocking access by following the given instructions:

1 The Restrict based on radio group offers the criteria to use: Username and password or Username, password and access level. While the latter is more complex, it also requires that you have user levels defined in your table.

2 If using the Username, password and access level option, you will have to select from the list the levels that are granted access to the page. This list is retrieved from the login settings of the Control Panel.

3 If you need to add (new) levels or change any settings, you can press the Change Login settings button to open the mentioned entry in the control panel.





When viewed in the browser, if you are not logged in properly, you will get redirected either to the default login failed page, or the page specified as redirect for your precise user level.


Restrict Access To FolderIn order to implement access restrictions to several pages, you normally would have to open each of the pages and apply the Restrict Access To Page server behavior, based on user name and password and/or level for each. If all of these pages must share the same restriction settings and are located inside the same folder, USER Login Module provides a quicker way: Restrict Access To Folder.


251

The end result of this command is similar to the Restrict Access To Page one, when viewed on a single page. The difference lies in the fact that this command applies itself to several pages at the same time. Only pages that have the same extension as required by the server model you're working on will be processed, and not all files in the respective folder (e.g. images, text files etc.).

The Restrict Access To Folder command is accessible from the Developer Toolbox tab of the Insert bar.

Note: Due to some technical reasons, Restrict Access To Folder can only be opened from this location. It cannot be accessed from the Server Behaviors tab in the Application panel, the Developer Toolbox entry.

To block users that are not logged in and do not have the required access level from entering pages from a specified folder, follow the next steps when configuring the command. It has two tabs.

To set the dialog box options for the first tab, follow the next steps:

1 In the Folder to protect text box enter the folder containing the site pages to protect. Use the Browse button to navigate through the site's structure and select the desired folder.

2 After you select a folder, all the files that are to be processed are displayed in the grid below, and the path is displayed in the Folder to protect text box.

Note: Access is restricted only for the files that have the extension (.php, .asp, .cfm) corresponding to the server model used. For example, .jpg files will not benefit from the command's effect.


• Click OK when you are done configuring the command.



4 These buttons appear on both interfaces of the Restrict Access To Folder command.


252

5 Click on the Levels tab to continue with configuring the command.

The dialog box corresponding to the second tab is identical to the one from the Restrict Access To Page server behavior. So click here for instructions on configuring this tab.

Note: If you use this command on the ColdFusion server model, a file named Application.cfm will be automatically generated in the site root folder. Do not delete this file, as it contains settings related to session variables used by the command and the current application. If you remove this file or modify it, application pages that use sessions will not function properly.

Logout the userWhen a user has finished with your site, they may choose to close their session. This can also be done automatically, when the user enters a certain page. This is called a logout operation.

Note: This server behavior is only available for ColdFusion and ASP_VbScript server models. For PHP_MySQL this has been replaced with Logout Form wizard..

Building the logoutTo implement this action, the User Login module contains a server behavior called Logout User. You can access it from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Logout User. The dialog box has only one tab.

To set the dialog box options::1 The Log out when radio group offers a choice for the start method of the logout operation:

• If you choose Link clicked, you can select from the associated drop-down menu either a text section you've previ-ously selected or Create New Link: "New link" (it will automatically generate the link into the page). A second option is "Forgot your password?".

• If you choose Page loads, the logout operation will be started when the page loads in the browser.


253

2 In the After logout, go to text box, enter the page that will be opened after the user logs out. You can use the Browse button to locate the file.

3 If you need to change anything regarding the general login settings, you can press the Change Login settings button to open the login settings entry of the Control Panel.






Advanced user login actionsThis section shows you how to improve the user authentication parts of your site and how to implement authenti-cation features step by step:

• “Create Forgot Password Form” on page 253

• “Create Activation Page” on page 255

• “Check Old Password” on page 256

• “Check Account Activation” on page 257

• “Check E-mail” on page 258

Create Forgot Password FormThe Create Forgot Password Form server behavior is for users who no longer remember their password. The page will take a user's email address, verify that it exists in the database, and send the user their current password.

There are two ways to automatically create a page for users who forgot their passwords. The first is a checkbox in the Login Form wizard. The second is applying the Create Forgot Password Form server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Create Forgot Password Form.

The following dialog box will appear:

The three buttons offer the next functionalities:

• Click OK if you want to generate a password reminder form.


254

• Click Cancel if you don't want to apply the server behavior.


The page will contain a form where the users will submit their email address. The generated page in Dreamweaver looks like this:

The browser view will look like in the image below:

Once the address is found in the database, an email is sent out to the user with the following default message:


255

If the email address is not found in the database, an error message will appear:


Create Activation PageThere are two ways to automatically create a page for users to activate their account. The first is a checkbox in the User Registration wizard. The second is applying the Create Activation Page server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Create Activation Page.

The following dialog box will appear:

Create Activation Page will generate an Update Transaction to change the value of the active column in your database table. Ideally, the active column should be a boolean type (Y/N).

Also, the generated activation page acts as a redirect after the Update Transaction occurs. The user will be sent to either the login page, or they will be automatically logged in. This depends on whether or not a random key has been set up in your database.

Below is a list of the server behaviors generated by the Create Activation Page server behavior:


256


Check Old PasswordThe Check Old Password trigger is used when a user wants to change their password. It can be applied from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Check Old Password. Apply it only if you build the update form manually.

If you use the Update Record Form wizard and you set the transaction to use the same table as defined in the login settings entry of the Control Panel, and you also set the password column to use a password type field in the form, this trigger will be added automatically.

To use the Check Old Password trigger, create a form first and apply the Update Record Transaction, then check the old password. If the password is OK, then the update proceeds.

The interface should look like the one below:

For instructions on completing this dialog box, see the Advanced tab. For the Check Old Password trigger, by default the Priority is set to 60 and the Type is BEFORE, as it should execute before the transaction takes place.


257


Check Account ActivationThe Check Account Activation trigger checks if account activation is used and if the account to be activated is unique. It also checks whether or not the account has already been activated by someone else.

Generally, this trigger is automatically created by the User Registration wizard or by the Create Activation Page server behavior.

It is possible to manually create your own activation page with the Update Record Transaction and the Check Account Activation trigger (to check the activation status of a user before the update occurs). Both of these actions though can be performed simultaneously with the Create Activation Page server behavior.

Access the trigger from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Check Account Activation.

An example of the trigger interface can be seen below:

For instructions on completing this dialog box, see the Advanced tab. For the Check Account Activation trigger, by default the Priority is set to 1 and the Type is BEFORE, as it should execute before the transaction takes place.


258


Check E-mailThe Check E-mail trigger verifies that the given email address exists in the database before sending out an email. In a typical Forgot Password Form, the user enters an e-mail address, and the password is sent to that address. The trigger is used to make sure the address is valid before the e-mail message is sent.

The trigger is automatically generated by the Create Forgot Password Form server behavior, and also by checking the "Forgot Password" checkbox in the Login Form wizard. If you decide to create your forgot_password page manually, the trigger can be added directly from the Application panel, Server Behaviors > + > Developer Toolbox > User Login > Advanced > Check E-mail.

The trigger interface will then appear:

For instructions on completing this dialog box, see the Advanced tab. For the Check E-mail trigger, by default the Priority is set to 20 and the Type is BEFORE, as it should execute before the transaction takes place.



259

Logout Form wizard (PHP_MySQL server model)If you use the PHP_MySQL server model, the Logout has been changed in order to allow you to associate triggers to the logout operation. This way you can perform various tasks when the user clicks the logout link - like cleaning up user specific information, or saving the logout date into a logging table. You can apply the new Logout Form wizard from the Application tab > Server Behavior tab > Plus (+) > Developer Toolbox > User Login.

When a user has finished with your site, they may choose to close their session. Or this can be done in an automatic manner, when the user enters a certain page. This is called a logout operation.

The logout has been turned into a wizard which adds its own transaction (logout transaction) to the page. This has been done in order to allow the developer attach various triggers and actions to this operation.

The user interface contains two steps:

The first step is informative allowing you to revise the options set in the Login Settings section of the Control Panel. If all options are set correctly, you can click the Next button to move forward to the second step of the wizard. If not, you can click the Change Login Settings button in order to load the Control Panel user interface and adjust the options.

The second step allows setting the start condition for the logout action, as well as the page to load after the operation complete.

To set the dialog box options:• The Log out when radio group offers a choice for the start method of the logout operation:

• If you choose Link clicked, you can select from the associated drop-down menu either a text section you've previ-ously selected or Create New Link: "New link" (it will automatically generate the link into the page). A second option is "Forgot your password?".

• If you choose Page loads, the logout operation will be started when the page loads in the browser.

• In the After logout, go to text box, enter the page that will be opened after the user logs out. You can use the Browse button to locate the file.

Logout Form Transaction (PHP_MySQL server model)If you prefer to build the logout page by its building blocks, instead of using the wizard, you can do so by applying the Logout Form Transaction. You can access this server behavior from the Application tab > Developer Toolbox > User Login > Advanced > Logout Transaction.

The user interface is divided into two tabs, each with a different set of options:

• The Basic tab - set the connection and table to use, starting condition and redirect page.

• The Advanced tab - configure the transaction unique name.

Learn how to complete these options below, for each tab.

The Basic tabOn the Basic tab you can configure most of the logout operation settings, as follows:

1 The Connection, Table and Primary key column are disabled, as they allow only checking if the configuration inside the Login Settings area are correct. If you have not configured them, or would like to change them you can click the Change Login Settings button to load the corresponding user interface.


260

2 In the First check variable drop-down menu select the variable that will start the logout operation. For the reference enter the name of the variable that is being passed to the page.

3 In the After logging out, go to text field enter the path to the page that will load once the user has been logged out. Use the Browse button to select the desired page in the site structure, and the Developer Toolbox Dynamic Data if you need any parameters.

The Advanced tabOn the Advanced tab you have only one setting: the transaction name. If changing this name, please make sure that there are no duplicates on the same page, to prevent conflicts.


261

This server behavior is also added by the Logout Form wizard, and by double-clicking its name in the server behaviors tab you can change the logout settings.

262

Chapter 11: Conditional Operations

This chapter provides information on the server behaviors that ship with Adobe® Dreamweaver® Developer Toolbox and which allow displaying a part (or all) of the content based on different conditions. Depending on the condition you need, there are several server behaviors that you can use, and that will be described in this chapter.


• “Show If Conditional Region” on page 262

• “Show If Field Has Changed” on page 264

• “Show If File Exists” on page 266

• “Show If User Is Logged In” on page 268

Show If Conditional RegionThe purpose of the Show If Conditional Region server behavior is to allow the display of a specific region based on the evaluation of a condition. Before applying it, select a region containing data in Dreamweaver's editable area. If the region is empty, an error message will pop-up requesting to select some data.

You can access this server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Condi-tional Regions > Show If Conditional Region.



263

To set the dialog box options for the first tab:1 Start building your condition by entering its first member in the Expression 1 text box. You can use the lightning bolt icon to select dynamic data to be evaluated.

2 In the Condition drop-down menu select the operator you want. The available options are:

• == - equal: the two parameters have to be equal one to another.

• != - not equal: the two values have to be different one from another.

• < - less: the first value is less than the second one.

• <= - less or equal: the first parameter is less or equal to the second.

• > - greater: the first value is greater than the second.

• >= - greater or equal: the first value is greater or equal than the second.

3 In the Expression 2 text-box enter the second member of the condition. You can use the lightning bolt icon to select dynamic data to be evaluated.

4 The Has ELSE checkbox determines if a second region will be inserted into the page, region that will be displayed if the condition is not met. Checking this option creates a second translator around a bogus "Else text: change this" content. You will have to replace the Else text: replace this with the content that should appear when the specified condition is not met.





These buttons are common to both tabs of the Show If Conditional Region server behavior interface.



264

To set the dialog box options for the second tab:1 In the Expression text area you can see the condition you build in the Basic tab. If you prefer, here you can write the condition without using the expression builder, by typing in the members and the operator. This way more complex conditions can be constructed. It allows an improved flexibility, as there are no more restrictions on the operands.

You can switch between the Advanced and Basic tab as long as the expression in the text area is simple enough to be displayed using the basic elements.

2 In the Name text box enter the name for the conditional region. You can use any name you want, as long as it is unique per page.

3 The Has ELSE checkbox determines if a second region will be inserted into the page, region that will be displayed if the condition is not met. Checking this option creates a second translator around a bogus content (Else text: Replace this).


Dreamweaver will display a translator surrounding the areas to be displayed based on the condition, and will also add a server behavior. If you want to change the condition, simply edit the existing server behavior.

When editing the server behavior, if you check the Has ELSE option, the ELSE region content will be added to the end of the if region content.

Show If Field Has ChangedThe purpose of the Show If Field Has Changed server behavior is to allow the display of a region only when a certain table field changes its value. Before applying it, create a recordset containing the field to be used in the condition, and then select or create the page content that will be displayed when the field changes. If no content is selected, an error message will be displayed when trying to apply the server behavior.

You can access this server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Condi-tional Regions > Show If Field Has Changed.


265


To set the dialog box options for the first tab:1 In the Recordset drop-down menu select the beforehand created recordset that contains the field to act as a condition. By default, the first recordset on page is selected.

2 In the Field drop-down menu select one of the recordset's field that will be the condition. If that field's value will change, then the region will be displayed; if its value does not change, the else region (if any) will be displayed. The first field returned by the recordset will be selected by default.

3 The Has ELSE checkbox creates a new region that is displayed when the field changes. It is similar to the one used in the Show If Conditional Region. If the Has ELSE option has been checked, you will have to replace the Else text: replace this with the content that should appear when the specified condition is not met.





These buttons are common to both tabs of the Show If Field Has Changed server behavior interface.


266


To set the dialog box options for the second tab:1 In the Name text box enter a name for the conditional region. This name must be unique on page. Change the default name only if you are certain that no other element has the same name. If you do not have any special require-ments regarding the region's name, you can skip configuring this tab.

2 The Has ELSE checkbox has the same functionality as the one in the Basic tab (described above), allowing the display of a region if the field does changes.


After applying this server behavior, at least one translator is shown on page: the one surrounding the initial region. If the Has ELSE option has been checked, then a second translator containing a bogus content ("Else text: replace this") will be displayed. Replace this content with the one you want to display.

In order to change the field that acts as the condition, or to add/remove an ELSE region, simply edit the existing Show If Field Has Changed server behavior from the Server Behaviors tab. When removing an ELSE region, its content will be added after the IF region's content.

Show If File ExistsThe purpose of the Show If File Exists server behavior is to display a certain region of content only if a file exists in a certain location. The folder and file name are specified through the user interface. Before applying it, create a recordset containing the table column to be used, and then select a region containing data in Dreamweaver's editable area. If the region is empty, an error message will pop-up requesting to select some data.

You can access this server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Condi-tional Regions > Show If File Exists.


267


To set the dialog box options for the first tab:1 In the File folder text-box enter the location where the file used in the condition is located. You can either type its name, browse for it, or construct its name from dynamic data using mark-ups. Use the Developer Toolbox Dynamic Data lighting bolt icon if using the last option.

2 In the Recordset drop-down menu select a beforehand created recordset containing the field into which is stored the file name. If the file name is not stored in a table field, you can leave this menu on its default value

3 In the Field drop-down menu select from the recordset fields the one that stores the file name. If the file name is not stored in a table field, leave this menu set to None. If you select None: Rename rule, the Renaming rule text box will be enabled.

4 In the Renaming rule text-box enter the name of the file to check, or construct it by pressing the Developer Toolbox Dynamic Data icon and select mark-ups.

5 The Has ELSE checkbox determines whether aside the initial content displayed if the file exists, an alternative region will be created and displayed in case the file does not exist. If the Has ELSE option has been checked, you will have to replace the Else text: replace this with the content that should appear when the file does not exist.





These buttons are common to both tabs of the Show If File Exists server behavior interface.


268


To set the dialog box options for the second tab:1 In the Name text-box enter the region's name, which must be unique on page. Only modify the default, unique name only if you have special needs regarding the region's name. If you do not have any special requirements regarding the region's name, you can skip configuring this tab.

2 The Has ELSE checkbox has the same functionality as the one in the Basic tab, allowing the creation of the alter-native region to be displayed when the file does not exist.


After applying this server behavior, at least one translator is shown on page: the one surrounding the initial region. If the Has ELSE option has been checked, then a second translator containing a bogus content ("ELSE text: Replace this") will be displayed. Replace this bogus content with the one you want to display when the file does not exist.

In order to change the field that acts as the condition, or to add/remove an ELSE region, simply edit the existing Show If File Exists server behavior from the Server Behaviors tab. When removing an ELSE region, its content will be added after the IF region's content.

Show If User Is Logged InThe purpose of this server behavior is to allow the display of a specific region only when a user is logged on, and/or has a certain level of access. Before applying it, select a region containing data in Dreamweaver's editable area. If the region is empty, an error message will pop-up requesting to select some data.

You can access this server behavior from the Application panel, Server Behaviors > + > Developer Toolbox > Condi-tional Regions > Show If User Is Logged In.


269


To set the dialog box options for the first tab:1 In the Restrict based on radio group, decide what to take into account when verifying the user: the username and password only, or also the access level:

• If you only need the Username and password, select the associated radio button.

• If you need the Username, password and access level, select the corresponding radio button in this case.

2 When the second radio button is selected, the Select level(s) list is enabled, allowing the selection of the desired level(s). The values selected here (multiple select is possible) must be matched by the ones in the user's properties, when attempting access, in order to display the selected region.

3 The available levels are configured in the Login settings section of the Developer Toolbox Control Panel. You can access it directly by clicking the Login Settings button (in case you want to make some changes or to view the current settings).

4 If in need of displaying another region when the condition is not met (the user is not logged in, or does not have the proper level), check the Has ELSE option. In this case, you will have to replace the Else text: replace this with the content that should appear when the user is not logged in or does not have the required access level.


• Click OK when you are done configuring the server behavior



These buttons are common to both tabs of the Show If User Is Logged In server behavior interface.


270


To set the dialog box options for the second tab:1 In the Name text-box enter a name for the conditional region; this name must be unique on page. Change the default name only if you are certain that no other element has the same name. If you do not have any special require-ments regarding the region's name, you can skip configuring this tab.

2 The Has ELSE checkbox has the same functionality as the one in the Basic tab, allowing the display of another region if the field does changes.


After applying this server behavior, at least one translator is shown on page: the one surrounding the initial region. If the Has ELSE option has been checked, then a second translator containing a bogus content ("ELSE text: Replace this") will be displayed. Replace this bogus content with the one you want to display when the user is not logged it or does not have the access rights.

In order to add/remove the ELSE region, simply edit the existing Show If User Is Logged In server behavior from the Server Behaviors tab. When removing an ELSE region, its content will be added after the IF region's content.

271

Chapter 12: Send Mail

This chapter provides information about generating and sending e-mail messages in dynamic sites and the benefits that come with it. E-mail messages obviously improve interactivity and drive more people to the web site.

For example, an e-mail message could be sent automatically to require an account validation; it could also notify that somebody has posted a message in a forum, or that a purchase decision needs to be confirmed by the buyer. In all these cases, the e-mail message is usually generated dynamically (filling in some information in an e-mail template) when the site visitors submit a form or click certain links. Adobe® Dreamweaver® Developer Toolbox automates the e-mail sending process, to relieve the developers' and site owners' effort.


• “Send E-mail” on page 271

• “Send E-mail To Recipients From Recordset” on page 276

• “Send Page Section By E-mail” on page 281

Send E-mailThe Send E-mail trigger allows the site developer to automatically send an e-mail when a form is submitted. It is an AFTER trigger, and it can be executed after insert/update/delete/custom transactions.

This trigger is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Send E-mail > Send E-mail.

The user interface is divided into three (or four) tabs, depending on the server model you use. ASP, VBScript, and ColdFusion server models have three tabs; the PHP_mySQL server model has four tabs.

• The Main tab - set the basic e-mail options here: sender, receiver, message and subject.

• The Options tab - set more advanced e-mail options, like format, carbon copies and importance.

• The Attachments tab - available only for the PHP_mySQL server model, allows defining rules for attaching files to a message.

• The Advanced tab - define trigger importance and starting time.

You can learn how to configure each of the interface tab in the sections below.


272

The Basic tabAllows defining the basic e-mail options.

To set the dialog box options for the first tab:1 In the From text box enter the sender's e-mail address (the administrator's address). The default option is the one set in your e-mail settings. If you haven't edited it in the Developer Toolbox Control Panel, then your sender's address is [email protected]. You can use the Developer Toolbox Dynamic Data feature to input dynamic data in the corresponding field. You can also type your message template directly, using the Developer Toolbox mark-up language. Text between braces (such as {text}) that will not be recognized as valid mark-up language, will remain as such, without being replaced by anything and without breaking the application code.

Note: If you used a certain sender in your From field and later on apply the same server behavior, wanting to go back to the default sender, type in the From text box: {KT_defaultSender} (you will notice that your previous choice will be displayed there due to the user interface persistence). Learn more about the Developer Toolbox mark-up language by reading the description given here.

2 In the To text box enter the e-mail address to which you want the message to be sent. You can also input dynamic data in that text box.

3 In the Subject text box type the title/subject that you want the e-mail message to have. The Developer Toolbox Dynamic Data is available here too.


273

4 In the Body drop-down menu select one of the two available options: Write content or Retrieve content from file. Depending on your choice, the last field of the interface will differ:

5 In your configuration, if the Body field is Write content, follow the next instructions:

a In the Content text area type the actual body of the message you want to send. The Developer Toolbox Dynamic Data feature is available for this field. Use it to add data from database fields to the message body.

b The Insert all fields button offers the possibility of inserting all the database columns in the message content with a single mouse click. You can do this also by using the Developer Toolbox Dynamic Data, but you would have to click on each of the columns in order to add them to the message. Precious seconds of your time are saved by using this button when you need to insert all or most of the columns in the message content.

6 In your configuration, if the Body field is Retrieve content from file, follow the next instructions:

7 In the File text box enter the name of the file that you want to send as the e-mail body. You can also use the Browse button to select the file (a template file) that contains the actual message content. If the file is located outside the site root folder, it should be copied to the site folder and uploaded to the remote server, in order to be retrieved by the web application. Dreamweaver prompts you to do this. The file is not sent as an attachment, but constitutes the actual e-mail message body.

The accepted file types are .txt for Text Only messages and .htm, and .html for HTML Text messages.

Note: Any <script> tag will be removed from both Text Only and HTML Text messages. Database field names can be used in the message body by inserting them between braces. In the actual e-mail message, they will be replaced by the corresponding contents from the database. For instance, "Dear {firstname}" will be replaced by "Dear John".



274




These buttons are common to all three tabs of the Send E-mail trigger interface.

9 Click on the Options tab to continue with configuring the trigger.

The Options tabDefine the e-mail format and importance.

To set the dialog box options for the second tab:1 In the Cc text box enter the e-mail addresses to which you want carbon copies of the respective message to be sent (the list of e-mail addresses will be seen by all those who receive the message);

2 In the Bcc text box enter the e-mail addresses to which you want blind carbon copies of the respective message to be sent (the list of e-mail addresses will be invisible to each of those who receive the message).

Note: In the To, Cc, and Bcc fields you can also enter multiple e-mail addresses, separated by commas.

3 The Format radio buttons offer two types of e-mail messages from where you can choose: HTML Text and Text only. The first option is the default one. Text only messages are stripped of all formatting and HTML tags.


275

4 In the Importance drop-down menu select one of the three available options that indicate the message priority: Low, Normal, High. By default, the Normal option is selected. Recipients who use an e-mail client (such as Outlook Express) are able to sort messages by priority.

5 In the Encoding drop-down menu select one of the three encoding types: ISO-8859-1, UTF-8, and None. By default, the ISO-8859-1 option is selected.

The Attachments tabThis tab of the user interface is only available for the PHP_mySQL server model and allows the user to select files that will be sent with the e-mail message as attachments.

To configure the user interface options:1 The Attachments grid displays all of the attachment rules defined for the current server behavior. You can add and remove attachments by using the Plus (+) and Minus (-) buttons on top of the grid. Fill in each rule's options by selecting it in the grid and filling in the fields below.

2 In the Folder field enter the relative path to the folder storing the file(s) you wish to send. You can use the Browse button to select the folder from the site structure. The path to the folder will be displayed relative to the current document.

3 In the Field drop-down menu select which of the transaction field stores the file name. If not using a recordset, or using a custom naming, select the None: Rename rule option.


276

4 In the Renaming rule text field enter the name of the file to attach. This field is enabled only when using the Rename rule option, and allows you to enter static and dynamic data which will compose the name of the file. You can either enter Developer Toolbox mark-up directly or use the Developer Toolbox Dynamic Data icon to visually select it.

The Advanced tabOn the last and optional tab of the user interface, configure the trigger properties: transaction to attach to, priority and when to execute it.

For instructions on completing this step, see the Advanced tab.

Send E-mail To Recipients From RecordsetThis trigger allows the site developer to send an e-mail message to multiple recipients when a form is submitted. By recipients, we understand the contacts (people, departments, companies) the site developer has, contacts whose e-mail addresses are stored in the database. The table column that contains the e-mail addresses will have to be included in a recordset before applying this trigger (thus the name of the trigger).

Note: The Send E-mail To Recipients From Recordset server behavior should not be used with large numbers of recip-ients, because you will not have perfect control over the mailing queue. Depending on your mail server configuration, the execution time might expire, if your mailing queue is very long.


277

Send E-mail To Recipients From Recordset is an AFTER trigger, and it requires the existence of an insert/update/delete/custom transaction and of a previously created recordset.

This trigger is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Send E-mail > Send E-mail To Recipients From Recordset.

The user interface is divided into three (or four) tabs, depending on the server model you use. ASP, VBScript, and ColdFusion server models have three tabs; the PHP_mySQL server model has four tabs.

• The Main tab - set the basic e-mail options here: sender, receiver, message and subject.

• The Options tab - set more advanced e-mail options, like format, carbon copies and importance.

• The Attachments tab - available only for the PHP_mySQL server model, allows defining rules for attaching files to a message.

• The Advanced tab - define trigger importance and starting time.

You can learn how to configure each of the interface tab in the sections below.

The Basic tabAllows defining the basic e-mail options.


278

To set the dialog box options for the first tab:1 In the Recordset drop-down menu select the recordset that you had previously created (and that contains the database table column which stores the e-mail addresses).

2 In the E-mail to field drop-down menu select the field that contains the e-mail addresses of the recipients to whom you will send an e-mail message.

3 In the From text box enter the administrator's/sender's e-mail address. The default option is the one set in your e-mail settings. If you haven't edited it in the Developer Toolbox Control Panel, then your sender's address is [email protected]. You can add dynamic data in the text box by using the Developer Toolbox Dynamic Data feature.


4 In the Subject text box type the title or subject of the e-mail message. This text box also benefits from the Developer Toolbox Dynamic Data facility.

5 In the Body drop-down menu select one of the two available options: Write content or Retrieve content from file. Depending on your choice, the last field of the interface will present differences. To see how to configure this last field, see the Content or File fields.





These buttons are common to all three tabs of the Send E-mail To Recipients From Recordset trigger interface.

7 Click on the Options tab to continue configuring the trigger.


279

The Options tabDefine the e-mail format, carbon and blind carbon copies and importance.

For instructions on completing this step, see “The Options tab” on page 274.


280

The Attachments tabThis tab of the user interface is only available for PHP_MySQL server models and allows the user to select files that will be sent with the e-mail message as attachments.

Configure the user interface options as shown below:1 The Attachments grid displays all of the attachment rules defined for the current server behavior. You can add and remove attachments by using the Plus (+) and Minus (-) buttons on top of the grid. Fill in each rule's options by selecting it in the grid and filling in the fields below.


3 In the Field drop-down menu select which of the transaction fields stores the file name. If not using a recordset, or using a custom naming, select the None: Rename rule option.



281

The Advanced tabOn the last and optional tab of the user interface, configure the trigger properties: transaction to attach to, priority and when to execute it.

For instructions on completing this step, see the Advanced tab.

Send Page Section By E-mailThis server behavior allows the site developer to send a page section (after previously selecting the section) by e-mail and then redirect to another URL.

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Send E-mail > Send Page Section By E-mail.


282

The user interface is divided into two or three tabs, depending on the server model you use. ASP, VBScript, and ColdFusion server models have three tabs; the PHP_mySQL server model has four tabs. Directions about their correct configuration are given below.

To set the dialog box options for this tab:1 In the From text box enter the administrator's/sender's e-mail address. The default option is the one set in your e-mail settings. If you haven't edited it in the Developer Toolbox Control Panel, then your sender's address is [email protected]. You can use the Developer Toolbox Dynamic Data feature to input dynamic data in the corre-sponding field.


2 In the To text box enter the e-mail address to which you want the message sent. You can also input dynamic data in that text box.

3 In the Subject text box type the title or subject of the e-mail message. Once again, the Developer Toolbox Dynamic Data feature is available for you.

4 In the Redirect to page text box enter the page to be opened after the message is sent or click the Browse button to select a page.





These buttons are common to both tabs of the Send Page Section By E-mail server behavior interface.


283

6 Click on the Options tab to continue with configuring the server behavior.

For instructions on completing this step, see “The Options tab” on page 274.


284

The Attachments tabThis third tab is available only for the PHP_mySQL server model. It allows you to define what files to send together with the e-mail message.

To configure the user interface options:1 The Attachments grid displays all of the attachment rules defined for the current server behavior. You can add and remove attachments by using the Plus (+) and Minus (-) buttons on top of the grid. Fill in each rule's options by selecting it in the grid and filling in the fields below.


3 In the Recordset drop-down menu select the page recordset to use to retrieve the file name.

4 In the Field drop-down menu select which of the recordset field stores the file name. If not using a recordset, or using a custom naming, select the None: Rename rule option.


285

Chapter 13: Reuse content with server-side includes

This chapter provides information on another Adobe® Dreamweaver® Developer Toolbox bundle: Server-Side Includes. Through its server behaviors, Server-Side Includes offers an easy way of including reusable code blocks in Dreamweaver. It is very important to know that the code from the included file is not duplicated in the file that includes it. The code, automatically generated in the file where the server behaviors are applied, simply refers/calls on the included file.

By using Server-Side Includes you can:

• include one file from your site in another by simply selecting the file to be included.

• include files depending on the value of an URL parameter by either 1) retrieving the necessary data (URL parameter value, file name, page title, meta keywords, meta description) from a database table that stores it or 2) manually typing the elements mentioned above and creating a list of files with the appropriate information.

When file A is included in file B, and the B Dreamweaver page is previewed in the browser, the content of file A is displayed in the spot of file B where the server behavior was applied. If the case, depending on the value of the URL parameter passed, the content of different files can be displayed in that spot from file B.


• “Server-side Include” on page 285

• “Server-side Includes From Table” on page 286

• “Server-side Includes From List” on page 289

Server-side IncludeThe Server-Side Include server behavior allows the site developer to include a file in the current Dreamweaver page. The file to be included can be modified later, the new modifications being seen in the page where this server behavior is applied.

This feature is useful when you have to include the same elements in multiple pages. You can do this in one operation now instead of repeating the same steps over and over again for each page.


286

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Server-Side Includes > Server-Side Include. The user interface has one tab:

To set the dialog box options:1 In the Filename text box enter the file to be included in the current Dreamweaver page. You can click the Browse button to select the file. Choose a file from the site structure so there won't be any problems when you publish the site. If you want to include a file outside the site structure, you should copy it somewhere in the root folder and then upload it onto the server.





Server-side Includes From TableWith the Server-Side Includes From Table server behavior your dynamically included content can be retrieved from a database table, which stores the following data:

• the values for the URL parameter passed.

• the names of the files to be included in the page where the server behavior is applied.

• the title of the page in browser when a certain included file is loaded (the title is displayed on the bar).

• the meta keywords that characterize the content of the respective included file and that will be listed in the HTML meta keyword tag.

• the meta description of the included file which will be presented in the HTML meta description tag.


287

The meta keywords and the meta description contribute significantly to the Search Engine Optimization, helping with the Google ranking. When surfing the web looking for specific pages, the search engine will use the keywords of a page to generate the results. The results list will contain the meta description of the pages found.

Here is an example of how these HTML tags look like (<meta> tags are included within the <head> tag along with the <title> tag):

<meta name="keywords" content="dreamweaver extensions, web development, dynamic website" /> <meta name="description" content="Dreamweaver Extensions for Dynamic Web Sites." />

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Server-Side Includes > Server-Side Includes From Table. The user interface has two tabs:

To set the dialog box options for the first tab:1 In the Connection drop-down menu select the database connection defined for your site. If you don't have a connection yet, you can use the Define button and create one now.

2 In the Table drop-down menu select the database table that contains the information needed when dynamically including files in the current page.

3 In the URL parameter value drop-down menu select the table column that stores the URL parameter values.

Note: If a table record has in the URL_pag column (where the URL parameter values are stored) no value entered, then the associated file will be loaded by default in browser.

Note: If a table record has in the URL_pag column (where the URL parameter values are stored) the value 404, then the associated file will be automatically loaded when a page cannot be found (e.g. due to a missing page, or a wrong URL parameter value).

4 In the Filename drop-down menu select the table column that stores the names of the files to be included (called, referred).


288

5 In the Page title drop-down menu select the table column that stores the titles of the pages in browser (what goes in the HTML <title> tag).

6 In the Meta keywords drop-down menu select the table column that contains the meta keywords for the included file.

7 In the Meta description drop-down menu select the table column that contains the meta description for the included file.





These buttons are common to both tabs of the Server-Side Includes From Table server behavior interface.

9 Click on the Parameter tab to continue configuring the server behavior.

To set the dialog box options for the second tab:1 In the URL parameter name text box enter the name of the URL parameter that you are going to use in your site pages. The default name given is mod.


Before being able to see this server behavior at work, there are several things that need to be done in your current Dreamweaver page (let's consider this page being named includes.php):

• For each URL parameter value, create a link in page that would point to the page itself (simply write down a word/text, select it, right-click on it, and Make Link).


289

• Make sure the link passes the URL parameter specified in the Advanced tab (mod), with the value specified in the corresponding database table (URL_pag, in our case). When clicking on this created link in the Dreamweaver page, the Property Inspector should look like this:

In browser, when clicking on this link, the file corresponding to the URL parameter value (article) will be included in your current page.

Note: If you applied the Server-Side Includes From Table server behavior in your page, you cannot apply it again in the same page, and you cannot apply Server-Side Includes From List either.

If you want to use nice URL's for your included files, there are three things you should do:

• Make sure that in your database table, the URL parameter values are stored like this: "/value" (having a slash before the actual value).

• In the Parameter tab, remove the URL parameter name.

• For each of the links through which files are included in your current page, replace in the Property Inspector the "?mod=" with a slash (/).

For more details about the nice URL's and how they can be obtained, read the similar paragraphs in Server-Side Includes From List.

Server-side Includes From ListThe Server-Side Includes From List server behavior allows the site developer to include files in the current Dream-weaver page, files that are individually specified in a list. Besides the filename, some additional information is necessary (and manually specified):

• the values for the URL parameter passed, and corresponding to each value - the file to be included.

• the title of the page in browser when a certain included file is loaded (the title is displayed on the bar).

• the meta keywords that characterize the content of the respective included file.

• the meta description of the file.

Note: Read more about meta keywords and meta description and see an example here.


290

This server behavior is accessible from the Application panel, Server Behaviors > + > Developer Toolbox > Server-Side Includes > Server-Side Includes From List. The user interface has two tabs:

To set the dialog box options for the first tab:1 In the Include files grid, you can list the URL parameter values and the files they point to. You can add or remove elements by clicking on the Plus (+) and Minus (-) buttons on top of the grid. Also, you can change the order in which elements are displayed by pressing the Up (^) and Down (v) buttons. For each element of this list, you have to provide the information mentioned below.

2 In the URL value text box enter the value for the URL parameter passed.

Note: If you choose to enter no value in the URL value text box, then the associated file will be the one loaded by default in browser.

Note: If you enter the value 404 for the URL parameter value, then the associated file will be automatically loaded when a page cannot be found (e.g. due to a missing page, or a wrong URL parameter value).

3 In the Filename text box enter the file to be included in the current Dreamweaver page. You can click the Browse button to select the file. Choose a file from the site structure so there won't be any problems when you publish the site. If you want to include a file outside the site structure, you should copy it somewhere in the root folder and then upload it onto the server.

4 In the Page title text box enter the title that you want to be displayed in the browser bar.

5 In the Meta keywords text box enter the meta keywords of the included file.

6 In the Meta description text box enter the meta description of the included file.



291




These buttons are common to both tabs of the Server-Side Includes From List server behavior interface.

8 Click on the Parameter tab to continue configuring the server behavior.

To set the dialog box options for the second tab, follow the next steps:

9 In the URL parameter name text box enter the name of the URL parameter that you are going to use in your site pages. The default name given is mod.


Before being able to see this server behavior at work, there are several things that need to be done in your current Dreamweaver page (let's consider this page being named includes.php):

• Create a link in page that would point to the page itself (simply write down a word/text, select it, right-click on it, and Make Link).

• Make sure the link passes the URL parameter specified in the Advanced tab (mod), with the value specified in the Basic tab (product). When clicking on this created link in the Dreamweaver page, the Property Inspector should look like this:


292

In browser, when clicking on this link, the included file (product.php) will be loaded in your current page.

Note: If you applied the Server-Side Includes From List server behavior in your page, you cannot apply it again in the same page, and you cannot apply Server-Side Includes From Table either.

Using friendly URL's"Friendly" URL's can increase your site's ranking on various search engines. With the new Server-Side Includes, you can customize the URL's displayed in the address bar of your site, transforming them into "friendly" URL's. For example, with the configuration above, when the product.php file is loaded, the URL is:

http://your_server/your_folder_hierarchy/your_site/includes.php?mod=product.

However, this URL will receive a poor ranking on search engines such as Google, because the address contains parameters. Instead, you could turn the above URL into something easier to read:

http://your_server/your_folder_hierarchy/your_site/includes.php/product

With the new Server-Side Includes (only on Apache), URL's for the included files can be rewritten to become Google friendly.

Note: In order to use friendly URL's, PHP must be compiled as an Apache module. When PHP runs as CGI, friendly URL's cannot be used.

If you want to turn it into a 'nicer' URL:1 In the Basic tab, add a slash (/) before the URL value (product) in the corresponding interface field:


293

2 In the Advanced tab, delete the name of the URL parameter, leaving the text box blank:

3 Select the link that when clicked, uploads the included file, and in the Property Inspector, replace the “?mod=” with a slash (/):

4 If you preview the page in browser and click on the link, you will notice the nice URL being displayed in the address bar:

http://your_server/your_folder_hierarchy/your_site/includes.php/product

Set correct redirect pages when using includesWhen using Developer Toolbox's Insert, Update or Delete standalone transactions with Server-Side Includes, you must configure the page set to load after the transaction completes correctly.

Server-Side Includes redirects must be set relative to the master page - the one that includes the others, and not to the individual transactions. This means that if you have insert, update or delete transactions applied on different pages saved inside the pages subfolder of the site, and the master page is the index in the site root, in the After inserting, go to fields for the redirect you must enter index.php?mod=. You must not use ../index.php?mod= as it will actually point outside of the current site root.

When creating included pages using Dynamic Lists and Forms you do not need to specify the path relative to the master document as it will be automatically translated by the includes behavior.

294

Chapter 14: CSS Skins

Almost all of Adobe® Dreamweaver® Developer Toolbox generated elements can be customized to fit the look of your site, by simply changing the CSS Skin that’s applied to them. You can use one of the pre-designed skins, or simply create one of your own.

Note: All modifications you make to default skins will be lost when you update the “includes” folder using the Update Includes Folder feature from the Developer Toolbox Control Panel. Therefore, if you want to make modifications to an existing skin, duplicate it and make your changes to the copied version. Follow the same steps as the ones for creating a new skin (detailed below).

This chapter contains instructions on:

• “Create your own skin” on page 294

Create your own skinAlthough Developer Toolbox ships with a variety of skins, with versions for both link and button-style links, to achieve complete integration with the particular look of your site, a custom skin will have to be created.

Before starting to create a new skin, here are some the things you should know:

All skins are stored in the includes > skins folder

Each skin is a folder, containing the following elements:

• The images folder - this is where all images used in the CSS must be placed:

• A preview.gif picture - this is the picture that is displayed in Developer Toolbox Control Panel > CSS Skins. This should be representative for the skin, to ease selection.

• The nav.css file - this file stores the CSS settings for the navigation pack elements

• The nxt.css file - this stores CSS settings for the Dynamic Lisst and Forms.

• The tng.css file - this stores CSS settings regarding transaction engine elements that can use skins

• The wdg.css file - this stores CSS settings for the form controls (widgets).

Besides the files in this folder, in the skins root, you can find the following files:

• common.css - this file stores common CSS settings for all skins

• style.js - this is a JavaScript library, controlling the effects and transformations. Edit this file only if you have solid JavaScript knowledge.


295

• mxkollection3.css - this stores only references to the current skin. When a new skin is selected in the Control Panel, references inside this file are changed, and it has to be uploaded to the remote server.

Creating a skin requires CSS manipulation, therefore, basic knowledge about CSS concepts is recommended. To start learning about CSS, read this W3C CSS Primer.

To create a new skin:1 Copy an existing skin's folder into the skins directory. Rename the new folder to the skin's desired name.

2 Replace the preview.gif image with the new skin's preview. You must create this image using a photo editing software of your choice. The maximum size for the image is 100x200 [height/width]

3 You also need to replace all of the files in the images folder with the files you have created for the new one. If you use the same file names for the same elements, you will not have to edit the CSS file in order to replace the names. Otherwise, open each CSS file in the folder to search and replace the image file's names.

4 Edit the CSS files and adjust the properties for each desired CSS selector. Save each edited file.

5 Open a page of the site you need customized. Go to Developer Toolbox Control Panel > CSS Skins and select your now skin in the drop-down menu. Click OK to apply the skin.

6 Save the page and upload the includes/skins folder to the remote server. Now browse the site, and the new skin should be in effect.

Note: Due to different implementation of the CSS Standard on the various browsers available, some of the CSS options might only be correctly rendered on some of the browsers, while on some the result can be null or even damaging to the design. Therefore, when creating your own custom skin, and altering the CSS file to suit your particular needs, be careful of the used options, and the different rendering of the CSS on different browsers.

296

Chapter 15: Export Recordset As XML

XML Export is an extension for Adobe® Dreamweaver® CS3 that lets you export the content of a recordset as XML. The XML can then be consumed by pages that use XML data sources, such as pages with Spry data sets.

This server behavior is also available when you install Adobe® Dreamweaver® Developer Toolbox.

This document contains the following topics:

• “About the XML Export extension” on page 296

• “Exporting a recordset as XML” on page 297

About the XML Export extension

Install the XML Export extensionNote: If you’ve installed Developer Toolbox, the XML Export server behavior is already included with the other Developer Toolbox server behaviors. You do not need to install it as a separate extension.

1 Make sure Dreamweaver CS3 and Adobe® Extension Manager CS3 are installed on your system.

2 Double-click the .mxp extension file in Windows Explorer (Windows) or in the Finder (Macintosh).

3 Follow the onscreen instructions to install the extension.

4 After you’re done, restart Dreamweaver.

XML Export extension overviewThe XML Export extension adds a server behavior to Dreamweaver called Export Recordset As XML. The server behavior adds XML export logic to a dynamic page that contains a recordset. When the page is requested by another page in a web browser, the logic converts the recordset data to XML and writes the XML in the page. The web server then sends the page to the requesting page, which typically consumes the XML. For example, if you have a page that defines a PHP recordset, you can create a page with a Spry data set that requests the PHP recordset page and consumes the resulting XML.

System requirementsTo use the XML Export extension, the following software must be installed and properly configured:

• Dreamweaver CS3

• Extension Manager CS3

• One of the following web servers: Microsoft Internet Information Server 5.1 (Windows XP Professional) or 6.0 (Windows 2003), Apache 1.3.x or 2.0, or the built-in web server in ColdFusion® 6.0 or later

• One of the following application servers: PHP 4.4.0 or later, ColdFusion 6.0 or later, ASP 5.5 or later

• If using PHP , the mbstring library must installed and enabled. This library handles multibyte encodings in PHP.


297

• If using ColdFusion, make sure the CreateObject function is enabled. You can enable and disable this function using the ColdFusion Administrator. In ColdFusion MX7, for example, open the Sandbox Security page, click the Edit icon next to your application’s server directory (ColdFusion security must be enabled to see it), and click the CF Functions tab.

CompatibilityThe XML Export extension works with Dreamweaver CS3. It is not compatible with previous versions of Dream-weaver.

The extension is compatible with the following server models:

• PHP - MySQL

• ColdFusion

• ASP (VBScript)

Exporting a recordset as XML

Adding XML export logic to the recordset page Before creating and consuming XML based on a recordset, you must add logic to the recordset page that exports the recordset data to XML. You can add the logic by using the Export Recordset As XML server behavior installed by the XML Export extension.

1 Make sure your site is defined correctly in Dreamweaver.

You must define a valid PHP, ColdFusion, or ASP (VBScript) testing server for your site in Dreamweaver. You must also have a working database connection.

2 Open the PHP, ColdFusion, or ASP page that contains the recordset you want to export.

You can create a blank dynamic page and define a recordset for it. For instructions, see Dreamweaver help.

3 In the Server Behaviors panel, click the Plus (+) button and select Developer Toolbox > Export Recordset As XML.

The Export Recordset As XML dialog box appears.

You can also open this dialog box from the Developer Toolbox category of the Insert bar.

4 Complete the dialog box and click OK to add logic to the page that performs the export operation.

For instructions, see “Basic options of the Export Recordset as XML dialog box” on page 297 and “Advanced options of the Export Recordset as XML dialog box” on page 298.

5 Upload the folder called includes/XMLExport to your server.

6 Upload the page to your server.

The recordset data is exported to XML when the page is requested by a web browser. Typically, a separate web page requests the page and consumes the XML directly. For more information, see “Consuming the XML” on page 299.

Basic options of the Export Recordset as XML dialog boxUse the basic options to set the required options.


298

Recordset lets you select the recordset that contains the data to export to an XML file. If the current page does not have a recordset, cancel the server behavior and define one for it first.

Columns lets you see all the recordset columns that will be exported as XML. Use the Plus (+) and Minus (-) buttons to add or remove columns to be exported.

XML Node/Attribute lets you specify another name for the exported XML element for the selected column. Enter only alphanumerical characters. Also, the name cannot start with a digit.

The following is an example of the dialog box with some basic options set.

Advanced options of the Export Recordset as XML dialog boxUse the advanced options to define additional export options.

Export Columns As lets you select the XML property that will hold the field information. You have two options: Nodes and Attributes. If you select Nodes, each record field will have a corresponding XML node (tag). If you select Attributes, each field will be set as an attribute for the current node.

Export All Records lets you determine whether to export all records in the recordset or not. If checked, all the records will be exported.

Number of Records lets you specify how many records retrieved by the recordset to export in XML format. This option is only enabled when the Export All Records option is unchecked.

Root Node lets you specify the name of the root XML node. The default name is export.

Row Node lets you specify the name of the row node. The default name is row.

XML Encoding lets you select the encoding method used when exporting the recordset in XML format. You must specify the same encoding as the database. You can also enter an encoding if it’s not listed in the popup menu. If you use a different encoding for the XML file, you will not get an error and information will be exported as is, without any conversion. The XML encoding you specify will be set for the file (in the XML header), but not used in any manner.


299

The following is an example of the Advanced tab.

Consuming the XMLAfter adding the XML export logic to your recordset page, you can specify the recordset page as an XML data source in another page. When the recordset page is requested by a page in a browser, the contents of the recordset page is replaced by pure XML and then the page is sent to the requesting page. The requesting page can then consume the XML directly.


300

For example, suppose you define a ColdFusion recordset in a page called bookdata.cfm and then add the XML export logic to the page. In a separate page, you can define a Spry data set that retrieves the ColdFusion page and consumes the XML. To do so, specify the ColdFusion file, bookdata.cfm, as the XML source of the Spry data set, as follows:

If your recordset data is not likely to change, you can open the recordset page in a web browser, save it as an XML file, and store it on your server for re-use. With this approach, the server does not have to process the recordset page every time a web page requests the XML data. For example, you might have a lookup table of country names that you want to regularly consume as XML.

1 In a web browser, request the recordset page by entering its URL directly in the Address text box.

When the browser displays the page, its contents now consist entirely of XML.

2 Use the browser’s Save As command to save the file as an XML file to your hard disk, and then upload the file to your server so that it can be consumed by other pages.

301

Chapter 16: Custom transactions and triggers

In this chapter you will find examples and instructions that will help you understand how to build custom actions and integrate them into the Adobe® Dreamweaver® Developer Toolbox action flow. You will learn how to use Custom Triggers to execute custom actions that are associated to a transaction on a page.


• “Execute SQL queries” on page 301

• “Use transaction fields” on page 304

• “Add and set transaction fields” on page 305

• “Check unique key for multiple fields” on page 307

• “Save additional information on login” on page 309

Execute SQL queriesIn addition to having the transaction on page execute some kind of SQL query, you may need to execute another on a different table, or on the same table to either insert a related record, to update a field or even delete a record. You can achieve this by using a custom trigger that runs the SQL query using tNG methods. Using the tNG offered functions and methods for working with SQL queries will ensure that if you ever want to change the database or other component, your code will still work.

Before adding a Custom Trigger that executes an SQL query, you must meet the following prerequisites:

1 Have Developer Toolbox correctly installed.

2 Have a page with a transaction applied on it - this can be an insert, update, delete, login, register, custom or any other of the supported transactions.

3 Have basic knowledge of the application server language you intend to use - you will have to customize the examples below for your particular situation.

After creating the basic application page which contains a transaction, you must apply the Custom Trigger server behavior. This allows you to enter code that will get executed in the transaction's context. Through the Custom Trigger properties you can define the execution order. You can learn more about the Custom Trigger server behavior here.

You can use Developer Toolbox methods to run the query, escape values for use with SQL and even handle errors. This will mean that your triggers will still work if you change the database type or other underlying setting. Some of the methods you can use when creating a custom trigger that executes SQL:

• tNG>connection>execute("query") - this executes the actual query

• KT_escapeForSql("value","type") - in order to use a value within a sql query and not get an error you must escape it properly. This function properly encloses values based on type and the database type used.

• tNG>getColumnType("column_name") - this allows retrieving the type of a column.


302

The basic code for a custom trigger that will execute an sql query is as follows:1 First define the query to run. You should assign the query to a string variable for ease of use. You can create any type of query, no matter how complex.

query = "SELECT [column_list | *] FROM [table_name]"

2 Run the query using the tNG>connection>Execute method, and assign its result to a variable:result = tNG>connection>Execute(query)

3 The Custom Trigger must return a value:

return RET

Note: Do not copy and paste code from the fragment above, as it will cause errors. Instead use some of the examples below.

In addition to this basic structure that allows you to run a query, you can also use the tNG error object to handle the case when the query execution failed.

To do so, you must:1 Check if the query execution result (the variable to which it was assigned) contains the expected results:

if (result = FALSE)

2 Next create a new instance of the error object, and initialize it with the desired error message:

query_error = new tNG_error ("The query has failed error message here), array(), array())

3 Next you have to exit the custom trigger and return the new error object to the dispatcher:

return query_error

4 For the case when everything goes smoothly, you have to return NULL. Create an else branch and add the return NULL instruction:

else

return Null

Examples The following examples show you how to build a post message page. When posting a new message, aside the regular information you have to enter in the form fields, an additional field has to be set after the insert operation: the id_init_msg field must be set to the same value as the new message ID. The custom trigger that is executed after the insert transaction performs an update on the last record and sets the correct values through an update transaction.

For PHP:

$query = "UPDATE message_msg SET id_init_msg = ".KT_escapeForSql($tNG>getPrimaryKeyValue(), $tNG>getColumnType($tNG>getPrimaryKey()))." WHERE id_msg = ".$tNG>getPrimaryKeyValue(); $update_result = $tNG>connection>execute($query); if(!$update_result) { $updateError = new tNG_error("Error setting the initial message ID",array(),array()); return $updateError; } else { return NULL; }


303

For ASP:

query = "UPDATE message_msg SET id_init_msg = " & KT_escapeForSql(tNG.getPrimaryKeyValue(),tNG.getColumnType("id_msg")) & " WHERE id_msg = " & tNG.getPrimaryKeyValue() On Error Resume Next Set update_result = tNG.connection.Execute(query) if Err.Number <> 0 then Set updateError = new tNG_error update_error.init "Error setting the initial message ID", Array(), Array() Set Trigger_Custom = updateError else Set Trigger_Custom = nothing end if On Error GoTo 0

For ColdFusion:

You must use a different approach because you are not allowed to execute queries within <cfscript> tags. And a Custom Trigger is contained within <cfscript> tags. To still be able to use triggers that execute SQL queries, you must add a separate function within the page code that takes care of the sql related operations - let's say named AliasCus-tomTrigger, and in the trigger's code box only enter code to return the function's value: return Request.AliasCus-tomTrigger. The same objects and Developer Toolbox functions can be used within the function to prepare the query and handle errors. The code sample below shows the function and the custom trigger code used to call it:

<cffunction name="AliasCustomTrigger"> <cfargument name="tNG" required="true"> <cfset var query = ""> <cfset var result = ""> <cfset var myerror = ""> <cfset query = "UPDATE message_msg SET id_init_msg = " & tNG.getPrimaryKeyValue() & " WHERE id_msg = " & tNG.getPrimaryKeyValue()> <cflock name="ins_message_msg" type="exclusive" timeout="10"> <cftry> <cfquery name="result" datasource="#tNG.connection#"> #PreserveSingleQuotes(query)# </cfquery> <cfcatch> <cfset updateError= Request.tNG_CreateObject("tNG_error")> <cfset updateError.init ("Error setting the initial message ID", ArrayNew(1), ArrayNew(1))> </cfcatch> </cftry> </cflock> <cfif IsObject(updateError)> <cfreturn updateError> <cfelse> <cfreturn Request.KT_Null> </cfif> </cffunction> <cfset Request.AliasCustomTrigger = AliasCustomTrigger>


304

<cfscript> //start Trigger_Custom trigger function Trigger_Custom(tNG) { return Request.AliasCustomTrigger(tNG); } Request.Trigger_Custom = Trigger_Custom; //end Trigger_Custom trigger </cfscript>

In the next section you will learn how to use fields in a transaction for a custom action.

Use transaction fieldsCustom trigger code can access the columns of the transaction to which it is registered through the following methods of the tNG class:

• getPrimaryKeyValue() - returns the value of the primary key of the record modified by the transaction

• getColumnValue("column_name") - returns the value of the column. You must specify the name as it is used in the transaction.

• getColumnType("column_name") - returns the type of the specified column.

You can use these methods to retrieve column value and use them for any processing - either before or after the trans-action. Note that the primary key value can only be used in an after trigger, as it gets initialized only after the trans-action has completed.

Example: the following example shows you how you can build post message page. When posting a new message, aside the regular information you have to enter in the form fields, an additional field has to be set after the insert operation: the id_init_msg field must be set to the same value as the new message ID. The custom trigger that is executed after the insert transaction performs an update on the last record and sets the correct values through an update transaction.

For PHP:$query = "UPDATE message_msg SET id_init_msg = ".KT_escapeForSql($tNG>getPrimaryKeyValue(), $tNG>getColumnType($tNG>getPrimaryKey()))." WHERE id_msg = ".$tNG>getPrimaryKeyValue(); $update_result = $tNG>connection>execute($query); if(!$update_result) { $updateError = new tNG_error("Error setting the initial message ID",array(),array()); return $updateError; } else { return NULL; }

For ASPquery = "UPDATE message_msg SET id_init_msg = " & KT_escapeForSql(tNG.getPrimaryKeyValue(),tNG.getColumnType("id_msg")) & " WHERE id_msg = " & tNG.getPrimaryKeyValue() On Error Resume Next Set update_result = tNG.connection.Execute(query) if Err.Number <> 0 then Set update_error = new tNG_error


305

update_error.init "Error setting the initial message ID", Array(), Array() Set Trigger_Custom = update_error else Set Trigger_Custom = nothing end if On Error GoTo 0

For ColdFusion:Because the code sample below needs to execute a SQL query, the functions are used within the function that resolves this. See the Execute sql queries topic for more details.

<cffunction name="AliasCustomTrigger"> <cfargument name="tNG" required="true"> <cfset var query = ""> <cfset var result = ""> <cfset var myerror = ""> <cfset query = "UPDATE message_msg SET id_init_msg = " & tNG.getPrimaryKeyValue() & " WHERE id_msg = " & tNG.getPrimaryKeyValue()> <cflock name="ins_message_msg" type="exclusive" timeout="10"> <cftry> <cfquery name="result" datasource="#tNG.connection#"> #PreserveSingleQuotes(query)# </cfquery> <cfcatch> <cfset updateError= Request.tNG_CreateObject("tNG_error")> <cfset updateError.init ("Error setting the initial message ID", ArrayNew(1), ArrayNew(1))> </cfcatch> </cftry> </cflock> <cfif IsObject(updateError)> <cfreturn updateError> <cfelse> <cfreturn Request.KT_Null> </cfif> </cffunction> <cfset Request.AliasCustomTrigger = AliasCustomTrigger> <cfscript> //start Trigger_Custom trigger function Trigger_Custom(tNG) { return Request.AliasCustomTrigger(tNG); } Request.Trigger_Custom = Trigger_Custom; //end Trigger_Custom trigger </cfscript>

In the next section you will learn how to modify the value of fields involved in a transaction.

Add and set transaction fieldsUsing Custom Triggers you can add new fields to a transaction, or set the value for a transaction field. You can use any language feature you need to compute the value of a transaction field, or securely add one.


306

There are two methods of the tNG object that allow adding and setting the value of a transaction fields:

• addColumn - allows adding a column to the transaction

• setColumnValue - allows setting the value for a specific column

Triggers that modify a transaction columns must be of type BEFORE, in order for the changes to be considered when executing the transaction.

The basic structure of such a trigger is as follows:

• to add a new transaction field:

value = myvalue //code that computes the actual column value tNG>addColumn(column_name, type, value, "")

• to set the value of a transaction field:

value = myvalue //code that computes the actual column value tNG>setColumnValue(column_name, value)

The examples below show you how you can enhance a posting page.

The first example assumes that the subject field has been left out of the insert transaction, and it is automatically set to the first 30 characters of the message. The Custom Trigger is of type BEFORE, and the code is as follows:

For PHP:$newSubject = substr($tNG>getColumnValue("content_msg"),0,30); $tNG>addColumn("subject_msg","STRING_TYPE","VALUE",$newSubject);

For ASP_VBScript:newsubject = left(tNG.getColumnValue("content_msg"),30) tNG.addColumn "subject_msg", "STRING_TYPE", "VALUE", newsubject, ""

For ColdFusion:subjectValue = left(tNG.getColumnValue("content_msg"),30); tNG.addColumn("subject_value","STRING_TYPE","VALUE",subjectValue,"");

In the following example, the subject field is displayed on the page as a text field, but it is not mandatory to be filled. A BEFORE custom trigger checks if the user entered anything, and if not, it sets the column value to the first 30 letters of the content field:

For PHP:if($tNG>getColumnValue("subject_msg") == "") { $newSubject = substr($tNG>getColumnValue("content_msg"),0,30); $tNG>setColumnValue("subject_msg",$newSubject); }

For ASP_VBScript:If(tNG.getColumnValue("subject_msg") = "") Then newsubject = left(tNG.getColumnValue("content_msg"),30) tNG.addColumn "subject_msg", "STRING_TYPE", "VALUE", newsubject, "" End If


307

For ColdFusion:if(tNG.getColumnValue("subject_msg") EQ "") { subjectValue = left(tNG.getColumnValue("content_msg"),30); tNG.addColumn("subject_msg","STRING_TYPE","VALUE",subjectValue,""); }

In the following topic you will learn how to create a custom trigger that performs a check for a unique value on more than one field.

Check unique key for multiple fieldsDeveloper Toolbox provides a trigger as a server behavior that allows checking if the value in a transaction field already exists in the table, and stop the insert operation if true. This is useful when trying to prevent duplicate records - e.g. when registering user accounts. But in order to check multiple fields you have to build your own custom trigger. In the example below, a custom trigger is built to prevent posting duplicate messages - which have the same subject and content.

The trigger retrieves the values of the subject and content fields from the transaction and uses them to build a select query. If the query yields any results, then the message is a duplicate and the transaction is stopped. The trigger uses only the methods explained for the Execute sql queries and Use transaction fields sections, and the basic structure is as follows:

//first retrieve the transaction fields' values and store them in local variables, for convenience subject = tNG.getColumnValue("subject_field") content = tNG.getColumnValue("content_field");

//next use the two values to build the query query = "SELECT * FROM [message_table] WHERE subject_field = ".KT_escapeForSql(subject ,"STRING_TYPE")." AND content_field = ".KT_escapeForSql(content ,"STRING_TYPE")

//run the query and retrieve the result into a variable result = tNG.connection.execute(query)

//check if the resulted recordset contains any records; if not, return NULL if( result.recordCount() = 0) return NULL //otherwise, create a new error object and return it check_failed = new tNG_error("Error message",array(), array()) return check_failed

The structure above, adapted to your particular scripting language and scenario allows building the custom trigger to check for unique entries. From the trigger properties page, you must set it to the BEFORE type, so that it is executed before the actual insert, and will block it if it fails.

Next you will see an example of a multiple field unique check created for all server models:


308

For PHP:

$query = "SELECT * FROM message_msg WHERE subject_msg = ".KT_escapeForSql($tNG>getColumnValue("subject_msg"),$tNG>getColumnType("subject_msg"))." AND content_msg = ".KT_escapeForSql($tNG>getColumnValue("content_msg"),$tNG>getColumnType("content_msg")); $result = $tNG>connection>Execute($query); if(!$result) { $error = new tNG_error("Could not access database!",array(),array()); return $error; } else { if($numberOfRecords = $result>recordCount()) { $uniqueFailed = new tNG_error("There is already a message with the same subject and content!",array(),array()); return $uniqueFailed; } else { return NULL; } }

For ASP_VBScript

'Trigger that checks if two combined fields are unique Dim subjectValue Dim contentValue Dim query subjectValue = tNG.getColumnValue("subject_msg") contentValue = tNG.getColumnValue("content_msg") query = "SELECT * FROM message_msg where subject_msg = " & KT_escapeForSql(subjectValue,tNG.getColumnType("subject_msg")) & " AND content_msg = " & KT_escapeForSql(conentValue,tNG.getColumnType("content_msg")) on Error Resume Next set check_result = tNG.connection.Execute(query) If Err.Number <>0 Then Set check_failure = new tNG_error check_failure.init "Could not access database!", Array(), Array() Set Trigger_Custom2 = check_failure Else if(check_result.recordCount() <>0 ) Then Set not_unique = new tNG_error not_unique.init "A message with the same subject and content already exist. You cannot enter duplicates", Array(), Array() Set Trigger_Custom2 = not_unique else Set Trigger_Custom2 = nothing end if end if On Error GoTo 0


309

For ColdFusion:

You must create a function that constructs the query, executes it and checks the number of records. It's result is assigned to the custom trigger return:

<cffunction name="AliasCustomTrigger2"> <cfargument name="tNG" required="true"> <cfset var query = ""> <cfset var result = ""> <cfset var myerror = ""> <cfset query = "SELECT * FROM message_msg WHERE subject_msg = " & Request.KT_escapeForSql(tNG.getColumnValue("subject_msg"),tNG.getColumnType("subject_msg")) & " AND content_msg = " & Request.KT_escapeForSql(tNG.getColumnValue("content_msg"), tNG.getColumnType("content_msg"))> <cflock name="check_multiple_unique" type="exclusive" timeout="10"> <cftry> <cfquery name="result" datasource="#tNG.connection#"> #PreserveSingleQuotes(query)# </cfquery> <cfif result.RecordCount GT 0> <cfset myerror = Request.tNG_CreateObject("tNG_error")> <cfset myerror.init ("There is already a message with the same subject and content!", ArrayNew(1), ArrayNew(1))> </cfif> <cfcatch> <cfset myerror = Request.tNG_CreateObject("tNG_error")> <cfset myerror.init ("Could not access database!", ArrayNew(1), ArrayNew(1))> </cfcatch> </cftry> </cflock> <cfif IsObject(myerror)> <cfreturn myerror> <cfelse> <cfreturn Request.KT_Null> </cfif> </cffunction> <cfset Request.AliasCustomTrigger2 = AliasCustomTrigger2> <cfscript> //start Trigger_Custom2 trigger function Trigger_Custom2(tNG) { return Request.AliasCustomTrigger2(tNG); } Request.Trigger_Custom2 = Trigger_Custom2; //end Trigger_Custom2 trigger </cfscript>

Save additional information on loginIf you want to help your users by displaying the date of the last login, or have a statistic with the number of logins for each user, you can use the User Login Form from Developer Toolbox and some custom code in a Custom Trigger. The Custom Trigger executes after the login operation and saves information to the table.

For this example, the user table has the following structure:


310

• id_usr - table primary key, stores the unique ID for each user

• name_usr - the user name

• email_usr - the user e-mail address

• password_usr - the user password

• active_usr - the account activation status

• lastlogin_usr - date and time of the last login. It is updated on each login

• logincounter_usr - number of logins for the user. It is incremented on each login

Creating a login form is not covered in this sample, as you can learn how to create it here. You will only learn to add the code that updates the database with the last login time and increments the login counter.

To create this trigger you will make use of the following methods of the Transaction Engine:

1 KT_DynamicData - this method performs the evaluation of the Developer Toolbox mark-up that is passed as argument. The method call is like the following:KT_DynamicData($expression, $tNG, $escapeMethod = '', $useSavedData = false, $extraParams = array(), $errorIfNotFound = true)

2 KT_formatDate2DB - this method converts the date from the screen format to the database format set in the Developer Toolbox Control Panel. The method call is like:

KT_formatDate2DB(date_to_convert)

3 Detailed explanations on these methods' arguments can be found in the online API documentation, here.

4 Methods that allow executing an SQL query and returning an error or success, as explained here.

The actual code for the trigger is as follows - pick the section corresponding to your particular server model.

For ASP:datetime_in_screen = KT_DynamicData("{NOW_DT()}", nothing, null, null, null, null) datetime_in_db = KT_formatDate2DB(datetime_in_screen) query = "UPDATE user_usr SET logincounter_usr = logincounter_usr+1, lastlogin_usr = '" & datetime_in_db & "' WHERE id_usr = " & Session("kt_login_id") On Error Resume Next Set update_result = tNG.connection.Execute(query) if Err.Number <> 0 then Set updateError = new tNG_error update_error.init "Error updating the user record", Array(), Array() Set Trigger_Custom = updateError else Set Trigger_Custom = nothing end if On Error GoTo 0


311

For PHP:$datetime_in_screen = KT_DynamicData("{NOW_DT}", '', '', '', '', ''); $datetime_in_db = KT_formatDate2DB($datetime_in_screen); $query = "UPDATE user_usr SET logincounter_usr = logincounter_usr+1, lastlogin_usr = '".$datetime_in_db."' WHERE id_usr = ".$_SESSION["kt_login_id"]; $update_result = $tNG>connection>execute($query); if(!$update_result) { $updateError = new tNG_error( "Error updating the user record", array(), array()); return $updateError; } else { return NULL; }

For ColdFusion:<cffunction name="AliasCustomTrigger"> <cfargument name="tNG" required="true"> <cfset var query = ""> <cfset var result = ""> <cfset var datetime_in_screen = Request.KT_DynamicData("{NOW_DT}", #tNG#)> <cfset var datetime_in_db = Request.KT_formatDate2DB(datetime_in_screen)> <cfset updateError= ''> <cfset query = "UPDATE user_usr SET logincounter_usr = logincounter_usr+1, lastlogin_usr = '" & datetime_in_db & "' WHERE id_usr = " & Session["KT_login_id"]> <cflock name="loginTransaction" type="exclusive" timeout="10"> <cftry> <cfquery name="result" datasource="#tNG.connection#">#PreserveSingleQuotes(query)#</cfquery> <cfcatch> <cfset updateError= Request.tNG_CreateObject("tNG_error")> <cfset updateError.init ("Error updating the user record", ArrayNew(1), ArrayNew(1))> </cfcatch> </cftry> </cflock> <cfif IsObject(updateError)> <cfreturn updateError> <cfelse> <cfreturn Request.KT_Null> </cfif> </cffunction> <cfset Request.AliasCustomTrigger = AliasCustomTrigger> <cfscript> //start Trigger_Custom trigger function Trigger_Custom(tNG) { return Request.AliasCustomTrigger(tNG); } Request.Trigger_Custom = Trigger_Custom; //end Trigger_Custom trigger </cfscript>

After adding the code in the Basic tab of the Custom Trigger user interface make sure that on the Advanced tab the correct transaction and the trigger type are selected: for the transaction, the login transaction must be selected, and for the trigger type select After - this will cause the trigger to execute only after a successful login.

312

Chapter 17: Understanding the Transaction Engine

Understanding the Transaction Engine presents in detail all the features, facilities and performances that you can benefit from when using the transaction engine.

This chapter contains the following topics:

• “What is the Transaction Engine?” on page 312

• “Transactions” on page 314

• “Error handling in Transaction Engine” on page 327

• “Extend Transaction Engine” on page 335

• “Transaction recordset” on page 337

• “How user interface persistence works” on page 338

What is the Transaction Engine?This chapter presents the main features of the transaction engine. In order to provide better PHP code, Adobe® Dreamweaver® Developer Toolbox uses a set of PHP classes known as the Transaction Engine.

The Transaction Engine supports PHP, ColdFusion and ASP VBScript.

The Transaction Engine has been designed to act as a framework which allows developers encapsulate application login, in order to create powerful applications easier.

The Transaction Engine allows developers to associate application triggers with standard database related transac-tions, like sending an email after a record was inserted, or checking referential integrity from the application.

The Transaction Engine implementation is object oriented.

ConceptsThe main concepts used by the Transaction Engine are:

• “Transaction” on page 312

• “Dispatcher” on page 314

• “Trigger” on page 314

TransactionA transaction is, in general terms, a set of operations that the server-side script must perform. The transaction has a main operation that is performed, that is generally a SQL statement. However, you can build transactions that do not use SQL commands at all.

As an example, a transaction can perform the following operations:


313

• Check if a form was submitted.

• Check if all the required forms values were correctly submitted.

• Build and execute a SQL statement using the submitted form values (e.g. an INSERT statement).

• Upload & save a file selected in the form.

• If every operation was successfully executed, go to another page.

• If not, inform the user of the errors and/or ask the user to re-insert the form informations.

The schematics of a transaction shows that the transaction itself is the whole made up from the main operation and the smaller operations performed before, after or in case of an error:

Depending on the main operation's type, there are several transaction types:

• Insert Transaction Transaction that has as main operation the execution of a single SQL/INSERT statement (will insert a record in a database).

• Update Transaction Transaction that has as main operation the execution of a single SQL/UPDATE statement (will update a record in a database).

• Delete Transaction Transaction that has as main operation the execution of a single SQL/DELETE statement (will delete a record from a database).

• Custom Transaction Transaction that can have as main operation any SQL statement or no SQL statement at all, just a set of instructions. It is generally used to execute more complex INSERT/UPDATE/DELETE statements.

• Multiple Insert Transaction Transaction that has as main operation the execution of one or more SQL/INSERT statements (will insert one or more records in a database).

• Multiple Update Transaction Transaction that has as main operation the execution of one or more SQL/UPDATE statements (will update one or more records in a database).

• Multiple Delete Transaction Transaction that has as main operation the execution of one or more SQL/DELETE statements (will delete one or more records from a database).

Whenever the transaction will throw an error, its execution will fail.


314

DispatcherIt represents a container for the transactions, and it is needed to improve the flow when using multiple transactions on the same page. Any transaction that will be executed in a page will have to be registered with the dispatcher. The dispatcher is represented in page by the following line of code:

$tNGs = new tNG_dispatcher("");

The $tNGs variable will be created only once and it will act like a global variable throughout the entire request. The dispatcher is unique on page. It receives as parameter the current file's relative path from the site root.

The Dispatcher is very important, as it handles all interactions between the page and the Transactions that are regis-tered to it (executes the Transactions, feeds the recordsets generated by the Transactions to the page, displays Trans-action's error messages etc).

TriggerTriggers represent operations that prepare or complete the Transaction's main operation. [They can exist only as a part of a Transaction and they are executed by the transaction].

It represents a code block that registers to a transaction, has access to the transaction's contextual information, and is executed before/after the transaction.

There are five types of triggers, based on the cascaded execution of a transaction:

• STARTER triggers are executed before the transaction is started. They can decide whether a transaction is executed or not as they are separate from the BEFORE triggers, because an error is not thrown when the starter trigger stops the execution.

• BEFORE triggers are executed if the transaction is accepted by its start conditions. The before triggers usually check the posted data or change it, making it suitable for the SQL transaction generation. The validation triggers are a good example, as they verify the data's compliance to the validation rules and stop the transaction if it doesn't match.

• AFTER triggers are executed after the transaction has correctly run, without throwing any errors. The AFTER triggers usually manipulate files or use the just updated information.

• END triggers are executed when all the AFTER triggers have already been executed and no error was thrown.

• ERROR triggers are triggers that register to a transaction, and that get executed when the transaction fails. The transaction might fail from various reasons (database integrity, trigger error etc).

TransactionsThis section presents information on the code generated behind the Insert/Update/Delete Transactions to help you better understand how it works. Afterwards, you will be able to build additional actions using the Transaction Engine to better suit your particular needs:

• “Insert transaction” on page 315

• “Update transaction” on page 317

• “Delete transaction” on page 319

• “Multiple insert transaction” on page 320

• “Multiple update transaction” on page 323


315

• “View of the generated code” on page 324

• “General triggers” on page 326

Insert transactionA typical insert transaction uses code like the snippet below, to achieve its purpose: inserting a set of values into a database table.

The first thing that occurs when adding a new transaction into a page is the inclusion of the Transaction Engine classes. They are included in a file called tNG.inc.php, in the includes/tng folder on the server. This folder is created automatically when using a Transaction Engine feature in one of the site's pages:

// Load the tNG classes require_once('includes/tng/tNG.inc.php');

As you can have multiple transactions on page, each one must register with the page's unique dispatcher, so that it can establish a coherent order of execution. In order to create a new dispatcher, the generated code creates a new instance of the dispatcher object, passing it as parameter the file's path relative to the site root (e.g. for a file in the /files folder, the path is ../):

// Make a transaction dispatcher instance $tNGs = new tNG_dispatcher("");

The standard connection is transformed into a Transaction Engine connection and made available through a variable:

// Make unified connection variable $conn_localhost = new tNG_connection($localhost, $database_localhost);

The triggers for this page are now created. For form validations, the tNG_FormValidation trigger is used.

The fields that are required for validation will be added using the addField method. If the field does not require any validation, it will not be added to the tNG_FormValidation object. After the fields are added, the Dispatcher is instructed to prepare the validation:

// Start trigger $formValidation = new tNG_FormValidation($tNGs); $tNGs>prepareValidation($formValidation); // End trigger

This code section creates the actual transaction type: an insert one. As you can see, all is done OOP; creating a new insert transaction resumes to instantiating a class. Aside creating the transaction, it is also registered to the dispatcher, by the addTransaction method, that takes the name of the transaction as a parameter:

// Make an insert transaction instance $ins_company_com = new tNG_insert($conn_localhost); $tNGs>addTransaction($ins_company_com);

To add Triggers to the Transaction, the tNG>registerTrigger() method is used. The first three parameters are required, (Trigger type, Trigger name, Trigger priority), and the last are optional and represent the parameters used by the Transaction to call the Trigger. Besides these extra parameters, the first parameter always passed when calling a Trigger is the reference to the instance of the current executing Transaction. In this way, the trigger has access to the Transaction context:


316

// Register triggers $ins_company_com>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "POST", "MM_Insert1"); $ins_company_com>registerTrigger("BEFORE", "Trigger_Default_FormValidation", 10, $formValidation); $ins_company_com>registerTrigger("END", "Trigger_Default_Redirect", 99, index.php);

For example, in this case, the transaction will execute the trigger Trigger_Default_Redirect like this:

Trigger_Default_Redirect($this,"index.php");

The next section of code assigns the table into which the insert will occur (in the first line) and then adds the actual columns to the table. The last line defines the primary key of the table: the field name, and its type. When adding a column, the arguments passed to the addColumn method are: the column name, column type, method of passing the value, reference and default value:

// Add columns $ins_company_com>setTable("company_com"); $ins_company_com>addColumn("name_com", "STRING_TYPE", "POST", "name_com"); $ins_company_com>addColumn("address_com", "STRING_TYPE", "POST", "address_com"); $ins_company_com>addColumn("active_com", "NUMERIC_TYPE", "POST", "active_com"); $ins_company_com>setPrimaryKey("id_com", "NUMERIC_TYPE");

When using the addColumn method, there are several column types that can be used:

• STRING_TYPE - allows a string of characters to be added; if the value is missing, it is set by default to NULL.

• NUMERIC_TYPE - allows adding of numbers; if the value is missing, it is set by default to NULL.

• DOUBLE_TYPE - allows adding of double values (numbers that also use decimals); if the value is missing, it is set by default to NULL.

• DATE_TYPE - allows adding of dates; if the value is missing, it is set by default to NULL.

• DATE_ACCESS_TYPE - allows adding dates in the access format (the date is between # signs);if the value is missing, it is set by default to NULL.

• FILE_TYPE - allows adding a file type column; if the value is missing, it is set by default to NULL.

• CHECKBOX_YN_TYPE - allows adding a column from a yes/no checkbox; if the value is missing, it is set by default to “N”.

• CHECKBOX_1_0_TYPE - allows adding a column from a 1/0 checkbox; if the value is missing, it is set by default to “0”.

• CHECKBOX_-1_0_TYPE - allows adding a column from a -1/0 checkbox; if the value is missing, it is set by default to “0”.

• CHECKBOX_TF_TYPE - allows adding a column from a TRUE/FALSE checkbox; if the value is missing, it is set by default to “F”.

There are also several reference methods to use with the addColumn() call:

• HIDDEN - the value is ignored, used just to add a field to a Transaction.

• VALUE - the actual value is passed directly.

• FILES - a form field of file type.

• SERVER - a server value.

• SESSION - a session value.


317

• COOKIE - a HTTP cookie value.

• POST - a HTTP POST value.

• GET - a HTTP GET value.

• CURRVAL - will pass the current field value on to the transaction. It is usually used in an UPDATE transaction, to pass the same value as the one that already existed in the record

• EXPRESSION - this will evaluate the numeric or string expression passed as reference

After all Transactions with their corresponding triggers were set and added to the Dispatcher, it can be executed:

// Execute all the registered transactions $tNGs>executeTransactions();

The Dispatcher will execute each Transaction by calling the executeTransaction() method for each of them.

If any of the Transactions will export a recordset , we can ask the Dispatcher to search and retrieve it from its Trans-actions:

// Get the transaction recordset $rscompany_com = $tNGs>getRecordset("company_com"); $row_rscompany_com = mysql_fetch_assoc($rscompany_com); $totalRows_rscompany_com = mysql_num_rows($rscompany_com);

Update transactionThe Transaction Engine update transaction is similar in terms of code to the insert transaction, the main difference is the class that's being instanced. The code looks like illustrated below, with the associated explanations.



As you can have multiple transactions on page, each one must register with the page's unique dispatcher, so that it can establish a coherent order of execution:




The triggers for this page are now created. For form validations, the tNG_FormValidation trigger is used.

The fields that are required for validation will be added using the addField method. If the field does not require any validation, it will not be added to the tNG_FormValidation object. After the fields are added, the Dispatcher is instructed to prepare the validation:

// Start trigger $formValidation = new tNG_FormValidation($tNGs); $tNGs>prepareValidation($formValidation); // End trigger


318

This code section creates the update transaction by creating an instance of the update record object. Aside creating the transaction, it is also registered to the dispatcher, by the addTransaction method, that takes the name of the trans-action as a parameter:

// Make an update transaction instance $upd_company_com = new tNG_update($conn_localhost); $tNGs>addTransaction($upd_company_com);

To add Triggers to the Transaction, the tNG>registerTrigger() method is used. The first three parameters are required, (Trigger type, Trigger name, Trigger priority), and the last are optional and represent the parameters used by the Transaction to call the Trigger. Besides these extra parameters, the first parameter always passed when calling a Trigger is the reference to the instance of the current executing Transaction. In this way, the trigger has access to the Transaction context:

// Register triggers $upd_company_com>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "POST", "MM_Update1"); $upd_company_com>registerTrigger("BEFORE", "Trigger_Default_FormValidation", 10, $formValidation); $upd_company_com>registerTrigger("END", "Trigger_Default_Redirect", 99, index.php);

For example, in this case, the transaction will execute the trigger Trigger_Default_Redirect like this:

Trigger_Default_Rediret($this,"index.php");

The next section of code assigns the table into which the update will occur (in the first line) and then adds the actual columns to the table. The last line defines the primary key of the table: the field name, and its type. When adding a column, the arguments passed to the addColumn method are: the column name, column type, method of passing the value and the reference:

// Add columns $upd_company_com>setTable("company_com"); $upd_company_com>addColumn("name_com", "STRING_TYPE", "POST", "name_com"); $upd_company_com>addColumn("address_com", "STRING_TYPE", "POST", "address_com"); $upd_company_com>addColumn("active_com", "NUMERIC_TYPE", "POST", "active_com"); $upd_company_com>setPrimaryKey("id_com", "NUMERIC_TYPE", "GET", "id_com");

When using the addColumn method, there are several column types that can be used:

• STRING_TYPE - allows a string of characters to be added; if the value is missing, it is set by default to NULL.

• NUMERIC_TYPE - allows adding of numbers; if the value is missing, it is set by default to NULL.

• DOUBLE_TYPE - allows adding of double values (numbers that also use decimals); if the value is missing, it is set by default to NULL.

• DATE_TYPE - allows adding of dates; if the value is missing, it is set by default to NULL.

• DATE_ACCESS_TYPE - allows adding dates in the access format (the date is between # signs);if the value is missing, it is set by default to NULL.

• FILE_TYPE - allows adding a file type column; if the value is missing, it is set by default to NULL.

• CHECKBOX_YN_TYPE - allows adding a column from a yes/no checkbox; if the value is missing, it is set by default to “N”.

• CHECKBOX_1_0_TYPE - allows adding a column from a 1/0 checkbox; if the value is missing, it is set by default to “0”.


319

• CHECKBOX_-1_0_TYPE - allows adding a column from a -1/0 checkbox; if the value is missing, it is set by default to “0”.

• CHECKBOX_TF_TYPE - allows adding a column from a TRUE/FALSE checkbox; if the value is missing, it is set by default to “F”.

There are also several reference methods to use with the addColumn() call:

• HIDDEN - the value is ignored, used just to add a field to a Transaction.

• VALUE - the actual value is passed directly.

• FILES - a form field of file type.

• SERVER - a server value.

• SESSION - a session value.

• COOKIE - a HTTP cookie value.

• POST - a HTTP POST value.

• GET - a HTTP GET value.

• CURRVAL - will pass the current field value on to the transaction. It is usually used in an UPDATE transaction, to pass the same value as the one that already existed in the record

• EXPRESSION - this will evaluate the numeric or string expression passed as reference

After all Transactions with their corresponding triggers were set and added to the Dispatcher, it can be executed:


The Dispatcher will execute each Transaction by calling the executeTransaction() method for each of them.

If any of the Transactions will export a recordset , we can ask the Dispatcher to search and retrieve it from its Trans-actions:

// Get the transaction recordset $rscompany_com = $tNGs>getRecordset("company_com"); $row_rscompany_com = mysql_fetch_assoc($rscompany_com); $totalRows_rscompany_com = mysql_num_rows($rscompany_com);

Delete transactionThe delete transaction follows exactly the same steps as the insert and update transactions, even though there is no data to add.


// Load the tNG classes require_once('../includes/tng/tNG.inc.php');

As you can have multiple transactions on page, each one must register with the page's unique dispatcher, so that it can establish a coherent order of execution:



320



This code section creates the actual transaction: a delete one. As you can see, all is done object oriented, creating a new delete transaction being reduced to creating an instance of an object:

// Make an instance of the transaction object $deleteTransaction = new tNG_delete($conn_localhost); $tNGs>addTransaction($deleteTransaction);

This code section register triggers with the transaction. In this case we only have 2 triggers: a starter, which verifies if data has been received through POST, and an end trigger that performs the page redirect after the transaction and all other triggers executed successfully:

// Register triggers $deleteTransaction>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "GET", "id_com"); $deleteTransaction>registerTrigger("END", "Trigger_Default_Redirect", 99, "index.php");

In order to delete only one record, the one that has been selected in another page, the primary column must be selected. Also, the table from which to delete is selected in this code section:

// Add columns $deleteTransaction>setTable("company_com"); $deleteTransaction>setPrimaryKey("id_com", "NUMERIC_TYPE", "GET", "id_com");

All that remains is to actually call the transaction for execution:


As you can see from the three code examples, the only difference lies in the name of the object. The methods for the different objects are pretty much the same.

Multiple insert transactionIf in the Dynamic list more than one element has been selected for editing (by checking multiple checkboxes) or if you want to insert more records at the same time (by choosing the number of records to add from the drop-down menu located next to the Add new button), more than one set of form elements will be displayed, allowing you to work on the entire number of records selected at once. Changes that occur on all records are submitted at the push of one button.


321

Each record to be inserted or updated contains the same fields, in the same order, and are identified by a title. There is only one set of buttons that process the entire page. Depending on the option you selected in the Display as grid drop-down menu from the Create Dynamic Form wizard (last step), the multiple insert form can look like in the following images:

The multiple insert operation is in fact a series of single insert operations. Only one STARTER and one END triggers can exist for the multiple insert or update, but separate BEFORE or AFTER triggers can exist for each single operation that belongs to the multiple operation. (e.g. the Form Validation trigger is applied on each transaction, stopping only the ones that do not comply the validation rules).

If one of the insert/update transactions fails for whatever reason, it is the only one that is stopped, the other transac-tions, either before or after the failure will be executed correctly, as you can see in the example below:


322

• In the multiple insert below (3 different products at the same time), the second one does not have a numeric entry for the price and the form validation is applied:

• When the Insert button is pressed, the page will display that an error occurred, but also that some of the operations were executed:

The first and third products were successfully inserted into the table, but the second one had an incorrect price and thus that particular insert operation was stopped. Once the wrong data is corrected in the form and the Insert button is pressed, the record will be added to the table as well.


323

Multiple update transactionYou can update multiple records at the same time by using Dynamic lists and forms.

Let's consider the following Dynamic list. The skin used is the aqua one, and the buttons and navigation bar are not duplicated. The rows are ordered ascending by name:

A multiple update operation requires at least two records to be updated. Let's say that the two records selected above are to be modified. After clicking the edit button in the left lower corner of the list, the associated Dynamic form opens:


324

If you click the Update button, you will get the message that only one update operation succeeded, while the other one encountered an error (a validation rule was not respected):

This is a great advantage since you don't have to enter again the updated information for all the records, but only for the one with the error.

View of the generated codeThis sub-section describes the main advantage of using the tNG classes over procedural programming in Developer Toolbox. This advantage lies in the reuse of generated code. Most of our transactions (insert, update, delete) call the same classes. The only changes reside in the names of the functions to call, depending on the desired result:

• “Basic view on the generated code” on page 324

• “Extended view on the generated code” on page 325

Basic view on the generated codeThis is how generated code looks like, considering the Insert Transaction settings:

<?php // Load the tNG classes require_once('includes/tng/tNG.inc.php');

// Make an unified connection instance $conn_test = new tNG_connection($test, $database_ test);


// Make an insert transaction instance $insertTNG1 = new tNG_insert($conn_test); $tNGs>addTransaction($insertTNG1);

// Register triggers $insertTNG1>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "POST", "MM_Insert"); $insertTNG1>registerTrigger("END", "Trigger_Default_Redirect", 99, "index.php");


325

// Add columns $insertTNG1>setTable("departments_dep"); $insertTNG1>addColumn("id_dep", "NUMERIC_TYPE", "POST", "id", "1"); $insertTNG1>addColumn("name_dep", "STRING_TYPE", "POST", "name", ""); $insertTNG1>setPrimaryKey("id_dep", "NUMERIC_TYPE");


// Get the transaction recordset $rsDepartments_dep = $tNGs>getRecordset("departments_dep"); $row_rsDepartments_dep = mysql_fetch_assoc($rsDepartments_dep ); $totalRows_rsDepartments_dep = mysql_num_rows($rsDepartments_dep );

For detailed information regarding the different code parts, see “Extended view on the generated code” on page 325.

Extended view on the generated codeThe main generated code sections are:

• Defining the transaction connection. This object is used to create a database independence layer for Transaction Engine Lite:

$conn_test = new tNG_connection($test, $database_test);

• Defining the transaction dispatcher:$tNGs = new tNG_dispatcher("");

• Create a transaction instance:

$insertTNG1 = new tNG_insert($conn_test);

• Add the created transaction to the dispatcher:

$tNGs>addTransaction($insertTNG1);

• Register triggers (STARTER and END - Redirect):$insertTNG1>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "POST", "MM_Insert"); $insertTNG1>registerTrigger("END", "Trigger_Default_Redirect", 99, "index.php");

• Set the appropriate table to the transaction:$insertTNG1>setTable("departments_dep");

• Add all selected columns with all specified parameters (name, type, method, reference, default value):

$insertTNG1>addColumn("id_dep", "NUMERIC_TYPE", "POST", "id", "1"); $insertTNG1>addColumn("name_dep", "STRING_TYPE", "POST", "name");

• For each column specified in the Columns grid in the Server Behavior interface, one addColumn() function call will exist.

addColumn(DB_FIELD_NAME, DB_TYPE, METHOD, REFERENCE, DEFAULT_VALUE);

• Set the primary key:

If the transaction is of Insert, Update or Delete type, the primary key and its type will have to be specified. The Custom Transaction and other transactions that will be developed in the future, do not require a primary key to be defined:

$insertTNG1>setPrimaryKey("id_dep", "NUMERIC_TYPE");

• Execute the transaction:


326

$tNGs>executeTransactions();

• Get the Transaction Recordset. The dispatcher will search all registered transactions that are linked to the given table and will return the correct Recordset.

// Get the transaction recordset $rsDepartments_dep = $tNGs>getRecordset("departments_dep"); $row_rsDepartments_dep = mysql_fetch_assoc($rsDepartments_dep ); $totalRows_rsDepartments_dep = mysql_num_rows($rsDepartments_dep );

General triggersThis section offers a useful presentation of the general triggers often used in Developer Toolbox applications:

• “Custom trigger” on page 326

• “Linking transactions” on page 326

Custom triggerA custom trigger is a function whose first parameter is a reference to the executing Transaction. This allows any trigger to have access to the Transaction context (SQL fields, primary key etc.).

If an error is raised inside the trigger it must be returned as an instance of the tNG_error object.

Here is a sample of a custom trigger that checks if a user is authenticated or not:

function TriggerBEFORE_checkSession(&$tNG) { if (!isset($_SESSION['authorised'])) { $errObj = new tNG_error('User is not authenticated.', array(), array()); return $errObj; } else { return null; } }

This code uses the following:

• a trigger named TriggerBEFORE_checkSession; as it can be seen from the suggestive naming, it is a BEFORE trigger;

• whether or not the user is authenticated is stored in a session variable called authorised, and which can be called through the $_SESSION['authorised'] expression (this is PHP syntax);

• the error message is returned by using an instance of the tNG_error object.

• A custom trigger can only return NULL, or a transaction engine error object. If no error is thrown during the trigger execution, NULL is returned. If an error occurs, the tNG_error object is returned, which contains the user and developer error (as you can see in the above code example - the two error messages are the same).

Linking transactionsOne more improvement in the Transaction Engine is the ability to link two transactions, and this way, to insert data into two tables at the same time.

In order to insert/update into two tables at once, the two separate transactions must be added first. This can either be with the wizard, or with the Server behaviors and Dreamweaver tools. One mention has to be made concerning the second (also known as detail) transaction: all fields must be displayed on the form, including primary and foreign key.


327

After creating the two transactions, you must apply the Link Transactions trigger, which will pass the first's trans-action primary key as the second's foreign key and will submit them both.

The code behind this trigger is similar to the one shown below:

//start trigger LinkTransactions function KT_TriggerAFTER_LinkTransactions(&$tNG) { global $ins_contact_con; $LinkTransactions = new tNG_linkedTrans($tNG, $ins_contact_con); $LinkTransactions>setLink("idcom_con"); return $LinkTransactions>execute(); } //end trigger LinkTransactions

As you can see, it is an after trigger, that executes only after the first (master) transaction took place and inserted data into its table. It then passes the primary key to the foreign key , which is used to determine the link in the setLink method. It is also an error trigger, as if anything happens, it will roll back the executed transaction(s).

The link transaction trigger registers itself to both transactions on page.

Just as for any other Transaction Engine trigger or transaction, all code works with objects and methods, and this shows in the clear code.

Error handling in Transaction EngineThis section presents new and improved methods that come with the Transaction Engine, methods that regard the errors handling from the server-side. This means that errors are detected and treated after submitting the page to the server. It also means that the result of the error-handling routines is displayed when reloading the page, and not immediately after the error occurs.

In order to maintain the values already submitted by the page through its forms, Transaction Engine uses the trans-action recordset . The recordset holds the values, so when an error occurs, data can and will be placed in the form, and the wrong field will be highlighted. This feature provides the user with the exact field that had the wrong input, and the developer with the right debug information.

When talking about debug modes, it is worth mentioning the two modes that Transaction Engine comes with and that can be switched on the fly in order to hide or display complex details regarding the errors on page:

• the Development mode - it provides a great amount of information, including the stack trace of all the operations (both executed and to-be-executed), with the errors marked; it also provides additional help and solutions;

• the Production mode - it only displays a limited amount of information, being more suited for finished applica-tions that are visited by the public.

This section contains the following topics:

• “Server-side error handling” on page 328

• “Development mode error handling” on page 330

• “Production mode error handling” on page 331

• “Error log options” on page 332

• “Customize error messages” on page 332


328

Server-side error handlingThis section offers information about the transaction recordset's role in handling the occurring errors. This includes the way the Transaction Engine deals with the errors that occur, and the development and production debug modes, and switching between them.

At development time, the developer is interested to see exactly in which part of the transaction the error occurred and a more detailed error message (e.g. for a failed file upload, what caused the failure (missing write permissions on the upload folder, etc) and where in the transaction the error occurred (the AFTER trigger that performed the upload failed)).

Once the application is deployed and becomes a "live" application, the developer will want to hide these complex error messages to the user and display a message like: "An error occurred while uploading the file. Please contact the system administrator." or something similar.

This is why any error will have to have a "development-time" error message and a "deployed-time" error message. Depending on the configuration, the Transaction Engine will display the appropriate error message.

To read more about the server-side error handling, check out the next topics:

• “Use the transaction recordset to preserve submitted values” on page 328

• “Handle SQL errors” on page 328

• “Development and production” on page 330

• “Switch error handling levels” on page 330

Use the transaction recordset to preserve submitted valuesTo allow easier error handling methods, the Transaction Engine uses the transaction recordset as a means of trans-ferring data.

The transaction recordset goes through three different states:

• Initial state - when it is created, it is filled with some default values. If the page contains an update transaction, the transaction recordset will be populated with filtered data from the table to be updated, based on the record ID passed to the page.

• When the page is submitted, the recordset will contain all data from the form corresponding to the transaction it is registered to. This way, when error handling is done server side, it can rollback to the page containing the form, which will be populated with data extracted from the transaction recordset. The wrong or missing fields will be highlighted, or if there is a different kind of error (like a duplicate entry, or a bad password, etc) the error message displayed, but no values will be lost.

Handle SQL errorsErrors raised by the SQL queries are handled in compliance with the error reporting mode selected at design time from the Developer Toolbox Control Panel: production or development.

There are two types of SQL errors:

• Field errors - these errors are directly related to a particular field which caused them. A message is displayed next to the form field that caused it.

• General errors - these errors have a more general cause (e.g. the database server cannot be contacted, etc), and are displayed on top of the page.


329

When in production mode, only a limited amount of information regarding the SQL transaction and field that failed is displayed, as shown in the image below, where a SQL error was raised due to an attempt to add a null value into a non-null field.

As you can see, the error message is clear and concise, pointing to the wrong entry, as well as hiding complex detail.

When switching to development mode for error reporting, a detailed trace of all transactions and triggers until the error is displayed, along with detailed information on the exact query that failed and the reason why it did. The same error as above is now completely explained, pointing the developer to the exact line of code that caused the error. This way it is easier to identify programming errors versus bad input errors.

The first zone displays the same error message as for production mode.

The second one, marked developer details, shows the exact query, filled with the values that it was trying to process, that failed.


330

The Transaction Engine Execution Trace is not expanded at first, but it can be made fully visible by clicking the View link.

Development and productionDeveloper Toolbox provides two ways of handling errors (also called debug modes), that differ on the quantity of information displayed concerning each error that occurs. This modes are called Production and Development, as they are useful for one of these phases of a web application's life cycle.

The Production mode displays relatively general information about the cause of the error, while Development mode has been thought as to help the developer understand what errors occur and where exactly.

In the following topics you will discover details concerning Production and Development error handling modes.

Switch error handling levelsTo switch between production and development error handling modes, you must access the Debugging mode from the Developer Toolbox Control Panel.

A dialog box similar to the one below will be displayed:

In the Debug mode drop-down menu, you can select the error handling mode. This is called the Debug Mode, since it actually helps track errors in the code. The available options are Development and Production.

Once you've selected the desire mode, click on OK to apply it, and then, if you do not have automatically put files activated, you will have to upload the includes/tng folder, so that changes will be visible when accessing pages on the server.

Development mode error handlingThis section offers information upon how the Transaction Engine core provides the developer with details regarding the exact error, the line that triggered the error and hints on how to correct it. It also provides a stack trace view of all instructions, the one that caused the error being marked in red. this helps locate the error and correct it faster, even if it is a form submission error, or a SQL query error.

Along the error details there is a link that sends the user to a page recommending possible solutions for the problem, as well as giving a more detailed explanation concerning the cause.

To read more about the development mode error handling, check out the next topic:

• “Stack trace for development mode” on page 331


331

Stack trace for development modeThe stack trace is available only when the site is in development debug mode. It is a valuable tool for the developer, as it displays all instructions related to the Transaction Engine that are available on page, both the ones executed before an error has been raised, as well as the ones that were not executed due to the premature halt of the application.

In the first step, the entire stack trace is not shown, only the fact that it is there and a link to expand its view being displayed, as in the image below.

Only after clicking on the View link, the entire list of instruction is displayed, the one that caused the halt of the program being marked with red:

As you can see, the list displays all the Transaction Engine related instructions, like the ones belonging to the triggers and transactions on page, in the order they were meant to be executed. This way, the ones that got run are displayed above the error, and the ones left to execute are below it.

Using this stack trace, together with the other developer details and the related help provided for each error, debugging the page to avoid future errors is easy.

Production mode error handlingWhen switching to production mode in the Developer Toolbox Control Panel> Debugging Mode, the main change is in the error reporting system. There is a diminished amount of information provided when an error is raised. The error message displayed is very general, so as not to disclose any information regarding the system's architecture.

When in production mode, only the fact that an error occurred will be displayed, without a stack trace or additional help, unless provided by the developer.


332

Error log optionsAside from the two ways of reporting errors, Development and Production, Developer Toolbox allows the creation of logs for all errors. With the Debugging mode entry in the Developer Toolbox Control Panel, you can decide how to maintain these logs: you can either write into a file whenever an error is raised, or receive an e-mail every time an error occurs.

A dialog box similar to the image below will be displayed:

When using the log to file option, a file called readme.txt is generated in the includes/tng/logs folder, and the appro-priate setting is set in KT_config.inc.php. When you need to check the errors, simply open the file (or download it from the server using what method of file transfer you prefer).

For instructions on configuring this dialog box, see “Debugging mode” on page 9.

Customize error messagesThis section presents a great feature of Developer Toolbox that, when an error occurs, allows you to display a customized message easy to be dealt with by the user:

• “Change the style (CSS)” on page 332

• “Change the content (text)” on page 335

Change the style (CSS)In Developer Toolbox, error messages that result from validations and processing, for both development and production debugging mode, as well as client-side and server-side display differently, based on the skin you have selected for the site. Error messages viewed on a site with the Aqua skin will differ from those on a site with the Developer Toolbox skin, or even from those with a custom skin.

Error messages' components use the skin CSS files to define the colors, fonts and other attributes. In order to make the error messages for your particular application match the entire site appearance, you can simply edit the CSS file containing the error message definition classes. These classes can be found in the CSS files of the current skin's, in the tng.css file (e.g. in the includes/skins/aqua/ folder). The following examples are taken from the aqua skin.

There are two portions of CSS code that relate to error messages styles:

• The client-side related error display properties. These take effect when client-side validation, or evaluation fails, and an error message must be displayed. The various classes control colors, borders and fonts, and each of them is commented:


333

/* The client-side error displaying */ /* How the label should change on error */ .form_validation_field_error_label { /* color:#cc0000; */ } /* How the input's container (TD) should change on error */ .form_validation_field_error_container { /* border: 2px solid black; */ } /* How the input textfield should change on error */ .form_validation_field_error_text { /* border:2px solid #cc0000; */ } /* The actial error message style */ .form_validation_field_error_error_message { color:#cc0000; font-weight: bold; clear:left; } form.form_validation_form_error table { border: 2px solid red; }

• The server-side error display properties. Whenever an error occurs in the code that is executed on the server, these classes control the appearance:

/* The server-side error displaying */ /* topmost error div */ #KT_tngerror { padding: 10px 10px 10px 80px; margin:5px; font-family: 'Lucida Grande', Geneva, Arial, Verdana, sans-serif; font-weight:bold; font-size: 12px; color: #555555; background-color:#f2f2f2; background-image:url(images/error.gif); background-repeat:no-repeat; background-position:1% 50%; border: solid 1px #4F72B4; } /* trace container ( iniitally collapsed), and "Submit this... " area */ #KT_tngdeverror, #KT_tngtrace { padding: 5px 10px 5px 5px; margin:5px; border: solid 1px #4F72B4; color: #555555; background-color:#f2f2f2; font-family:Courier, monospace; font-size: 12px; } #KT_tngdeverror a, #KT_tngdeverror a:visited, #KT_tngdeverror a:active, #KT_tngdeverror a:hover, #KT_tngtrace a, #KT_tngtrace a:visited, #KT_tngtrace a:active, #KT_tngtrace a:hover { font-family: 'Lucida Grande', Geneva, Arial, Verdana, sans-serif; font-weight: bold;


334

font-size: 14px; text-decoration: none; color: #555555; padding: 0px 5px 0px 12px; margin-right: 0px; } #KT_tngdeverror a:hover, #KT_tngtrace a:hover { text-decoration: underline; } /* alignment and borders for the form submit buttons */ #KT_tngdeverror #KT_needhelp { text-align: right; } #KT_tngdeverror label, #KT_tngtrace label { display: block; font-family: 'Lucida Grande', Geneva, Arial, Verdana, sans-serif; font-weight:bold; } #KT_tngtrace ul { padding-left:10px; margin-left:10px; } #KT_tngtrace_details { display: none; } #KT_tngwarning { padding: 10px 10px 10px 50px; margin:5px; font-family:Verdana, Arial, Helvetica, sans-serif; font-weight:bold; color: #0000CC; font-size: 12px; border:1px solid blue; background-color:#E4FFFF; background-image:url(images/warning.gif) ; background-repeat:no-repeat; background-position:left; }

For the above settings, if a client-side validation fails, the error message that is displayed inline with the field looks like:

Let's change the color for the error message to green. To do so, you must first look in the client-side classes, and find the one controlling the error message's properties.

The only class defining how the text will look (bold, and with the red color) is the following:


335

/* The actual error message style */ .form_validation_field_error_error_message { color:#cc0000; font-weight: bold; clear:left; }

In order to display the message in green, simply replace the color value from #cc0000 to green: color:green;

In the same manner you can customize all other error elements that appear on client or server -side errors. One thing to mention is that when you change the site's skin in the Developer Toolbox Control Panel, the changes made for one skin's CSS will not be visible for another.

Change the content (text)The error messages that are displayed in applications created with Developer Toolbox, or products that are also a part of the bundle, can be of three types:

• Error messages that are added by the user with the use of the Throw Error trigger. The text for these error messages are entered by the developer, and as such, can be modified by editing the server behavior.

• General error messages that are not set from trigger interfaces (e.g. SQL errors, etc). These messages are stored in the application resources - the site's folder / includes/resources. In order to customize error messages to your choice, simply open the resource file corresponding to the specific product (e.g. NXT.res.php for Dynamic Lists and Forms), locate the error message that is already displayed and change it. Upload the modified files to your site's remote server, and when the error occurs again, the new message will be displayed.

• Internal error messages. These cannot be customized, as they are displayed only when severe errors occur, and customization can no longer be processed anyway.

Extend Transaction EngineThis section presents some advanced operations that can be performed in a site application when benefiting from the Transaction Engine.

Create custom transactionsA Custom Transaction can have as main operation any SQL statement or no SQL statement at all, just a set of instruc-tions. It is generally used to execute more complex INSERT/UPDATE/DELETE statements.

Let's build a custom transaction that executes an insert statement and then redirects to another page using some of the submitted values.

We'll start the page by including the Transaction Engine classes:


And then create the unique page dispatcher object:


336




Next comes the code for defining the custom triggers, but they will be displayed in detail later. After this, the actual Custom Transaction is instantiated and the custom triggers are added to the new Transaction:

// make an instance of the transaction object $customTransaction1 = new tNG_custom($conn_test); $tNGs>addTransaction($customTransaction1);

// register triggers $customTransaction1>registerTrigger("STARTER", "Trigger_Default_Starter", 1, "POST", "MM_custom"); $customTransaction1>registerTrigger("BEFORE", "TriggerBEFORE_AddField1", 1); $customTransaction1>registerTrigger("BEFORE", "Trigger_Default_Validate", 1, $Validate1); $customTransaction1>registerConditionalTrigger(@$_POST['cb'] == 1, "END", "TriggerEND_Redirect1", 98); $customTransaction1>registerTrigger("END", "TriggerEND_Redirect1", 99);

The above code is similar to that of a classic insert. What comes next is particular for the custom transaction: You can set the actual SQL string to be executed:

// set transaction SQL $customTransaction1>setSQL("INSERT INTO users (UserID, Forename, Surname, Email, Level) VALUES ({UserID}, {Forename}, {Surname},{Email}, {Level})");

The above SQL statement is different from a classic SQL insert statement because it doesn't contain values to be inserted, but placeholders, or mark-up language, such as {FieldVariable}. They are replaced with their corresponding values at runtime because the Transaction has columns registered to it and knows how to get the values:

$customTransaction1>addColumn("Surname", "STRING_TYPE", "POST", "Surname", ""); $customTransaction1>addColumn("Email", "STRING_TYPE", "POST", "Email", "[email protected]"); $customTransaction1>addColumn("Level", "NUMERIC_TYPE", "POST", "Level", 2); $customTransaction1>addColumn("UserID", "STRING_TYPE", "POST", "UserID", "");

Finally, execute the transaction and get the result Recordset:

$tNGs>executeTransactions(); $rsCustom = $tNGs>getRecordset("custom"); $row_rsCustom = mysql_fetch_assoc($rsCustom); $totalRows_rsCustom = mysql_num_rows($rsCustom);

As you can see in the above code, the getRecordset() method of the dispatcher doesn't receive a table name as parameter (like in the insert/update transactions), but a default string (“custom”).

Create custom triggersThere are two custom triggers that are registered to the Custom Transaction presented in the previous section: TriggerBEFORE_AddField1 and TriggerEND_Redirect1. The other two triggers are standard ones, present for the regular Insert Transaction section.


337

If you compare the SQL statement's columns and the columns added by addColumn() method, you'll notice that {Forename} is only present in the SQL statement. This means that the Custom Transaction will not know how to evaluate the {Forename} placeholder at runtime. The solution is to use the TriggerBEFORE_AddField1 to add the Forename field to the transaction:

//trigger AddField1 function TriggerBEFORE_AddField1(&$tNG) { $tNG>addColumn("Forename", "STRING_TYPE", "EXPRESSION", "{Surname} used as Forename"); return null; }

The only method type allowed when using addColumn() after the transaction has started is “VALUE”. Also, please notice the use of an expression to set the value of Forename.

The other custom trigger used in this Custom Transaction is an END custom redirect trigger:

function TriggerEND_Redirect1(&$tNG) { $redObj = new tNG_Redirect($tNG); $redObj>setURL("insert.php?UserID={UserID}&Forename={Forename}&Email={Email}"); $redObj>setKeepURLParams(true); return $redObj>Redirect(); }

The actual redirect is done using an instance of the tNG_Redirect object. Also notice the use of setURL(..) method that (like evaluateFieldExpr(..)) can replace the placeholders used in the passed parameter string with their actual values.

Transaction recordsetThis section presents the recordset generated by the current transaction. The recordset is generated from the database using the information set for the transaction (table name, database columns, database columns type, primary key, etc). The dispatcher will search through all the transactions and find which one generated a recordset.

For instance, if the page has an Update Transaction, the dispatcher will return the recordset generated by the Update Transaction (select the row corresponding to the primary key of the Update Transaction; the columns of the recordset will be the columns added to the transaction by the addColumn method).

The recordset appears in both the Bindings panel and in the Server Behavior panel.

For more information regarding the dispatchers, see “Concepts” on page 312.

Why is it required?The transaction recordset represents an unified way to pre-fill a form with the default values (either on insert or on update) and to keep the values submitted when an error was thrown in the executing Transaction. This way, the form can be easily refilled with the already entered values, directly from the recordset.

Differences from the regular recordsetThe Transaction Recordset, like regular recordsets, appears in both the Bindings and Server Behaviors tabs of the Application panel.

The Bindings tab will show the collection of all columns referred in all the transactions from the current page.


338

The Server Behaviors tab will show the recordset as a normal server behavior. There will be some differences as the user will not be able to delete or edit this recordset. Instead it will be pointed to delete or edit the transaction it is related to, as the recordset has no meaning by itself.

When a transaction will be edited, the recordset will be affected as follows:1 If there is a change in the transaction column list, the Bindings tab's content will be updated.

2 If the transaction table is changed:

• If there is another transaction for the same table then nothing will be inserted into the page (in addition to the transaction code changes), but it may have an impact on the Bindings tab as the number of columns may change.

• If there is no transaction for the same table then a new Get the Transaction Recordset code will be inserted into the page for that table.

Deleting the transaction will also affect the recordset:1 If there is not another transaction for the same table, the recordset will be removed.

2 If there is another transaction for the same table, the Binding tab will present a new set of columns as their number may change.

Generated codeThe recordset code is inserted after the transaction initialization and it looks like the sample below:

// Get the transaction recordset $rsdepartments_dep = $tNGs>getRecordset("departments_dep"); $row_rsdepartments_dep = mysql_fetch_assoc($rsdepartments_dep); $totalRows_rsdepartments_dep = mysql_num_rows($rsdepartments_dep);

Using the Transaction RecordsetThe Transaction Recordset is used by default by all the transactions provided with this product.

As a standalone recordset, it can be used in the regular manner by the developers, all normal operations being supported.

From the developer’s point of view there will be no differences in relation with the recordset usage. The code generated into the page after a 'drag & drop' operation from the Bindings tab will be the same with the code for the standard recordset.

How user interface persistence worksThe User Interface persistence is one of the features in Developer Toolbox that allows interfaces remember settings that have already been set. This way, repeating the same action is much faster, because settings are automatically filled by the persistence.

You can turn persistence on or off, as you need it, from the Developer Toolbox Control Panel, the User interface persistence and database caching entry.

Developer Toolbox saves persistence data in an XML file that is stored in Dreamweaver's Configuration folder. On PC systems, running windows, you can find this file in:


339

<system drive>\Documents and Settings\<current user>\Application Data\Macromedia\Dreamweaver MX\Configuration\persistence.xml.

On MacOS, the file is located in:

[MAC HDD] /Users/[user]/Library/Application Support/Macromedia/ Dreamweaver MX 2004/Configuration.

This file is generated if User Interface Persistence is enabled and at least one element that stores data in the file has been used. The xml file stores the following elements:

• as a first level tag, the persistence version. This is useful as when switching different versions of persistence (e.g. when you upgrade the product). different options might be enabled.

• as a second level, the server model is saved as a node

• on the third level node, the user interface that generated the data is recorded

• actual data is stored as node tags on the fourth level.

A sample structure of the persistence.xml file can be seen below:

Through the persistence.xml file, for each server model the following information is saved:

• The last connection and table used.

• The last settings used in a server behavior or wizard : database connections and primary keys, as well as primary keys types, regardless of the site they've been used on.


340

• For each connection, the names of the tables involved are stored. For each table, column properties (label, display as and submit as elements) are saved as well.

Some server behaviors and wizards share part of the information stored in the user interface persistence (e.g. between the Dynamic Lists and Form, between the Transaction Engine wizards and Dynamic Lists and Forms etc). The only condition to meet in order to achieve this sharing is to use the same database connection.

Default values for the form fields are stored as well, even if the form field uses a recordset. When the same connection is used, the user interface persistence will also generate the recordsets associated to form fields. (e.g. for a dynamic menu that uses a recordset, if the same field on the same database connection has been already set up once, the recordset providing the default values is automatically generated).

Download - Adobe Dream Weaver Developer Toolbox Help

Top Related