02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page iii
Professional
Adobe®Flex 2 TM
Rich Tretola Simon Barber Renaun Erickson
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page ii
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page i
Professional
Adobe®Flex 2 TM
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page ii
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page iii
Professional
Adobe®Flex 2 TM
Rich Tretola Simon Barber Renaun Erickson
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page iv
Professional Adobe®Flex 2 TM
Published by Wiley Publishing, Inc. 10475 Crosspoint Boulevard Indianapolis, IN 46256 www.wiley.com Copyright © 2007 by Wiley Publishing, Inc., Indianapolis, Indiana Published simultaneously in Canada ISBN: 978-0-470- 10267-1 Manufactured in the United States of America 10 9 8 7 6 5 4 3 2 1 Library of Congress Cataloging-in-Publication Data Tretola, Rich, 1971Professional Adobe Flex 2 / Rich Tretola, Simon Barber, Renaun Erickson. p. cm. Includes index. ISBN 978-0-470-10267-1 (pbk.) 1. Internet programming. 2. Application software--Development. 3. Web site development--Computer programs. 4. Flex (Computer file) I. Barber, Simon, 1980- II. Erickson, Renaun, 1977- III. Title. IV. Title: Professional Adobe Flex Two. QA76.625.T74 2007 005.2'768--dc22 2007008855 No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8600. Requests to the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475 Crosspoint Blvd., Indianapolis, IN 46256, (317) 572-3447, fax (317) 572-4355, or online at http://www.wiley.com/go/permissions. LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: THE PUBLISHER AND THE AUTHOR MAKE NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS WORK AND SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE. NO WARRANTY MAY BE CREATED OR EXTENDED BY SALES OR PROMOTIONAL MATERIALS. THE ADVICE AND STRATEGIES CONTAINED HEREIN MAY NOT BE SUITABLE FOR EVERY SITUATION. THIS WORK IS SOLD WITH THE UNDERSTANDING THAT THE PUBLISHER IS NOT ENGAGED IN RENDERING LEGAL, ACCOUNTING, OR OTHER PROFESSIONAL SERVICES. IF PROFESSIONAL ASSISTANCE IS REQUIRED, THE SERVICES OF A COMPETENT PROFESSIONAL PERSON SHOULD BE SOUGHT. NEITHER THE PUBLISHER NOR THE AUTHOR SHALL BE LIABLE FOR DAMAGES ARISING HEREFROM. THE FACT THAT AN ORGANIZATION OR WEBSITE IS REFERRED TO IN THIS WORK AS A CITATION AND/OR A POTENTIAL SOURCE OF FURTHER INFORMATION DOES NOT MEAN THAT THE AUTHOR OR THE PUBLISHER ENDORSES THE INFORMATION THE ORGANIZATION OR WEBSITE MAY PROVIDE OR RECOMMENDATIONS IT MAY MAKE. FURTHER, READERS SHOULD BE AWARE THAT INTERNET WEBSITES LISTED IN THIS WORK MAY HAVE CHANGED OR DISAPPEARED BETWEEN WHEN THIS WORK WAS WRITTEN AND WHEN IT IS READ. For general information on our other products and services please contact our Customer Care Department within the United States at (800) 762-2974, outside the United States at (317) 572-3993 or fax (317) 572-4002. Trademarks: Wiley, the Wiley logo, Wrox, the Wrox logo, Programmer to Programmer, and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates, in the United States and other countries, and may not be used without written permission. Microsoft and Excel are registered trademarks of Microsoft Corporation in the United States and/or other countries. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor mentioned in this book. Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books.
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page v
To the love of my life, Kim, and my beautiful daughters, Skye and Coral. — Rich Tretola The work on this book is dedicated to my family and friends, most notably Phil, Tina, Joanna, and Kimberley. — Simon Barber The book for Einar and Ranel, my love to Eve and the boys. — Renaun Erickson
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page vi
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page vii
Credits Contributing Writers
Production Manager
Marco Casario Marc Leuchner Andrew Muller
Tim Tate
Vice President and Executive Group Publisher Richard Swadley
Executive Editor Chris Webb
Vice President and Executive Publisher Joseph B. Wikert
Development Editor Kevin Shafer
Compositor Laurie Stewart, Happenstance Type-O-Rama
Technical Editors Charles Freedman Andy McIntosh Drew McLean Clint Modien Josh Tynjala
Project Coordinator
Production Editor
Indexer
Christine O’Connor
Robert Swanson
Copy Editor
Anniversary Logo Design
Kim Cofer
Richard Pacifico
Editorial Manager Mary Beth Wakefield
Hether Kolter
Proofreader James Brook, Word One
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page viii
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page ix
Acknowledgments This book would not have been possible without the hard work of my co-authors Simon and Renaun, and I want to thank them both for their contributions. I would also like to thank the Acquisitions Editor, Chris Webb, and the Development Editor, Kevin Shafer, for their commitment to getting the project completed through many challenges. Special thanks to the members of the Internet Services team at Herff Jones, including Michael McKellip, Jeff Titus, Bill Davis, Tim Johnson, Rob Schimp, Brent Johnson, and my manager, Jeff Patrick. The support of these team members and management has enabled me to transition my development career to be focused on Rich Internet Application development. Most importantly, I would thank my wife, Kim. She has given me two beautiful daughters, Skye and Coral, and is my best friend. Without her support, it would not have been possible for me to transform my career path to software development. She has supported me through good times and bad, and has always believed in me, and for this I am eternally grateful. Aloha no au ia 'oe. — Rich Tretola Thank you to my co-authors, Rich and Renaun; without you this would never have been possible. Also, I would like to thank Chris Webb, the Acquisition Editor, for all his hard work in making this book a success. Many thanks go out to my family, co-workers, and friends, without whom this would not have been possible. — Simon Barber I would like to first thank Chris Webb for helping me become a part of this project. I would like to thank Rich and Simon for the opportunity to contribute as an author on the project. All the hard work of the editor Kevin Shafer and other technical editors is an experience I’ll never forget — thank you. — Renaun Erickson
02671ffirs.qxd:02671ffirs
4/20/07
11:21 AM
Page x
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xi
Contents Acknowledgments Introduction
ix xxvii
Part I: Getting Started
1
Chapter 1: Introducing Flex 2.0
3
Rich Internet Applications OpenLaszlo Ajax XUL Windows Presentation Foundation History of RIA Benefits of RIA
Overview of Flex Flex 2 Flash Player 9 Flex Builder 2 Flex Free SDK 2 Flex Data Services (FDS) Flex Charting
Summary
Chapter 2: Introducing Flex Builder 2.0 Flex Builder 2.0 Eclipse Standalone and Plugin Creating a Flex Project Flex Builder Perspectives The Development Perspective Source Mode The Development Perspective Design Mode The Debugging Perspective Debugging Your Application Starting the Debugger
Compiling Your Application Running Your Application Summary
3 3 4 4 4 4 4
5 5 5 6 6 7 8
8
9 10 10 14 14 15 19 19 22
23 24 24
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xii
Contents Chapter 3: Flex 2.0 Basics
25
Flex 2 Programming Model
25
MXML ActionScript Flex Class Library
Flex Charting Components
25 27 30
31
Charting Types
31
Flex Data Services
32
Data Management Service Messaging Service Publish-Subscribe Messaging Data Push RPC Services FDS Alternatives
Summary
Chapter 4: Using Flex Builder 2.0
32 33 33 34 34 34
34
35
Getting Started with Flex Builder
35
Learning Flex Builder Flex Builder Workbench Basics
36 40
Flex Builder Basics Working with Projects Running Applications Navigating and Customizing the Flex Builder Workbench
Developing with Design Mode Building a Flex User Interface Adding View States and Transitions Adding Interactivity with Behaviors
Programming Flex Applications Code Editing in Flex Builder
Summary
44 44 50 52
54 54 56 56
57 57
58
Part II: Developing in Flex 2.0
59
Chapter 5: Programming Languages
61
Developing MXML Applications UI Layout Using Containers UI Controls XML Namespaces
xii
61 61 63 63
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xiii
Contents Data Binding with Components RPC Services Data Validation Data Formatting Cascading Style Sheet (CSS) Skins Adding Effects Custom MXML Components
MXML Basic MXML Syntax MXML Naming Conventions
ActionScript Flex Components Separating ActionScript from MXML Developing ActionScript Components Performing Reflection
Handling Events Event Flow Event Class EventDispatcher Class Event Usage Propagation Priorities Subclassing Events Keyboard Events
Summary
Chapter 6: Building User Interfaces Visual Components Class Hierarchy UIComponent Class Component Sizing Event Handling Styling Components Adding Behaviors Applying Skins Modifying Components at Run-time Extending Components
Data Providers and Collections Data Providers Collections
64 65 67 68 69 70 72 73
74 74 74
75 75 78 79 80
84 84 85 85 86 88 90 91 92
93
95 95 95 96 97 98 101 103 104 104 105
106 106 109
xiii
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xiv
Contents IList Interface ICollectionView Collection Change Events Hierarchical Data Providers Remote Data Providers
111 112 115 117 119
Positioning and Sizing Components
120
Layout of Components Component Sizing Component Positioning and Layout Constraint-based Layout
120 121 122 123
Getting Familiar with Flex Controls Summary
124 125
Chapter 7: Customizing the User Interface Applying Behaviors Using Behaviors
Applying Styles Using Styles Using Local, Application, and Global Selectors
Applying Fonts Device Fonts Embedded Fonts FlashType Fonts
Skinning the Application Graphical Skins Programmatic Skins
Item Renderers Building Custom Item Renderers and Item Editors
Item Editors Overview of Cell Editing Process Editable Cell Returning Data from an Item Editor Sizing and Positioning an Item Editor Cell Editing Events
Tooltips Creating Tooltips ToolTipManager Class
Cursor Manager Adding and Removing Cursors Busy Cursor
Summary
xiv
127 127 128
131 132 133
134 134 135 136
140 140 141
143 144
147 147 147 148 148 149
152 153 155
157 157 158
159
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xv
Contents Chapter 8: Flex UI Topics Repeaters and Containers Using the Repeater Component Repeater Component Execution Process
Using View States Using Transitions Transitions Applied to View States Transition Event Handling Transition Action Effects Effects and Filters
Using the Drag-and-Drop Manager List Control Drag-and-Drop Functions Adding Drag-and-Drop Support to Other Components
Embedding Assets Images Fonts SWF and Sound Files
Using the History Manager Components with Built-in History Management Adding History Management to Components
Flex Printing Basic Printing Printing Multiple Pages Printing Grid Data
Communicating with the Wrapper Flex to JavaScript, JavaScript to Flex Verifying that JavaScript Has Loaded
Working with Shared Objects Saving and Reloading Data from Shared Objects
Designing Accessible Applications Enabling Accessibility in Your Application Components with Built-in Accessibility Customizing Your Components for Accessibility
Summary
Chapter 9: Flex Data Data Binding Using Binding to Variables with [Bindable] Binding Directly to Component Properties Data Modeling with Flex
161 161 161 162
165 167 167 169 170 170
171 171 172
175 175 176 176
177 177 177
180 181 181 182
183 183 185
187 187
189 189 189 189
190
191 191 191 192 193 194
xv
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xvi
Contents A Basic Data Model Using an External XML File Binding a Data Model to a Custom Component Binding Data to a Data Model
Validating Data Flex Built-in Validators Validating a Data Model Simple Data Validation Using errorString Testing Validation Events Validating with ActionScript
Formatting Data Flex Built-in Formatters Formatter Errors
Summary
Chapter 10: Flex Charting Flex Chart Examples Area Chart Bar Chart Bubble Chart Column Chart Line Chart Pie Chart Plot Chart Candlestick Chart HighLowOpenClose (HLOC) Chart
Charting Classes
194 195 196 198
200 200 201 203 204 207
208 208 210
211
213 213 215 216 218 220 222 223 225 226 228
229
Axis Label Axis Title Axis Renderer Grid Lines Axis Types ChartItem ChartItemEvent Hit Data Legend
229 230 230 231 231 232 232 232 232
Advanced Charting
232
Chart Events Drill-Down Charts Mixed Series Types
232 234 236
xvi
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xvii
Contents Multiple-Axis Charts Axis Rotation
Charting Effects SeriesInterpolate SeriesSlide SeriesZoom
237 239
240 240 240 240
Chart Style Examples Summary
241 244
Chapter 11: Data Access
245
Server-side Data
245
Flex Data Access RPC Services Data Management Service Messaging Service
245 246 247 248
Data Services Configuration
248
Service Configuration Files Message Channels Data Serialization Destinations and Security Configuring Logging Software Clustering Custom Error Handling
248 249 250 258 259 261 262
RPC Service Components
263
Defining RPC Components Calling a Service and Handling Results
263 264
RPC Services Configuration
265
Destination Configuration Destination Properties
265 266
Flex Messaging
267
The Basics of Flex Messaging Flex Messaging Architecture Producer Components Consumer Components
267 268 269 272
Message Service Configuration
274
Message Service Configuration Message Service Destination Configuration Building a Custom Message Service Adapter
Data Management Services Data Management Service vs. RPC Features
274 275 277
278 278
xvii
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xviii
Contents Data Management Service Data Flow Data Synchronization Conflicts
Distributed Data Distributed Data Application Class Mappings Data Synchronization Handling
Data Management Service Configuration Data Management Service Destination Configuration Data Push from Servers to Client
Summary
Part III: Creating and Extending Flex Components Chapter 12: Creating MXML Components Creating Simple MXML Components Scoping Your Components Styling Your Components Advanced MXML Components Adding Custom Properties and Methods to a Component
279 279
280 280 281 283
284 284 286
286
287 289 289 291 292 293 293
Creating Composite Components Template Components
295 297
Creating a Template Component Using a Template Component
297 298
MXML Interfaces Creating Interfaces Using Interfaces
Using IMXMLObject Summary
Chapter 13: Flex Component Properties Elements of a Component The package Statement import Statements Defining the Class Name The Default Constructor Defining Properties Defining Methods Overriding Methods Using super
xviii
302 302 302
303 304
305 305 305 306 306 306 307 309 311
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xix
Contents Creating a Simple ActionScript Component Implementing and Overriding UIComponent Methods Creating Advanced Components in ActionScript Summary
313 314 315 318
Chapter 14: Flex Components
319
Custom Events in Components
319
Dispatching Custom Events
Using Metadata Tags in Components [ArrayElementType] [Bindable] [DefaultProperty] [Embed] [Event] [Effect] [IconFile] [Inspectable] [InstanceType] [NonCommittingChangeEvent] [RemoteClass] [Style]
Compiling Components Compiling Components with Flex SDK Compiling Components with Flex Builder Deploying Components
Summary
Chapter 15: Custom Formatter, Validator, and Effect Components Custom Formatters Customizing the SwitchSymbolFormatter Class Extending the Formatter Class Custom Formatter Example Formatter Errors
Custom Validators Creating Effects Extending the Effect Class Extending the EffectInstance Class Custom Effect Example Extending the TweenEffect Class
319
321 321 321 324 324 325 326 327 327 328 328 330 330
332 332 332 338
340
341 341 341 344 345 346
347 349 349 350 350 353
xix
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xx
Contents Extending the TweenEffectInstance Class Custom TweenEffect Example Custom Effect Triggers
Summary
Part IV: Programming ActionScript 3.0 Chapter 16: Overview of ActionScript Programming Introduction to ActionScript What’s New in ActionScript 3.0 Compatibility with Previous Versions
Getting Started with ActionScript ActionScript 3.0 Is More than Flex ActionScript 3.0 Coding Considerations Running ActionScript Applications
Display Programming Understanding the Display Architecture Working with Display Objects Using the Core Display Classes
Summary
Chapter 17: Data Types and Classes Value Types Primitive Data Types Complex Data Types
Dates and Times Creating Calendar Dates and Times Retrieving Time Values by Unit Date Manipulation
Strings Length Property Characters in Strings String Comparison Obtaining String Representations of Objects Concatenation Patterns and Substrings Uppercase and Lowercase Conversion
Arrays Index Arrays
xx
353 354 357
359
361 363 363 364 366
367 367 372 373
374 374 376 381
387
389 389 390 390
391 391 392 393
395 395 395 396 396 397 397 399
399 399
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxi
Contents Associative Arrays Multidimensional Arrays Cloning Arrays
Error Handling Error Types Custom Error Classes Exception Handling
Regular Expressions Regular Expressions and Strings Using the RegExp Class Using Groups
XML Introduction to XML E4X Introduction E4X Classes
Summary
Part V: Building and Deploying Flex 2.0 Applications Chapter 18: Building and Deploying Flex Applications Flex Framework and Application Directory Structure Flex and Flash Player Security and Technology Concerns Network Security Concerns Open Technology Concerns Flash Player Security Features
Building and Deploying Applications Building for Flex 2 SDK Building for Flex Data Services 2 Compiling an Application Deployment Directory Structure
Applying Flex Security Flex Security Features
403 407 408
408 408 411 414
415 415 416 417
418 418 420 420
426
427 429 429 432 432 433 434
435 436 437 439 442
445 445
Improving Startup Performance
447
Startup Order Using Deferred Creation Deferring Component Creation Using Ordered Creation Using the callLater() Method
447 449 452 455 458
Summary
460
xxi
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxii
Contents Chapter 19: Debugging and Testing Logging Overview
461 461
Flash Debug Player Logging API Compiler Logging Web-tier Logging
462 463 464 464
Client-side Logging
464
Using the Logging API Custom Logger
Flex Builder Debugging Tools Invoking Configuring Breakpoints and Stepping
465 465
471 472 472 475
Command-line Debugger
475
Invoking Configuring Debugger Commands
475 476 477
Summary
Chapter 20: Deploying Flex Applications Deployment Considerations Server-side and Client-side Caching Deployment Options RSL Deployment Flash Player Sandbox and Cross-Domain Consideration
Deploying a Flex 2 SDK Application that Uses RSL Compiling for Deployment Troubleshooting Tips and Common Deployment Problems
478
479 479 481 485 485 487
488 493 497
Asset and Dependent Files Run-time Data Access Proxy Server Accessing Server-side Resources from Different Domains
497 498 498 499
Deploying a Flex Data Service Application Under Tomcat Configuring for FDS Creating a Wrapper
500 506 508
Migrating and Transferring Files Defining Features mxmlc Compiler
xxii
509 510 511
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxiii
Contents Adding Features to the Wrapper Creating a Wrapper that Supports Web Standards and
512 514 518
Using Express Install Editing Your Wrapper Configuring Express Install on Flex Data Services Upgrading Without Express Install Summary
520 521 525 526 527
Part VI: Advanced Flex 2.0 Chapter 21: Using the Cairngorm Framework
529 531
The Cairngorm Framework Understanding Frameworks
531 532
Application Frameworks Architectural Frameworks
532 532
Building an Application Using the Cairngorm Framework Value Object and Model Locator Pattern The View The Front Controller, Cairngorm Event Broadcaster, and Command Patterns Business Delegate and Service Locator
Summary
Chapter 22: Using the Flex-Ajax Bridge Why Use Flex with JavaScript? Requirements for the FA Bridge Memory-Consumption Issues Flex-Ajax Bridge Samples Using Flex Validators from JavaScript Create Flex Components Using JavaScript
Summary
Chapter 23: Using the ActionScript 3.0 Libraries Types of Libraries How to Include the SWC in Your Application Building a Simple Application Using One of the Libraries Summary
533 534 537 541 545
547
549 549 550 551 551 551 555
559
561 562 562 565 571
xxiii
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxiv
Contents Chapter 24: Using ColdFusion/Flex Connectivity Using the Flash Remoting Update Using the Flex Messaging Event Gateway The Structure of Messages
Using the ColdFusion Event Gateway Adapter Using the Flex Data Service Assembler Configuring ColdFusion Value Object CFC EmployeeAssembler.cfc The DAO.cfc
ColdFusion Extensions for Flex Builder 2 Eclipse RDS Support Plugin Installation Create CFC Wizard ActionScript to CFC Wizard CFC to ActionScript Wizard Services Browser
Summary
Part VII: Integration Techniques Chapter 25: Rich Media Integration Integration Audio Video Using the Camera
Building an Application with Rich Media Integration The Inner Workings of the Application
Summary
Chapter 26: Integration with External Applications Using the External API
573 573 583 585
587 591 591 594 595 596
597 597 601 604 605 605 606
606
607 609 610 610 610 612
613 617
620
621 621
AVM1 and AVM2 SWF Communication
622
ExternalInterface and LocalConnection Building Custom Tracing Utility
625 626
Flash Player Process Structure Using LocalConnection and C# .NET Windows Application
Summary
xxiv
626 627
641
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxv
Contents Appendix A: Flex 2.0.1
643
Run-time CSS Support ASDoc Tool
643 647
ASDoc Tags and Syntax Documenting the Logger Classes Using the ASDoc Compiler Documenting the Logger Classes – Continued
647 648 649 650
Building Modular Flex Applications Summary
657 663
Index
665
xxv
02671ftoc.qxd:02671ftoc
4/20/07
11:22 AM
Page xxvi
02671flast.qxd:02671flast
4/20/07
11:23 AM
Page xxvii
Introduction The Flex product line was originally released by Macromedia in 2003, then followed up by Flex 1.5, and now Flex 2 by Adobe in 2006. Flex 2 marks a milestone for the Rich Internet Applications (RIAs) development community because it has developed into a mature product with excellent development tools and resources. Although previous versions were expensive and targeted large corporations, this has changed with Flex 2 because the new pricing model puts the power of Flex into the hands of all developers and companies for as little as free. Developers worldwide rejoiced when Adobe announced that it would be releasing portions of Flex at no charge, as well as a very reasonably priced development environment for those who choose to use it. Flex applications run within the Flash Player, which is the single-most downloaded piece of software in the history of the Internet. Because so many people already have the Flash Player and the Flash Player is so easily upgraded, Flex applications being built today will be available to run on a large section of the population’s computers. There is a growing wave of excitement around Flex, and we find ourselves in the early stages of a revolution of the Internet. Flex will play a large part in reshaping the Internet from the 1990s into a new, richer, more interactive Internet, sometimes referred to as Web 2.0. A great opportunity exists to make your mark on Web 2.0 by using Flex technologies, and this book will help you get there.
Who This Book Is For If you have been using Flex since its version 1 release (or you are someone who is starting with Flex), this book will provide valuable information for handling just about any possible request during the development of your applications. It will also prove itself to be an invaluable resource as a reference manual. The examples provided throughout this book are concise and very easy to understand. Code samples within this book have been carefully written so that they can be easily applied to real-world applications. If you are someone who wants to start building Flex applications (or is already doing so), this book will help you take your applications to a higher level.
What This Book Covers This book covers all aspects of Flex 2, including the Software Development Kit (SDK), Flex Data Services (FDS), Flex Builder 2 Integrated Development Environment (IDE), Flex Charting, and much more. You will learn about MXML (which is a tag-based programming language), as well as ActionScript 3 (which is the companion scripting language), and where to use each. This book will also show you how to use Flex components and how to create your own custom components. You will see how to structure your applications with frameworks and best practices.
02671flast.qxd:02671flast
4/20/07
11:23 AM
Page xxviii
Introduction
How This Book Is Str uctured This book has been broken down into seven sections, each covering specific areas of Flex. These sections are as follows: ❑
Getting Started — This section introduces Flex and Flex Builder. It covers some of the Flex basics and demonstrates how to use Flex Builder.
❑
Developing in Flex 2.0 — This section focuses on building user interfaces, customizing those interfaces, accessing data from your Flex application, and Flex charting components.
❑
Creating and Extending Flex Components — This section shows you how to create components using both MXML and ActionScript, as well as how to customize them.
❑
Programming ActionScript 3.0 — This section discusses programming and data typing ActionScript classes.
❑
Building and Deploying Flex 2.0 Applications — This section focuses on building, debugging, and deploying Flex applications. It also covers the configuration of the integrated JRun server.
❑
Advanced Flex 2.0 — This section discusses the usage of the Cairngorm Framework, the Flex-Ajax Bridge, ActionScript 3.0 libraries, and ColdFusion/Flex connectivity.
❑
Flex 2.0 Integration Techniques — The last section covers integration with rich media and external applications.
Appendix A also includes an overview of Flex 2.0.1, and discusses what is new with this updated release of Flex 2.
What You Need to Use This Book Although all of the examples in this book were created using the Windows operating system, almost all will also run perfectly on the other operating systems supported by Adobe. For the best results, you should use Flex Builder to compile the examples in the book. However, if you are a non-GUI kind of person, you can certainly compile them using the free Flex SDK.
Conventions To help you get the most from the text and keep track of what’s happening, a number of conventions have been used throughout the book.
Boxes like this one hold important, not-to-be forgotten information that is directly relevant to the surrounding text.
Tips, hints, tricks, and asides to the current discussion are offset like this.
xxviii
02671flast.qxd:02671flast
4/20/07
11:23 AM
Page xxix
Introduction As for styles in the text: ❑
Important new terms and important words are highlighted when they are introduced.
❑
Keyboard strokes are shown like this: Ctrl+A.
❑
Filenames, URLs, and code within the text are shown like this: persistence.properties.
❑
Code is presented in the following two ways:
In code examples, new and important code is highlighted with a gray background. The gray highlighting is not used for code that’s less important in the present context, or has been shown before.
Source Code As you work through the examples in this book, you may choose either to type in all the code manually, or use the source code files that accompany the book. All of the source code used in this book is available for download at http://www.wrox.com. Once at the site, simply locate the book’s title (either by using the Search box or by using one of the title lists), and click the Download Code link on the book’s detail page to obtain all the source code for the book. Because many books have similar titles, you may find it easiest to search by ISBN; for this book the ISBN is 978-0-470-10267-1. Once you download the code, just decompress it with your favorite compression tool. Alternatively, you can go to the main Wrox code download page at http://www.wrox.com/dynamic/books/download .aspx to see the code available for this book and all other Wrox books.
Errata We make every effort to ensure that there are no errors in the text or in the code. However, no one is perfect, and mistakes do occur. If you find an error in one of our books (such as a spelling mistake or faulty piece of code), we would be very grateful for your feedback. By sending in errata you may save another reader hours of frustration and at the same time you will be helping us provide even higher quality information. To find the errata page for this book, go to http://www.wrox.com and locate the title using the Search box or one of the title lists. Then, on the book details page, click the Book Errata link. On this page, you can view all errata that has been submitted for this book and posted by Wrox editors. A complete book list including links to each book’s errata is also available at www.wrox.com/miscpages/booklist.shtml.
If you don’t spot “your” error on the Book Errata page, go to www.wrox.com/contact/techsupport .shtml and complete the form there to send us the error you have found. We’ll check the information and, if appropriate, post a message to the book’s errata page and fix the problem in subsequent editions of the book.
xxix
02671flast.qxd:02671flast
4/20/07
11:23 AM
Page xxx
Introduction
p2p.wrox.com For author and peer discussion, join the P2P forums at p2p.wrox.com. The forums are a Web-based system for you to post messages relating to Wrox books and related technologies and to interact with other readers and technology users. The forums offer a subscription feature to email you topics of interest of your choosing when new posts are made to the forums. Wrox authors, editors, other industry experts, and your fellow readers are present on these forums. At http://p2p.wrox.com you will find a number of different forums that will help you not only as you read this book, but also as you develop your own applications. To join the forums, just follow these steps:
1. 2. 3.
Go to p2p.wrox.com and click the Register link.
4.
You will receive an e-mail with information describing how to verify your account and complete the joining process.
Read the terms of use and click Agree. Complete the required information to join, as well as any optional information you wish to provide, and click Submit.
You can read messages in the forums without joining P2P, but in order to post your own messages, you must join. Once you join, you can post new messages and respond to messages other users post. You can read messages at any time on the Web. If you would like to have new messages from a particular forum e-mailed to you, click the Subscribe to this Forum icon by the forum name in the forum listing. For more information about how to use the Wrox P2P, be sure to read the P2P FAQs for answers to questions about how the forum software works, as well as many common questions specific to P2P and Wrox books. To read the FAQs, click the FAQ link on any P2P page.
xxx
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 1
Part I: Getting Started Chapter 1: Introducing Flex 2.0 Chapter 2: Introducing Flex Builder 2.0 Chapter 3: Flex 2.0 Basics Chapter 4: Using Flex Builder 2.0
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 2
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 3
Introducing Flex 2.0 Flex 2.0 is arguably the most important new Internet development tool set released to date. It will help speed the migration of the Internet to the Web 2.0 that we have been promised for so long now. Not only has Adobe introduced an extremely easy-to-use development environment in Flex Builder 2.0, but it has also released an SDK allowing for Flex Rich Internet Applications to be developed with absolutely no fees. So what are Rich Internet Applications? Let’s start with a definition.
Rich Internet Applications A Rich Internet Application (RIA) is an application that runs in the traditional browser but utilizes an intermediate layer that can bypass the traditional page refresh that has been a standard of most current Web applications. The most common tools that can achieve this intermediate layer include JavaScript used in Asynchronous JavaScript and XML (Ajax) applications, as well as Flex or Flash using the Flash Player. Other RIA solutions include OpenLaszlo (which utilizes the Flash Player as well as Ajax), XUL (which is dependent on a Mozilla-compatible browser), and the Windows Presentation Foundation (which is part of the Microsoft .NET Framework 3.0).
OpenLaszlo Like Flex, OpenLaszlo can compile to SWF and, because it is open source, it is also free for developers to use. OpenLaszlo applications are built using JavaScript, as well as an Extensible Markup Language (XML) based programming language named LZX, and compiled to SWF. It is very similar to Flex, and because it was available for free, it garnered a larger amount of attention during the days of Flex 1.5. Because OpenLaszlo compiles to SWF, it enjoys the same write-once-run-anywhere feature that is synonymous with Flex and Flash applications. The one advantage to OpenLaszlo over Flex is that the next version of OpenLaszlo (code-named legals) will allow write-once-and-compile to either an SWF or a dynamic HTML (DHTML), or Ajax, application. The major disadvantages of OpenLaszlo are that it has a smaller set of built-in components than Flex, and it has always been at least one full version behind in optimization for the most current Flash Player.
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 4
Part I: Getting Started
Ajax Ajax is a combination of HTML or Extensible HTML (XHTML), Cascading Style Sheets (CSS), and JavaScript to create an application-type feel from a standard Web page request. CSS and JavaScript can be used to trigger updates to the visual aspect of the page, and XMLHttpRequests can be used to fetch data in the background of the page. The combination of these techniques allows a single Web page to change its appearance and update its data without any additional page requests from the server. There are many limitations to this type of RIA, including compatibility issues with browser versions, as well as differences in (or lack of) JavaScript support necessary for the RIA to perform as expected.
XUL XML User Interface Language (XUL) is an XML-based language developed by the Mozilla project. It is a tag-based language that contains many predefined widgets (buttons, radio buttons, and so on) that will be rendered only by a Mozilla-compatible browser such as Firefox. Although it can also be used in the creation of RIAs, XUL has been most widely used in the creation of Mozilla applications and extensions.
Windows Presentation Foundation Windows Presentation Foundation (WPF) consists of an engine and a framework that will be preinstalled in Windows Vista, and introduces Extensible Application Markup Language (XAML) as a new tag-based language. XAML is very similar to MXML because it is a tag-based XML language with attributes whereby each tag creates an object model class. XAML tags are fully extendable, allowing developers to create custom classes. XAML, along with C# (which is the programming language), would correspond to MXML and ActionScript 3 in Adobe Flex. WPF is used for both traditional desktop applications and browser-based RIAs. With Microsoft’s backing, WPF and XAML are sure to make a large contribution to Web 2.0 and RIA. Microsoft has stated that it will also introduce Windows Presentation Server Everywhere (WPF/E), which will provide support for other browsers and platforms. One major advantage of WPF is that it will support three dimensions out of the box, which is something that has been lacking in the Flash Player. A disadvantage of WPF is that it does not run within the Flash Player, and it will be a long time before Microsoft can expect the same penetration of its runtime as the Flash Player.
History of RIA Although the concept of a Web application that performs more in line with the traditional desktop application has been around for years, RIAs were first introduced by Macromedia in March 2002.
Benefits of RIA RIAs offer many benefits over traditional Web applications. Following are a few of the many advantages of RIAs:
4
❑
RIAs offer a richer interface that provides a more engaging user experience without the need for page reloads.
❑
RIAs offer real-time feedback and validation to the user, triggered by user events.
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 5
Chapter 1: Introducing Flex 2.0 ❑
The look and feel of a traditional desktop application can be accomplished with an RIA.
❑
RIAs also can include a full multimedia experience, including audio and video.
❑
RIAs have capabilities such as real-time chat and collaboration that are either very difficult or simply impossible with traditional Web applications.
Over view of Flex Flex was developed to create a development environment that more closely resembled the traditional development environment utilized by other programming languages. The goal was to take the already tremendously successful Flash visual development environment and open it up to programmers who are more comfortable with a code-based model. In 2004, Macromedia released Flex 1.0, which caused a buzz in the world of RIAs because it was the first time that it was possible to compile Flash SWF files from code. In 2005, Flex 1.5 was released, which was a big improvement over Flex 1.0 and included many new features. A few of the notable new features included new charting components, updates to the datagrid component, and new component-skinning techniques for more control over the look and feel of Flex 1.5 applications. Flex 1.5 was very successful, but was still targeted to the mid- to large-size company, and it was priced that way. For smaller companies and developers, Flex 1.5 was simply out of reach because of Macromedia’s pricing model. In 2006, Adobe released Flex 2.0 and announced that it was now possible to create and distribute Flex 2.0 applications absolutely free. This has created a large influx of developers into the Flex community, and shows tremendous growth potential.
Flex 2 Flex 2 is a tremendous upgrade over its predecessor. It includes a new version of the MXML tag-based language, as well as a new version of ActionScript. Adobe has built the Flex 2 Framework to be fully extendable, allowing developers to create custom components that extend or combine base components using either MXML or ActionScript 3. Flex 2 is built to run within the all-new Flash 9 Player, which in itself includes huge performance increases over previous versions. Flex 2 includes a new development environment built on the Open Source Eclipse integrated development environment (IDE) named Flex Builder 2, the free Flex 2 SDK, as well as the new Flex Data Services (FDS) application server. Flex 2 also offers a new set of charting components that are not part of the basic free versions of the Flex SDK but can be purchased separately or as part of a Flex Builder package.
Flash Player 9 In May 1996, a small company named FutureWave Software released a product that it called FutureSplash Animator. FutureSplash was released as a browser extension using the new plug-in API from Netscape. Ironically, FutureWave attempted to sell its technology to Adobe, but at the time, Adobe wasn’t interested. Macromedia was interested in FutureSplash, and, in December 1996, acquired FutureWave Software. Macromedia renamed FutureSplash as Flash Player 1.0.
5
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 6
Part I: Getting Started Following is a timeline of key events in this history of the Flash player: ❑
1997 — FutureSplash is renamed and released as Macromedia Flash 1.0.
❑
1997 — Flash 2 adds buttons, the Library, sound support, and color tweens.
❑
1998 — Flash 3 adds new animations and alpha transparency.
❑
1999 — Flash 4 adds MP3 audion streaming and motion tweens.
❑
1999 — 100-millionth download of the Flash Player.
❑
2000 — Flash 5 adds ActionScript 1.
❑
2000 — Flash Player installs reach the 92 percent penetration mark.
❑
2002 — Flash Player 6 adds support for Flash remoting, Web services, video, shared libraries, and components.
❑
2003 — Flash Player 7 introduces ActionScript 2.0 and streaming audio and video.
❑
2005 — Flash Player 8 adds filter effects, GIF and PNG images, bitmap caching, new video codec (On2 VP6), file upload and downloading, and FlashType.
❑
2006 — Flash Player 9 is released and introduces ActionScript 3, E4X XML parsing, regular expressions, and binary sockets.
The introduction of Flash Player 9 in 2006 represents the most significant release of any Flash Player to date. The incorporation of ActionScript 3 brings true object-oriented programming to Flex 2 and the upcoming Flash 9 authoring tool. Flash Player 9 boasts performance increases of up to ten times over Flash Player 8. Flash Player 9 is based on the ECMAScript standard and adds new features, including ECMAScript for XML (E4X), regular expressions, a standardized event model, and binary sockets. Flash Player 9 also includes better memory utilization, improved application initiation speed, as well as improvements in the debugger and error reporting.
Flex Builder 2 Flex Builder 2 is the new development tool that (although it is not necessary for Flex development because any text editor can be used) offers the most complete development environment for rapidly creating Flex applications. Because Flex Builder 2 has been built on top of the mature Eclipse IDE, it will be very familiar to developers who have already been developing software in other languages using Eclipse as their tool of choice. Eclipse is a development environment that was built with extendability in mind, and this can also work to the benefit of Flex developers because it can be customized to suit the needs of the Flex developer. Chapter 2 provides a more comprehensive look into Flex Builder 2.
Flex Free SDK 2 The Flex Software Development Kit (SDK) is a free download from Adobe and includes the Flex framework (component class library), compiler, and debugger. Using the text editor of your choice, you can create the ActionScript and MXML files for your application, and then compile to SWF using the SDK. The SDK allows for data communication via Web services, HTTP services, and Flash remoting with ColdFusion as the back-end server.
6
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 7
Chapter 1: Introducing Flex 2.0
Flex Data Services (FDS) FDS is the server version of Flex that must be installed under any Java 2 Enterprise Edition (J2EE) server. FDS is essentially the next generation of Flex 1.5, which was sold only as a server. As well as a full commercial edition, the FDS server is available in an Express edition, which is free and available for commercial use (but is limited to one CPU without clustering). FDS is made up of several components and capabilities, including the following: ❑
Flex Messaging Services (FMS)
❑
Publish-subscribe messaging
❑
Data push
❑
RPC services
Flex Messaging Services FMS is one of the pieces that make up FDS, and it allows for the creation of applications that support real-time messaging, as well as collaboration. The messaging service has support for Java Message Service (JMS), as well as other existing messaging services, allowing for the creation of cross-platform chat applications.
Publish-Subscribe Messaging FMS uses the producer/consumer publish-subscribe metaphor, which allows for the creation of co-browsing applications. To understand what is meant by a co-browser application, imagine a company’s customer service representative being able to make edits to a form on the user’s screen in real time while the user watches.
Data Push Data push is the capability for the server to push data changes to the client without any user interaction or polling of the servers. This can be critical when an application has hundreds or thousands of users connected, and they can all see changes to business-critical data in real time. This is a feature that is available only when using the FDS server.
RPC Services Remote procedure call (RPC) services are the suite of services used to connect to external data. They include the following: ❑
WebService — The WebService component can be used to access any Web service that complies with the WSDL 1.1 standard and returns data formatted as Simple Object Access Protocol (SOAP) messages over HTTP.
❑
HTTPService — The HTTPService component can send HTTP GET, POST, HEAD, OPTIONS, PUT, TRACE, or DELETE requests. It does not support multipart requests.
❑
RemoteObjects — The RemoteObject component uses Action Message Format (AMF) to transfer data that is a binary format and is the fastest of the RPC services. It is an ideal way to interact with server-side Java objects that are within the FDS server’s source path. It can also be
7
02671c01.qxd:02671c01
4/20/07
11:24 AM
Page 8
Part I: Getting Started used to connect to local or even remote ColdFusion servers. Both Java objects and ColdFusion components can be mapped to ActionScript objects, allowing for seamless integration between the server-side and client-side objects. The WebService and HTTPService components are included for free with the Flex SDK, whereas the RemoteObject component is available only for use with the FDS server (Commercial or Free Express Edition) or ColdFusion 7.02.
Flex Charting The Flex charting components are a set of rich charting components that enable easy development of professional dashboard and business intelligence (BI) systems. The charting components are sold as a stand-alone product or bundled with Flex Builder 2. A free trial of the charting components is available from Adobe. You can learn more about the charting components in Chapter 10.
Summar y This chapter defined RIA and gave some examples of the benefits of RIA, as well as the software options available for creating RIAs. It also provided an overview of Flex and its history, as well as the pieces that make up Flex. Most of the information on Flex covered in this chapter is covered in more depth later in this book. Chapter 2 introduces the all-new Flex Builder 2 built on top of Eclipse.
8
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 9
Introducing Flex Builder 2.0 One of the most significant pieces of the new Flex 2 product family is the all-new Flex Builder 2. The original Flex Builder was built on top of Dreamweaver, and, to put it bluntly, the community was not shy about letting Macromedia (now Adobe) know just how bad Flex Builder 1 actually was. Fortunately for the Flex development community, Macromedia acknowledged this, decided to scrap it completely, and started over using Eclipse as the base for Flex Builder 2. Flex Builder 2 is light years ahead of the original, and most developers now use it as the tool of choice for doing Flex MXML and ActionScript development. Most modern systems will not have any problems running Flex Builder 2. Following are the official requirements from Adobe for Flex Builder on Windows: ❑
Intel Pentium 4 processor
❑
Microsoft Windows XP with Service Pack 2, Windows XP Professional, Windows 2000 Server, Windows 2000 Pro, or Windows Server 2003
❑
512MB of RAM (1GB recommended)
❑
300MB of available hard-disk space
❑
Java Virtual Machine: Sun JRE 1.4.2, Sun JRE 1.5, IBM JRE 1.4.2
Following are the official requirements for Mac (as of this writing, the Mac version is still in beta): ❑
PowerPC or Mactel (1GHz or greater)
❑
Mac OS X 10.4.7
❑
1GB of RAM recommended
❑
300MB of available hard-disk space
❑
Java Virtual Machine: Sun JRE 1.5
❑
Eclipse 3.2 (plugin configuration only)
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 10
Part I: Getting Started
Flex Builder 2.0 Eclipse Standalone and Plugin Flex Builder 2 is available in two different distributions. The standalone version operates exactly the same as the plugin version, but is a lighter-weight application. The standalone version runs on top of a strippeddown version of Eclipse, which makes it a smaller install and a smaller memory footprint. However, for those who have already been using the full version of Eclipse for other development (such as Java, ColdFusion, and so on), Flex Builder comes as a plugin that installs into Eclipse, just like the many other Eclipse plugins. If you are using the Eclipse standalone version with a previous ActionScript plugin, it is recommended that you uninstall it before installing the Flex 2 plugin to avoid any conflicts with file associations.
Creating a Flex Project To create a Flex project, simply choose New and then Flex Project from the File menu, as shown in Figure 2-1.
Figure 2-1: Creating a new Flex project
10
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 11
Chapter 2: Introducing Flex Builder 2.0 Choose the way you want your application to access data and how it should be compiled, as shown in Figure 2-2. Selecting Basic will automatically compile your application each time you save a file within Flex Builder. If you choose Flex Data Services (FDS) as your method for accessing data, you also have the option to compile your application using the FDS server at run-time. Next, as shown in Figure 2-3, enter a project name and either browse to a location or choose the default location for your project file storage.
Figure 2-2: Selecting the type of project
Figure 2-3: Defining the storage location of project files
11
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 12
Part I: Getting Started Next, you will need to name the main file for your application. Figure 2-4 shows this step with the main application file being named Index.mxml. Note that you should not name the main file of your application the same as an existing component or a component you intend to build. This could create bizarre, non-verbose conflicts in the project. At this point, you can switch to the Library Path tab to add SWC libraries to your project. You can also choose to add SWC files to your project after it has been created. Choose either the Add SWC Folder or Add SWC button to add the library to the project (Figure 2-5). To add a library to an existing project, simply right-click the project name within the Navigator window and choose Properties. Next, select Flex Build Path and then choose the Library Path tab (Figure 2-5). Choose either the Add SWC Folder or Add SWC button to add the library to the project. For more information on SWC files, see Chapter 14.
Figure 2-4: Naming the main application file
12
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 13
Chapter 2: Introducing Flex Builder 2.0
Figure 2-5: Adding a library during project creation
Figure 2-6: Adding a library to an existing project
13
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 14
Part I: Getting Started
Flex Builder Perspectives Flex Builder has multiple perspectives. A perspective defines a set of editors and view panels that are useful to the task at hand. For example, Flex Builder will switch to a different perspective if you are debugging an application. Switching to a perspective will alter the views and editors that show within the Eclipse application. Switching perspectives will happen automatically in some situations. The default perspective is the Development perspective, and it includes a Source mode (Figure 2-7) and a Design mode. The other perspective is the Debugging perspective.
Figure 2-7: The Development perspective in Source mode
The Development Perspective Source Mode The Source mode is a basic code editor that will include code hints, code completion, syntax coloring, and real-time error reporting for both MXML and ActionScript code. Figure 2-8 shows the Development perspective with the Outline view of the Source mode enabled. The Outline view shows the hierarchy of your MXML code when editing an MXML file, or the properties and methods of your class files when editing an ActionScript class. Either way, you can go directly to a line of code by clicking the entry in the Outline views.
14
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 15
Chapter 2: Introducing Flex Builder 2.0
Figure 2-8: Outline view of Development perspective in Source mode
The Development Perspective Design Mode As shown in Figure 2-9, switching to the Design mode makes available two panels on the right-side screen: the States panel and Components panel. The Editor panel located in the middle of the screen changes to become a visual editor, allowing the drag-and-drop positioning of components, as well as drag-and-drop of components from the Components panel. The States panel allows you to create new states that can be designed visually as well. For more information on how to use states, see Chapter 8. Note that you cannot switch to Design mode when editing an ActionScript file. It is only available for editing MXML files. Note that, by default, the Components panel appears in the same pane as the Outline view on the left of the screen, and the States and Properties appear on the right. Another part of Design mode, the Properties view, has multiple sections, as well as the following property view options: ❑
Standard property view options — There are three separate sections within the Standard view of the Properties view: ❑
Common section — This allows for editing of the component properties, as shown in Figure 2-10.
15
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 16
Part I: Getting Started
Figure 2-9: The Development perspective in Design mode
Figure 2-10: The Common section of the Properties view
16
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 17
Chapter 2: Introducing Flex Builder 2.0 ❑
Style section — As shown in Figure 2-11, this makes use of color selectors, sliders, combo boxes, and buttons to allow for easy editing of the selected component’s style properties. The changes are reflected in real time within the design editor.
❑
Layout section — This is the area where you make changes to layout properties, including width and height when working in directional layouts. It also includes x, y, and the layout constraints when working within an absolute layout. Use the checkboxes within the constraint options section to anchor the selected component to one or more corners of the parent container. Figure 2-12 shows the Layout section with a component anchored to the bottom-right corner of the parent container. Any changes made will be reflected in the design editor in real time.
❑
Category property view options — The Category view shown in Figure 2-13 is a tree layout of the available properties. They can be edited by updating the text fields next to each property. Some of the text fields will include visual editors to make editing of colors and known property options easier.
❑
Alphabetical property view options — As shown in Figure 2-14, the Alphabetical view includes all of the same properties shown in the Category view, but in a simple alphabetical list, rather than a tree layout.
To use the Properties view to make changes to your components, simply click a component within the design editor, which will update the Properties panel to show the options available for the selected component.
Figure 2-11: The Style section of the Properties view
17
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 18
Part I: Getting Started
Figure 2-12: The Layout section of the Properties view (note that the controls shown will not be available if the application is not using absolute layout)
Figure 2-13: The Category view of the Properties view
18
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 19
Chapter 2: Introducing Flex Builder 2.0
Figure 2-14: The Alphabetical view of the Properties view
The Debugging Perspective Switching to the Debugging perspective allows you to run the Flex debugger, set breakpoints, watch variables, and step through your code. To switch to the debugging perspective, simply choose Flex Debugging perspective from the perspectives menu at the top-right corner of the editor, as shown in Figure 2-15. The Flex Debugging perspective will not be available as shown in Figure 2-15, unless it has been opened at least once before. To show it for the first time, you must either click the Open Perspective button in the top right or navigate to Window ➪ Perspective ➪ Flex Debugging.
Debugging Your Application Flex Builder 2 offers debugging capabilities that allow you to find bugs within your application. A debugger allows you to stop and start the application to find problems, or to examine or substitute values for variables. To debug your application, you must first switch your perspective to the Flex Debugging perspective using the buttons within the tabs at the top of the editor window, as shown earlier in Figure 2-15. Once you are in the Flex Debugging perspective, you can set breakpoints by right-clicking the line of code you wish to break on, and selecting Toggle Breakpoint from the context menu, as shown in Figure 2-16. You can also simply double-click the line of code to toggle on and off a breakpoint. Note that the Debugging perspective is automatically opened when a breakpoint is encountered, or when a run-time error is thrown.
19
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 20
Part I: Getting Started
Figure 2-15: Switching to Flex Debugging perspective
Figure 2-16: Adding a breakpoint
20
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 21
Chapter 2: Introducing Flex Builder 2.0 The Debugging perspective also includes views to read, edit, and watch variables, manage breakpoints, and watch expressions. These include the Console view, the Variables view, the Breakpoints view, and the Expressions view.
Console View The Console view displays any trace statements that are within your source code while your application is running within a debug session. This view will become one of your best friends while debugging your Flex applications. The Console view also displays run-time errors.
Variables View The Variables view of the debugger allows you to easily copy, find, change, and watch your variables while debugging your application. To do so, simply right-click a variable name, and then use the context menu shown in Figure 2-17 to perform any of the aforementioned functions. Selecting Watch from the context menu will add the variable to the Expressions view (discussed shortly).
Figure 2-17: Variables view of the Debugging perspective
The Variables view contains many icons and symbols that can be a bit confusing. The following table provides definitions for the various symbols. Symbols
Definition
Red Square
Defines a private variable
Green Circle
Defines a public variable
Yellow Diamond
Defines a protected variable
Blue Diamond
Defines an internal variable
Orange Box (Package)
Defines a variable scoped to a user-defined namespace
21
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 22
Part I: Getting Started The following table provides definitions for the various icons. Icons
Definition
C icon
Defines a constant variable
D icon
Defines a dynamic variable
S icon
Defines a static variable
Getter Icon
Indicates that the variable has a getters
Breakpoints View The Breakpoints view is an easy place to manage your breakpoints while in a debugging session. As shown in Figure 2-18, you can right-click a breakpoint and use the context menu to change the status, or to remove a breakpoint. You can also use the breakpoints toolbar for additional functionality, including jumping to the breakpoint within the source code, skipping all breakpoints, as well as expanding and collapsing the breakpoint tree.
Figure 2-18: Breakpoints view of the Debugging perspective
Expressions View Use the Expressions view to add and edit expressions on the variables you are watching. You can also choose to re-evaluate the expressions you are watching because the data may have changed as you proceeded through the debug session. As shown in Figure 2-19, you can right-click an expression and use the context menu.
Starting the Debugger To run the debugger and start a debugging session, click the arrow next to the bug button on the toolbar, and then select the application you wish to debug. If the application is not listed, choose Debug As and select Flex Application, as shown in Figure 2-20. Chapter 19 provides more information on debugging.
22
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 23
Chapter 2: Introducing Flex Builder 2.0
Figure 2-19: Expressions view of the Debugging perspective
Figure 2-20: Running an application in debug mode
Compiling Your Application Flex Builder 2 will compile your application as you build it, unless you specifically tell it not to by unchecking Build Automatically in the Project menu. Each time you save a file, Flex Builder will compile the SWF file, as well as generate the wrapper files and supporting files for running, debugging, and history management. By default, these files are compiled to the bin directory within your project, although this can be changed within the Flex Build Path section of the project properties.
23
02671c02.qxd:02671c02
4/20/07
11:24 AM
Page 24
Part I: Getting Started
Running Your Application To run your application, you must simply select the down arrow next to the green arrow button on the toolbar, and then select the application you wish to run from the list (Figure 2-21). If the application is not yet in the list, choose Run As and select Flex Application. To run the same application again, you can simply select the button with the green arrow.
Figure 2-21: Running an application
Summar y This chapter discussed the all-new Flex Builder 2 IDE. After reading this chapter, you should be able to create a project, edit it in either Source or Design view, and then run the application. This chapter also examined the tools available to use Flex Builder to debug your Flex application. Chapter 3 introduces the pieces that make up Flex. This includes the programming model, examples of MXML and ActionScript, the Flex class library, charting components, data services, and messaging services.
24
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 25
Flex 2.0 Basics The first two chapters of this book introduced you to the Flex 2 product line and the concepts of Rich Internet Applications (RIA). This chapter explains how to build a Flex 2 application using the Application Model. First, before you build anything, you are introduced to the XML markup language (MXML) and ActionScript. The following section, “Flex 2 Programming Model,” explains what the different elements are when developing your applications. The elements described are MXML, ActionScript, and the Flex 2 Framework.
Flex 2 Programming Model The Flex 2 Programming Model consists of MXML, ActionScript, and the Flex class library. To build a full-fledged application, you must have a good knowledge of all these technologies. To start off, you are introduced to the basics of MXML. Then you are shown how ActionScript and MXML work together to create powerful, rich user interfaces. The third element of the programming model is the Flex 2 Framework, which contains Flex components, managers, and behaviors. This component-based development model allows developers to incorporate pre-built components, extend the component library by creating new components, or combine pre-built components to create composite components.
MXML The first element of the programming model, MXML, is an XML language that defines the user interface for an application. MXML is also used to define non-visual aspects such as server-side data sources and bindings between the user interface and the server side.
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 26
Part I: Getting Started To write a Flex application, you must be able to write MXML and ActionScript. As mentioned earlier, MXML is an XML language that is used to lay out your user interface. MXML is very similar to HTML in that it provides tags for user interface elements. If you have worked with HTML, then MXML should be very familiar to you. MXML has a much broader tag set than HTML, and defines visual components such as data grids, buttons, combo boxes, trees, tab navigators, and menus, as well as non-visual components, Web service connections, data binding, and effects. The biggest difference between HTML and MXML is the MXML-defined file that is compiled into a Shockwave file (SWF) and rendered by the Flash Player. MXML can be written in a single file or in multiple files. MXML requires that you close off every tag that you declare in your Flex application. Otherwise, the Flex compiler will throw an error.
Example Application Using MXML One of the great things about MXML is that it can be written in a wide range of integrated development environments (IDEs) that support text editing because it’s a plain XML file. The following example shows the mandatory “Hello World” application. It consists of an tag and two children, the and tag.
The tag is always the root tag of a Flex application. The tag defines a Panel container that includes a title, title bar, status message, border, and an area for its children (that is, the control). The tag is a Label control that simply displays text. Figure 3-1 shows the “Hello World” application rendered in the Flash Player.
Figure 3-1: “Hello World” application rendered in the Flash Player
26
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 27
Chapter 3: Flex 2.0 Basics
ActionScript The second element of the programming model, ActionScript, extends the functionality of a Flex application. ActionScript provides control and object-manipulation features that are not available in strict MXML. The ActionScript programming language is used in Adobe’s Flash Player. Included are built-in objects and functions that allow you to create your own objects and functions like many object-oriented programming (OOP) languages. ActionScript 3.0 offers a robust programming model that is more familiar to developers with basic knowledge of OOP. ActionScript is executed by the ActionScript Virtual Machine (AVM), which is part of the Flash Player. The code is compiled into a bytecode format by the compiler, such as the one built into Flex Builder 2. ActionScript and JavaScript are very similar, so being familiar with JavaScript will make your life easier when using ActionScript. JavaScript is derived from The European Computers Manufacturers Association (ECMA) document ECMA-262, which is the international standard for the JavaScript language. ActionScript is based upon the ECMA-262 Edition 4 specification, so this is where the similarities come in between the two languages. ActionScript 3.0 contains a lot of new features, such as run-time exceptions, run-time types, sealed classes, method closures, ECMAScript for XML (E4X), regular expressions, namespaces, and new primitive types. All these new features allow the developer to speed up the development process. One important point to note is that Flex Builder 2 converts all MXML files into ActionScript before the code is compiled into bytecode for use with the AVM.
ActionScript in MXML Flex developers will find that ActionScript extends the capabilities of Flex when developing applications. In ActionScript, you can define event listeners, create new classes, handle callback functions, and define getters and setters, packages, and components. Following are some of the ways that ActionScript can be used in Flex applications: ❑
ActionScript is inserted between the tags. This code can be comprised of new functions, error handling, or events, and can perform any other tasks your Flex application may require.
❑
Create new components in ActionScript.
❑
Create new components and compile into SWC files (which are external components compiled to be reused in many applications).
❑
Extend existing components with ActionScript classes.
❑
Take advantage of ActionScript support for OOP concepts such as code reuse, inheritance, encapsulation, and polymorphism.
❑
Use global ActionScript functions that are available in any part of an SWF file where ActionScript is used, or in any user-defined class.
❑
Use the standard Flex components that comprise the Flex Class Libraries. All the components and libraries are written in ActionScript.
27
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 28
Part I: Getting Started Overview of ActionScript Compilation Process A Flex application can consist of MXML files, ActionScript classes, SWF files, and SWC files. The Flex compiler transforms the main MXML file and its children into a single ActionScript class linking in all the reference-imported classes. Once the transformation is complete, the end result is a single SWF file that can be deployed on the server. Every time you make changes to your application, a new SWF file is generated. You may find it more convenient to remove the reusable components and compile those into SWC files, which can be included in a library path for your application.
ActionScript Code in MXML ActionScript code is only allowed to be declared in between the following tag in MXML files:
Statements and expressions must be wrapped in functions; otherwise, you will receive a compiler error. Also, you cannot define classes or interfaces in the tag, because the MXML file you have defined is a class in itself. You may have noticed the odd CDATA construct. This is used to tell the compiler not to interpret the script block as XML, but rather as ActionScript. The tag must be located at the top-level component tag of the MXML file. Multiple tags can be defined, but for readability, it’s recommended to have them in one location. The following example shows ActionScript being defined in an MXML file:
28
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 29
Chapter 3: Flex 2.0 Basics In MXML, you can use ActionScript to refer to visual or non-visual components. You do this by specifying the id property of the component in MXML. Then you use id to refer to the component in ActionScript. The following example shows how this is achieved:
If you want to access the control, you must refer to the id property in ActionScript. To do this, the following code must be used: var str:String = lbl1.text;
The code gets the value from the Label control named lbl1.
Import and Include There is a noticeable difference between the terms “importing” and “including” in reference to ActionScript. Importing is adding a reference to a class file or package so that you can access the objects and properties of the external classes, as shown in the following example: import mx.controls.TextInput;
Including ActionScript is copying the lines of code of an external ActionScript file into another. This can either be done in the tag using the include directive, or the tag to add the ActionScript into your Flex applications. The following example is using the include directive within the tag:
Introduction to ActionScript Components This section provides a brief overview of how to create reusable components using ActionScript. Later in this book, you will build more complex components using MXML and ActionScript. Custom components can contain graphical elements, define some kind of business logic, or extend existing components in the Flex framework. Defining your own components in ActionScript has several advantages: ❑
Divide your application into individual models that can be developed and maintained separately.
❑
Implement commonly used logic within the components.
❑
Build a collection of components that can be reused among all your Flex applications.
29
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 30
Part I: Getting Started When creating custom components, you may find it useful to extend the component from the Flex class hierarchy. This allows you to inherit functionality already built into the Flex components. As shown in the following example, you can define a custom TextInput and derive it from the Flex TextInput control: package myComponents { public class MyTextInput extends TextInput { public function MyTextInput() { ... } ... } }
The filename of the control MyTextInput must be in a filename called MyTextInput.as and stored at the root of your Flex application in a subdirectory name myComponents. As you may have already picked up, the package name reflects the location of the component, myComponents. To use the custom component in your Flex application, you will need to write the following MXML:
The code xmlns:components=”myComponents.*” defines a namespace called components that points to the subdirectory myComponents. You can then reference the component as an MXML tag using the namespace prefix.
Flex Class Library The Flex 2 Framework contains Flex managers, components, and behaviors. The component-based model allows developers to incorporate pre-built components, create new ones, or combine components into composite components. Later in this book, you are introduced to more of the Flex 2 Framework. The following lists some of the common packages that you will use in your Flex application:
30
❑
mx.controls — Flex user interface controls
❑
mx.collections — Flex collection components
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 31
Chapter 3: Flex 2.0 Basics ❑
mx.charts — Flex charting components
❑
mx.utils — Flex utility classes
❑
flash.events — Flex event classes
❑
flash.net — Flex classes for sending and receiving from the network, such as URL downloading
and Flash Remoting There are many more packages in the Flex Framework, and listing them would be out of the scope of this chapter.
Flex Char ting Components The visual aspect that Flex charting offers over a simple table of numeric data is much easier for your Flex application users to comprehend. The Flex charting components are not included in the free Flex 2 SDK, and must be downloaded separately to use them inside your Flex application.
Charting Types Charts come in many different types, including the following: ❑
Area charts — The AreaChart control is used to represent data that emphasizes a change in values by filling in the portion of the graph beneath the line connecting various data points. The chart allows for an icon or symbol to represent each data point along the line or a simple line without any icons or symbols. These custom symbols are part of the built-in data series renderer functionality, which you learn about in future chapters.
❑
Bar charts — The BarChart control is used to represent data across categories, and is ideal for showing the variations in the value of an item over time, or for showing the values of several items at a single point in time. It is essentially a column chart rotated 90 degrees to the right.
❑
Column charts — The ColumnChart control is used to represent data using vertical bars (called columns) to display different values of one or more items. They are used to compare values across categories. They are ideal for showing the variations in the value of an item over time.
❑
Bubble charts — The BubbleChart control is used to represent data with three values for each data point. A bubble chart is a type of xy (scatter) chart. The first of the three values determines the position along the x-axis, the second value determines the position along the y-axis, and the third value determines the size of the bubble symbol.
❑
Candlestick charts — The CandlestickChart control is used to represent data that contains open, high, low, and close values for each time period you want to display. The hollow or filled portions of the candlestick are called the body. The long thin lines above and below the body represent the high/low range and are called shadows. The high is marked by the top of the upper shadow, and the low by the bottom of the lower shadow.
❑
Line charts — The LineChart control is used to represent data over time or categories as a series of points using coordinates. Icons and symbols can be used at each data point along the line with visual markers.
31
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 32
Part I: Getting Started ❑
Pie charts — The PieChart control shows the size of items that make up a data series proportional to the sum of the items. It always shows only one data series, and is useful when you want to emphasize a significant element in the data.
❑
Plot charts — The PlotChart control is used to represent data in Cartesian coordinates with one data point being along the x-axis and the other data point along the y-axis.
❑
HighLowOpenClose (HLOC) charts — The HLOCChart control is most often used to represent data for stock prices, but can also be used for scientific data (for example, to indicate temperature changes). The HLOCChart control does not require the data point that represents the opening value.
Chapter 10 provides more detail about the charting capabilities of Flex.
Flex Data Ser vices Flex Data Services (FDS for short) allows developers to build applications deployed on standard Java 2 Enterprise Edition (J2EE) servers. FDS provides connectivity with existing server-side data and business logic to create powerful business applications. FDS offers many great features, including the following: ❑
A robust messaging architecture that provides services that automatically synchronize data between client and server
❑
Real-time data push and publish-subscribe messaging
❑
Collaborative and disconnected applications
When developing an application, some consideration must be taken regarding how your data will flow from the client to the server and vice versa. FDS could be a viable option if you need the following features.
Data Management Service Developing RIAs requires more powerful data management compared to the traditional request/response model. Creating a richer and more powerful experience will require data-intensive applications, and with this, new challenges arise. This is where data management services make things simple when working with distributed data. Data Management Service adds functionality to provide data synchronization, data replication, and occasionally disconnected application services.
Data Synchronization This process is managed by FDS, and it removes the complexity and room for error by providing a highperformance data synchronization engine between client and server. Existing solutions can be integrated with data synchronization to provide an end-to-end solution.
32
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 33
Chapter 3: Flex 2.0 Basics Data Paging FDS takes care of paging large datasets, which allows you to focus your knowledge on application business logic instead of worrying about basic data management.
Messaging Service The Flex Messaging Service is comprised of the basic messaging functionality in the form of publishsubscribe API for Flex applications. This allows Flex and Flash clients to use publish-subscribe messaging to integrate with back ends that use Java Messaging Service (JMS) systems. Messages are sent asynchronously by passing packets of data (called messages) to and from a message service. A message is usually comprised of a header and a body, where the header contains the routing information and the body contains the application data. In the jargon of the world of messaging, an application that sends messages is called a producer and an application that receives messages is called a consumer. The producer and consumer need not know anything about each other, because the producer sends messages to a messaging destination and the messaging service routes it to the appropriate consumers. Figure 3-2 shows the flow of data from message producer to message consumer.
Data
Message producer
Channel
Destination
Message data flow
Channel
Data
Message consumer
Figure 3-2: Flow of data from message producer to message consumer
Publish-Subscribe Messaging Publish-subscribe messaging has been around for a while, and works asynchronously. The way it works is a producer creates a message and sends it to some predetermined destination. At the same time, a consumer attaches itself to the destination and listens for the sent messages. Producers and consumers (also known as message agents) collaborate by exchanging messages through a common gateway (which is the destination). Examples of applications that would benefit from the use of publish-subscribe messaging are stock trading services, inventory control, visualization tools, and any application that requires messages to be sent to multiple subscribers. Figure 3-3 shows a simple publish-subscribe message flow.
33
02671c03.qxd:02671c03
4/20/07
11:25 AM
Page 34
Part I: Getting Started
Producer/ Publisher
Message
Channel
Channel
Message
Consumer/ Subscriber
Channel
Message
Consumer/ Subscriber
Destination
Figure 3-3: Publish-subscribe message flow
Data Push In FDS, you can push data changes from the server to the client without polling the server. This is robust and highly scalable to allow pushing of data to thousands of concurrent users.
RPC Services You can develop a Remote Procedure Call (RPC) application without the use of FDS by using either HTTP services or Web services, and no server-side proxy service. To get the RPC service to work, it should either be in the same domain as the server hosting your application, or have a crossdomain.xml file on the remote server hosting your RPC service. FDS RPC functionality allows you to develop enterprise functionality into your applications, including servicing data from different domains, a white list of permitted RPC services, server-side logging, localization support, and client authentication. The RemoteObject component is used to access remote Java objects using Action Message Format (AMF), without exposing them as compliant Web services.
FDS Alternatives As of this writing, a company called Midnight Coders has an alternative solution to FDS called WebORB. It is a platform enabling development, deployment, and run-time execution of RIAs. The product allows connectivity between rich clients created with Flex, Flash, and Ajax, as well as server-side applications developed with .NET, Java, Ruby on Rails, and PHP. Most of these products will have an implementation of FDS in their commercial editions.
Summar y This chapter is just an overview of what’s to come in the world of Rich Internet Applications using Adobe Flex 2. Some of these topics may be a little over your head, such as the Flex Data Services, but you will quickly learn to integrate these technologies into your applications. Chapter 4, “Using Flex Builder,” is where all the fun starts. Flex Builder is something you will need to get familiar with quickly to enter the world of RIA development.
34
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 35
Using Flex Builder 2.0 Learning how to use the full potential of the Adobe Flex Builder 2 makes developing Flex applications easier and quite enjoyable. In the end, every application consists of text files, MXML, and ActionScript, which are compiled into a binary SWF file. The Flex Builder is the tool to help organize, visualize, create, and run commands on the application code. This chapter teaches you how to learn more about the Flex Builder from within the Flex Builder. It covers basic layout and workbench areas, as well as how to customize the workbench experience. Finally, you learn about Flex Builder’s ability to build applications with both the Design and Source views.
Getting Star ted with Flex Builder The Flex Builder is a fully integrated development environment (IDE). It provides tools to assist you in creating, debugging, packaging, and compiling code into SWF applications. Following are the included feature sets: ❑
Text editor — Flex Builder 2 provides separate editors for MXML, ActionScript, and CSS code. You do not need to keep track of which editor is for which file type. This is because the Flex Builder automatically handles it for you. The editors also provide features that are discussed in this chapter, including code hinting, navigation, formatting, commenting, and others.
❑
Design editor — The Design view editor is specific to the MXML editor. It provides a collection of views to help create components and applications visually by placing user-interface and data-access controls on the design mode stage.
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 36
Part I: Getting Started ❑
Navigation features — The Navigator and the Outline views provide the ability to navigate not only projects, but also components. Flex Builder also provides the functionality to open code through definition links and view editors with line numbers to help locate specific code.
❑
Build tools — The mxmlc compiler does all compiling of the applications, but what Flex Builder does is provide the ability to manage the process. You can configure projects to build automatically as you write code and save the file, or be built manually. Configuration settings are also set per project to give you full control of the compilation and deployment process.
❑
Integrated debugger — Flex Builder integrates the mxmlc compile-time errors with the Console view for easy access to error locations. Run-time debugging is handled through the Flex Debugging perspective and the associated Console, Debug, Variables, Breakpoints, and Expressions views.
❑
Integrated Adobe Flex 2 Help — The Flex Builder help system provides eight main categories, from how Flex works to the Flex 2 language reference. It also provides a list of links to other online Flex resources. The Dynamic Help view provides in real time contextual help as you write your code. Another help item is the Key Assist popup list, containing a quick view to all the shortcuts.
❑
Eclipse plugins and third-party tools — Eclipse provides a plugin architecture embraced by the community with many well-done projects to support other development requirements. Most common are development and version control plugins such as Ant, Tomcat, CVS, Subversion, and ColdFusion. Along with the plugin architecture, Eclipse allows you to configure external tools from within the Flex Builder.
If you have built applications with other comparable development environments, you will find that the Flex Builder and Eclipse platform provides extensive capabilities. Flex Builder 2 comes in two installation options. The first is the stand-alone Flex Builder with the prepackaged Eclipse environment included. The second option is to install Flex Builder as an Eclipse plugin into an existing Eclipse installation. Although this chapter uses the stand-alone Flex Builder in its examples, the information is still pertinent to the plugin edition as well. When installing the Flex Builder Eclipse plugin into an installation with other ActionScript or MXML plugins, you must resolve editor conflicts through the Eclipse preferences window.
Learning Flex Builder One of the most overlooked places to start learning about Flex Builder is the Flex Start Page. If you are like most developers, you probably vaguely remember seeing it the first time you opened up Flex Builder. Do not worry if you did skipped over it; you can bring the Flex Start Page back up by selecting Help ➪ Flex Start Page. The result is shown in Figure 4-1. The next step to finding extensive information on Adobe Flex 2 and related technologies is Flex Help itself. Figure 4-2 shows the Flex Builder Help system, which opens as a separate application outside of Eclipse when you select Help ➪ Help Contents from the Flex Builder menu system.
36
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 37
Chapter 4: Using Flex Builder 2.0
Figure 4-1: Flex Start Page
Figure 4-2: Flex Help application
37
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 38
Part I: Getting Started Figure 4-2 also shows the name of the eight main titles in the Flex Help library. The library is quite extensive, and many times you’ll want to narrow your search to specific sections of the library. You do this by clicking the blue “Search scope” link found on the top middle area of Figure 4-2. The search mechanism uses groups of topics as named search lists that can be selected as the current search scope. Figure 4-3 shows the two dialog windows used to create and select a search list for just the “Using Flex Builder 2” section of the Flex library. The selection of scope will now filter all search results to only pull information from the “Using Flex Builder 2” help section. The search scope not only affects the external help system, but also affects the Help view search mode available inside Flex Builder. You can see that in Figure 4-4, which demonstrates a search result on the term “debugging.” The search returns the same filtered results as the Help view search mode shown in Figure 4-5. The ability to use the external help application or the internal Help view search mode demonstrates the flexibility of Flex Builder’s options. One of the nice help features is called Dynamic Help. It uses the same help view area as the Help view search mode. Open the Dynamic Help view, shown in Figure 4-6, by selecting Help ➪ Dynamic Help.
Figure 4-3: Dialog windows used to create and select a search list
38
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 39
Chapter 4: Using Flex Builder 2.0
Figure 4-4: Search result on the term “debugging”
Figure 4-5: Help view search mode
39
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 40
Part I: Getting Started
Figure 4-6: Dynamic Help view
The Dynamic Help works as you select or move the editor cursor over key words. The Dynamic Help view shown in Figure 4-6 displays the reference link to mx.logging.Log in connection to the Log class in CustomLoggerMain.mxml source editor being highlighted. The Go To section in Figures 4-5 and 4-6 is another way to switch between the different modes of the Help view. Related Topics is another definition given to the Dynamic Help view mode. The bookmarks option displays a list of bookmarked help pages. You bookmark the current help page by clicking the Bookmark Document icon located in the top-right section of the help page. There it is — the power to pull information from the Flex library as you continue learning about Flex Builder from within the Flex Builder itself.
Flex Builder Workbench Basics The Flex Builder workbench is made up of perspectives, editors, and views. The following table provides definitions to better explain the basics of the Flex Builder workbench and other related topics.
40
Term
Definition
Perspective
A group of views and editors in a workbench.
Editor
Specific functionality to edit files of specific types.
02671c04.qxd:02671c04
4/20/07
2:31 PM
Page 41
Chapter 4: Using Flex Builder 2.0 Term
Definition
View
Container for functionality, also as known as panels.
Workspace
Defines an area of the file system that contains project resources.
Perspectives, Editors, and Views The grouping of views and editors related to what current development actions are taking place are organized in perspectives. Adobe Flex Builder 2 provides two default perspectives: one for development and one for debugging. Flex Builder provides hooks into the IDE to change perspectives automatically, depending on the task at hand. For example, when you create a new project and are not presently in the Flex Development perspective, a prompt will ask if you would like to switch perspectives, as shown in Figure 4-7.
Figure 4-7: Prompt asking if you would like to switch perspectives
The Flex Development perspective includes two modes that are dependent on the MXML editor. The first mode is Source mode, which also defines the layout for the perspective when an ActionScript or CSS editor is in use. The MXML editor in Design mode is the second mode of the Flex Development perspective. The following table shows the default development view configuration, as well as which Flex Development perspective mode the view appears in. The specific list of views in each perspective described here defines the default configuration layout. You can customize any perspective for your specific development environment needs. Chapter 2 introduces the basic views and provides figures for most of the views discussed here. View Name
Group
Typical Layout Area
Navigator
Source/Design
Left Side
Outline
Source/Design
Left Side
Editor
Source/Design
Middle
Continued
41
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 42
Part I: Getting Started View Name
Group
Typical Layout Area
Problems
Source/Design
Bottom
Components
Design
Left Side
States
Design
Right-Top
Properties
Design
Right-Bottom
The following table shows the default debugging view configuration, as well as which Flex Development perspective mode the view appears in. View Name
Group
Typical Layout Area
Navigator
Debugging
Left Side
Debug
Debugging
Middle-Top
Editor
Debugging
Middle
Variables
Debugging
Right-Top
Breakpoints
Debugging
Right-Top
Expressions
Debugging
Right-Top
Console
Debugging
Bottom
The following table shows the default optional views, as well as what groups and which Flex Development perspective mode the view appears in. View Name
Group
Typical Layout Area
Search
Any
Bottom
Console
Any
Bottom
Tasks
Any
Bottom
To open any view in the current perspective, select Window ➪ Other Views…, and a popup of all the available views will open. Figure 4-8 shows the dialog window that pop ups upon selecting the Other Views menu item.
42
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 43
Chapter 4: Using Flex Builder 2.0
Figure 4-8: Dialog window that pop ups when selecting other views
Later in this chapter, you learn how to navigate and customize the views in the Flex Builder workbench.
Workspace Workspaces are larger than perspectives, and allow you to organize resource and configuration groupings on the same machine. Each workspace must have a separate location on the file system. The process of creating new workspaces and retrieving old ones is called switching workspaces. You will find the menu item under File ➪ Switch Workspace…, as shown in Figure 4-9. Figure 4-10 shows the workspace switch dialog box. To select a new workspace you can browse or type in a new location on the file system.
Figure 4-9: Switching workspaces
43
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 44
Part I: Getting Started
Figure 4-10: Workspace switch dialog box
Switching to different workspaces makes sense if you work in different environments with many clients or separate projects. For example, an author of a book can create a workspace specific for the example projects needed to be published, but also keep a workspace for other clients or personal projects. Each workspace will reference different projects and can configure the layout of perspectives and views differently. If you have used other Adobe products, such as Flash 8 Professional or Dreamweaver, workspaces work similarly to the workspace layout feature found in those products.
Flex Builder Basics With the workbench and the basic parts explained in the previous sections, let’s examine how to use the workbench. The project is the most basic organizational unit used by the Flex Builder workbench. Managing and navigating the project and its resources make up a big part of a developer’s daily tasks.
Working with Projects There are three project types defined by the Flex Builder: Flex Project, ActionScript Project, and Flex Library Project. Figure 4-11 shows the three Flex Builder project types, along with the some other Eclipse basic projects. The icons next to the specific project wizard found in Figure 4-11 also show up in other places of the workbench, in particular the Navigator view. New projects can be created a few different ways:
44
❑
You can select a wizard by right-clicking in the Navigator view and selecting New ➪ Project..., or from the main menu’s File ➪ New ➪ Other….
❑
You can choose a specific project wizard type straight from the main menu by selecting File ➪ New ➪ , or from the context menu in the Navigator view New ➪ . The specific type options are Flex Project, ActionScript Project, or Flex Library Project.
❑
You can import a previous project by selecting from the main menu File ➪ Import…, or by selecting Import… from the context menu in the Navigator view. This method is not covered in the book, but is noted here for reference.
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 45
Chapter 4: Using Flex Builder 2.0
Figure 4-11: Three Flex Builder project types
Each project type has a specific wizard for creating a project. The wizard for creating a new Flex project walks you through the application data access setup, project file location, and the build path setup dialog windows. In particular, Figures 2-2 through 2-6 in Chapter 2 show the wizard dialog windows for creating a new Flex Project. The ActionScript Project is used for creating applications with ActionScript code that does not use any of the Flex Framework. The DrawCircles.as class introduced in the next section, “Multiple Applications,” is an example of an ActionScript application. The DrawCircles.as code is defined in Listing 4-1 later in this chapter. The non-Flex Framework application only needs to extend the Sprite class, and can be run just like a typical Flex application. The Flex Library Project is covered in the “Compiling Components with Flex Builder” section of Chapter 14. After creating the project, there are few things to learn about how to add and manage resources within the project. Projects can have multiple applications, link to external resources, be built automatically or manually, and publish source code.
Multiple Applications When you create a project, it creates a default MXML application file. There a multiple ways to add more applications to a project. The default MXML application file receives the same name as the project, unless the project name contains spaces or special characters. If the latter is the case, the filename is defaulted to main.mxml. Create a Flex Project with basic data access called Chapter4. You should see a Chapter4.mxml file as shown in Figure 4-12.
45
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 46
Part I: Getting Started
Figure 4-12: Chapter4.mxml file
The following steps outline the first of two methods on how to add multiple applications to the project:
1.
Create a new MXML application by selecting Flex ➪ New ➪ MXML Application, or by selecting New ➪ MXML Application from the right-click context menu from the Navigator view.
2.
Type MyApp into the filename input box located on the New MXML Application dialog window shown in Figure 4-13.
The first approach is quite simple, and creates the MXML application file for you, as well as assigning the application to the project. The green sideways triangle located over the top-left area of the MXML file icon indicates the file is a runnable application for the project, as shown in Figure 4-14. The blue circle over the bottom-right area of the MXML file icon indicates which application is the default runnable application.
Figure 4-13: New MXML Application dialog window
Figure 4-14: Sideways triangle located over the top-left area of the MXML file icon
46
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 47
Chapter 4: Using Flex Builder 2.0 The following steps outline the second approach to add an application to the project:
1. 2. 3.
Create a new MXML or ActionScript file. For example, select File ➪ New ➪ File. Name the file DrawCircles.as. Open the DrawCircles.as file and add the source code shown in Listing 4-1 to the file.
Listing 4-1: DrawCircles.as package { import import import import import
flash.display.Graphics; flash.display.Shape; flash.display.Sprite; flash.display.StageScaleMode; flash.display.StageAlign;
public class DrawCircles extends Sprite { private var childCount:int = 0; public function DrawCircles() { stage.scaleMode = StageScaleMode.NO_SCALE; stage.align = StageAlign.TOP_LEFT; doDrawCircle( 0x336699 ); doDrawCircle( 0x993333 ); doDrawCircle( 0x339933 ); } private function doDrawCircle( color:uint ):void { var child:Shape = new Shape(); child.graphics.beginFill( color ); child.graphics.lineStyle( 2, 0xCCCCCC ); child.graphics.drawCircle( 30, 40, 30); child.graphics.endFill(); child.x = (childCount * 65) + 10; child.y = 0; addChild(child); childCount++; } } }
4.
Right-click the DrawCircles.as file and select Set as Default Application. Or you can rightclick the Chapter4 project name and select Properties.
Note that the Set as Default Application menu item is disabled for ActionScript files in non-ActionScript typed projects in Flex Builder 2.0.1. You must change the nature of the project or create a new project of ActionScript project nature. Or you could manually set the default application through the project’s Properties window.
47
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 48
Part I: Getting Started 5. 6. 7.
Select Flex Applications, as shown in Figure 4-15. Click the Add… button and select the DrawCircles.as file, as shown in Figure 4-16. Click OK and go back to the workbench.
Now, DrawCircles.as will have an icon indicator showing that it is a runnable application. Click the DrawCircles.as file and run the application. The DrawCircles application is shown in Figure 4-17. You can now add MXML or ActionScript applications to any project you want to and know how to run it. A lot of the examples in the Flex language reference documentation are ActionScript applications, just like DrawCircles.as. Therefore, it’s important to understand how to run ActionScript applications.
Figure 4-15: Selecting Flex applications
Figure 4-16: Selecting the DrawCircles.as file
Figure 4-17: Running the DrawCircles application
48
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 49
Chapter 4: Using Flex Builder 2.0 Linking External Resources A linked folder on the file system links external resources in a project. Select File ➪ New ➪ Folder to activate the New Folder Wizard. Name the folder myPictures, click the Advanced ➪ button, and check the “Link to folder in the file system” checkbox, as shown in Figure 4-18. Click the Finish button and a folder pointing to the My Pictures folder is created in the project. This can be used for quick access to other resources from within the Flex Builder to save the developer from using an operating system file explorer application.
Figure 4-18: New Folder Wizard
Building Applications Automatically and Manually To set a project to build automatically, first click inside the Navigator view on the project name or a file in the project. Then, select Project ➪ Build Automatically. There are situations where manually building is warranted (for example, when you want the build script to run unit tests, move files, or manipulate other resources outside the Flex compiler). The most common methods of doing advanced manual builds use Apache Ant, which is out of the scope of this book. An important feature for any build process is the Clean command. To clean a project, select Project ➪ Clean… with the project you want cleaned selected in the Navigator view. The Clean command forces the build scripts to delete all cache and output files, and then compile all source files from scratch. This single feature can resolve a lot of build project compile issues, especially if you are changing large chunks of files within a project.
Publishing Source The project feature makes it easy to publish the source of your application. Figure 4-19 shows the wizard that opens by selecting Project ➪ Publish Application Source… from the main menu system.
49
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 50
Part I: Getting Started This feature works only for Flex applications. ActionScript applications will not have the View Source menu option on the right-click context menu. Running this feature inserts a value into the viewSourceURL property of the default MXML application tag. To access the published source, run the application and select the View Source context menu item when you right-click the SWF. Figure 4-20 shows what the generated publish source application looks like.
Figure 4-19: Publish Application Source Wizard
Figure 4-20: Generated publish source application
Running Applications After building your applications, you can run or debug them a couple of different ways from within Flex Builder. The content covered in this section does not discuss debugging, but many of the launch configuration options apply to debugging as well. In-depth information about debugging applications is covered in
50
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 51
Chapter 4: Using Flex Builder 2.0 Chapter 19. The simplest method of running an application is by pressing the green Run button, or by selecting Run ➪ Run . Applications can be configured to be run through a browser, or through the stand-alone player. The configuration option for running or debugging applications is called the launch configuration. Figure 4-21 shows the toolbar icon that allows you to open a specific application’s launch configuration for any applications in the currently selected project in the Navigator view. The Create, Manage, and Run Configurations dialog box provides three tabs with configuration options: Main, Source, and Common. To configure an application to run in a stand-alone Flash Player, uncheck the “Use defaults” checkbox in the Main tab. Then select the Run (or Debug) browse button, and select the application SWF file instead of the default HTML file, as shown in Figure 4-22.
Figure 4-21: Opening the launch configuration
Figure 4-22: Main tab of the Create, Manage, and Run Configurations dialog box
51
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 52
Part I: Getting Started Clicking the Run command launches the application in the stand-alone Flash Player. Other standard preferences located in the Windows ➪ Preferences ➪ Web Browser allow for the default browser used to run the application to be changed.
Navigating and Customizing the Flex Builder Workbench Customizing the workbench to your specific development needs revolves around the understanding of the topics from previous chapters. To change perspectives, you can click the perspective-specific button, or select the perspective from the drop-down list, as shown in Figure 4-23.
Figure 4-23: Changing perspectives
Also shown in Figure 4-23 is the ability to select the Other… option that allows adding other perspectives to the perspective toolbar. To create a new perspective, select the Window ➪ Perspective ➪ Save Perspective As… menu item. A dialog box will appear, where you fill in the new perspective name and click OK. The steps to delete a Flex Builder perspective are to go to Windows ➪ Preferences ➪ Perspectives, select the perspective, and click the Delete button. The current state of each view is saved for the current perspective automatically. There are a couple options to customize the layout of your views in a perspective. Each view can be minimized, restored, and maximized. A quick way to maximize and minimize views or editors is to double-click the view/editor tab containing the name of the specific workbench item. To move or dock a workbench item, view, or editor, click the tab area with the name and drag it to the new location. As you drag the workbench item over potential areas, a dotted line will appear, indicating the potential layout placement. If you want a particular view to live outside the Flex Builder’s layout constraints, you can right-click the view and toggle the Detached menu item. Detaching the view from Flex Builder then opens up a new window, which is not the layout constraint for the view. You can dock workbench items on the left, right, top, bottom, in layers, tiled, or many other ways. Figure 4-24 shows views and editors in various docking positions. A special layout feature in Flex Builder is called fast views. You can drag any view down into the fast view’s default lower left-hand corner location. The fast view places the view’s icon into a toolbar-like container, allowing for toggle-style visible views. The fast view toolbar can also be customized to be docked on the left, bottom, or right side of the Flex Builder.
52
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 53
Chapter 4: Using Flex Builder 2.0
Figure 4-24: Views and editors in various docking positions
Moving around the workbench can be greatly enhanced by learning more about the common keyboard shortcuts. You can view a quick list of the available shortcuts by selecting the Help ➪ Key Assist… menu item. All actions in the Flex Builder can be assigned new keyboard shortcuts through the Windows ➪ Preferences ➪ Keys configuration tabs. Moving around the code files is a very common task when using the Flex Builder. There a few good methods that help developers move around the files efficiently. The first is the open definition feature. To use this feature, click any property or object in a code file and press F3. For example, open up the DrawCircles.as file and select the doDrawCircle method on line 13, and press F3. The open definition action takes you to the declaration point of doDrawCircle. This works on methods, properties, and classes, including Flex Framework source files found in the Flex 2 SDK installation folder. The outline view is a very powerful tool to very quickly move around a class structurally. The outline view provides a tree structure of the class and its elements. By clicking a node in the outline tree, the editor updates to the correlating line in the code. The Navigation view has a specific feature called working sets, which can be defined to contain different resource items across projects. The set of commands to create, edit, and select working sets is found in the Menu icon on the Navigation view toolbar.
53
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 54
Part I: Getting Started The last navigation feature discussed here is the search functionality in the Flex Builder. To bring up the global search functionality, select the Edit ➪ Find in Files… menu item. The action will open a dialog box, shown in Figure 4-25, providing a search input box, filename filtering, and scope settings.
Figure 4-25: Search dialog box
Developing with Design Mode Flex Builder’s Design mode and supporting views provide the features to create applications visually. The Flex Framework visual components contain the following characteristics: ❑
Size
❑
Events
❑
Styles
❑
Behaviors
❑
Skins
The Design mode’s development workflow capabilities relate directly to manipulating the visual component’s characteristics. This is demonstrated in the following sections.
Building a Flex User Interface Follow these steps to create a basic application using Components view and Flex Properties view:
1. 2. 3. 54
Open the Chapter4.mxml file located in the Chapter4 project. Click the Design mode button. Drag a Label control from the Components view onto the stage area.
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 55
Chapter 4: Using Flex Builder 2.0 4.
5. 6.
Click the Label instance and then, in the Flex Properties view, change the following properties: ❑
ID — txtTitle
❑
Text — Professional Flex 2 by Wrox
❑
Constraint checkboxes — Left 20 and Top 20
Drag a Button control from the Components view onto the stage area. Click the Button instance and then, in the Flex Properties view, change the following properties: ❑
ID — txtSwitch
❑
Label — Switch
❑
Constraint checkboxes — Left 20 and Top 45
Figure 4-26 shows the proper layout of the controls on the stage, and the Flex Properties view displays the values for the Label control. Before continuing to the next part of the example, this is a good time to point out two icons on the Design mode editor toolbar. These two icons are the Refresh and Show Surrounding Containers (F4) icons located after the Design mode button and before the States combo box. You can also change the design stage size to a common resolution size, or change it to some custom values for your specific project needs. The Flex Properties category and alphabetical views both are methods of viewing the properties for controls or components currently selected.
Figure 4-26: Proper layout of the controls on the stage and Flex Properties view
55
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 56
Part I: Getting Started
Adding View States and Transitions The next step in developing the example application visually is to create states of the application. Each Flex application has a default state that all child states relate to. You can nest states relatively in a tree hierarchy structure. The hierarchical structure constrains the application state changes, but does not restrict how the states can be navigated. The example application will have a switchBottom state that moves the label and button to the bottom of the application.
1. 2. 3. 4. 5. 6. 7. 8. 9.
Open the States view and right-click the (start). Select the New State… context menu item. Name it switchBottom and click OK. Select the switchBottom state. The States combo box located in the Design mode editor’s toolbar can also be used to switch between states. Select the Label control and change the Top property to Bottom property with the same value. Select the Button control and change the Top property to Bottom property with the same value. Select the Button control and add currentState = “”; to the On Click property. Select the . Select the Button control and add currentState = “switchBottom”; to the On Click property.
Run the application. When you click the button, it will move the button and label to the bottom of the application. States can be used for many purposes. For example, a good usage might be for forms having a large number of fields that might not be filled out by everyone. You can have the base state show a form of all the required input form items, and an optional state that opens up to show all the other fields. A good rule of thumb to know when a specific usage of states might be less optimal is to ask yourself if the states cover the same data and/or user logic.
Adding Interactivity with Behaviors States changes can look very rigid when large layout changes are taking place on the page. To alleviate this, you can use different effects or behaviors. The Design mode supports behavior development through the Flex Properties view.
1.
Click the Label control and select the Flex Properties view, along with changing it to the Category view.
2.
Open up the Effects folder node.
3.
❑
Set mouseDownEffect property to WipeRight.
❑
Set moveEffect property to Fade.
Open up the Events property folder node. ❑
Set mouseDown to txtTitle.text = (txtTitle.text == “Is Great” ) ? “Professional Flex 2 by Wrox” : “Is Great”;
56
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 57
Chapter 4: Using Flex Builder 2.0 4.
Click the Button control and select the Flex Properties view, along with changing it to the Category view.
5.
Open up the Effects folder node. ❑
Set moveEffect property to Fade.
From changing states, text, and adding effects to the controls of the Flex application, the Design mode is a powerful visual tool. You do not have to touch any source code to make complex applications, or change simple component properties and behaviors.
Programming Flex Applications Although visually creating applications has many benefits, most likely the development process will require changing source MXML, ActionScript, and CSS files. Flex Builder provides the normal code-editing features usually found in IDEs.
Code Editing in Flex Builder The code assistance or code hinting is not only for MXML files, but is also available in ActionScript and CSS source files. As you use the code assistance, Flex Builder will also automatically insert any package import dependencies. There are also other tag, method, and syntax completion benefits derived from using the code assistance tool that help the developer be more productive. The CSS code assistance provides a list of valid values with dash-separated values. It is still valid to name the style properties in camel-case notation (that is, background-color and backgroundColor are valid CSS properties, even though code assistance only displays background-color). Flex Builder supports code folding to help you organize and view source code. The code folding icons show up as blue circles in the left gutter of the code with either minus or plus signs. Another, lesser-known source code navigation feature of Flex Builder is creating bookmarks. Any line of code can be bookmarked for viewing and link access through the Bookmark view. To add a bookmark to a line of code, you first select the line of code, then right-click in the left gutter, and select the Bookmark… context menu item. It will be placed in the Bookmark view’s list, where each bookmark can be double-clicked to return to the specific source file and line number. To delete bookmarks, open up the Bookmark view and right-click the bookmark to be deleted. Select the Delete button from the context menu. Just as with Bookmarks, you can also assign tasks manually in the same process. The Task view allows for simple to-do list functionality to be used while working with many source files.
57
02671c04.qxd:02671c04
4/20/07
2:32 PM
Page 58
Part I: Getting Started The part of making your development life easy while editing source files is to learn the shortcuts. The following table lists a few of the more useful shortcuts defaulted in Flex Builder. Shortcut Keys
Name
Description
Ctrl+Shift+T
Open Type
Opens a full list of types dialog box.
F3/Ctrl+click
Go to Definition
Jumps to identifier’s declaration code.
Ctrl+O
Quick Outliner
Pop ups outline view with filtering ability.
Shift+F2
Find in Language Reference
Opens context-sensitive help.
Ctrl+Space
Content Assist
Opens code-hinting popup window.
Right-click in gutter
Folding
Code folding features.
Summar y In this chapter, you have learned how to use Flex Builder. You learned the basic definitions of what Flex Builder is and how the workbench works. This chapter also provided a good overview of how to work with projects by setting up custom workbenches, and learning how to navigate through projects. Finally, you learned about the skills to develop an application through the Design mode, as well as about the Source mode. Chapter 5 discusses the building of your first Flex applications. You not only learn the basic components that make up your Flex applications, but you explore a list of Flex application capabilities such as CSS, skinning, custom components, basic data access, and handling events.
58
02671c05_6.qxd
4/20/07
2:39 PM
Page 59
Part II: Developing in Flex 2.0 Chapter 5: Programming Languages Chapter 6: Building User Interfaces Chapter 7: Customizing the User Interface Chapter 8: Flex UI Topics Chapter 9: Flex Data Chapter 10: Flex Charting Chapter 11: Data Access
02671c05_6.qxd
4/20/07
2:39 PM
Page 60
02671c05_6.qxd
4/20/07
2:39 PM
Page 61
Programming Languages Chapter 3 introduced you to MXML and ActionScript, and how they work together to build rich client applications in Flex. This chapter goes into more detail regarding Flex’s programming languages.
Developing MXML Applications The process of developing using MXML allows you as the developer to separate application logic from the user interface. This is great because you can lay out all or most of the user interface before writing a single line of code. You may find this useful when showing clients what the application may look like initially. Obviously, the interface will change over time as more and more users use the application, but at least you can visualize what it may look like when it is finished. MXML allows developers to build applications from the end user’s perspective, because it is the user interface to the business and data access logic.
UI Layout Using Containers MXML supports two kinds of user interface components: controls and containers. Controls are buttons, combo boxes, text inputs, and date fields. Containers, on the other hand, are rectangular boxes that contain the controls and/or other containers. When laying out controls, you may find it useful to use containers such as the HBox, VBox, and Grid. The HBox container lays out child components horizontally. The VBox container lays them out vertically, and the Grid container is used to lay out child components in columns and rows.
02671c05_6.qxd
4/20/07
2:39 PM
Page 62
Part II: Developing in Flex 2.0 Flex also has navigator containers that are used to control user navigation through the application. Following are examples of navigator containers: ❑
The ViewStack navigator container is the same as the TabNavigator and Accordion containers in that only one child container is visible at a time, but the ViewStack does not have any way to navigate between them by default.
❑
The TabNavigator container contains a collection of child containers in which only one child is visible at a time. Flex automatically creates a TabBar container at the top of the TabNavigator container, with a tab corresponding to each child container. Each tab can have its own label and icon. When the user clicks a tab, the corresponding child container becomes visible as the selected child of the TabNavigator container.
❑
The Accordion container has a collection of child containers, but only one is visible at a time (like the TabNavigator). The difference is that the Accordion has navigator buttons called accordion headers, which you use to navigate between the children.
There are ways to associate a navigation control with a ViewStack container to navigate between the children. This is done by assigning the ViewStack container’s id property to the navigation control’s dataProvider property. You can associate a LinkBar, TabBar, or ToggleButtonBar container with a ViewStack container to provide a navigation interface.
In this code example, the control’s dataProvider property is assigned to the container id property . To label each button in the LinkBar control, you must assign a name to the label property of the ViewStack container’s children. Figure 5-1 shows what the preceding code looks like when compiled into an SWF file.
62
02671c05_6.qxd
4/20/07
2:39 PM
Page 63
Chapter 5: Programming Languages
Figure 5-1: A ViewStack container and LinkBar navigator
UI Controls Flex has a variety of user interface controls, such as TextInput, ComboBox, Button, and LinkButton. These controls are usually added to the interface once you have the layout and navigation of your application defined. The following example contains a VBox (vertical box) container with two child components, a TextInput control and a Button control:
XML Namespaces In a typical XML document, tags are associated with a namespace. This allows you to refer to more than one set of tags in the same XML document: Some Text
63
02671c05_6.qxd
4/20/07
2:39 PM
Page 64
Part II: Developing in Flex 2.0 In MXML, you define an XML namespace using the xmlns property within the root tag of your application or component. Do not specify a prefix if you want to use the default namespace. To add additional tags, you will need to specify a tag prefix and a namespace. In the main file of your Flex application within the tag, you will notice an xmlns property that indicates the tags in the MXML namespace use the prefix of mx: and a namespace of http://www.adobe.com/2006/mxml:
The XML namespace allows you to use custom tags that are not found within the MXML namespace. This will come in handy when you need to define your custom components that are located outside the default namespace. The following component is located in the subdirectory [applicationroot]/mycomponents/ view. To access the MXML component (MyComponent.mxml) you need to define a namespace xmlns:mycomponent?view=”mycomponents.view.*“. The namespace mycomponentview can be allocated any name of your choice as long as it’s one word and without punctuation marks.
To be able to define this component outside of the mycomponents.view.* namespace, you will need to add a namespace to the root tag of the MXML file:
This is done by adding the property xmlns:view=”mycomponents.view.*” to the root tag, which, in this case, happens to be the Application tag. Now all you need to do is instantiate the component by adding the tag .
Data Binding with Components Data binding is a powerful feature of Flex that allows you to tie data in one object to another. This feature lets you pass data between client-side objects in your application. Binding automatically copies the value of a property in the source object to a property in the destination object when the source property changes.
64
02671c05_6.qxd
4/20/07
2:39 PM
Page 65
Chapter 5: Programming Languages This allows you to pass data between different layers of the application, such as the UI, data models, and data services. Flex provides three ways to use data binding: ❑
The curly braces {} syntax
❑
The tag in MXML
❑
The BindingUtils static methods in ActionScript
Even though data binding is a powerful feature, it may not always be appropriate for all situations. You may find that a piece of data only needs to be updated occasionally, or you need strict timing when updating your user interface. The requirements for data binding are a source property, a destination property, and an event that triggers to indicate when to copy the data from the source to the destination. The following example shows the Label control with its text property bound to the TextInput control’s text property. When you type, the TextInput control’s text property (the source property) is copied to the Label control’s text property (the destination property).
Chapter 9 provides more information about data binding.
RPC Services A Remote Procedure Call (RPC) lets your applications interact with remote servers to provide data to your applications or send data to a server. Flex has several types of RPC services that allow access to local and remote server-side or business logic. Your applications can connect to a Web service using the Simple Object Access Protocol (SOAP), a Java object residing on the server using Action Message Format (AMF), or an HTTP URL that returns data in a custom format (such as XML or JSON). Flex provides components for all three RPC services, which can be defined in MXML or ActionScript: ❑
WebService component, which provides access to the SOAP-based Web services.
❑
HTTPService component, which provides access to HTTP URLs that return custom data.
❑
RemoteObject component, which provides access to Java, PHP, and .NET objects using the AMF protocol. With the RemoteObject component, you can access methods of server-side
objects, such as Java objects, without manually configuring the objects as Web services. You need to configure the objects that you want to access as Remote Service destinations in the Flex services configuration file, which is part of Flex Data Services.
65
02671c05_6.qxd
4/20/07
2:39 PM
Page 66
Part II: Developing in Flex 2.0 The following example shows an application using the HTTPService component to call a Flickr service that returns a list of recent photos. The application binds to srv.lastResult.rsp.photos.photo, which is the HTTPService component’s id property (srv) and the result of the last invocation (lastResult property). Flickr will return the result in XML and, by default, the HTTPService component will serialize the data into an object. This allows you to access the list of photo objects using the syntax srv.lastResult .rsp.photos.photo. You may have noticed in the TileList control that there are two new tags: and . These are used to define custom inline item renderers for the TileList control. You learn more about item renderers in later chapters, but for now, all it does is replace the current item renderer with a custom Image control to show the thumbnails from Flickr.
Figure 5-2 shows the application rendered in a Web browser. The thumbnails are displayed within the TileList control, and the data was extracted from Flickr using the HTTPService component.
66
02671c05_6.qxd
4/20/07
2:39 PM
Page 67
Chapter 5: Programming Languages
Figure 5-2: Photos retrieved from Flickr
Data Validation In Flex, you can use the validator components to validate data stored in a data model or a user-interface component. There is a set of standard validator components that comes with the Flex SDK, and you can also build your own by extending the Validator class. The following example uses the CreditcardValidator component to validate the credit card number in the TextInput control. The ComboBox control contains the different card types (for example, American Express, Mastercard, and Visa). {cardTypeCombo.selectedItem.data} {creditCardInput.text}
Figure 5-3 shows the application rendered in a Web browser. As you can see, a border around the TextInput control is visible and a tooltip is displayed to inform the user that the validation has failed. If the validation is successful, an Alert control is displayed to inform the user that the credit card number is valid. Chapter 9 provides more information about validating data.
Figure 5-3: Data validation application
Data Formatting Formatter components are used to convert raw data into a formatted string. Each formatter implements a format method that takes in an Object and returns a formatted string depending on the value of the formatString property. A DateFormatter component, for example, may have a formatString of DD/MM/YYYY and, when passed into the format method, the result would be 29/08/2006.
68
02671c05_6.qxd
4/20/07
2:39 PM
Page 69
Chapter 5: Programming Languages To create a custom formatter, you must extend the Formatter class in the package mx.formatters and override the format method with your own functionality. The following example uses a DateFormatter component to format the date from the DateField control and display it in the TextInput control. The formatString in this case is “EEEE, MMM. D, YYYY at H:NN A”, which determines what the output of the format will look like.
Figure 5-4 shows the application rendered in a Web browser. Chapter 9 provides more information about formatting data.
Figure 5-4: Data formatting application
Cascading Style Sheet (CSS) A Cascading Style Sheet (CSS) allows you to style your Flex application in a similar manner to an HTML Web page. You can either declare your styles within the inline MXML tag, or reference an external file that contains the styles. To use the tag, it is must be a second-level child tag of the root tag in the MXML file and it can be used only in MXML applications and not MXML components. There are two different types of selectors when applying styles to components. The first is the class selector, which can be applied to an individual component. The second is the type selector, which is applied to all components of a certain type.
69
02671c05_6.qxd
4/20/07
2:39 PM
Page 70
Part II: Developing in Flex 2.0 The following example shows a class selector and a type selector using the inline method within an MXML file. Both styles are applied to the same control. .myLabel /* class selector */ { fontSize: 20; } Label /* type selector */ { color: #0000FF; }
Figure 5-5 shows the application rendered in a Web browser.
Figure 5-5: CSS application
Skins Skinning is the process of changing the appearance of a component by modifying or replacing its visual elements. These elements can be made up of images, SWF files, or class files that contain drawing API methods. Flex components can be reskinned without changing their functionality. Skins can be applied to components with various states (for example, the Button control, which has many skins for various states). Skins are defined using the downSkin, upSkin, and overSkin style properties to represent the way the Button control appears when it is down, up, and when the mouse is over the control. Refer to the Flex 2 documentation for all skins regarding the Button control. You can define style properties in a few ways: either inline using the tag, the setStyle() method, or Cascading Style Sheets (CSS). You can add skins to Flex components either graphically or programmatically.
70
02671c05_6.qxd
4/20/07
2:39 PM
Page 71
Chapter 5: Programming Languages Graphical Skins You need to embed image files into your Flex application to use graphical skins. The graphical skins replace the existing skins when you define the files as style properties. The main advantage of graphical skinning is that designers can use tools such as Adobe Photoshop to create the skins as images with no knowledge of ActionScript. However, graphical skins may take up more memory and increase the file size because the external images or SWF files are embedded within the Flex application. Another disadvantage when using graphical skins is that they may distort if you resize the component. The solution to this problem would be to use a technique called Scale-9 to create your skins. This will allow your components to resize without distorting skins. The following code example shows the styles defined inline between the tag. The overSkin, upSkin, and downSkin style properties point to the image files. Button { overSkin: Embed(“assets/images/over_skin.png”); upSkin: Embed(“assets/images/up_skin.png”); downSkin: Embed(“assets/images/down_skin.png”); }
Programmatic Skins Programmatic skins are drawn using ActionScript and are declared in class files. Knowledge of the Flash drawing API is needed to successfully apply skins to your Flex controls. This is a disadvantage because developers are required to create the skins, and not the designers. This means that the developer must translate the designer’s designs into code. One advantage of using programmatic skins is that you have much more control over your styles. If you wanted to control the radius of the Button control’s corners, this is possible using programmatic skins. They also use less memory because they are compiled without any reference to external files, such as images or SWF files. The following code example is a typical outline of a programmatic skin class that could be used to skin a Button control: package { // Import necessary classes here. import flash.display.Graphics; import mx.skins.Border; import mx.skins.ProgrammaticSkin; import mx.styles.StyleManager;
71
02671c05_6.qxd
4/20/07
2:39 PM
Page 72
Part II: Developing in Flex 2.0 public class MySkin extends ProgrammaticSkin { public function MySkin() { // Set default values here. } override protected function updateDisplayList(w:Number, h:Number):void { // Add styleable properties here. // Add logic to detect component’s state and set properties here. // Add drawing methods here. } } }
Adding Effects An effect is a change to a component that occurs over a specified period of time. Examples include fading, resizing, and moving a component. Effects are initialized using a trigger (such as a mouse click), receiving focus on a component, or a component becoming visible. All these triggers are used to form behaviors. Behaviors let you animate, add motion, and add sound to your application in response to some user or programmatic action. For example, if you move your mouse cursor over a Button control, it may inform you by resizing slightly. To create a behavior, you define an effect with an id property and bind it to the trigger (mouseUpEffect). The following example has two effects defined, each with their own id property to distinguish them from each other. The one effect enlarges the component, while the other effect reverts it back to ts original size. These effects are assigned using their id property to the mouseDownEffect and mouseUpEffect triggers of the Button control.
72
02671c05_6.qxd
4/20/07
2:39 PM
Page 73
Chapter 5: Programming Languages
Custom MXML Components In Flex, the ideal way to build your applications is using multiple MXML and ActionScript files. The reason for this is that the architecture promotes modular design and code reuse, and lets multiple developers work on the same project without much hassle. MXML components are MXML files that you create and use as custom MXML tags within other MXML files. The name of the MXML file becomes the class name, which you can reference in another MXML file. You will find the main use of MXML components is to extend the current functionality found in existing Flex components. A simple example of using a custom MXML component would be to have a ComboBox control with a list of states. It would be a pain to create and initialize a ComboBox component with the list of states every time you needed one in your application. The solution would be to create a custom MXML component that extends the ComboBox control and have the list of states defined in there. So anytime you need a state selector in your application, you could use the custom MXML component. The name of this example file is StateSelector.mxml, which extends the ComboBox control and adds an array of objects containing the list of states:
The following MXML code shows you how to use the StateSelector.mxml in your Flex application:
The StateSelector.mxml is in the same subdirectory as the main application MXML file. So no namespace is required when defining the custom MXML component.
73
02671c05_6.qxd
4/20/07
2:39 PM
Page 74
Part II: Developing in Flex 2.0
MXML This section describes the basics of the MXML syntax, which, as you may know, is used to build your user interfaces.
Basic MXML Syntax You will find that most MXML tags correspond to ActionScript 3.0 classes or properties of those classes. The Flex compiler parses the MXML tags and compiles them into one SWF file that contains the SWF byte code. You have already seen many examples so far using MXML syntax. Let’s start off with an easy example, such as defining a Button control:
As you can see, the id property of the Button control has been set to myButton, which needs to be unique for each control in the MXML file. The label property sets the text that is shown inside the Button control. The following example shows a complete Flex application with one Button control defined:
MXML Naming Conventions When you create new MXML files, there are naming conventions you must adhere to: ❑
Filenames can only start with a letter or an underscore (_), and they can only contain alphanumeric and underscore characters after that.
❑
Filenames cannot be the same name as ActionScript class names, component id values, or the word “application.“ Also, do not use filenames that match MXML tags in the mx namespace.
❑
All filenames are required to end with the lowercase .mxml file extension.
A lot of MXML tags correspond to ActionScript classes. When defining the tags, you use the same naming conventions as the ActionScript class. In other words, the class begins with a capital letter, and each capital letter separates the words in the class name. Also, the properties and events also correspond to the ActionScript class.
74
02671c05_6.qxd
4/20/07
2:39 PM
Page 75
Chapter 5: Programming Languages
ActionScript ActionScript is the reason Flex developers exist. Without it, your application would have no logic, and all it would be is a useless user interface. Flex developers need ActionScript to be able to extend the functionality of their applications. The language provides control and object manipulation that is not available in MXML.
Flex Components As a Flex developer, you will find that ActionScript’s primary use will be working with visual controls and containers in your application. In this section, you learn how to reference a Flex control and manipulate the properties in ActionScript.
Referring to a Control in ActionScript Before you write any ActionScript, you must define a control in MXML and assign an id property to it. This allows you to reference the Flex control in ActionScript.
The id property is optional and is only required when referencing the component. The MXML compiler creates a variable called myTextInput that contains a reference to the TextInput object. You can access all the public methods and properties using the dot notation in ActionScript. To access the control in ActionScript, you must reference the id property. The following example shows you how this is done:
75
02671c05_6.qxd
4/20/07
2:39 PM
Page 76
Part II: Developing in Flex 2.0 The getText() method returns a string, refers to the TextInput control’s id property (myTextInput) and accesses the text property of the object. One thing to note is that the ids for all tags in an MXML component, even deeply nested, generate public variables in the component being defined. In other words, all id properties must be unique within the document. If the id property of a Flex component is not defined, you can use the methods of the component’s container, namely, getChildAt() and getChildByName():
This example casts the getChildAt(0) to type TextInput to access the name property and assigns the value to the variable name. The variable name is passed into the childChildByName(name) method and cast to type TextInput to allow access to the text property, which is assigned to variable text. The this keyword is another way to reference components in a document using ActionScript. To access the object, you use the keyword, followed by the square brackets, passing in a string between them. The following code example has the same functionality as the previous one, except it uses the this keyword to reference the TextInput control:
Component Method Invocation In ActionScript, you can invoke a method on a component using the standard dot-notation syntax, as shown here: myTextInput.setSelection(0, 5);
The myTextInput is the id property of the TextInput control, which, as you know, is a variable. Using the dot notation, the setSelection() method is called with the required parameters. If you need to invoke a method from a child document (such as an MXML component), you can use the parentApplication, parentDocument, or Application.application properties. With these methods, you can access parent document public methods and properties. An example of where this may come in useful is when you need to call a method on the parent document from a popup window.
Using ActionScript to Create Visual Components To create visual components at run-time, you must use the new operator. This is the same way you create instances of an ActionScript class. When the component is instantiated, all its default properties are available, but it does not have a parent or any children. Also, you will not be able to see the component, because it is not yet in the display list of the Flash Player. This is the most appropriate time to set any properties on the component before it is added to the display list. Once you have all the necessary properties set, you must add the new component to a container by using the container’s addChild() or addChildAt() method. This will put the component into the Flash Player’s display list, and the component’s children are then created. The children are created late so that you can set the properties that affect the children as they are created. The following piece of code creates a TextInput control using the container’s addChild() method. If you want to add a control to a specific index in the display list, you can use the addChildAt() method.
77
02671c05_6.qxd
4/20/07
2:39 PM
Page 78
Part II: Developing in Flex 2.0
To remove a control at run-time, you can use the removeChild() method or removeChildAt() method. There is also a method called removeAllChildren() that will remove all the children from the container. One thing to remember when using these methods is they do not actually delete the objects from memory. Some time in the future of the application cycle, the Flash Player will include the objects in the garbage collector, unless you have a reference to the child on some other object. The addChild() method can only take a parameter of type DisplayObject. If you create a new object that is not a subclass of flash.display.DisplayObject, you must wrap it in a DisplayObject before attaching it to a container.
Separating ActionScript from MXML This section shows you several different methods of separating ActionScript from MXML. The first method is having one MXML file with the event-handling logic in the event attribute:
The second method is another MXML document, but instead putting the event-handling code in the block:
Lastly, the third method is an MXML document again, but with the event-handling code in a separate ActionScipt file:
The thirdsample.as file contains the following code: public function setLabel():void { myLabel.text = “Third method”; }
Developing ActionScript Components In ActionScript, you can create reusable components and reference them in MXML as tags. You can create your own components from scratch, or extend existing components within the Flex Framework. Developing your own components in ActionScript allows you to modularize the application and maintain your code separately. This is great when you have many developers working on the same application. Each Flex developer can write a component (or a separate part of a component), and from there, you will eventually have a full suite that can be reused between applications.
79
02671c05_6.qxd
4/20/07
2:39 PM
Page 80
Part II: Developing in Flex 2.0 When developing components, you may consider basing them off the current Flex components because there will most likely be logic you can reuse within your own custom components. For example, you may want to create a masked TextInput control and, instead of starting from the beginning, you can extend the existing Flex TextInput control. The following piece of code is a custom component called MaskedTextInput derived from the TextInput control and the package name is com.mycompany.components: package com.mycompany.components { import mx.controls.TextInput; public class MaskedTextInput extends TextInput { public function MaskedTextInput() { super(); } } }
To reference your custom component in your application, you must define a namespace components (this can be any name) that points to the directory of the MaskedTextInput.as file:
Types of Components In ActionScript, you can create the following types of custom components: ❑
User-interface (UI) components are Button, TextInput, and ComboBox controls plus VBox, HBox, and Canvas containers that a user can interact with using the mouse and keyboard. A typical custom visual component extends the UIComponent class or other Flex visual components.
❑
Non-visual components are Flex components that have no visual elements, such as the HTTPService, Web service, and DateFormatter components. These components do not extend the UIComponent class and provide greater efficiency at run-time.
Performing Reflection Reflection is the process by which an application can be modified in the process of being executed, in a manner that depends on abstract features of its code and its run-time behavior. In other words, the program has the ability to “observe” and possibly modify its own structure and behavior.
80
02671c05_6.qxd
4/20/07
2:39 PM
Page 81
Chapter 5: Programming Languages The following is an example in Java using the java.lang.reflect package. If you are familiar with Java, and have used the java.lang.reflect package, this should be easy to understand. // Java code to illustrate how reflection works // Without reflection Person person = new Person(); person.walk(); // With reflection Class cl = Class.forName(“Person”); Method method = cl.getMethod(“walk”, null); method.invoke(cl.newInstance(), null);
Both code fragments create an instance of a class Person and call its walk() method. The difference is, in the first fragment, the names of the class and method are hard-coded. It is not possible to use a class of another name. In the second fragment, the names of the class and method can easily be made to vary at run-time. In ActionScript, the introspection API (discussed shortly) is not as advanced as the Java equivalent, but does allow you to read the methods and properties, and invoke methods of an object at run-time. Reflection is an activity that allows an object to have information about the structure. The programming paradigm driven by reflection is called reflective programming. In ActionScript 3, reflection is referred to as object introspection. There are two ways to do introspection in ActionScript: ❑
Using the for…in loops
❑
Using the introspection API
For…in Loops The for…in loop does not enumerate over declared variables and methods of classes but only dynamically added properties. So, in other words, most of the ActionScript API classes would not display any properties. The following code example creates an instance of the Object class and adds properties to that instance. The Object class is dynamic, which means you can add or change properties at run-time.
The output of the trace statement would look like this: firstname: Simon emailaddress:
[email protected] lastname: Barber
There is a toString() method in the mx.utils.ObjectUtil class that will print all the dynamically added properties of an object: public function dump(o:Object) { trace(ObjectUtil.toString(o)); }
Introspection API In the previous section, you were shown how to use the for…in loop and ObjectUtil class’s toString() method to print out dynamic properties of an object. The introspection API in ActionScript allows you to list all the public properties and methods of a non-dynamic (sealed) class or class instance using the describeType() method. The method is in the flash.utils package and returns an E4X XML object that contains an XML description of the object’s type. To return information about the non-static members of a class, use describeType (this), with this meaning any object instance or ActionScript primitive types. If you want to return information about the static members of a class, use describeType(getDefinitionByName(“MyClass”)). The following examples traces out the variables of the TextInput control instance textInput:
82
02671c05_6.qxd
4/20/07
2:39 PM
Page 83
Chapter 5: Programming Languages
The output displays the variables of the TextInput control: Variable isPopUp = false (Boolean) Variable states = (Array) Variable transitions = (Array)
One more other useful method for introspection is the ObjectUtil’s getClassInfo() method, which returns an Object with the name and properties of the object. The following example traces the object out using the toString() method of the ObjectUtil’s class:
Handling Events Being able to handle events in Flex is very important because you will most likely need to use them to interact with Flex controls, custom controls, and components. This section provides you with basic information about the event model in Flex 2, and describes the Event object, its subclasses, and the event dispatching model. Events inform a developer that something has happened within a Flex application. They can be generated when the visual appearance of a component changes, when the component is created and destroyed, and by using user devices such as the mouse and keyboard. In other words, any user interaction will most likely trigger an event, or even data that is returned from the server may trigger an event. This happens without any user interaction. The developer can listen for these events by adding event listeners, which are functions used to respond to the triggered events. They are commonly referred to as event handlers. To give you an example, a user clicks a button that downloads data from the server. An event handler listens for an event to be triggered once the data has been fully downloaded. The event is fired, which, in turn, calls the event-handler function and parses the data into some meaningful information to be used in a DataGrid control, for example. All or most components in Flex have built-in events that can be handled in ActionScript in your MXML applications.
Event Flow The event model allows developers to listen for any events being dispatched by another control. The flow of an event starts when the Event object is dispatched. It then makes a journey from the root of the display list to the target node, checking for registered listeners. The target node is the node where the event originated from (for example, a user clicks a Button control named Button1). The Event object’s target node holds a reference to Button1. There are three parts to the way event flow works: ❑
84
Capturing phase — This phase comprises of all the nodes from the root node to the parent of the target node. Once this phase is in execution, the Flash Player starting at the root examines each node to see if there is a listener registered to handle the event. If it finds registered listeners, it will set the values of the Event object and then call the listener function. The Flash Player stops after it has reached the target node’s parent and called the registered event listeners.
02671c05_6.qxd
4/20/07
2:39 PM
Page 85
Chapter 5: Programming Languages ❑
Targeting phase — This phase consists only of the target node. The Flash Player sets the values on the Event object, looks at the target node for any registered event listeners, and then calls those listeners.
❑
Bubbling phase — This phase consists of all the nodes from the target node’s parent to the root node. It begins at the target node’s parent where the Flash Player sets the values on the Event object and then calls the event listeners on each of these nodes. The Flash Player will stop after any listeners on the root node are called.
These phases are examined in more detail later in this chapter.
Event Class The flash.events.Event class is the base class for all events in your application. Any time an event occurs in Flex, this class is implicitly created when it is dispatched. It contains properties with information about the event that occurred. The event listeners can access the details that were passed with the event’s properties, such as the event type and the target that dispatched the event. However, passing an Event object to the event listener is optional. The Event object is created only once on every dispatch. During the bubbling and capturing phases, the values on the Event object change as it moves up or down the display list. This is much more efficient than creating a new Event object for each node.
Subclassing Events There are two packages that house all the major event classes that extend the flash.events.Event class. They are mx.events and flash.events. The mx.events.* packages contains all the events that are specific to the Flex controls, such as the DropDownEvent and ItemClickEvent classes. The other package, flash.events, contains all the events that are defined by the Flash Player, such as the TextEvent and MouseEvent classes. When developing Flex applications, you must create your own events that extend the Event class. These custom events will contain additional unique properties that hold vital information that the Event class does not contain. For example, the TextEvent class extends the Event class and has a text property that contains a character or sequence of characters entered by the user.
EventDispatcher Class The EventDispatcher class allows any object that inherits from it to participate in the Flex event model. All objects in the Flash Player’s display list inherit the functionality of the EventDispatcher class. The reason for this is that all objects in the display list inherit from the DisplayObject class, which, in turn, extends the EventDispatcher class. Although you may think the EventDispatcher only allows you to dispatch or send events, you would be mistaken. This class gives you the functionality to register for events, check for event listeners, and remove
85
02671c05_6.qxd
4/20/07
2:39 PM
Page 86
Part II: Developing in Flex 2.0 event listeners. The most common method used in the EventDispatcher is the addEventListener() method, which you use to register an event listener. More advanced programmers and component developers will use the dispatchEvent() method to manually dispatch or send events a custom Event object into the event flow. One other method to mention is the hasEventListener() method, which checks for an event listener of a specific event type on a particular display object and returns true if it is found.
Event Usage To use events in Flex, you must first define an event listener or event handler. This is a function or class method that responds to an event when it is dispatched. The signature of the function can optionally include an argument that specifies the event type. The following example is a basic event listener function that traces a string to the console:
Secondly, you must register the event listener or function with a display list object by using the EventDispatcher class addEventListener() method: btn1.addEventListener(MouseEvent.CLICK, eventListenerFunction);
There is a simpler method to listener registration for Flex controls in MXML. You define the click event, which references the listener function on the Button control using an attribute:
This is the same as using the addEventListener() method to register the listener in the previous code example. However, it is better practice to use the addEventListener() method because it gives you greater control and you can configure the priority and capture settings, and use event constants. With event constants, you can ensure that the event type is valid at compile time. Any time an event is dispatched, Flex creates an Event object containing information about the event, such as the type and a reference to the control that fired it. To have access to the Event object, it must be passed into the event listener function, as this following code example shows: public function eventListenerFunction(event:Event):void { trace(“Event type: “ + event.type); }
86
02671c05_6.qxd
4/20/07
2:39 PM
Page 87
Chapter 5: Programming Languages To do the same within MXML using an inline event, you must explicitly pass the event into the listener:
The event model allows you to register multiple event listeners with a single event. This may be useful when you want two things to happen when a user clicks a Button control. The following example shows multiple event listeners registered to a single instance of a button in MXML and ActionScript: // MXML // ActionScript public function initUI():void { btn1.addEventListener(MouseEvent.CLICK, eventListenerFunction1); btn1.addEventListener(MouseEvent.CLICK, eventListenerFunction2); }
To set the order in which the event listeners are called, you must specify the priority parameter of the addeEventListener() method. This obviously cannot be done using the inline method in MXML. The opposite also works by registering a single event listener with multiple components. The following example again shows the registration of a single event listener with multiple components in MXML and ActionScript: //MXML //ActionScript public function initUI():void { btn1.addEventListener(MouseEvent.CLICK, eventListenerFunction); btn2.addEventListener(MouseEvent.CLICK, eventListenerFunction); }
The Target Property of the Event Class As mentioned earlier, the Event object contains a reference to the object dispatching the event. In essence, you can access all the public methods and properties of the instance within the event listener. The following example accesses the currentTarget.name property of the UIComponent: public function eventListenerFunction(event:Event):void { trace(“The button instances name is “ + event.currentTarget.name); }
To call methods and access properties on the current target within the event listener, you must cast the currentTarget property to a DisplayObject. If you need to access the properties of a specific control (such as the Button control), the currentTarget property must be cast to type Button.
87
02671c05_6.qxd
4/20/07
2:39 PM
Page 88
Part II: Developing in Flex 2.0 The following example sets the label of the Button control to “Label Changed”: import mx.controls.Button; public function eventListenerFunction(event:Event):void { Button(event.currentTarget).label = “Label Changed”; }
Propagation There are three phases during which Flex looks for event listeners when events are triggered. The phases occur in the following order:
1. 2. 3.
Capturing phase Targeting phase Bubbling phase
In this section, you learn more about how event propagation is handled in Flex, and learn more about each phase.
Difference Between the Target and currentTarget Properties All Event objects have a target and currentTarget property, which keeps track of where it is in the propagation process. The target property references the dispatcher of the event, and the currentTarget property references the current node that is being examined for event listeners. When a user clicks a control, the target property often refers to a subcomponent such as a UITextField (which renders the label) in a Button control. In other words, when the Flash Player dispatches the event, it might be triggered from the internal subcomponent and not the Button control. Most likely, you will have the Button control listen for the event, and the target property of the event listener might refer to the UITextField or subcomponent of the control. The MouseEvent will bubble up the chain within the control, but the target property (which might be the UITextField) will stay the same. The currentTarget property will be set to each level as it moves up the chain, and eventually reference the Button instance. So, for this reason, you should use the event.currentTarget property rather than the event.target property.
Capturing Phase As mentioned, the capturing phase is when Flex examines an event’s ancestors in the hierarchy for registered event listeners. It starts at the root ancestor, and carries on down the display list until it reaches the parent’s target. Figure 5-6 shows the structure of a basic application. The capturing phase starts at the Application object and moves through to the Panel (parent of the target).
88
02671c05_6.qxd
4/20/07
2:39 PM
Page 89
Chapter 5: Programming Languages Application
VBox
Panel
TextInput
Figure 5-6: Capturing phase
The currentTarget property will change on the Event object to the node of the listener being called during the capturing phase. The target property will remain the same, referring to the dispatcher of the event. The useCapture property of the addEventListener() method defaults to false and has to be explicitly set to true. Adding an event listener using MXML will result in the argument being set to false, and there is no way to override it.
Targeting Phase The targeting phase is when Flex invokes only the event dispatcher’s listeners. So, no other nodes in the display list are looked at during this phase, and the currentTarget and target properties remain.
Bubbling Phase The bubbling phase is very similar to the capturing phase, except it looks for event listeners in reverse. In other words, it starts at the dispatcher’s parent and carries on up the display list to the root application. Figure 5-7 shows the same structure of a basic application as the capturing phase. The bubbling phase starts at the parent of the dispatcher and moves through to the root of the application. The events will only bubble and process the event bubbling phase if the bubbles property is set to true. Keyboard and mouse events bubble by default, but it can be dangerous to set all your events to bubble by default. The reason for this is that if you are listening for different events, but the event type is the same, all those listeners will trigger. This can be difficult to debug, and it is recommended not to bubble your events unless it’s really necessary.
89
02671c05_6.qxd
4/20/07
2:39 PM
Page 90
Part II: Developing in Flex 2.0 Application
VBox
Panel
TextInput
Figure 5-7: Bubbling phase
There is one more thing to remember. If you set the useCapture property to true, the bubbling phase will not process. If you want both phases to be processed, you have to call the addEventListener() method twice, once with useCapture set to true and the other with useCapture set to false.
Priorities Event priority is really used when there are many event listeners registered with a single event. The event listeners are called depending on the order in which the addEventListener() methods are defined. Using MXML to register the events results in an unpredictable order. To change the order in which the event listeners are called, you specify the priority property parameter in the addEventListener() method. The priority works from highest to lowest. The listener2() method will be called first because it has the highest priority of 2, and the listener1() method will be called next. public function initUI():void { btn1.addEventListener(MouseEvent.CLICK, listener1, false, 1); btn1.addEventListener(MouseEvent.CLICK, listener2, false, 2); }
If all the event listeners have the same priority, they will be executed in the order they are defined. The priority can be either positive or negative, and the default value is 0. To change the priority of the event listener, the removeEventListener() method must be called to remove the event listener. You will then need to register the event listener again with a different priority.
90
02671c05_6.qxd
4/20/07
2:39 PM
Page 91
Chapter 5: Programming Languages An important point to remember is that there is no guarantee that the listener will finish executing before the next one in the priority list is called. In other words, you should ensure that listeners do not rely on other listeners to complete before calling the next one. The Flash Player does not necessarily wait for the first handler to finish executing before proceeding to the next one.
Subclassing Events In Flex, there are many subclasses that are based off the Event class. They contain specific information about the event that is not available in the Event class, such as the DragEvent class. Flex controls generate an Event object that is a specific event type (for example, when you drag a row from one List control to another). If you specify the event type as a parameter in the event listener functions, you can access all the subclass’s properties. The following is an event listener that listens for the dragComplete event to be dispatched. You can define the event parameter as a basic Event class, but you will have to cast it in the event listener to access the properties specific to the subclassed event. This way it can use less memory, but it is best practice to declare the type. private function doDragComplete(event:DragEvent):void { trace(“dragComplete triggered: “ + event.type); }
While developing Flex applications, you will need to create custom events that carry specific information not found on the Event class. To accomplish this, create a custom class that extends the Event class, as the following example shows: package com.mycompany.events { import flash.events.Event; import com.mycompany.vo.UserVO; public class LoginEvent extends Event { public function LoginEvent(type:String, userVO:UserVO, bubbles:Boolean=false, cancelable:Boolean=false) { super(type, bubbles, cancelable); this.userVO = userVO; } public var userVO:UserVO; } }
The LoginEvent class extends the Event class and adds an extra property called userVO. This contains a reference to another custom class called UserVO, which has all the properties associated with a user of the application. The userVO property is set in the constructor of the LoginEvent class. This can be set as optional by specifying the property to be equaled null. public function CustomEvent(type:String, userVO:UserVO=null, bubbles:Boolean=false, cancelable:Boolean=false)
91
02671c05_6.qxd
4/20/07
2:39 PM
Page 92
Part II: Developing in Flex 2.0 { super(type, bubbles, cancelable); this.userVO = userVO; }
Keyboard Events As you may already know, or may have gathered, the Flash Player supports all the basic functionality using keyboard combinations from the operating system. You can also trap or override any key or combination of keys to perform an action. You may find that you want to trap keys globally so that wherever a user is in the application, the keystrokes are identified and the necessary action is performed. No matter where the mouse is in an application, Flex recognizes the global keyboard events. The most common way to handle keyboard events is to create an event listener. If you want to trap any key when it is pressed, you can add an event listener to the stage object, as the following example shows: private function addKeyboardListeners():void { stage.addEventListener(KeyboardEvent.KEY_DOWN, trapKeys); }
As you can see, every time a user presses a key, the trapKeys() method is called to process any logic that the developer has defined. The following example shows what the trapKeys() method looks like for this basic example. The function traces out the event.charCode and event.keyCode to the console. private function trapKeys(event:KeyboardEvent):void { trace(“charCode: “ + String(event.charCode) + “ | keyCode: “ + String(event.keyCode)); }
To accomplish the same task in MXML using the inline method, you can define the keyDown event of a UIComponent and reference the trapKeys() method:
Keys can only be trapped on components that can have focus. You should avoid trying to trap keys on containers that cannot have focus, such as the Box containers. Instead, if a container has children that accept focus and keyboard input from the user, you can set the event handler on the container and assume it will bubble up.
Precedence on KeyboardEvent Registering event listeners for keyboard events with regard to order does not work the same way as explained earlier in the chapter. Defining the keyUp and keyDown event listeners for the parent and control will result in each component dispatching the same event twice, because the event bubbles. This will result in the target property changing.
92
02671c05_6.qxd
4/20/07
2:39 PM
Page 93
Chapter 5: Programming Languages In the following example, the keyDown event is registered in the application, Panel container, and the TextArea control: private function addKeyboardListeners():void { application.addEventListener(KeyboardEvent.KEY_DOWN, trapKeys); panel1.addEventListener(KeyboardEvent.KEY_DOWN, trapKeys); textarea1.addEventListener(KeyboardEvent.KEY_DOWN, trapKeys); }
The order in which the keyboard events are dispatched is the child controls are first before any of their parents. In this example, the TextArea control event is dispatched first, then the Panel control, followed by the Application.
MouseEvents The MouseEvent class and all its subclasses have extra properties that determine if a specific key was held down when clicking the mouse button: ❑
altKey — Set to true if the Alt key is held down when the user pressed the mouse button.
❑
ctrlKey — Set to true if the Ctrl key is held down when the user pressed the mouse button.
❑
shiftKey — Set to true if the Shift key is held down when the user pressed the mouse button.
You may want the user to be able to open a popup window by holding down the Alt key and Shift key together while pressing the mouse button anywhere within application.
Summar y This chapter provided the insight and knowledge to build your first Flex application. You learned about the MXML syntax and using ActionScript to provide flow control and object manipulation that is not available in MXML. Lastly, you learned about one of the most important features in Flex — handling events within your applications. Chapter 6 describes how to improve the user experience by adding functionality to your application and customizing the user interface. You learn about styles, fonts, skins, and item renderers, and how to localize your applications.
93
02671c05_6.qxd
4/20/07
2:39 PM
Page 94
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 95
Building User Interfaces This chapter describes how to use Flex 2 components to build user interfaces for your applications. Flex 2, as you know, has many built-in components that make life a lot easier when it comes to building the interface. You are introduced to Flex controls, data providers, and collections, and how to lay out controls using containers. Flex makes it very easy to lay out your user interfaces using MXML.
V isual Components The component-based development model Flex provides allows you to develop applications that are architecturally sound, achieving great scalability and reliability. The pre-built visual components in Flex allow you to build interfaces faster without having to create your own components. That said, Flex includes a well-thought-out component architecture that allows you (as the developer) to build your own components, either by extending existing ones, or creating your own. You have a lot of power at your fingertips when using visual components in Flex. They are extremely flexible and provide a great deal of control over their appearance (the font and size of the text in any component, the sizing of components), as well as their response to user interactions. This section provides an overview of the characteristics of visual components such as size, events, styles, behaviors, and skins.
Class Hierarchy All visual components in Flex generally extend the UIComponent class. This is the base class for all visual components in Flex, both interactive and non-interactive. When creating custom components, you should extend the UIComponent class because it contains functionality for width, height, handling double-clicks, id property, style names, and x and y properties. Figure 6-1 shows the class hierarchy from the Object class through to all visual components in Flex.
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 96
Part II: Developing in Flex 2.0 Object
EventDispatcher
DisplayObject
InteractiveObject
DisplayObjectContainer
Sprite
UIComponent
All Visual Components
Figure 6-1: Class hierarchy from the Object class through to all visual components in Flex
UIComponent Class The UIComponent class has many properties and methods that are accessible when extending the class. The most commonly used properties are listed in the following table.
96
Property
Type
Description
doubleClickEnabled
Boolean
Specifies whether the UIComponent object receives doubleClick events
enabled
Boolean
Whether the component can accept user interaction
height
Number
Number that specifies the height of the component, in pixels, in the parent’s coordinates
id
String
ID of the component so that you can refer to it using ActionScript
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 97
Chapter 6: Building User Interfaces Property
Type
Description
percentageWidth
Number
Number that specifies the height of a component as a percentage of its parent’s size
percentageHeight
Number
Number that specifies the width of a component as a percentage of its parent’s size
styleName
String
The class style used by this component. Very similar to the way CSS works in HTML
toolTip
String
Text to display in the tooltip
visible
Boolean
Controls the visibility of the UIComponent
width
Number
Number that specifies the width of the component, in pixels, in the parent’s coordinates
x
Number
Number that specifies the component’s horizontal position, in pixels, within its parent container
y
Number
Number that specifies the component’s vertical position, in pixels, within its parent container
Component Sizing The Flex SDK has layout and sizing functionality that allows you to control the size of your visual components. You can determine the size of your components (explicit sizing), or let Flex do it for you (default sizing). To use default sizing, you do not specify the width and height of the component. Explicit sizing, on the other hand, requires you to specify the width and height of the visual component, as the following example shows:
You may find explicit sizing to be too precise. You can, instead, define the size of the component as a percentage. In Flex, this is called percentage-based sizing. The following example shows percentage-based sizing on a Panel control:
97
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 98
Part II: Developing in Flex 2.0 To specify the percentage-based sizing in ActionScript, you must access the percentageWidth and percentageHeight properties of the control. The following example will reset the Panel control’s width to 50 percent of the parent container: panel1.percentageWidth = 50;
The layout of your components is very important. Flex has a mechanism called constraint-based layout that allows you to control the size and position by anchoring the sides, or centering the components within their containers by specifying the top, bottom, left, right, verticalCenter, and horizontalCenter properties. The following example shows a VBox container defining constraint-based layouts:
You can mix the sizing and layout properties as long as they are done appropriately. You must not specify the width and percentageWidth of a control, because you can use only one or the other.
Event Handling A user interacts with a component such as clicking a button that, in turn, fires an event. You can write code to process the click event that may pop up an Alert control, informing the user that something important has occurred. As you may know, Flex applications are event-driven, and this makes it a very powerful platform to develop your Rich Internet Applications (RIA). The basic cycle of event handling starts when events are dispatched. The objects that have registered listeners are notified for that event. Event handlers (or event listeners) are defined to process the event in ActionScript. You register event listeners in either ActionScript or the MXML declaration of the component. The following example registers an event listener in MXML that is processed when the Button control is clicked:
98
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 99
Chapter 6: Building User Interfaces This example passes in the event object when declaring the click event handler handleClickEvent (event). The event handler in this example does not make use of the event, but you will need to do so in many of the applications you build. You do not have to pass in the event object, as long as it is not defined as a parameter in the event handler. The following example shows the event object being accessed within the event handler. The List control contains the names of the three authors. The event handler is registered to the change event. Any time a user selects an item in the List control, the Alert control pops up and shows the name of the selected author through the selectedItem property.
Component Instantiation Component instantiation works as a sequence of steps that occur when you create a component instance from an ActionScript component class. The easiest way to create an instance of a component is declaring it in MXML. On the other hand, you can do the same process in ActionScript. The following example creates a Button control in ActionScript and adds it to the display list of the Flash Player: import import import import
mx.effects.easing.Back; mx.controls.Button; mx.containers.VBox; mx.core.Container;
99
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 100
Part II: Developing in Flex 2.0 private function initUI():void { var vboxContainer:VBox = new VBox(); addChild(vboxContainer); var buttonControl:Button = new Button(); buttonControl.label = “Click”; vboxContainer.addChild(buttonControl); }
The following steps occur when this code is executed:
1. 2. 3. 4. 5.
The constructor of the vboxContainer instance is called. The addChild() method is called to add the vboxContainer instance to the display list. The constructor of the buttonControl instance is called. The buttonControl instance label property is set to the string “Click”. The vboxContainer instance addChild() method is called to add the buttonControl instance to the display list or stage. The following actions are performed internally when the button instance is added to the stage:
6.
a.
The parent property of the component is set to reference its parent container.
b.
The style settings of the component are processed.
c.
The add event for the button is dispatched.
d.
The childAdd event for the parent container is dispatched.
e.
The preinitialize event of the component is dispatched. The component is currently in a very raw state, and the control creates internal child components. For example, the Button control creates the UITextField to show the label text.
f.
The component’s children are created and initialized, including the internal children.
g.
The initialize event is dispatched on the component, of which, at this stage, all children have been initialized, but the component is not fully processed. No sizing or layout has been executed yet.
A render event is dispatched to display the application, and Flex does the following: a.
All the processing is completed to display the component, including layout of the component.
b.
The visible property is set to true to show the component.
c.
The creationComplete event is dispatched and the component’s size and layout has been processed, including all the properties.
d.
The updateComplete event is dispatched. This event is dispatched whenever the position, size, or other visual characteristics of the component changes.
If you were to remove the component using the removeChild() method, the child’s parent property would be set to null. The Flash Player will delete the component from memory using the garbage
100
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 101
Chapter 6: Building User Interfaces collector if there are no references to the component. This happens at an undetermined time when the Flash Player does a sweep to remove objects from memory. Figure 6-2 shows the following major events that are dispatched in a component’s creation life cycle: ❑
The preinitialize event occurs very early in the life cycle of a component to do any initialization. In rare situations, it may come in handy when you must set the properties on a parent before the children are created.
❑
The initialize event is useful to configure a component before Flex has determined the visual appearance. So, in other words, use this to set properties that affect its appearance (such as width and height).
❑
The creationComplete event should be used to set accurate values on the component (such as the size or position). Using this event to perform actions that change the visual appearance will require Flex to recalculate its layout, which creates unnecessary processing overhead.
❑
The updateComplete event should be used to perform actions each time the characteristics of the component change. preinitialize
initialize
creationComplete
updateComplete
Figure 6-2: Major events that are dispatched in a component’s creation life cycle
Styling Components Styling in Flex is defined using Cascading Style Sheets (CSS), which allow you to set the characteristics of components (such as fonts, padding, and alignment). All visual components can define their own styles, but, by default, they are inherited from its superclass. You may notice that some styles are inherited not by the subclass but from the superclass. To find out more about which styles are supported in the visual component, refer to the Adobe Flex 2 documentation. Styles can be defined in MXML as tag attributes, such as setting the padding between borders of a container or defining the font weight of a TextInput control.
101
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 102
Part II: Developing in Flex 2.0 The following example shows a Label control with the fontWeight and fontSize style attributes defined in MXML:
Styles can also be defined using the tag in MXML or ActionScript using the setStyle() method. The setStyle() method takes two parameters: the style name (as a String) and the value. This example uses the ActionScript setStyle() method to set the Label control’s fontWeight and fontSize styles:
This example uses MXML and the tag. The styles are set using CSS syntax inline, or using an external file that contains style declarations. The style declaration is referenced in MXML using the styleName tag attribute on the visual component: .myLabelStyle { font-weight: bold; font-size: 20; }
102
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 103
Chapter 6: Building User Interfaces
The .myLabelStyle is a CSS class selector style definition that applies only to visual components that have referenced it using the styleName attribute. A type selector applies to all instances of the component type, such as shown in the following example: Label { font-weight: bold; font-size: 20; }
Adding Behaviors In Flex, a trigger combined with an effect is called a behavior. A trigger is an action similar to an event, and an effect is a visible change to a component of a specified period of time in milliseconds. Effects are fading, resizing, zooming, or moving a component around the stage. Multiple effects can be defined for a single trigger either in parallel or in sequence. Triggers are implemented as CSS styles, which means that you can set them as tag attributes in MXML using the tag or in ActionScript using the setStyle() method. Behaviors allow you to add animation, sound, and/or motion to your application in response to user or programmatic action. To create a behavior, you declare a specific effect with a unique id and bind it to the trigger. The following example declares a Fade effect with an id of fadeInstance, which is bound to the creationCompleteEffect trigger of the Button control. The Fade effect has an alphaFrom property, which is the initial transparency level between 0.0 and 1.0, where 0.0 means transparent and 1.0 means fully opaque. The alphaTo property is the final transparency level, and also takes a value between 0.0 and 1.0. The duration property is how long the effect takes to finish in milliseconds.
103
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 104
Part II: Developing in Flex 2.0
Applying Skins Chapter 7 provides more details about skinning in Flex, but for now, this discussion will serve as an introduction. Skins are graphical style elements that dictate the look of visual components. Many components have many skins. For example, the Button control has eight, one for each button state (such as Up, Down, Disabled, Selected, Focus, Over, and so on). All these elements can be made up of images, SWF files, or class files that use the drawing API methods to achieve the effect. There are two ways to add skins to a Flex component: graphically and programmatically. Figure 6-3 shows three Button controls: one with the upSkin, another with the overSkin, and, lastly, one with the downSkin.
Button
Button
Button
upSkin
overSkin
downSkin
Figure 6-3: Three Button controls
Modifying Components at Run-time In most languages such as Java or .NET, you can modify the look, size, or position of a component at run-time. Flex also allows you to do the same. You achieve this by using the component properties, styles, or ActionScript methods, including the x and y properties, and width and height properties, and by using the setStyle(stylename:String, value:Object) method. To use the x and y properties of a component, the parent container of the child must make use of absolute positioning. The Canvas container allows for absolute positioning by default, but the Application, Box, and Panel containers must set the layout property to absolute. With the x and y properties, you could reposition a TextInput control 10 pixels to the right and 10 pixels down when a user clicks a Button control. The following example shows how this is achieved:
104
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 105
Chapter 6: Building User Interfaces
The width and height properties are useful if you want to resize a component at run-time. In Flex, each component is set to a standard width and height if none are explicitly provided. The following example resizes a TextInput control by 10 pixels using the width and height properties:
One thing to remember about the width and height properties is that they are always set in pixels, regardless of whether they were originally fixed values, percentages, or not set at all.
Extending Components In Flex 2, you can create custom components that extend existing or custom components. When you extend existing components, you inherit all the functionality of the base component, plus you can add new properties and methods to it. The following example is a custom MXML component with a DateField control and TextInput control inside an HBox container. The TextInput control’s text property is bound to the DateField control’s selectedDate property. The filename for this component is MyCustomComponent.mxm, and it is located in a same directory as the application file.
105
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 106
Part II: Developing in Flex 2.0 To use the custom MXML component in your application, you must specify its filename as an MXML tag, as shown in the following example:
In this example, the custom component is in the same directory as the application file, which maps to the local namespace indicated by the asterisk. There are two ways to create custom components in Flex. The method you take depends on your application requirements of the component. ❑
Create custom components as MXML files that provide an easy way to extend existing components, modify the behavior, or add basic features to an existing component.
❑
Create custom components as ActionScript files by extending the UIComponent class or any of is subclasses. Using ActionScript to create custom components provides greater customization for visual or non-visual components.
For more information regarding creating MXML and ActionScript components, see Chapter 12, “Creating MXML Components,” and Chapter 13, “Flex Component Properties.”
Data Providers and Collections Many Flex controls use a data provider such as an array or ArrayCollection (for example, the ComboBox control, which reads in a data provider to define the options in the drop-down list). Collection classes are used to represent data providers in Flex, which is a group of objects with a set of methods to access, sort, filter, and modify items in the collection. This section describes data providers and collection classes, including an introduction to using data providers in controls. Also, you learn how to use collection classes to access and manipulate data.
Data Providers All List-based controls represent data using a data provider that is an object required by the control to make it function correctly. For example, the DataGrid control requires a data provider to determine the row of items to display to the user. The following are all the components that use data providers:
106
❑
Tree control
❑
DataGrid control
❑
ComboBox control
❑
List control
❑
TileList control
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 107
Chapter 6: Building User Interfaces ❑
Menu control
❑
MenuBar control
❑
ButtonBar control
❑
LinkBar control
❑
TabBar control
❑
ToggleButtonBar control
❑
LineChart control
❑
ColorPicker control
❑
PopUpMenuButton control
❑
HorizontalList control
❑
Repeater component
❑
DateField control
The easiest way to use a data provider with a control is declare an Array of strings or objects, which is then bound to the control’s dataProvider property. Using a raw data object has its limitations as a data provider, and you should use the collection classes if you have data that changes. Raw objects do not have the functionality to notify the control when changes to the base object occur. Therefore, the control does not get updated, unless it is redrawn or the data provider is reassigned. Another downside to using raw objects is that they do not provide functionality for accessing, sorting, or filtering data. The following example shows the difference between using an Array (raw object) and an ArrayCollection, with both of them bound to separate List controls. There are two Button controls: one calls the addCountryToArray()method, and the other one calls the addCountryToCollection() method. These two methods take the value from the TextInput control and add them to the relevant data providers.
You will see that the first List control does not reflect the changes when the Button control labeled Add Country to Array is clicked. However, when the Button control labeled Add Country to Collection is clicked, the List control below reflects the changes. The reason for this is that collections notify the control when changes are made to its data. Collections in Flex provide functionality to ensure data synchronization, simple and yet very sophisticated data access, and manipulation tools. They provide a consistent interface for managing and accessing data of many different types. Flex supports two basic types of data providers: ❑
Linear or listed-based data providers are one-dimensional, and are sometimes referred to as flat data consisting of a number of objects.
❑
Hierarchical data providers consist of tree-like structures, with the data source usually being an XML object. Controls that support hierarchical data are the Tree, Menu, MenuBar, and PopUpMenuButton.
The structure defined in hierarchical data providers matches the layout of a tree or cascading menu. A tree usually contains a root node with one or more branches or child nodes, which, in turn, contain branch nodes or children with an ending leaf node. Controls that support hierarchical data use the data descriptor interfaces to access and manipulate the data providers. You can write your own custom data descriptor if your hierarchical data does not support the format described by the DefaultDataDescriptor class. Once you have successfully
108
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 109
Chapter 6: Building User Interfaces implemented all the interfaces in your custom data descriptor, you can specify them in the hierarchical control’s dataDescriptor property. The ArrayCollection or XMLListCollection class and the ICollectionView or IList interface can be used to access or manipulate hierarchical data dynamically.
Collections Collections are more robust than plain Arrays because they provide functionality that includes adding and removing objects, as well as sorting and filtering the data. They also support change notification, which keeps data synchronized across an application. Collection interfaces provide the following features: ❑
They ensure that the control is updated properly when underlying data changes.
❑
They provide handling of paged data coming from remote data providers that may not initially be available.
❑
They contain a set of operations for handling data that is independent of those found in raw data providers such as an Array.
❑
The collections that implement the ICollectionView interface provide a view of the data that can be sorted or filtered by a custom method. These features affect the collection’s view and not the underlying data.
❑
Multiple components can use the same collection as their data provider.
❑
Collections can be modified so that changes are reflected by all the components that use the data provider.
The following example shows you how to define a collection in MXML: United States South Africa United Kingdom
You can do the same in ActionScript as long as you import the mx.collections.ArrayCollection class. To initialize the ArrayCollection with data, you must pass an Array into the constructor, as shown in the following example: import mx.collections.ArrayCollection; [Bindable] public var myCollection:ArrayCollection = new ArrayCollection([“United States”, “South Africa”, “United Kingdom”]);
109
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 110
Part II: Developing in Flex 2.0 If an instance of the ArrayCollection is created without passing in an Array to the constructor, you can set it to the source property at a later stage. var myArray:Array = [“United States”, “South Africa”, “United Kingdom”]; myCollection.source = myArray; ArrayCollections can be bound to a chart control and updated in real time because collections support notification changes. The following example does exactly this. A timer is set to run every 1000 milliseconds, which, in turn, adds a new object to the ArrayCollection, which reflects in the ColumnChart control. The object’s number property is set to a random number between 0 and 100. import import import import
mx.utils.UIDUtil; flash.utils.Timer; flash.events.TimerEvent; mx.collections.ArrayCollection;
[Bindable] public var myCollection:ArrayCollection = new ArrayCollection(); public function initTimer():void { var myTimer:Timer = new Timer(1000, 0); myTimer.addEventListener(“timer”, timerHandler); myTimer.start(); } public function timerHandler(event:TimerEvent):void { var o:Object = new Object(); //o.uid = UIDUtil.createUID(); o.number = Math.random() * 400; myCollection.addItem(o); }
110
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 111
Chapter 6: Building User Interfaces
Collection Interfaces In the Flex Framework, the collection model uses the following interfaces to define how collections represent data, provide access to it, and manipulate them: ❑
IList — A collection of items organized in an ordinal fashion. Provides access and manipula-
tion methods based on the index. The interface does not provide sorting, filtering, or cursor functionality. ❑
ICollectionView — A view onto a collection of data. It can be modified to show the data
sorted according to certain criteria, or be reduced by filters without modifying the underlying data. The interface provides access to an IViewCursor object to access the items. ❑
IViewCursor — The interface for enumerating over a collection view bidirectionally. The cursor provides find, seek, and bookmarking functionality.
IList and ICollectionView interfaces allow developers access to two alternative methods for accessing and manipulating data. The IList interface is a simple interface that provides adding, setting, getting, and removing operations on linear data.
The ICollectionView interface, however, provides more complex functionality than the IList interface, and is appropriate if the underlying data is organized in a non-linear fashion. The collection that implements the ICollectionView interface can represent a subset of data by using the sort or filtering operations. The ArrayCollection and XMLListCollections classes implement both the IList and ICollectionView interfaces.
IList Interface The IList interface contains simple methods for linear data access using an index. Anything you change in the collection changes the data provider. For example, inserting an item at an index of two will also reflect as the second item in the underlying data source. The following can be achieved with the IList interface: ❑
Get, set, add, or remove an item at a specific index from the collection.
❑
Add an item at the end of the collection.
❑
Get an index of an item in the collection.
❑
Get the amount of items in the collection.
❑
Remove all the items from the collection.
111
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 112
Part II: Developing in Flex 2.0
ICollectionView The ICollectionView is a view of the underlying data source that represents a collection of items. The interface is more complex than that of the IList interface. The following can be achieved with the ICollectionView interface: ❑
Modify the view to show data in a sorted order, or show only a subset of the items using the filtering capabilities without changing the underlying data.
❑
Move through the collection, use bookmarks to save locations in the collection, and add and remove items by accessing the data using a cursor.
❑
Represent remote data that might not initially be available yet, or the dataset that may become available at different times.
Sorting Collections The Sort class allows you to sort on data in collections. Multiple fields are supported when sorting data, and require that the entries be unique. A custom comparison function can be used to order the sorted output, and the Sort class can also search for item in the collection. If you apply a sort instance to the collection, you are required to call the refresh() method of the collection to apply the changes. The SortField class is used to specify the fields to use in the sort. You create an instance of the SortField class and add it to the fields array property of the Sort class instance. All the SortField instances of the collection must be unique. The following example sorts an ArrayCollection in descending order. The primary sort is on the label field of the collection, case-sensitive, and in descending order. import mx.collections.SortField; import mx.collections.Sort; import mx.collections.ArrayCollection; [Bindable] public var myCollection:ArrayCollection = new ArrayCollection([{label: “A”}, {label: “B”}, {label: “C”}, {label: “D”}, {label: “E”}]); public function sortCollection():void { var sort:Sort = new Sort(); sort.fields = [new SortField(“label”, true, true)]; myCollection.sort = sort; myCollection.refresh(); }
112
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 113
Chapter 6: Building User Interfaces
Filtering Collections Filtering limits the ICollectionView to a subset of the data provider’s underlying data. You define a function that takes a single Object parameter and returns a Boolean value to specify whether to include the item in the view. The same step applies with sorting as it does with filtering. You must call the refresh() method of the collection when you set the filter function. The following example uses both filtering and sorting of an ArrayCollection. There are two Button controls to apply the sort and filtering, respectively, and one to reset the view to its original state. = “A” && item.label < “N”; } public function resetCollection():void { myCollection.filterFunction = null; myCollection.sort = null; myCollection.refresh(); } ]]>
113
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 114
Part II: Developing in Flex 2.0
IViewCursor Interface The IViewCursor interface defines the functionality to enumerate over a collection view. The ICollectionView interface contains a createCursor() method that returns an IViewCursor object referred to as a cursor. The cursor is used to transverse the items in the view, as well as to access and manipulate data. It is a position indicator that points to a particular item in the collection. The IViewCursor interface has the following methods and properties to perform the following operations: ❑
Move the cursor backward and forward.
❑
Move it to specific items.
❑
Get the item at a cursor location.
❑
Add, remove, and change items.
❑
Save the cursor as a bookmark so that you can return to it at a later stage.
To use the ICollectionView interface, you must access it by calling the method of a collection instance, as shown in the following code snippet: public var myArrayCollection:IViewCursor; public var myCursor:IViewCursor; public function getCursor():void { myCursor = myArrayCollection.createCursor(); }
The moveNext() and movePrevious() methods are used to move the cursor forward and backward by one item at a time. To check whether you have reached the bounds of the collection, use the beforeFirst and afterLast properties.
114
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 115
Chapter 6: Building User Interfaces To search within the collection, you can use the findAny(), findFirst(), and findLast() methods that match the parameter, but you must apply a Sort to the ICollectionView instance. It is important to note that if you do not need to find the first or last occurrence of an item in the collection, the findAny() method is more efficient than the findFirst() and findLast() methods. To find the last occurrence of an item in the collection, you must apply a Sort, as the following example shows: var sort:Sort = new Sort(); // the null parameter on the SortField constructor specifies a collection of simple objects (String, Boolean or numeric) sort.fields = [new SortField(null, true)]; myCollection.sort = sort; myCollection.refresh(); myCursor.firstLast(“NY”);
You can search for a complex object using the findLast() method on multiple sort fields. However, you cannot skip fields in any of the find methods. If the object has three fields, you can specify the combinations 1 or 1, 2 or 1, 2, 3 as a parameter, but not 1, 3. The following code will find the last object with a label field “NY” and a data field “New York”: myCursor.firstLast({label: “NY”, data: “New York”});
The seek() method moves the cursor to a location at an offset from the specified bookmark. You can move to the first and last element in the collection, or to the last bookmark you saved. The IViewCursor interface has methods and properties to access and manipulate data. The current property is a reference to the item at the current cursor location. The insert() method adds an item before the cursor’s current position, and the remove() method removes the current item and returns a reference to it. When inserting an item using the insert() method of the IViewCursor interface and the collection view is sorted, the inserted item will move to the sorted location and not the cursor location.
Collection Change Events Collections have a mechanism that provides feedback to the developer whenever changes occur to the data within the collection. Any class that implements the IList or ICollectionView interface dispatches a CollectionEvent class event whenever the collection changes. The CollectionEvent class contains a kind property that indicates the way in which the collection has changed. To determine this, you compare the kind property to the value of the CollectionEventKind class constants, such as CollectionEventKind.ADD. The CollectionEvent class contains another useful property, items, which is an Array of objects whose type varies depending on the event kind property. If it is the ADD and REMOVE event, the array contains the added or removed items. If it is the UPDATE event, the items property contains an Array of PropertyChangeEvent event objects. This object contains the type of change and the property value before and after the change.
115
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 116
Part II: Developing in Flex 2.0 The PropertyChangeEvent class kind property indicates the way in which the property changed. This is determined by the comparing the kind property value with the PropertyChangeEventKind constants. The constants can either be UPDATE or DELETE. The collection events are used to monitor changes to the collection, which, in turn, is used to update the display. If you have a custom control that uses a collection as its data provider, you can listen for the change events on the collection and update the custom control accordingly. The following example lets you add, remove, and replace items in a list control. An event handler is registered to the collectionChange event of the ArrayCollection instance. Any time an item is added, removed, or replaced, a message is logged in the TextArea control.
Hierarchical Data Providers The structure of hierarchical data providers is more advanced than your typical linear data providers (such as an Array). They display data in a nested hierarchy of nodes and subnodes like a tree with branches and leaves. In Flex, there are a few controls that accept hierarchical data providers, including the Menu, MenuBar, PopUpMenuButton, and Tree controls. Your typical hierarchical data sources are XML, which can be Strings containing well-formed XML, or XML, XMLList, or XMLCollection objects. Objects that have nested objects (including Arrays or ArrayCollection objects) are also considered hierarchical data sources. The structure must have the children in the children field of the data source. Otherwise, you must create your own custom data descriptor class. This will allow you to support other hierarchical data provider structures with custom field names other than the children field.
Data Descriptors A data descriptor class is used to parse the hierarchical data used in Tree- and Menu-based controls. It provides an interface between the hierarchical control and the data provider object. Flex has two types of data descriptor interfaces for hierarchical controls. The ITreeDataDescriptor is used by the Tree controls, and the IMenuDataDescriptor is used for the Menu, MenuBar, and PopUpMenuButton controls. Flex provides a DefaultDataDescriptor class that implements both of the interfaces just mentioned. You can specify a custom data descriptor by assigning a new one to the dataDescriptor property of the hierarchical controls. The only reason you would want to define a custom data descriptor is if your data models do not conform to the default descriptor structure.
XML Data Provider In most cases, the data for a Tree control is retrieved from a server in the form of XML, but can also be defined within the tag. The or tag can be used to define an XML or XMLList object in MXML, and lets you use binding expressions in the XML nodes.
117
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 118
Part II: Developing in Flex 2.0 The following example shows MXML binding in an tag:
If your data provider for a hierarchical control is going to be dynamic, you should use the XMLListCollection object instead of the XML or XMLList object. This ensures that your component will represent any changes made to the data provider. The XMLListCollection class supports the IList and ICollectionView interface methods for manipulating data at run-time. The following example uses two Tree controls, two XMLListCollection objects, and a Button control to copy an object in the one XMLListCollection object to the other:
Remote Data Providers The Remote Procedure Call (RPC) components provide Flex with the functionality to call remote servers to retrieve data for use in your application. The components that are provided with Flex are the HTTPService, WebService, and RemoteObject components. The following example is a basic application that uses the HTTPService component to download the list of featured videos from the video-sharing site, YouTube:
119
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 120
Part II: Developing in Flex 2.0
Positioning and Sizing Components In Flex, the controls are laid out using a set of rules that are a combination of sizing rules for individual components, and sizing and positioning rules for containers. Automatic layout is supported in Flex, which lets you concentrate on building the logic for your application; if need be, you can always adjust the dimensions at a later stage. Many controls and containers have default layout rules, but you can use the component’s properties and methods to customize it yourself. Every Flex component has several properties (such as width and height) to adjust the size of the component. Containers also have properties and styles that you can use to configure their layout, including the verticalAlign and horizontalAlign properties to set the alignment of their children. Flex also allows you to position children using the x and y properties of the container. Only containers that support absolute positioning (including the Canvas container) allow for this.
Layout of Components The Layout Manager has the job of controlling the layout in Flex. The manager has a three-step process in which it sizes and lays out components in the application:
120
1.
Commitment pass — Determines the properties of the application components. During this pass, the Layout Manager causes each component to execute its commitProperties() method, which determines the property values.
2.
Measurement pass — Calculates the default size of every component in the application. This starts from the most deeply nested components and works its way out toward the Application container. During this pass, the Layout Manager causes each component to execute its measureSizes() method, which calls the measure() method to determine its default size.
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 121
Chapter 6: Building User Interfaces 3.
Layout pass — This pass lays out your application, including resizing and moving of any components. This starts from the outermost container and moves to the innermost container, determining the actual size and placement of each component. During this pass, the Layout Manager causes each component to execute its updateDisplayList() method to lay out the component’s children.
Component Sizing The layout phase and measurement determine a component’s width and height, and you can retrieve these dimensions by using the width and height properties. The following properties (and others not listed here) are used to control the sizing of components: ❑
Default sizing — The size of the controls and containers are determined automatically.
❑
Explicit sizing — You set the width and height properties to an absolute value.
❑
Percentage-based sizing — You specify the component size as a percentage of its container size.
❑
Constraint-based layout — You control the size and position by anchoring the component sides to the container.
There are several ways to control the size of components. This section describes the basic sizing properties, how to determine component sizes, how to use automatic, explicit, and percentage-based sizing, and various techniques for controlling component size.
Sizing Properties You will find that there are several properties affecting the size of components in Flex. The general rule is that you only need to use a few properties for most applications, but a knowledge of these properties can help you understand how the underlying sizing mechanism works in Flex. If you are not creating custom components, you would use the following basic properties to specify how a component is sized: ❑
The width, height, percentWidth, and percentHeight properties specify the width and height of a component. Using the MXML tags, you can use the width and height properties to specify the dimensions in pixels and as a percentage of the parent container. When using ActionScript, you use the width and height properties to specify the dimensions in pixels, and use the percentWidth and percentHeight properties to specify the dimensions as a percentage of the parent container.
❑
The minWidth, minHeight, maxWidth, and maxHeight properties specify the minimum and maximum dimensions that a component can have in Flex. If you explicitly set the width and height properties, these properties have no effect.
Default Sizing As a rule of thumb, you should determine whether a component’s default size is appropriate for your application. If you decide that default sizing is sufficient, you do not have to specify an explicit or percentage-based size.
121
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 122
Part II: Developing in Flex 2.0 The following example uses default sizing for the Button control:
Explicit Sizing To use explicit sizing, you specify the width and height properties of a component to set its size:
You may notice that the VBox container is smaller than the Button control. Flex will clip the Button control to the container’s boundary and display a scroll bar so that you can scroll the container to view the clipped content. The scroll bars will not be visible if you specify the verticalScrollPolicy and horizontalScrollPolicy properties of the container to off.
Component Positioning and Layout During the initialization phase, Flex will position the components appropriately, and also perform a layout pass to position or reposition components in the application. Flex provides two mechanisms regarding the positioning and layout of controls: ❑
Automatic positioning — Flex automatically positions the children within the container according to a set of container- and component-specific rules.
❑
Absolute positioning — The children’s x and y properties are set by the developer, or you can use a constraint-based layout that specifies the gap between each child in the container. This type of positioning is occasionally referred to as absolute layout.
There are three containers that support absolute layout or positioning. The Application and Panel containers use automatic positioning by default, but you can set the layout property to absolute. The third one is the Canvas container, which always uses absolute positioning.
Layout Rules Flex has a set of rules that are used to perform the layout of components. You should be able to understand the details of Flex layout if you can remember these rules. These rules will give you an understanding of
122
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 123
Chapter 6: Building User Interfaces why Flex lays out your application the way it does. This will help you when you need to modify the appearance of your application. ❑
Flex first determines all components’ measured or explicitly set sizes, up from the innermost child controls to the outermost Application control. This is all done in the measurement pass.
❑
After the measurement pass, Flex determines all percentage-based sizes and lays out components down from the outermost container to the innermost controls. This is done in the layout pass.
❑
Sizes that you set to a pixel value are mandatory and fixed, and override any maximum or minimum size specifications that you set for the component.
❑
The default sizes determined in the measurement pass specify the sizes of components that do not have explicit or percentage-based sizes (or use constraint-based layout), and are fixed.
❑
Percentage-based size specifications are advisory. The layout algorithms satisfy the request if possible, and use the percentage values to determine proportional sizes. However, the actual sizes can be less than the requested sizes. Percentage-based sizes are always within the component’s maximum and minimum sizes, and, subject to those bounds, don’t cause a container’s children to exceed the container size.
Forcing Layout Manually In rare instances, you may need to programmatically force Flex to lay out components again. Usually, Flex will delay processing of properties that require substantial computation until the scripts that caused them to be set finish executing. For example, if you set the width property of a component or container, it will be delayed because Flex prevents it from happening multiple times. Sometimes you may want to force the layout before the script has completed. To force the layout, you need to call the validateNow() method of the component. This will cause Flex to validate the properties, sizes, and layout of the object and all of its children. This method is processor-intensive and should be used cautiously if it is needed.
Constraint-based Layout Constraint-based layout allows you to anchor sides or the center of the component to a position relative to the viewable region of the component’s container. With constraint-based layout, you can anchor one or more corners of a component at a specific pixel offset from the container’s corresponding edge. The anchored child stays at the specific pixel offset even if the container is resized. If the anchor is set to top and bottom, then when the container resizes, the component will resize with it. To use constraint-based layout in your application, you must adhere to the following rules: ❑
Place the component inside a container that supports absolute layout (such as a Canvas container) or inside an Application or Panel container with the layout property set to absolute.
❑
Any component that extends the UIComponent class also supports constraint-based layout.
❑
Specify the top, bottom, left, right, verticalCenter, or horizontalCenter styles.
123
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 124
Part II: Developing in Flex 2.0 ❑
Do not specify a top or bottom style with a verticalCenter style, because the verticalCenter style overrides the other properties. The same applies to the left or right styles with a horizontalCenter style.
❑
Using constraint-based layout will override an explicit or percentage-based sizing. Specifying the top and bottom constraints will override any height or percentHeight properties.
The following basic example shows a Button control anchored 10 pixels from the bottom of the VBox container:
Getting Familiar with Flex Controls In Flex, controls are referred to as user interface (UI) components such as Button, TextInput, and ComboBox controls. There are two types of controls in Flex: ❑
Basic controls (such as a Button)
❑
Data provider–based controls (such as a List)
Controls are typically placed into containers, which are components that provide a hierarchical structure for controls. The tag is the root of your Flex application. This represents a base container that covers the entire Flash Player drawing area. You can place controls or containers directly onto this area. Controls have the following characteristics. ❑
Declare the control in MXML and specify its properties and events.
❑
Use the ActionScript API to call the control’s methods and set its properties at run-time.
❑
Customize the visual appearance by using the styles, skins, and fonts of the controls.
The easiest way to add a control to your Flex application is using the MXML API. To achieve this, you must specify the control’s MXML tag, as the following example shows:
124
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 125
Chapter 6: Building User Interfaces
Summar y In this chapter, you learned about the most important elements in creating rich user interfaces for your Flex applications. The most interesting topics were visual components, data providers and collections, sizing and positioning of components, and constraint-based layout. These topics will stand you in good stead on the road to developing Rich Internet Applications using Flex 2. Chapter 7 discusses improving the user experience by adding functionality to your applications. The topics covered are behaviors, styles, fonts, skinning, item renderers and editors, tooltips, and the Cursor Manager.
125
02671c06.qxd:02671c06
4/20/07
2:45 PM
Page 126
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 127
Customizing the User Interface This chapter discusses how to improve the user experience by adding functionality to your application and, more importantly, the user interface (UI). You are introduced to effects and behaviors, styles and themes, fonts, skins, item renderers and editors, tooltips, and cursor management.
Applying Behaviors A combination of a trigger paired with an effect is called a behavior. A trigger is an action such as a mouse click on a button, or a component receiving focus or becoming visible. An effect is a visible change to a component that occurs within a specific duration measured in milliseconds. Fading, moving, or zooming a component are examples of various effects. Behaviors allow you to add animation and motion to your application in response to user or programmatic action. For example, you could create a menu similar to the Apple Mac OS X Dock, which grows in size if your mouse gets close to the icons. You can define multiple effects to play in response to a single user or programmatic action. A good example of this would be the Apple Mac OS X Dock in hide mode. When you move your mouse close to the Dock, it appears and the icons grow depending on your mouse position. Flex components do not play an effect when a trigger occurs, but some components do indirectly, as when the ComboBox control’s drop-down list slides down when you click it. Note that triggers are not the same as events, because if you look at the properties of a Button control, for example, it contains a mouseUp event and a mouseUpEffect trigger. The mouseUpEffect trigger is associated with an effect, so that when the mouseUp event occurs, an effect is run.
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 128
Part II: Developing in Flex 2.0
Using Behaviors In MXML, you use the name of the effect to assign it to the trigger property of the component:
This code example declares two effects, one fading from fully opaque to fully transparent, and the other effect in reverse. So, when a user clicks the button, it disappears and reappears when the mouse button is released. In MXML, all properties that are effect triggers are implemented in Cascading Style Sheets (CSS) styles. Therefore, you can apply the effect using the tag. The following code example is the same as the preceding example, but it uses CSS styles, instead: Button { mouseDownEffect: myFadeOut; mouseUpEffect: myFadeIn; }
You could also use the setStyle() and getStyle() methods to manipulate triggers and their associated effects. In ActionScript, you can declare play effects often as part of an event listener. To invoke the effect, you call the play() method. The following example resizes a Panel container:
128
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 129
Chapter 7: Customizing the User Interface
Instead of specifying the target property of the Resize effect, you could pass in the myPanel instance as an array into the play() method of the resize effect instance: myResize.play([myPanel]);
Embedded Fonts with Effects The Fade, Dissolve, and Rotate effects work only with text that is rendered using embedded fonts. Nothing will happen to the text if system fonts are used. Embedded fonts are discussed in more detail later in this chapter. When applying a Zoom effect to text rendered with system fonts, Flex will scale the text between whole point sizes. In essence, you do not have to use embedded fonts with the Zoom effect, but it will appear smoother if you do.
Composite Effects You can combine or composite effects either by using the Parallel or Sequence effect. The Parallel effect plays the child effects at the same time, and the Sequence effect plays them sequentially. The following example defines Parallel and Sequence effects with the same child effects. The Parallel effect resizes the Panel container and blurs it at the same time, whereas the Sequence effect resizes the Panel container and, once that is finished, removes the blur.
129
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 130
Part II: Developing in Flex 2.0
Easing Functions In Flex, you can change the speed of an animation by defining an easing function for an effect. This allows you to create a more realistic rate of acceleration and deceleration. The easing function also includes the functionality to make objects look like they are bouncing. The following code shows the basic format of an easing function: function myEasingFunction(t:Number, b:Number, c:Number, d:Number):Number {}
Note the following: ❑
The t specifies time.
❑
The b specifies the initial position of a component.
❑
The c specifies the total change in position of the component.
❑
The d specifies the duration of the effect in milliseconds.
Easing functions can be found in the mx.effects.easing.* package. The following example is the same as the last code example regarding composite effects, except an easing function has been applied to the Resize effect by setting the easingFunction property:
You can also apply easing functions to controls such as the ComboBox control by specifying the openEasingFunction and/or closingEasingFunction. The following example shows how this is done:
Applying Styles Styles are useful for defining the look and feel of your Flex application. You use them to change the appearance of a single component, or across all components by using Cascading Style Sheets (CSS). To modify the appearance of components, you use style properties similar to those in CSS. These properties define the size of a font, background color, or the size of the border in a Panel container. Some styles are inherited from parent containers to their children, and across style types and classes. This allows you to define a style once that then applies to all controls of a single type or set of controls. Also, you can override individual properties for each control at a local, component, or a global level, leaving you with greater flexibility in the appearance of your application. Flex does not allow you to control all aspects of your component layout with CSS. Properties such as width, height, x, and y are not styles of the UIComponent class. As you may remember, the UIComponent
class is the base class for all visual components in Flex.
131
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 132
Part II: Developing in Flex 2.0
Using Styles You use CSS to apply styles to a document or across an entire application. The one way to apply styles is by referring to an external style sheet, or including them inline within the MXML document. The following example applies an external style sheet myStyleSheet.css to the current document:
If you prefer to use styles inside the document or inline, use the tag. This will apply the styles to your current document and its children. The following example defines a new style and applies it only to that instance of a Label control: .myLabel { font-size: 16; font-family: Arial; font-weight: bold; color: #FFCC00; }
This example defines a new style that applies to all instances of a Label control: Label { font-size: 16; font-family: Arial; font-weight: bold; color: #FFCC00; }
132
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 133
Chapter 7: Customizing the User Interface You can use the setStyle() and getStyle() methods of a control to manipulate style properties. Using these methods does require more processing power on the client than using style sheets, but it provides greater control over how you apply styles. myLabel.setStyle(“fontWeight”, “bold”);
Lastly, you can use attributes of MXML tags to apply styles inline and apply only to the instance of the control. This is the most efficient method of applying instance properties because no ActionScript code blocks or method calls are required. The following example sets the fontWeight style of the myLabel instance to bold:
Note that you must use the camel-case version of the style property in an MXML tag. For example, you must use fontSize and not font-size. You can also bind inline style properties to values.
Using Local, Application, and Global Selectors The tag contains style sheet definitions that adhere to the CSS 2.0 syntax and apply to the current document and all of its children in the current document. To define a local style, you would use the class selector. Any component that wants to use the style must refer to it in its styleName property. The following example defines a type and class selector in the tag: .myClass /* class selector */ { font-size: 16; font-family: Verdana; font-weight: bold; color: #FFCC00; } Label /* type selector */ { font-size: 16; font-family: Verdana; font-weight: bold; color: #FFCC00; }
Application Type Selector The Application container is the root of your Flex application and is the top-most document. Any styles defined in the Application type selector are inherited by all the container’s children, as well as the container’s subclasses. Styles that are not inheritable are applied only to the Application container and not its children.
133
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 134
Part II: Developing in Flex 2.0 Styles applied in the Application type selector that are not inherited by the Application object’s children are not inheritable. Use the global type selector to apply a non-inheritable style globally. Defining styles in the Application type selector are not required to declare a style for each component, because the components are children of these classes and inherit the Application type selector styles. The following example defines various styles in the Application type selector: Application { background-color: #FFFFFF; padding-top: 10; }
Global Type Selector Flex provides a global type selector that you can use to apply styles to all controls. Any properties defined by a global type selector apply to all controls, unless that control explicitly overrides it. The global selector is like a type selector, and so you do not have to preface it with a period in CSS. The following example defines the fontFamily and fontSize property to the global selector: global { font-family: Verdana; font-size: 10; }
Applying Fonts Flex has two types of fonts: device fonts and embedded fonts. Embedded fonts are smoother, and you can apply special effects to text-based controls such as rotating and fading. There are many ways to embed fonts in your application, such as using CSS syntax to embed FlashType fonts into the SWF files. The application stores the names of the fonts that you used to create the text. The Flash Player uses the font names to locate identical or similar fonts on the user’s system when the application runs. Using embedded fonts means that they are used regardless of whether the client system contains the fonts because they are embedded within the SWF file.
Device Fonts Device fonts do not export their outline information and are not embedded in the SWF or application. The Flash Player uses whatever fonts it can find on the client computer that closely resemble the device fonts.
134
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 135
Chapter 7: Customizing the User Interface The following example specifies three device fonts. The Flash Player looks for the first font, the second font, and so on. Application { font-family: Arial, Helvetica, Verdana; font-size: 10; color: Blue; font-weight: bold; }
The Flash Player supports the following three device fonts: ❑
_sans — The _sans device font is a sans-serif typeface (for example, Arial).
❑
_serif — The _serif device font is a serif typeface (for example, Times Roman).
❑
_typewriter — The _typewriter device font is a monospace font (for example, Courier).
When using device fonts, the size of the SWF does not increase. However, using device fonts can impact performance of the application because it requires the Flash Player to interact with the local operating system. If you are using device fonts, you are limited to three fonts.
Embedded Fonts You can embed TrueType Font (TTF) families in your Flex application rather than relying on a client machine to have the specific fonts. The font will always be the same when running your application, and you do not have to worry about missing fonts. Embedded fonts have the following benefits: ❑
The font does not need to be installed on the system.
❑
Embedded fonts are anti-aliased, meaning their edges are smoothed for easier readability (especially when the text size is larger).
❑
Embedded fonts can be partially or fully transparent and be rotated.
❑
Embedded fonts provide smoother playback when zooming.
❑
Text appears as you would expect when using embedded fonts.
The following are downsides to using embedded fonts: ❑
You can only embed TrueType fonts.
❑
Embedded fonts increase the size of your application because it must contain the outlines for the text.
❑
Embedded fonts decrease readability of text at sizes smaller than 10 points.
135
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 136
Part II: Developing in Flex 2.0 To use embedded fonts in your application, you would typically use CSS syntax. The @font-face declaration specifies the source of the embedded font, and then defines the name of the font by using the fontFamily property. Each font face from the same family must be specified using the @font-face declaration. Note the font licenses before attempting to embed fonts into your Flex application. Some fonts might have licensing restrictions that do not allow them to be stored as vector information.
Embedded fonts can be TTF files on your file system or an SWF file that is created in Adobe Flash. Fonts embedded using Flash take advantage of the FlashType technology, which makes them more readable at smaller sizes. The following example embeds the font Verdana located at c:\Windows\Fonts\Verdana.ttf: @font-face { src:url(“c:\\Windows\\Fonts\\Verdana.ttf”); fontFamily: myFontFace; }
After you have embedded the font, you can use the fontFamily name or alias in a type or class selector. The following example uses the myFontFace as a type selector for all Button controls: Button { fontFamily: myFontFace; }
FlashType Fonts FlashType is a new rendering engine included in Flash Player 8 and above that provides clear, high-quality text rendering in SWF files. It greatly improves the readability of text, especially when rendered at smaller font sizes. To use FlashType fonts in Flex, you create an SWF file in Adobe Flash 8 that contains the fonts you require in your application. You then reference that SWF file’s font contents so that it gets embedded into your application. Using FlashType fonts in your application may cause a slight delay when loading the application. The more you use, the slower the startup time of your application. It can also increase the memory usage by quite a bit. Embedding FlashType fonts in your application is the same as other embedded fonts. They are anti-aliased, and you can rotate them or make them fully or partially transparent.
136
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 137
Chapter 7: Customizing the User Interface A good practice is to include the four primary typefaces for each font that you want to embed (that is, plain, bold, italic, and bold italic). The reason for this is that some Flex controls use one of the non-plain typefaces. An example of this would be a label on the Button control that uses a bold typeface of the font. Embedding a plain typeface to use on a Button will likely not work, because it requires a bold typeface.
Creating an SWF to Embed FlashType Fonts The first step in embedding FlashType fonts in your application is to create an SWF using Adobe Flash 8 that contains those fonts. Once you have completed this part, you must embed them into your Flex application.
1. 2. 3.
Open Adobe Flash 8 and create a new document.
4.
In the Properties panel, select Dynamic Text from the drop-down list.
Select the Text Tool and create a text field on the Stage. Enter at least one character of text into the text field. If it is easier, you may want to type out the name of each typeface, as shown in Figure 7-1.
Figure 7-1: Entering text into the text field
137
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 138
Part II: Developing in Flex 2.0 5.
In the Properties panel, click the Embed button, and the Character Embedding dialog box shown in Figure 7-2 will appear.
6.
Then, select the ranges of glyphs you would like to embed. Only select all if you feel it is absolutely necessary. Selecting all the glyphs will make the file size fairly large, so rather, select only what you really need.
7. 8.
Create three more text fields, one for each typeface, such as bold, italic, and bold italic (Figure 7-3). Export your movie by pressing Ctrl+Enter to create an SWF file for use within your Flex application.
Figure 7-2: Character Embedding dialog box
Embedding FlashType Fonts After you have created your SWF file with the appropriate fonts, it is time to embed them into your Flex application using CSS.
1.
Embed each typeface with a @font-face declaration:
@font-face { src:url(myfonts.swf); fontFamily: Verdana; fontStyle: italic; fontWeight: bold; }
2.
Now, define a style for each embedded typeface. This can be done in an external style sheet or in the tag.
.myStyle1 { fontFamily: Verdana; fontSize: 11; }
138
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 139
Chapter 7: Customizing the User Interface
Figure 7-3: Three more text fields for each typeface
You must specify the fontFamily property and it must match the fontFamily property set in the @font-face declaration. The value of the fontFamily property stays the same, regardless of which typeface you are defining (in other words, if the typeface is bold, you do not specify Verdana Bold, but just Verdana). Remember that you must specify all the typeface properties like you did in the @font-face declaration. If the typeface is bold italic, define the fontWeight and fontStyle properties to match it. .myStyle2 { fontFamily: Verdana; fontSize: 11; fontStyle: italic; fontWeight: bold; }
139
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 140
Part II: Developing in Flex 2.0 3.
Apply the new style to your Flex controls:
You can also specify the styles inline instead of defining them in a style sheet. The only problem with this approach is that if you need to edit the styles, it will not be in one central place. There is one more way to embed FlashType fonts without using the @font-face declaration: by using the [Embed] metadata keyword. The following example embeds a Verdana font’s italic typeface: [Embed(source=”verdana_fonts.swf”, fontName=”Verdana”, fontWeight=”italic”)] public static var italicFont:Class;
Ensure that you are using the latest SWF file that contains your fonts. Otherwise, recompile the SWF file, if necessary.
Skinning the Application The process of changing the appearance of a component by modifying or replacing its visual elements is called skinning. The elements can be made up of images, SWF files, or a class that implements the drawing API methods.
Graphical Skins Image files embedded into your application that represent a state of a component are called graphical skins. Each image may be a different state of a component, such as the downSkin of a Button control. The following example shows the upSkin, overSkin, and downSkin style properties defined as new graphical skins. These style properties point to the different images for each state of the control. Figure 7-4 shows the graphical skins used in the following code example: Button { upSkin: Embed(“/skins/upSkin.png”); overSkin: Embed(“/skins/overSkin.png”); downSkin: Embed(“/skins/downSkin.png”); }
140
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 141
Chapter 7: Customizing the User Interface
Figure 7-4: Graphical skins Skins are actually a class, and when you are changing the reference from a current skin to a new one, it is just a new class. Flex wraps each embedded asset as a class within the current document’s class. Note that if you change any graphical skins, you must recompile the application because they are embedded into the SWF file. You can define skin properties either using CSS, inline, or by using the setStyle() method of the control you are skinning. The one downside to using graphical skins or images is that resizing the component will create distortion. You can use a technique called Scale-9 to create skins that do not become distorted. The technique lets you define nine sections of an image that scale independently.
Programmatic Skins In Flex you can write programmatic skins as ActionScript classes that use the Drawing API of the Flash Player. The methods for drawing at run-time are in the flash.display.Graphics package. The best way to learn how to create programmatic skins is to look at the ones that come with Flex and then either extend them or create your own. The programmatic skin recipe is a basic template that you can use to implement a skin for a component. The following code example is a programmatic skin class. You can use this class as a template to create new skins. package { import import import import
flash.display.Graphics; mx.skins.Border; mx.skins.ProgrammaticSkin; mx.styles.StyleManager;
public class MyCustomSkin extends ProgrammaticSkin { // Constructor. public function MyCustomSkin() { // Set default values here. } override protected function updateDisplayList(w:Number, h:Number):void { // Add styleable properties here. // Add logic to detect component’s state and set properties here. // Add drawing methods here. } } }
141
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 142
Part II: Developing in Flex 2.0 Programmatic skins define the appearance of a skin in multiple states of a control, such as the upSkin, downSkin, and overSkin of a Button control. These states refer to the default state, when the button is pressed, and when the mouse is over the button but has not been pressed.
Choosing a Superclass The first step in creating a programmatic skin is to select a superclass for the skin. You can extend the abstract base classes in the mx.skins package or the mx.skins.halo package, but the former gives you more control over the look and feel of your skins. The latter is fine if you use the default behavior of the Flex controls but want to add extra styling. Most skins extend the mx.skins.ProgrammaticSkin class, but any of the following classes can be used: ❑
The ProgrammaticSkin class implements all the necessary interfaces to make it easier for you to define skins for your components. It is also the most common superclass to use.
❑
The Border class extends the ProgrammaticSkin class and adds a property called borderMetrics that allows you to get the thickness of the border.
❑
The RectangularBorder class extends the Border class and adds a style property called backgroundImage so that you can set the background image of the component.
Note that a programmatic skin must implement the IFlexDisplayObject, IInvalidating, and ILayoutManagerClient interfaces. It must also implement the ISimpleStyleClient interface if it depends on the values of CSS styles. The superclass of a skin can be a subclass of the DisplayObject class as long as you implement all of those interfaces. The updateDisplayList() method is used to define the look of your skin. It is called after the skin’s constructor is called and then every time the skin is resized, restyled, moved, or interacted with in some way. In the updateDisplayList() method, you use the drawing methods to draw the programmatic skin. When implementing the updateDisplayList() method, remember to use the override keyword to override the superclass’s implementation, set the return type to void, and declare the method as protected. The method also takes the width and height of the component as arguments. The following code example draws a square with a border: override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void graphics.clear(); graphics.lineStyle(2, 0x000000, 1.0, true, LineScaleMode.NORMAL, CapsStyle.SQUARE, JointStyle.MITER); graphics.beginFill(0xFFFFFF, 0); graphics.drawRect(0, 0, unscaledWidth, unscaledHeight); graphics.endFill(); }
142
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 143
Chapter 7: Customizing the User Interface The following example applies a programmatic skin to a specific state of the control: Button { upSkin:ClassReference(‘MyCustomSkin’); }
Note that if you subclass the RectangularBorder class, you must also call the super.updateDisplayList() inside of your implementation of the updateDisplayList().
Item Renderers In Flex, there are several controls that represent a list of items. You can scroll through the list of items and select one or more from the list. They are all derived from the ListBase class, and the following controls are included: List, TileList, Menu, Tree, DataGrid, and HorizontalList. A list control uses a data provider for its data, which is a collection of objects. The data provider creates a layer of abstraction between the Flex list controls and the data that populates them. You can think of the data provider as the model and the Flex list control as the view onto the data. Every list control has a default view to display the data, and Flex lets you override this mechanism. To do this, you must create an item renderer. The simplest item renderer is the DataGridItemRenderer, which is the default item renderer for the DataGrid control. It contains the functionality to display text. The following example is a List control using the default item renderer to display a list of three different fruits: Apples Oranges Pears
If you wanted to display more than just text for each item in the list control, you must create your own custom item renderer. Custom item renderers and item editors provide you with the following benefits: ❑
Replace the display of text with a richer appearance.
❑
Combine multiple elements in a single list item such as an image and a label.
❑
Allow you to control the display of the item programmatically.
Figure 7-5 is a list control with a custom item renderer containing an Image control and a Label control inside of an HBox container.
143
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 144
Part II: Developing in Flex 2.0
Figure 7-5: List control with a custom item renderer
Building Custom Item Renderers and Item Editors There are several ways to use item renderers in your application, such as using the drop-in method or using the inline method or as reusable components. ❑
The drop-in method inserts a single component as an item renderer by defining it in the list control’s itemRenderer property.
❑
The inline method defines the item renderer as one or more components using the child tags of the list control.
❑
Using a custom component as an item renderer is more efficient and promotes reuse. This means that you can reuse it in more than one place or application.
The Drop-in Method If you only need to drop in single components (such as a DateField or Numerical Stepper control), the drop-in item renderer is perfect. In other words, you define an existing Flex component as an item renderer for the list control. The following example has a DataGrid control with a CheckBox control as the item renderer of the second column:
144
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 145
Chapter 7: Customizing the User Interface
Flex automatically uses the data property to populate the CheckBox control with the current value of the column because the dataField of that column is set to the selected object property.
The Inline Method The drop-in method shows you how easy it is to use an item renderer in a list control. The only problem is that you cannot configure them the way you might want to. For more flexibility, you create an item renderer as an inline component. The following example is from the drop-in example, but instead uses the inline method:
145
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 146
Part II: Developing in Flex 2.0 In this example, an inline item renderer was used that allows you to center the CheckBox control vertically and horizontally within the cell.
A Component as an Item Renderer The advantage of using a component as an item renderer is that you can reuse it all over the application and in different applications, too. Using this method, you can create more complex item renderers because you will create a separate document or class for them. The following example is a custom item renderer called MyCustomItemRenderer.mxml:
To show you the power of item renderers, this custom reusable component has three Flex controls contained inside an HBox container. If you click the button, an Alert control pops up with current selected fruit and date values. These are passed into the item renderer via the data property. This example is the main application with the item renderer defined in the List control using the itemRenderer property:
146
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 147
Chapter 7: Customizing the User Interface You may find several areas in your application where the MyCustomItemRenderer may come in handy. This exact example merely demonstrates how powerful item renderers are. Information passed to an item renderer or item editor is done so through the data property of the item renderer or item editor. The ListData class defines the data type of the listData property implemented by drop-in item renderers or drop-in item editors for the List control.
Item Editors Item editors let you modify the value of the cell in a list control. The List, DataGrid, and Tree controls support item editors. This allows the user of your application to be able to edit rows of data inline without having to pop up a dialog box or bind it to a form below.
Overview of Cell Editing Process The specific process that occurs when a cell in a list control is edited is as follows:
1. 2.
The user releases the mouse button over the cell, or tabs to a cell. The itemEditBeginning event is dispatched, which you can use to disable editing of a specific cell or cells.
3.
The itemEditBegin event is dispatched to open the item editor, and can be used to modify the data passed to the item editor.
4. 5.
The user then edits the cell.
6.
The itemEditEnd event is dispatched to close the item editor and update the cell with new data. You can modify the data returned to the cell via the event, validate the new data, or return the data in a different format.
7.
The new data appears in the cell.
The user then ends the editing session and the cell editing session quits when the user removes focus.
Editable Cell The Flex list controls, such as the List, Tree, and DataGrid, include an editable property that can be set to true so that users can edit the contents of the control. The editable property is set to false by default. Setting the editable property to true on a DataGrid control means all columns are editable. If you do not want every column editable, set the DatagridColumn.editable property to false. In the Flex list controls, you can use the default item editor (the TextInput control), a custom item editor, or a custom item renderer as an editor. If you want the item renderer to be the editor, set the rendererIsEditor property of the list control to true. If you set the rendererIsEditor property to true, Flex will ignore the itemEditor property and use the item renderer as the item editor.
147
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 148
Part II: Developing in Flex 2.0
Returning Data from an Item Editor By default, Flex expects an item editor to return a single value to the list control. The editorDataField property of the list control specifies the property of the item editor that contains the new data. The value is converted to the appropriate data type for the cell. The default value of the editorDataField property is text that corresponds to the default item editor of a list control, the TextInput control. If you changed the default item editor to a DateField control, you must set the editorDataField property to the selectedDate property, as the following example shows:
In the preceding example, a DateField control is the item editor and, therefore, the editorDataField property is set to selectedDate, the property of the DateField control that contains the new cell data.
Sizing and Positioning an Item Editor You may notice that when you click in a cell, a popup control appears above the selected cell of the list control. The list control also hides the current value of the cell. Four properties can be used to size and position item editors within list controls: ❑
148
editorHeightOffset — Specifies the height of the item editor in pixels, relative to the size of the cell for a DataGridColumn control, or the text field of a Tree control
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 149
Chapter 7: Customizing the User Interface ❑
editorWidthOffset — Specifies the width of the item editor in pixels, relative to the size of the cell for a DataGridColumn control, or the text field of a Tree control
❑
editorXOffset — Specifies the x location of the upper-left corner of the item editor in pixels, relative to the upper-left corner of the cell for a DataGridColumn control, or the upper-left corner of the text field of a Tree control
❑
editorYOffset — Specifies the y location of the upper-left corner of the item editor in pixels, relative to the upper-left corner of the cell for a DataGridColumn control, or the upper-left corner of the text field of a Tree control
The following example sets the editorXOffset property of the DataGridColumn control to 10 pixels. This will offset the DateField control 10 pixels from the left.
Cell Editing Events The cell editing process of a list component dispatches three events: itemEditBeginning, itemEditBegin, and itemEditEnd. This was mentioned earlier in this chapter. There are default event listeners defined for these three events, but you can implement your own event listeners that will execute before the default ones. In your implementations, you can modify the data passed to or returned from an item editor. If you modified the data in the event listener for the itemEditBeginning
149
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 150
Part II: Developing in Flex 2.0 event, that code would execute first, then the default event listener would run to continue the editing process. You can replace the default event listener with your own implementation. To prevent the default one from executing, call the event.preventDefault() method from anywhere in your event listener. Each editable list control has a corresponding event class that defines the event object for the cell editing events. The DataGrid control uses the DataGridEvent class; the List and Tree controls use the ListEvent class. The following example defines an event listener, but with no implementation for the List control: public function myCellBeginEvent(event:ListEvent):void { // implement the event listener. }
Accessing Cell Data When a user edits a cell, you can access the current value, the new value entered by the user, or the item editor used to edit the cell. To access the current value of a cell, use the editedItemRenderer property of the list control. The data provider element is accessible in Tree and List controls, and the element for the whole row in a DataGrid control. Use the itemEditorInstance property if you need to access the new cell value of the item editor. Note that the itemEditorInstance is not initialized until the cellBeginEvent has executed, and would typically only access it within the event listener of the itemEditEnd event. The following example contains an event listener defined on a DataGrid control for the itemEditEnd event:
In the preceding example, you get the item editor (which is a TextInput control) by casting it to the relevant type. If it were a custom item editor, you would need to cast it to that type. Now that you have a reference to the item editor, you can access the old value and new value.
Preventing a Cell from Being Edited To prevent a cell from being edited, you can call the event.preventDefault() method in the event listener of the itemEditBeginning event. The following example calls the preventDefault() method of the event passed in for the itemEditBeginning event:
151
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 152
Part II: Developing in Flex 2.0
The preceding example uses the rowIndex property of the event, but, in essence, you can use any property of the DataGrid to stop a cell being edited. If you try to edit the three rows of the DataGrid, it will not work.
Tooltips Tooltips, as you may already know, are a method of providing useful information to the user. When a user moves the mouse over a specific area, a tooltip pops up with the relevant information. Tooltips can be used to help your users work through your application, or you can use them to add extra functionality. You will find that tooltips are in many desktop applications written for Windows or Linux. They add extra information when a user moves the mouse pointer over an onscreen element. Figure 7-6 shows a tooltip that appears when the user’s mouse pointer hovers over the TextInput control. The tooltip will eventually disappear, even though the user’s mouse pointer remains over the component. You can set the time it takes for the tooltip to appear and disappear.
152
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 153
Chapter 7: Customizing the User Interface
Figure 7-6: Tooltip for TextInput control
Tooltips support style sheets and dynamic loading of the text, but do not support embedded HTML. Tooltips are the basis for the accessibility implementation, and all controls that support accessibility do so by making their tooltip text readable by screen readers.
Creating Tooltips All visual components that extend the UIComponent class support a toolTip property. You set the toolTip property to a text string and then, when a mouse pointer hovers over the component, the string appears in the tooltip. The following example shows a TextInput control with the toolTip property defined:
To do the same in ActionScript, set the toolTip property of the component instance to text string, as the following example shows:
With regard to children in containers, if you do not define a tooltip on the child of a container, the tooltip of the parent container is displayed, instead. For example, if you add a TextInput control to a Panel container that has a tooltip, the user sees the Panel container’s tooltip text when the mouse pointer is over the Panel. To clear the child’s tooltip text, set the toolTip property to a blank string. So, in other words, the children inherit the tooltip from the parent container.
153
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 154
Part II: Developing in Flex 2.0 Using Styles with Tooltips Tooltip text and tooltip box appearance can be changed using CSS syntax or the StyleManager class. Changes to the tooltip’s styles are reflected in the whole application. To change the styles of a tooltip, use the tag with a type selector to override the default one. The following example sets the styles of the tooltip using CSS: ToolTip { fontFamily: “Arial”; fontSize: 20; fontStyle: “bold”; color: #FFCC00; backgroundColor: #999999; }
To use the StyleManager class to apply styles to tooltips, use the setStyle() method on the tooltip type selector, as the following examples shows:
Tooltip Events Tooltips have many events that are dispatched during their life cycle. The types of events are contained in the ToolTipEvent class. The usual properties type and target are available, but there is also a property called toolTip that references the tooltip itself. With this reference, you can add the tooltip’s text property inside the event handler. The following example gets a reference to the tooltip and sets its text to the myLabel instance text property:
ToolTipManager Class The ToolTipManager class allows you to customize the tooltip functionality, such as enabling and disabling tooltips, or setting the display delay. The ToolTipManager class contains a reference to the current tooltip in the currentToolTip property.
Enabling and Disabling Tooltips To enable or disable a tooltip, set the ToolTipManager.enabled or ToolTipManager.disabled properties. The following example has two Button controls, one for enabling and one for disabling tooltips:
155
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 156
Part II: Developing in Flex 2.0 Delay Times for Tooltips The delay time is the amount of time that passes before something happens. If you move your mouse pointer over a component and tooltips are enabled, there is a brief delay by default before the tooltip appears. This is great if a user is not looking for the tooltip to appear. The ToolTipManager class allows you to set the length of time that passes before a tooltip appears, and how long the tooltip remains onscreen. There are three properties the ToolTipManager class exposes regarding delay times of tooltips: ❑
showDelay — The length of time (in milliseconds) that passes before Flex displays a tooltip
❑
hideDelay — The length of time (in milliseconds) that passes before Flex hides the tooltip
❑
scrubDelay — The length of time (in milliseconds) that a user can take when moving the mouse between components before Flex waits for the duration of the showDelay to display
the tooltip
Tooltip Effects Tooltips can use custom or standard Flex effects, by setting the showEffect or hideEffect property of the ToolTipManager class. The following example uses Blur and Fade effects when the tooltip appears. This is achieved by using the Parallel effect.
Fonts used in this example do not fade, because you must use embedded fonts to achieve this effect.
Cursor Manager The Cursor Manager allows you to customize the cursor in your Flex application. You can use this to provide visual feedback to the user, such as waiting for processing to complete. The cursor image can be a JPEG, PNG, GIF, or SVG file, or a Sprite object or an SWF file. The default cursor in Flex is the system cursor used in your operating system. The Cursor Manager lets your control the functionality and appearance of the cursor. You may want different cursors, depending on the context of your application. The Cursor Manager contains a list of cursors with priorities. The one with the highest priority is currently visible. You might have two cursors with the same priority, and Flex will use the most recent one.
Adding and Removing Cursors To create a new cursor, use the setCursor() static method of the CursorManager class. The new cursor will be added to the list. There is an optional priority property that can be specified so that the Cursor Manager knows what the priority of the new cursor is. If the priority is higher than any of the others in the list, that cursor is shown immediately; otherwise, the one with the highest priority must be removed to show another cursor. To remove the cursor, use the removeCursor() static method of the CursorManager class. If the cursor is removed that is currently being displayed, the cursor with the next-highest priority is shown immediately. The following example loads an external image. While it loads, the cursor is set to busy.jpg, and reverts back once the image has fully loaded into the Flash Player.
Busy Cursor Flex defines a busy cursor that is used to indicate to the user that your application is processing, such as calling a remote server and waiting for a response. The default busy cursor is an animated clock. The CursorManager has two static methods that can be used to control the busy cursor. The setBusyCursor() method obviously displays the busy cursor, and the removeBusyCursor() method removes it from the cursor list. The following example contains two Button controls; one shows the busy cursor and the other hides it:
When the busy cursor is shown, you can still interact with the entire application, unless you have disabled something such as a Panel and all its children. If you do not want the user to interact with your application when the busy cursor is showing, set the Application.application.enabled property to false.
158
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 159
Chapter 7: Customizing the User Interface
Summar y Being able to customize a Flex application’s user interface is very important when building a successful product. Flex allows your designers to customize the look and feel of the application to fit the user’s needs. At the end of the day, your imagination is your only limit. Chapter 8 carries on from here to show you more advanced topics, such as view states, transitions, drag and drop, embedding assets, Flex printing, talking to JavaScript, and using shared objects.
159
02671c07.qxd:02671c07
4/20/07
2:49 PM
Page 160
02671c08.qxd:02671c08
4/20/07
2:53 PM
Page 161
Flex UI Topics This chapter examines a variety of topics, including dynamic layout controls, states and transitions, embedded assets, local data storage using shared objects, communication with the browser, history management, and accessibility.
Repeaters and Containers The Repeater control is a layout control that allows the interface to be drawn dynamically by looping through its dataProvider. Each object in the dataProvider can be accessed within the repeater by binding to “repeater id”.currentItem.
Using the Repeater Component The basic example in Listing 8-1 shows a simple Repeater with a horizontal layout accessing the label property of the objects within ArrayCollection dp.
Listing 8-1: Basic Repeater
When the application is initialized, the repeater will execute and loop through its dataProvider four times (the length of the ArrayCollection), drawing four buttons horizontally. Figure 8-1 shows the results, and Figure 8-2 shows the results after setting the repeater’s layout property to vertical.
Figure 8-1: Using the Repeater control
Figure 8-2: Vertical Repeater control
Repeater Component Execution Process The Repeater component will execute initially when it is created, and then it will re-execute whenever there is a change to its dataProvider, startingIndex, or count. If any of these properties change, the Repeater will re-execute, destroy all of its children, then re-create the children, and automatically
162
02671c08.qxd:02671c08
4/20/07
2:53 PM
Page 163
Chapter 8: Flex UI Topics redraw the screen. This allows the developer a great deal of flexibility because the user interface can be drawn and redrawn by simply changing the dataProvider. The advanced Repeater example shown in Listing 8-2 uses a custom component and Tile control to show a real-world example of how a Repeater control could be used to represent multiple categories in a sample e-commerce application.
Listing 8-2: Advanced Repeater
Figure 8-3 shows how the code shown in Listing 8-2 will execute when the application initializes. The Repeater will loop through the category1 ArrayCollection creating the six product custom components. (For more information on custom components, see Chapter 13.) Figure 8-4 shows how the Repeater re-executes after the dataProvider changes when the Category 2 button is clicked.
163
02671c08.qxd:02671c08
4/20/07
2:53 PM
Page 164
Part II: Developing in Flex 2.0
Figure 8-3: Code execution when application initializes
Figure 8-4: Re-execution of the Repeater control when the Category 2 button is selected
Following is the custom component Product.mxml used in Listing 8-2:
164
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 165
Chapter 8: Flex UI Topics
Using V iew States View states enable developers to alter the appearance of the application view by simply adding code to add children, remove children, or change component properties. After defining the base state (all MXML files are created in the base state), the developer can create a new state using the Design view of Flex Builder, or by simply adding a code block like this:
Using this code, when you change view state to “newState”, the application will add a Button component to the view and position it before the hbox1 component. The Button would then show either to the left of hbox1 or above hbox1, depending on whether the application is a horizontal or vertical layout. To switch between states, you set the currentState property of the component or application. To go back to the base state, simply set the currentState property to an empty string. Listing 8-3 shows a sample application with a two-state view of a simple product.
Listing 8-3: Two-State View
Figure 8-5 shows the application in its base state, and Figure 8-6 shows the application in the “Description” state, after the user has clicked the Open Description button.
Figure 8-5: Application in base state
Figure 8-6: Application after user clicks the Open Description button
166
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 167
Chapter 8: Flex UI Topics
Using Transitions The preceding example accomplishes multiple states of a product view, but the application jumps from one state to the next rather abruptly. Luckily, Flex offers very simple ways to make the application change more gracefully. Flex calls these transitions.
Transitions Applied to View States A transition is a way to make a smoother change between states. A transition can be a single effect, or a group of effects run in sequence or in parallel. Using the simple state example, you can add a Resize effect by simply adding the following code right after the mx:Application tag:
This code block adds a Resize effect that plays for a duration of 500 (half a second) when switching from the ““ (base state) to the “Description” state, and then again when switching from the “Description” state back to the ““ (base state). Transitions allow you to apply more than one effect either in parallel or in sequence. The advanced transitions example shown in Listing 8-4 is a navigation system using state management to move between panels with a smooth transition. Each state sets the size and position of the three panels.
Listing 8-4: Advanced Transitions Example
167
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 168
Part II: Developing in Flex 2.0
168
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 169
Chapter 8: Flex UI Topics The transition is accomplished by using a sequence of a Move, followed by Rotate of 360 degrees, and finally a Resize. Because the transition is set to run when changing fromState * (all) to State *, it will run all state changes. The sequence is also set to target all panels, which means it will affect every panel on every state change, which is obvious when the Rotate effect plays (as shown in Figure 8-7). If you were to remove the Rotate effect, you would only see the effect on the panel that is growing and the panel (if any) that is shrinking.
Figure 8-7: Effect of Rotate
Transition Event Handling When Flex is changing states, there is a defined process order. There are two events dispatched along the way. The first event dispatch (currentStateChanging) occurs when the current state is changing, and the second occurs when the state has completed the change. The following seven steps (as defined in the Flex 2 documentation) show the official process Flex uses when changing from one state to another:
1. 2. 3. 4. 5. 6. 7.
You set the currentState property to the destination view state. Flex dispatches the currentStateChanging event. Flex examines the list of transitions to determine the one that matches the change of the view state. Flex examines the components to determine the one that matches the change of the view state. Flex applies the destination view state to the application. Flex dispatches the currentStateChange event. Flex plays the effect you defined in the transition.
It is important to know that if the currentState property is changed again, before Flex completes the current transition, Flex will skip to the end of the transition and start the cycle over again as listed in the previous steps.
169
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 170
Part II: Developing in Flex 2.0
Transition Action Effects To control the order that Flex uses to apply transitions, you can apply action effects. Action effects can be applied to the view state properties to gain additional control over the each property. There are four action effects that correspond to four view state properties. The following table shows the four action effects and their corresponding view state properties. Action Effect
View State Property
SetPropertyAction
SetProperty
SetStyleAction
SetStyle
AddChildAction
AddChild
RemoveChildAction
RemoveChild
Each action effect will play when the corresponding view state property occurs. Let’s go back to the basic state example in Listing 8-4 and change the transitions block to the following:
When running the application, you will now notice that the product description text does not appear until after the resize has occurred. The visible property has been given a startDelay of 500 to exaggerate the point. Action effects can give you that fine touch you need to really refine your transitions to be exactly the way you want them to perform.
Effects and Filters Transitions also support filters, which allow the developer to make sure certain effects run only on some of the targets in the Sequence, rather than all of the targets (which is the default behavior). Using the preceding code sample, simply add filter=“move” to the Rotate effect, and you will now notice that only the panels that are moving will have the Rotate effect applied. Transitions and states are one of the
170
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 171
Chapter 8: Flex UI Topics coolest features of Flex 2. Experiment by changing from Sequence to Parallel, or by using other effects (Blur, Dissolve, Zoom, and so on).
Using the Drag-and-Drop Manager The Flex DragManager class allows assets to be dragged and dropped for either purely visual reasons or for moving data between components.
List Control Drag-and-Drop Functions List controls have drag-and-drop functionality built in and are very easy to set up and use. The example shown in Listing 8-5 uses three simple List components — one original List to drag from and two additional List components to accept the drag item. The setup is as simple as setting dragEnabled=“true” on the List component that contains the drag data, and setting dropEnabled=“true” on the List components that will accept the data. Figure 8-8 shows the rotation transition. Figure 8-9 and Figure 8-10 show Listing 8-5 in action.
Listing 8-5: List Control Drag and Drop
171
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 172
Part II: Developing in Flex 2.0
Figure 8-8: The rotation transition
Figure 8-9: A valid drop when over a target
Figure 8-10: An invalid drop when not over a target
Adding Drag-and-Drop Support to Other Components Non–list-based controls (or containers) must explicitly add support by using a series of events and classes that must be implemented. The DragManager class and its doDrag() method manage the start of the drag.
172
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 173
Chapter 8: Flex UI Topics The DragSource class holds the data that is being dragged. In Listing 8-6, the data would be the name and price of the baseball hats. The DragEvent class dispatches events when the drag is in operation.
Listing 8-6: Custom Drag-and-Drop Operation
Figure 8-11 shows the results of the custom drag-and-drop operation.
Figure 8-11: The compiled results of Listing 8-6
Events that will be broadcast include dragEnter, dragOver, and dragComplete. Their definitions are described in the following table.
174
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 175
Chapter 8: Flex UI Topics Event
Description
dragEnter
The dragEnter event is dispatched when the drag item moves across the drop target. This allows you to alert the user that the item is over the target by programming a visual alert to the drop target. This could be a color change, a green border, and so on.
dragOver
The dragOver event is dispatched while the drag item is over the target and occurs after the dragEnter event. This would be a good time to validate that the item is going to be accepted by the target before it is dropped.
dragDrop
This is the dragDrop when the drag item is released over the target.
dragComplete
The dragComplete event broadcasts when the user releases the drag item, whether or not it is on the drop target.
dragExit
The dragExit event is broadcast when the drag item is dragged outside of the drop target, but is not dropped on the drop target.
Embedding Assets Flex supports the embedding of images, movies, sound files, and fonts. Embedding the assets will compile the image or font into the generated SWF file. Although you can load assets at run-time using relative paths, embedding the assets means that they are available as soon as the application initializes. It also means that you can distribute your application as a single SWF file. Another reason to embed assets is that there are some areas such as icons where only embedded assets are allowed by Flex.
Images There are several ways to embed an image asset. Here are two methods of embedding an image file to be used as a Button’s icon: ❑
Embed inline:
❑
Bind with ActionScript:
175
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 176
Part II: Developing in Flex 2.0
Fonts There are multiple benefits to embedding a font as an asset. Embedded fonts can be rotated, which is often necessary when labeling chart data. Embedded fonts can also show transparency, and show better results when using a Zoom effect. Another key feature of embedded fonts is that the developer can be sure that the fonts will appear the same on all machines because there is no need to rely on the machines’ installed fonts. Only fonts that are TrueType Font (TTF) files or fonts that have been embedded in an SWF file can be embedded. There are several ways to embed and apply a font: ❑
Embedding a font (Sample 1):
@font-face { src:url(“HELVETIB.TTF”); fontWeight: bold; fontFamily: myHelveticaBold; }
❑
Embedding a font (Sample 2):
❑
Using an embedded font via a Cascading Style Sheet (CSS):
Label { fontFamily: myHelveticaBold; fontWeight: bold; }
❑
Using an embedded font inline:
SWF and Sound Files SWF and sound files can be embedded as classes in the same way as image files.
Using the Histor y Manager History management in Flex is achieved when the application is embedded within a Web page. The page will contain a hidden HTML frame that contains a history SWF, which stores and retrieves information on the application’s current state. This enables the user to use the browser’s Back and Forward buttons to navigate within the application.
Components with Built-in History Management Components such as TabNavigator and Accordion have history management enabled by default. ViewStacks can also utilize history management, but it must be enabled by setting its historyManagementEnabled property to true. You can also turn off history management in the TabNavigator and Accordion by setting this property to false.
Adding History Management to Components It is also possible to add history management to other components by implementing mx.managers .IHistoryManagerClient and supplying the saveState and loadState methods, which are required by the interface. The following sample code extends the ToggleButtonBar and adds history management:
Note that history management will only work when all of the necessary JavaScript and SWF files are available in the application’s root folder, and the application’s HTML wrapper has the necessary code to include the needed files and create the hidden frame. Flex Builder 2 will generate the wrapper page and all necessary files within the project’s bin folder. You can also get these files from your SDK install. Listing 8-7 is a sample of the wrapper HTML page.
Listing 8-7: Sample Wrapper HTML Page Advanced Transitions body { margin: 0px; overflow:hidden } Get Flash’; document.write(alternateContent); // insert non-flash content } // -->
Flex Printing Flex 2 has come a long way in its printing capabilities. It is now very simple to print simple components, as well as to print multiple pages of grid data. All print jobs begin in the same way. The first thing to do is to create a new FlexPrintJob, followed by a call to start the print job. Then, simply add any object to the print job using the addObject method, and, finally, send it to the printer.
180
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 181
Chapter 8: Flex UI Topics
Basic Printing Listing 8-8 is a very simple print job that adds a Label component to the print job.
Listing 8-8: A Simple Print Job
Printing Multiple Pages Listing 8-8 prints the Label components’ text property “Hello World”. However, you could just as easily have set the addObject target to be a VBox, which would print all child components. Try changing the line printJob.addObject(myLabel,”none”); to printJob.addObject(this,”none”); and Flex will now print both the Label and Button components. By adding multiple objects to the print job, Listing 8-9 will print two pages: “Hello World page 1” and “Hello World page 2”.
Listing 8-9: A Simple Multipage Print Job
Rather than hard-coding the objects to be added to the print job, you could also loop over an array to add pages dynamically.
Printing Grid Data Another very common need is the ability to print grid data formatted properly. Flex 2 has made this a very easy thing to do. You can print multiple pages of data and Flex will handle all page breaks automatically. By simply advancing the print grid’s data using the nextPage() method, and then testing to see if the next page is valid within a while loop, you can add pages to the print job until there is a no additional data. At that point, simply break the loop and send the job to the printer. The other thing you will notice is that the visible property of the PrintDataGrid is set to false, but this doesn’t stop the job from printing correctly. Listing 8-10 will display a regular DataGrid component, but will print a PrintDataGrid component across multiple pages.
Listing 8-10: PrintDataGrid Sample
Communicating with the Wrapper The ExternalInterface API can communicate seamlessly from Flex to JavaScript, and from JavaScript to Flex. This gives the Flex application to access thousands of JavaScript methods and the browser access to all of the Flex methods. The ease of passing data from the browser to Flex and back opens up a whole new world of hybrid applications. Setting up the calls between Flex and JavaScript is as simple as importing the ExternalInterface class and creating callbacks. Callbacks define the function names and handlers, and allow Flex methods to be called from JavaScript. On the JavaScript side, all that is needed is a method to determine the browser type (this is simply a way to get the correct document name) and then a call to the callback function name, which was defined within Flex.
Flex to JavaScript, JavaScript to Flex Listing 8-11 will send messages from Flex to a JavaScript Alert, and also send messages from JavaScript to Flex.
Listing 8-11: Flex to JavaScript
183
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 184
Part II: Developing in Flex 2.0 import flash.external.ExternalInterface; import mx.controls.Alert; public function initApp():void { this.setupCallbacks(); } // Called from JavaScript public function callFromJavascript(s:String):void { Alert.show(s,”Flex Alert”); } // Call to JavaScript private function sendToJavaScript():void { ExternalInterface.call(“getFromFlex”,valueForJavascript.text); } // Set up callbacks private function setupCallbacks():void{ ExternalInterface.addCallback(“callFromJavascript”,callFromJavascript); }
Listing 8-12 is the HTML file with the JavaScript to handle the calls to and from Flex.
Listing 8-12: HTML with JavaScript ExternalInterfaceSample // get from Flex function getFromFlex(s) { alert(s); } // send to Flex function sendToFlex() { // Call a Flex function named callFromJavascript passing a string thisMovie (“ExternalInterfaceSample”).callFromJavascript(document.form1.valueForFlex.value); } // Determine browser type function thisMovie(movieName) { if (navigator.appName.indexOf(“Microsoft”) != -1) { return window[movieName]; } else { return document[movieName]; } }
184
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 185
Chapter 8: Flex UI Topics
Verify that JavaScript Has Loaded Listing 8-12 will work fine as long JavaScript is loaded before Flex has set up the callback methods. However, this is not something that can be assumed. There is a simple way to test to ensure that JavaScript has fully loaded and is ready before the callbacks are set up. The first thing that is needed is a way for JavaScript to know whether it is ready. By setting a function call within the HTML body tags’ onload property, you can set a local Boolean variable storing the state of JavaScript’s readiness to true. This variable can then be returned to Flex when Flex calls to test JavaScript’s readiness. The Flex side is a little more complicated. Once the Flex app is loaded, you call the method to get the JavaScript’s readiness state. If this returns true, you know JavaScript is ready, so you can set up the callbacks. If this variable returns false, a timer is created to poll JavaScript until it is ready. Once it is ready, the timer is stopped and the callbacks can be set up. Listing 8-13 and Listing 8-14 show how to test JavaScript’s readiness.
Listing 8-13: Flex Code to Test JavaScript
185
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 186
Part II: Developing in Flex 2.0 import mx.controls.Alert; import flash.external.ExternalInterface; private function initApp():void{ if(this.isJSReady()){ // JavaScript ready so we can set up the callbacks from JavaScript this.setupCallbacks(); } else { // create a timer to poll JavaScript until it is ready var readyTimer:Timer = new Timer(100); readyTimer.addEventListener(TimerEvent.TIMER, jsNotReady); readyTimer.start(); } } private function isJSReady():Boolean { // Call to JavaScript to see if it is ready return ExternalInterface.call(“isJSReady”);; } private function jsNotReady(event:TimerEvent):void { // Check to see if JavaScript is ready and stop timer if it is if (this.isJSReady()) { Timer(event.target).stop(); // JavaScript ready so we can set up the callbacks from JavaScript this.setupCallbacks(); } } private function setupCallbacks():void{ // Add callbacks here mx.controls.Alert.show(“JavaScript is Ready”); }
Listing 8-14: HTML Wrapper to Let Flex Know JavaScript Is Ready function thisMovie(movieName) { if (navigator.appName.indexOf(“Microsoft”) != -1) { return window[movieName]; } else { return document[movieName]; } } var jsReady = false; // called from Flex see if JavaScript is available function isJSReady() { return jsReady; } // called when the body’s onload fires function init() {
186
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 187
Chapter 8: Flex UI Topics // JavaScript is now available jsReady = true; }
The Flex/JavaScript communication bridge is accessible by default when the SWF is embedded in the same page as the JavaScript. This can be overridden by setting the allowScriptAccess property of the and tags on the wrapper HTML page.
Wor king with Shared Objects Shared objects are a very powerful tool in local data storage. It can be very useful for saving preference data to make the user experience a more personalized one. A good example would be a custom component layout in a portal-type application. You can also use the local shared object data storage to make an application perform correctly if the user is using the application offline. You can then write your own routines to sync back to the database server to store this information when a connection is established.
Saving and Reloading Data from Shared Objects Listing 8-15 will save the user’s data to a SharedObject when the rememberMe CheckBox is selected. Upon selecting the CheckBox, the application will write the firstname and lastname properties to the SharedObjects data property and then call the flush method to save the data to the user’s hard drive. Reloading the application will fetch the SharedObject and show the first and last names as they are being bound to the text inputs.
187
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 188
Part II: Developing in Flex 2.0 Listing 8-15: Saving a Shared Object
Another option to saving the information would be to create an instance of a custom person class to store both the firstname and lastname properties, and then save the full object to the SharedObject. Something to remember about SharedObjects is that users can determine the amount of disk space they are willing to give to storing these objects. Although the default is 100KB (which is a generous size for simple data), users can set it anywhere from none to unlimited within the Flash Player settings. If the application tries to store an object that pushes the storage total to be greater than the maximum allocated, users will get a dialog box asking them if they would like to increase the storage limit.
188
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 189
Chapter 8: Flex UI Topics
Designing Accessible Applications The Flex Accessibility class allows for communication with screen readers for visually impaired users by providing the application’s content to the user as speech or by driving a Braille display.
Enabling Accessibility in Your Application Flex does not have the accessibility features enabled by default. If you wish to enable accessibility for all applications under an FDS server, just make the following change to the flex-config.xml file: true
You can also enable or disable (if the config file has been updated as mentioned previously) by adding accessible=true or accessible=true to the application’s URL. Here is a sample: http://www.yourdomain.com/myapp/index.mxml?accessible=true http://www.yourdomain.com/myapp/index.mxml?accessible=false
If you are using the SDK command-line compiler, you can add the following argument: mxmlc -accessible c:/dev/myapps/mywar.war/app1.mxml
Components with Built-in Accessibility Many of the Flex components have accessibility built in. For example, when a screen reader encounters a TabNavigator, it will indicate each tab by saying the word “tab” and then indicate the selected tab with the word “active.” The user can also navigate between tabs with the arrow keys and select a tab with the Enter key. For a complete description of the behaviors of all of the Flex-accessible components, please refer to the Flex documentation.
Customizing Your Components for Accessibility Once your environment is set up for accessibility, you can add code to your application for defining custom names and descriptions of your components. The Accessibility class is static, and can be read or set on many Flex components by using the components’ accessibilityProperties property. To set accessibilityProperties, simply create an instance of the AccessibilityProperties class and assign properties. The properties you can assign include name, description, forceSimple (when set to true will hide any child components from a screen reader), silent (when set to true, will hide itself from the screen reader), and shortcut (where you can assign a keyboard shortcut). You can do a run-time check to see if the user’s environment supports accessibility by using the Capabilities.hasAccessibility property. Accessibility.active will let you know if the
user’s screen reader is present. You must also include a call to Accessiblity.updateProperties() after you have assigned the new accessibilityProperties. This call should only be made one time after you have completed all of your updates to accessibilityProperties.
189
02671c08.qxd:02671c08
4/20/07
2:54 PM
Page 190
Part II: Developing in Flex 2.0 The following example checks the user’s machine and then creates and assigns AccessibilityProperties to a Button component:
Another important thing to remember about accessibility is that the application will be read from left to right, and from top to bottom, by default. To change the way the application is read, you can use the tabIndex property of every component to customize the read order of your application.
Summar y This chapter covered a wide range of user interface elements including repeaters, view states, transitions, drag-and-drop techniques, asset management, the History Manager, Flex printing, ExternalInterface, shared objects, and accessibility techniques. Although not very difficult to implement, many of the items covered in this chapter are used integrally to create a Flex application that has the look and feel of a “Web 2.0” application. By simply adding drag-and-drop or transitions, you can give your application something that is very complicated, or simply impossible, with standard HTML. Chapter 9 demonstrates many ways to bind data using regular variables, Flex models, and external XML. It also shows you how to validate and format data.
190
02671c09.qxd:02671c09
4/20/07
2:56 PM
Page 191
Flex Data This chapter discusses a variety of topics concerning working with data within your Flex application. The discussion examines different ways to bind, store, validate, and format data. Flex makes handling data very easy. You will see several ways to accomplish each of these tasks.
Data Binding When developing rich applications, you will encounter the need to reflect values from components, or data models to other components. MXML simplifies the process of syncing data values between components. This process is known as data binding.
Using The mx:Binding tag is a very simple way to bind data between Flex components without the use of ActionScript. The usage is as simple as setting a source and a destination. Once you have done this, the destination component will automatically update whenever there is a change to the source property. The following example binds the text property for the TextInput component bindFrom to the text property of the destination component bindTo. This is a known as a one-way binding. To make the binding work in both directions, you can add a second binding tag right below the first, with the source and destination in reverse. An example would be , as shown here:
02671c09.qxd:02671c09
4/20/07
2:56 PM
Page 192
Part II: Developing in Flex 2.0
The results of the code can be seen in Figure 9-1.
Figure 9-1: Results of using
Binding to Variables with [Bindable] Flex also allows data to be bound using ActionScript. By declaring a variable or a class with the [Bindable] metadata tag, you can then bind the variable to your components surrounding it with curly braces. Flex will then update the component whenever there is a change to the bound variable. If the class is declared as [Bindable], all public properties within the class will be bindable. The following example declares a variable named myLabelName, sets it to be the String “Hello World”, and binds it to a Label component. When the application initializes, “Hello World” will show as the text of the Label. The application also contains a TextInput component that is set to update the myLabelName variable on its change event. When the user types into the TextInput component, the myLabelName variable is updated and the change is also seen in the Label component that it is bound to.
192
02671c09.qxd:02671c09
4/20/07
2:56 PM
Page 193
Chapter 9: Flex Data
Figure 9-2 shows how the application looks after it initializes, and Figure 9-3 shows how the Label has been updated after typing in the TextInput.
Figure 9-2: Application after it initializes
Figure 9-3: Updating the Label
Binding Directly to Component Properties You can also bind directly to component properties. This allows you to dynamically adjust the view. This is a great way to show and hide components when conditions make this desirable. The following example binds the HSlider’s value property to the width property of the Panel. Moving the slider automatically adjusts the width of the Panel.
Figure 9-4 shows how the application looks when the slider is set to 300, and Figure 9-5 shows how the application has changed when the slider is moved to 160.
193
02671c09.qxd:02671c09
4/20/07
2:56 PM
Page 194
Part II: Developing in Flex 2.0
Figure 9-4: Slider set to 300
Figure 9-5: Slider set to 160
Data Modeling with Flex There are many ways to model data with Flex. The following examples show a few ways to model the same data. All of the examples will produce the exact same results, as shown in Figure 9-6.
A Basic Data Model Using the mx:Model tag and nested XML structures, it is very easy to create an object model that is automatically bindable. This allows for rapid generation of forms and other data-driven client interfaces.
194
02671c09.qxd:02671c09
4/20/07
2:56 PM
Page 195
Chapter 9: Flex Data
Figure 9-6: Data modeling
The following example creates a simple mx:Model with an id of contactmodel. The individual properties of the contactmodel are then bound to the Label components. Rich Tretola 101 Skye St. Anytown NY 11111 5165559999
[email protected]
Using an External XML File Listing 9-1 and Listing 9-2 both use the Contact.xml file to load external data by binding it to the source property on the mx:Model and mx:XML components. Their only difference is that one uses mx:Model and the other uses mx:XML. The examples are simply meant to show that you can use either of these mx tags to
195
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 196
Part II: Developing in Flex 2.0 bind to an external XML file. The contactmodel properties are then bound to the Label components just as in the previous example. A benefit of using an external XML file over that of an mx:Model is that the XML can be updated, and the changes will be reflected the next time the data is loaded without the need to recompile the application. The results can be seen in Figure 9-6. The following is the Contact.xml file. Rich Tretola 101 Skye St. Anytown NY 11111 5165559999
[email protected]
Listing 9-1: Binding to Contact.xml File with
Listing 9-2: Binding to Contact.xml File with
Binding a Data Model to a Custom Component To facilitate good code reuse habits, you can create a custom component to accomplish the same results shown in Listing 9-1 and Listing 9-2. The component shown in Listing 9-3 and Listing 9-4 is a simple
196
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 197
Chapter 9: Flex Data VBox that has a public [Bindable] variable named contactmodel, which is of type Object. This component can then be used in multiple places within your application, and only requires that you pass in an object containing the properties that you are binding to. In this case, this would be a contactmodel. The example shown in these listings produces the same results as shown in Figure 9-6.
Listing 9-3: Custom Component Contact.mxml
Listing 9-4: Binding to Contact.xml File with and a Custom Component
It is simple to add a second instance of the Contact custom component to Listing 9-3 and Listing 9-4 to create two complete components. The power of this comes in when you bind the second component to a different model. The following code binds to Contact.xml, as was done earlier, but also binds to Contact2.xml, which is another XML file with the same structure as Contact.xml with different values.
Figure 9-7 shows the results of this code.
197
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 198
Part II: Developing in Flex 2.0
Figure 9-7: Adding a second instance of a component
Binding Data to a Data Model So far, you have seen examples of binding data from a model to components. However, you can also bind from the component value to the model. Listing 9-5 will bind the text properties of the TextInput components to the model.
Listing 9-5: Binding from the Components to the Model {fnametxt.text} {lnametxt.text} {addresstxt.text} {citytxt.text} {statetxt.text} {ziptxt.text} {phonetxt.text}
198
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 199
Chapter 9: Flex Data {emailtxt.text}
You can see the evidence of this when clicking the Show Model Data button. This will launch an Alert component showing the values of the data in the contactmodel, as shown in Figure 9-8.
Figure 9-8: Binding from components to the model
199
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 200
Part II: Developing in Flex 2.0
Validating Data Flex has many built-in validator classes and also allows its base validator classes to be extended to easily create custom validators for your own projects. Say your company has a very specific format in its product codes. You could easily write a custom validator that validates that the product code matches the specified pattern. The following examples show how to use the built-in validators, as well as how to create a custom validator.
Flex Built-in Validators Listing 9-6 shows how to use the built-in validator classes and assign their properties. Each validator has a several properties defined as shown in the following table. The validators in the first example are bound to each TextInput’s text property. They are set to trigger when the Validate button is clicked, and the listener is the corresponding TextInput. The results of this example can be seen in Figure 9-9. Notice the usage of different types of validators contextual to the type of form field. For example, the ziptxt field uses the built-in ZipCodeValidator, which not only checks to see if the field has been filled in, but also checks to see if the value is a 5-digit number or a 5-digit + 4-digit number. Property
Description
source
Bound to the object containing the data.
property
Property of the source object containing the data.
trigger
Bound to the object that will trigger the validation.
triggerEvent
The event of the trigger object that causes the validation.
listener
The object that will get the validation response and error string.
enabled
Setting this value to false will stop the validator from performing validation.
required
If true, specifies that a missing or empty value causes a validation error. Default is true.
requiredFieldError
Error message when a value is missing and the required property is true.
Listing 9-6: Built-in Validator Classes
200
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 201
Chapter 9: Flex Data
Validating a Data Model Listing 9-6 validated the values entered into each TextInput separately. Listing 9-7 shows another way to validate the same data. This example binds all of the TextInput text properties to a data model. The data model is then set as the source for the validators, and the property is now set as the data model’s corresponding property. Each validator also has the listener property set to be the TextInput component so that the error string will be applied to the visual component and not the model.
Listing 9-7: Binding to a Data Model {fnametxt.text} {lnametxt.text} {addresstxt.text}
201
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 202
Part II: Developing in Flex 2.0 {citytxt.text} {statetxt.text} {ziptxt.text} {phonetxt.text} {emailtxt.text}
Figure 9-9 shows the results of Listing 9-6. However, because Listing 9-7 is simply a different way to validate the same data, the application will also look like Figure 9-9.
202
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 203
Chapter 9: Flex Data
Figure 9-9: Validating a data model
Simple Data Validation Using errorString If the Flex Validation Components do not serve your needs, you can choose to write your own custom validation code in ActionScript and assign the errorString, which will show on the component as the default red border and error tooltip. Listing 9-8 does a simple check to see if the TextInput being validated has a length of 10 characters. If the length of the myText.text property is less than 10, an errorString is assigned. If the length is greater than 10, the errorString is set to null, which removes the red border and tooltip.
Listing 9-8: Simple Data Validation
203
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 204
Part II: Developing in Flex 2.0
The results of Listing 9-8 can be seen in Figure 9-10 and Figure 9-11.
Figure 9-10: The errorString when validation fails
Figure 9-11: The same example as Figure 9-10, but this time the data is valid
Testing Validation Events To gain even more control over validation, validators can be triggered using ActionScript. The validate method of any Flex validator returns an object of type ValidationResultEvent. By testing the results object’s “type” property against the static INVALID property of a ValidationResultEvent, you can track the overall validation of the form. Because you are calling the validate method on validators that have their listeners defined, the red border and error string tooltips will be automatically applied. Once you are sure all of the validators have returned true, you can then submit the form data to whatever service is needed to handle the valid data. Listing 9-9 follows this method of validation and returns the results in an Alert popup after each validation attempt.
Listing 9-9: Testing Validation Events {fnametxt.text} {lnametxt.text}
205
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 206
Part II: Developing in Flex 2.0 {addresstxt.text} {citytxt.text} {statetxt.text} {ziptxt.text} {phonetxt.text} {emailtxt.text}
Figure 9-12 shows the results of Listing 9-9.
206
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 207
Chapter 9: Flex Data
Figure 9-12: Validation popup
Validating with ActionScript Another method of validating data is to create and trigger your validators using only ActionScript. Listing 9-10 creates an EmailValidator component as a new object using its default constructor, rather than in the previous examples where validators were created using MXML tags. You can see that the source and property properties are set using ActionScript as well. Both methods of validation will have the same results, so deciding whether to use MXML or ActionScipt to define your validators is more a choice of personal preference.
Listing 9-10: Validating with ActionScript
Figure 9-13 shows the results of Listing 9-10.
Figure 9-13: Validating with ActionScript
Formatting Data Formatting data for display is quite easy with Flex 2 because it ships with many built-in formatters, as well as making it very easy to create custom formatters when needed. The following section shows how to use a built-in formatter. Chapter 15 provides more information on custom formatters.
Flex Built-in Formatters Formatters are an easy way to format data into standard character patterns. There are many built-in formatters including phone, zip code, currency, date formatters, plus many more. Many formatters will accept a formatString property, which will define the way in which the data will be represented. Formatting the data is as simple as calling the format method and passing in the data to be formatted.
208
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 209
Chapter 9: Flex Data The following example uses the DateFormatter and shows three different ways to format the same data; along with the data is its raw format:
The selectedDate property of the DateChooser is being bound to four Label components, with the top one showing the data in its raw format, and the next three using different formatStrings to represent the same data. The results can be seen in Figure 9-14.
Figure 9-14: Using built-in formatters
209
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 210
Part II: Developing in Flex 2.0
Formatter Errors Formatters also contain an error property that allows you to get information on the status of the formatter. The error property will return as an empty string when there is no error, or “Invalid Data” when an error exists after calling the format method. Check the documentation on each formatter to see the default errors that are returned. The following example will attempt to format the phone number using PhoneFormatter every time the data changes. The error property returns with the invalid string on every call until the phone number is valid. ”; } else { // append to results results+=”Valid Phone Number - “+phoneFormatter.format(phone.text) + “”; // format original TextInput phone.text=phoneFormatter.format(phone.text); } } ]]>
210
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 211
Chapter 9: Flex Data In a real-world application, it would be better to use a validator and only attempt to format when the data passes validation. You can see the results of this in Figure 9-15. When creating a custom formatter, you can return custom error strings. Chapter 15 provides an example of custom error strings.
Figure 9-15: Shows the PhoneFormatter’s error property changing on each keystroke
Summar y This chapter demonstrated the many different ways to bind data, including using data models and external XML data, as well as simple variable bindings. There were also examples showing a few different methods to validate data. Lastly, the Formatter classes were discussed and some examples were provided to demonstrate how to format and how to catch formatter errors. Chapter 10 discusses the Flex charting classes, and provides examples of the many chart types and ways to alter the display of the charts. Some advanced charting techniques (including chart events, drill-down charts, and axis manipulation) are demonstrated. Finally, examples of ways to style a chart are shown.
211
02671c09.qxd:02671c09
4/20/07
2:57 PM
Page 212
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 213
Flex Char ting This chapter examines the rich capabilities of Flex charting. This chapter is very code-intensive, and offers examples of all of the Flex charting components, as well as examples of some of the advanced features.
Flex Chart Examples The ability to take data and represent it graphically with such ease is something that is uniquely Flex. Data visualization is one of those features that creates the “wow” factor that leaves a great impression on your audience. Outside of the HighLowOpenClose and Candlestick charts, all of the following examples will share the same data, but will represent it differently. Listing 10-1 shows the data class that will be used.
Listing 10-1: ChartData.as package { import mx.collections.ArrayCollection; public class ChartData { public function getDataSet1():ArrayCollection{ var productSales:ArrayCollection = new ArrayCollection( [ { Quarter: “1”, Gizmos: 10000, Widgets: 3000, Gadgets: 1000, Total: 14000 }, { Quarter: “2”, Gizmos: 12000, Widgets: 4000, Gadgets: 2000, Total: 18000 }, { Quarter: “3”, Gizmos: 15000, Widgets: 8000, Gadgets: 5000, Total: 28000 }, { Quarter: “4”, Gizmos: 20000, Widgets: 10000, Gadgets: 9000, Total: 39000 } ]); return productSales; }
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 214
Part II: Developing in Flex 2.0 public function getStockData1():ArrayCollection{ var goog:ArrayCollection = new ArrayCollection( [ { date: “3-Jul-06”, open: 420.04, high: 423.77, low: 419.45, close: 423.20, volume: “2,156,700” }, { date: “5-Jul-06”, open: 421.52, high: 422.80, low: 415.64, close: 421.46, volume: “4,985,600” }, { date: “6-Jul-06”, open: 423.38, high: 425.38, low: 421.98, close: 423.19, volume: “3,687,100” }, { date: “7-Jul-06”, open: 426.05, high: 427.89, low: 415.88, close: 420.45, volume: “6,041,900” }, { date: “10-Jul-06”, open: 423.44, high: 425.23, low: 416.38, close: 418.20, volume: “4,436,400” }, { date: “11-Jul-06”, open: 418.51, high: 425.05, low: 413.03, close: 424.56, volume: “5,971,300” }, { date: “12-Jul-06”, open: 422.09, high: 422.74, low: 416.73, close: 417.25, volume: “4,906,700” }, { date: “13-Jul-06”, open: 414.00, high: 418.34, low: 406.83, close: 408.83, volume: “6,924,500” }, { date: “14-Jul-06”, open: 410.33, high: 411.49, low: 398.61, close: 403.50, volume: “7,552,100” }, { date: “17-Jul-06”, open: 404.63, high: 411.00, low: 403.72, close: 407.89, volume: “5,811,900” }, { date: “18-Jul-06”, open: 409.75, high: 410.57, low: 397.74, close: 403.05, volume: “8,536,800” }, { date: “19-Jul-06”, open: 395.01, high: 401.14, low: 394.66, close: 399.00, volume: “8,518,500” }, { date: “20-Jul-06”, open: 404.28, high: 404.44, low: 385.66, close: 387.12, volume: “12,538,700” }, { date: “21-Jul-06”, open: 386.14, high: 391.75, low: 377.69, close: 390.11, volume: “11,754,600” }, { date: “21-Jul-06”, open: 386.14, high: 391.75, low: 377.69, close: 390.11, volume: “11,754,600” }, { date: “24-Jul-06”, open: 392.82, high: 393.89, low: 381.21, close: 390.90, volume: “8,086,100” }, { date: “25-Jul-06”, open: 385.02, high: 391.31, low: 383.80, close: 389.36, volume: “5,761,100” }, { date: “26-Jul-06”, open: 388.20, high: 391.91, low: 383.00, close: 385.50, volume: “5,531,900” }, { date: “27-Jul-06”, open: 387.37, high: 387.49, low: 377.95, close: 382.40, volume: “5,641,100” }, { date: “28-Jul-06”, open: 382.00, high: 389.56, low: 381.73, close: 388.12, volume: “4,083,600” }, { date: “31-Jul-06”, open: 388.00, high: 389.17, low: 383.31, close: 386.60, volume: “4,595,300” } ]); return goog; } } }
214
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 215
Chapter 10: Flex Charting
Area Chart As shown in Listing 10-2, the AreaChart component displays its data by lines with fills bounded to these lines to represent the values of the AreaSeries. The area chart has various representations, such as overlaid, stacked, 100 percent stacked, and high-low areas.
Listing 10-2: Area Chart
Figure 10-1 shows an area chart.
215
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 216
Part II: Developing in Flex 2.0
Figure 10-1: Area chart
Bar Chart The BarChart component displays data in a series of horizontal bars representing the data of the BarSeries. The bar chart variations include clustered bars, overlaid, stacked, 100 percent stacked, and high-low areas.
Listing 10-3: Bar Chart
The bars can be clustered (Figure 10-2), overlaid, stacked (Figure 10-3), or 100 percent.
Figure 10-2: Clustered bar chart
217
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 218
Part II: Developing in Flex 2.0
Figure 10-3: Stacked bar chart
Bubble Chart As shown in Listing 10-4, the BubbleChart component displays data as points that are determined by a value for the horizontal axis, a value for the vertical axis, and a value for the size of the chart item. The bubble chart tag also takes the maxRadius property. This defines the size of the bubble representing the largest item in the model.
Listing 10-4: Bubble Chart
Figure 10-4 shows a bubble chart.
Figure 10-4: Bubble chart
219
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 220
Part II: Developing in Flex 2.0
Column Chart As shown in Listing 10-5, the ColumnChart component displays data in a series of vertical bars representing the data of the ColumnSeries. Column chart variations include simple columns, clustered columns, overlaid, stacked, 100 percent stacked, and high-low.
Listing 10-5: Column Chart
220
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 221
Chapter 10: Flex Charting The bars can be clustered (Figure 10-5), overlaid (Figure 10-6), stacked, or 100 percent.
Figure 10-5: Clustered column chart
Figure 10-6: Overlaid column chart
221
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 222
Part II: Developing in Flex 2.0
Line Chart As shown in Listing 10-6, the LineSeries component displays data as a series of points that are connected by a line. You can also display line charts without points, or you can specify an icon to display as the point.
Listing 10-6: Line Chart
Figure 10-7 shows a line chart.
222
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 223
Chapter 10: Flex Charting
Figure 10-7: Line chart
Pie Chart As shown in Listing 10-7, the PieChart component displays data in a standard pie chart display.
Listing 10-7: Pie Chart
223
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 224
Part II: Developing in Flex 2.0
The pie chart can be displayed as a standard pie, a doughnut, or a stacked pie chart, as shown in Figure 10-8.
Figure 10-8: Pie chart
224
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 225
Chapter 10: Flex Charting
Plot Chart The PlotChart component displays data points based on a value for the horizontal position and a second value for the vertical position. Listing 10-8 shows an example of the PlotChart component.
Listing 10-8: Plot Chart
Figure 10-9 shows a plot chart.
225
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 226
Part II: Developing in Flex 2.0
Figure 10-9: Plot chart
Candlestick Chart Candlestick charts are used in the financial world to represent high, low, open, and close values of a security. The fill of the chart items are determined by the relationship between the open and close values. A chart item that has a solid fill is a representation of a close value that is less than the open value. A chart item with a border and no fill is a representation of a close value that is higher than the open value. The CandlestickSeries shown in Listing 10-9 requires all four values: high, low, open, and close.
Listing 10-9: Candlestick Chart
Figure 10-10 shows a candlestick chart.
Figure 10-10: Candlestick chart
227
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 228
Part II: Developing in Flex 2.0
HighLowOpenClose (HLOC) Chart The HighLowOpenClose chart shown in Listing 10-10 is another financial charting component that represents the same data as the candlestick chart. Rather than using a fill or border on the chart items, HighLowOpenClose adds a tick on the left side to represent the open value and a tick on the right side to represent the close value. As in the candlestick chart, the height of each chart item demonstrates the overall range of all four values.
Listing 10-10: HLOC Chart
228
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 229
Chapter 10: Flex Charting
Figure 10-11 shows an HLOC chart.
Figure 10-11: HLOC chart
Char ting Classes This section describes the charting classes in Flex.
Axis Label Axis labels are defined by the labelFunction property of the chart’s axis. The signature of the method that is called by the labelFunction is as follows: public function setAxisLabel(labelValue:Object, previousLabelValue:Object, axis:CategoryAxis, labelItem:Object):String { return labelValue; }
Depending on the axis type, the return value can be a String for a CategoryAxis (as shown previously), a Number for a NumericAxis, and a Date for a DateTimeAxis.
229
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 230
Part II: Developing in Flex 2.0 By updating the CategoryAxis object to the ColumnChart example from Listing 10-5, adding the setAxisLabel function will update the display of the column labels to show Quarter 1, Quarter 2, Quarter 3, and Quarter 4, as shown in Figure 10-12. public function setAxisLabel(labelValue:Object, previousLabelValue:Object, axis:CategoryAxis, labelItem:Object):String { return “Quarter “ + labelValue; }
Figure 10-12: Axis labels
Axis Title By simply adding the title property to the horizontal or vertical Axis, Flex will display a title on the corresponding axis. Updating the code in Listing 10-5 to the following will add a title across the bottom of the chart, as shown in Figure 10-12.
Axis Renderer Axis Renderers are used to alter the appearance of the horizontal or vertical axis. Adding the following code to Listing 10-5 will change the color of the horizontal axis and vertical axis to black, and the tick marks to gray, as shown in Figure 10-12.
230
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 231
Chapter 10: Flex Charting
Grid Lines Grid lines can be added to a chart horizontally, vertically, or in both directions. The fill colors and stroke thicknesses can also be set. The code to add grid lines looks like this:
Axis Types All axes have similar properties, including the following: ❑
dataProvider — Defines the data that will be used within the chart
❑
categoryField — The name of the element within the dataProvider to be charted
❑
displayName — Any string value to represent the categoryField in human-readable terms
❑
title — A value to be displayed along the axis
❑
labelFunction — The name of the function that will format the chartItem labels
Following are common axis types: ❑
CategoryAxis — CategoryAxis is used to represent the values of chart item data when the data type will be of type String. The column chart throughout this chapter (Figure 10-12) uses a CategoryAxis to represent the quarters of a fiscal year.
231
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 232
Part II: Developing in Flex 2.0 ❑
DateTimeAxis — DateTimeAxis is used to chart date values across an axis. The class con-
tains minimum and maximum values that can be laid out evenly across these values. If these values are not set, the axis will be created based on the supplied data. Setting the dataInterval and dataUnits will determine how the data is displayed. If dataInterval is set to days and dataUnits is set to 15 in a column chart, the chart will attempt to display a column every 15 days along the axis. ❑
LinearAxis — LinearAxis is used to display numeric data across an axis. Properties of LinearAxis include minimum, maximum, and interval. If minimum is set to 1000, maximum is set to 5000, and interval is set to 1000, the chart will display data at 1000, 2000, 3000, 4000, and 5000.
❑
LogAxis — LogAxis is used to display positive numeric data across an axis. LogAxis cannot display negative data. The LogAxis will display data logarithmically across an axis from a minimum to a maximum value. If a minimum or maximum is not set, it will be determined by the chart’s data.
ChartItem ChartItem is the unit representing the data within a series. In a ColumnChart, the ChartItem would
be a single grouping of columns.
ChartItemEvent ChartItemEvent is the object that is returned when a specific event occurs (click, double click, and so on). ChartItemEvent contains a reference to the event type as well as the hitData.
Hit Data HitData contains an item property that holds the data included in the ChartItem that broadcast the ChartItemEvent.
Legend A chart legend creates a road map of the chart so that the reader can easily interpret the chart items. By simply setting the legend dataProvider, a legend will be automatically created. The legend can be displayed horizontally or vertically by setting the direction property, and can also be manually created. All of the examples displayed in this chapter contain a legend.
Advanced Char ting The following sections cover some of the more advanced features of Flex charting. These include chart events, drill-down charts, mixed series types, multiple-axis charts, and axis label rotation.
Chart Events Chart components, like most Flex components, broadcast events with user interaction. These include click, double click, mouse down, mouse move, mouse up, item roll out, and item roll over. Listing 10-11 shows the event and the values of the data column that triggered the event. The sample
232
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 233
Chapter 10: Flex Charting code has the click and double click events active, with the others commented out. Run the code and uncomment the other events to see how each one is broadcast.
Listing 10-11: Chart Event
233
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 234
Part II: Developing in Flex 2.0
Figure 10-13 shows the results of Listing 10-11.
Figure 10-13: Chart event
Drill-Down Charts As shown in Listing 10-11, when clicking one of the columns in the chart, you are able to get the data associated with that column. By simply adding another charting component (in this case, the PieChart component), you can chart the data that is broadcast by the click event. Listing 10-12 creates a new ArrayCollection using the data from the click on the ColumnChart and then assigns it to the dataProvider of the PieChart.
Listing 10-12: Drill-Down Chart ” + h.item.Total +””; } ]]>
235
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 236
Part II: Developing in Flex 2.0
Figure 10-14: Drill-down chart
As you click each column, the pie chart will be redrawn using the new drill-down data, as shown in Figure 10-14.
Mixed Series Types All charts that subclass the CartesianChart class allow for mixed data series. By simply adding an additional series to the column chart example from earlier in this chapter, Flex can then display both charting elements within the same chart. Listing 10-13 adds a LineSeries to the column chart example that shows the total product sales. The only code that was added was the LineSeries object. Figure 10-15 shows how the chart has been initialized.
Listing 10-13: Mixed Series Chart
236
02671c10.qxd:02671c10
4/20/07
3:00 PM
Page 237
Chapter 10: Flex Charting
Figure 10-15: Mixed series chart
Multiple-Axis Charts Figure 10-15 now has multiple axes displayed. However, it is more difficult to read because all of the chart components are displayed (columns and line) using a single axis that has now been extended to accommodate the total sales. Fortunately, there is a way to better utilize the second series, and that is by using a multiple-axis chart. Instead of adding the new LineSeries to the series that includes the ColumnSeries, Listing 10-14 adds a secondSeries to the chart.
237
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 238
Part II: Developing in Flex 2.0 Listing 10-14: Multiple-Axis Chart
By adding the second series, the interpretation of the chart is now based on both a left vertical axis and a right vertical axis that have different values, as shown in Figure 10-16.
238
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 239
Chapter 10: Flex Charting
Figure 10-16: Multiple-axis chart
The example now has two chart series types, the ColumnSeries as well as the LineSeries that you just added. You will also notice that there is now an additional title on the right axis. This was added using the following code:
Axis Rotation Referring back to the candlestick chart example in Listing 10-9, you will notice that in order to fit the labels properly, a horizontalAxisRendered was added with canDropLabels set to true. However, there is another option. You can set the axis label rotation to 45 degrees, which would allow the labels to lay out nicely, as shown in Figure 10-17. To set rotation on the axis labels, you must first embed the font class that will be used for the chart component. The following code block will accomplish this for the candlestick chart example. The arial.ttf font file has been added to the root folder of this example. @font-face { fontFamily: arial; src:url(“arial.ttf”); } CandlestickChart{ fontFamily: arial; }
239
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 240
Part II: Developing in Flex 2.0
Figure 10-17: Axis rotation
Next, you must add a new horizontalAxisRenderer. The code for this renderer looks like this:
Char ting Effects Charting effects are animations that will run when a charting component is created, and also when the component’s dataProvider is updated.
SeriesInterpolate The SeriesInterpolate event will morph the chart’s current data to the chart’s new data.
SeriesSlide The SeriesSlide event will slide the old data off the screen, and then slide the new data onto the screen. You can set the direction of the slide by using the direction property. The default direction is left.
SeriesZoom The SeriesZoom event will implode and explode the data. You can set the horizontalFocus and verticalFocus of the implosion and explosion. The default focus is center for both.
240
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 241
Chapter 10: Flex Charting Listing 10-12 would redraw the pie chart whenever a column from the column chart was clicked. The pie would change very abruptly. The following example adds an effect to the pie chart to make the redraw a more elegant transition. Adding the effect is as simple as defining an effect. In this case, you use the SeriesInterpolate effect with a duration of one second:
All that is left to do is to update the PieSeries tags by adding showDataEffect=“{showPieEffect}”, making the completed tag look like this:
When you run the example again, you will see the pie chart morph to show the new data whenever a new column is clicked in the column chart. You may also wish to try the SeriesZoom and SeriesSlide effects. Here is some sample code to try out. Because they all use the same ID, you should only use one at a time.
Char t Style Examples Continuing to build on the styling you started earlier, Listing 10-15 adds some gradient fills for the column series, as shown in Figure 10-18.
Listing 10-15: Gradient Fill
242
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 243
Chapter 10: Flex Charting
243
02671c10.qxd:02671c10
4/20/07
3:01 PM
Page 244
Part II: Developing in Flex 2.0
Figure 10-18: Gradient fill
Summar y This chapter demonstrated the power of the Flex charting components and just how easy it is to create beautiful charts displaying the same data in many different formats. It also demonstrated some of the advanced charting techniques, ways to change the look and feel of a chart through effects and styling, and also how to listen for charting events. Chapter 11 delves into the many ways of getting data into Flex. It demonstrates how to configure and implement Flex data services, RPC services, and messaging services.
244
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 245
Data Access This chapter describes features regarding external data, such as either sending data or receiving data from a remote server. It also introduces you to Flex Data Services (FDS), which run on standard J2EE platforms and servlet containers. You learn about the three Flex features designed to transport data to and from applications: RPC services, Data Management Service, and Message Service. Note that in order to implement FDS, you must have at least a basic knowledge of Java Web applications. All the examples in this chapter require that you install FDS to use some of the FDS classes in the examples.
Ser ver-side Data Flex 2 provides a new messaging infrastructure that allows you to build data-rich applications. FDS integrates with existing common middleware and provides services that automatically synchronize data between client and server. There is support for real-time pushing of data and publish-subscribe messaging to enable collaborative and occasionally disconnected applications.
Flex Data Access The new messaging capabilities of Flex 2 allow you to build data-rich applications. The following describes the three features Flex provides to send and retrieve data from your applications: ❑
RPC services — Remote Procedure Call (RPC) is initiated by the client sending a request message to a known remote server in order to execute a specified procedure using supplied parameters. A response is returned to the client, where the application continues along with its process. The Flex 2 SDK allows you to call the services directly, but you cannot use serverside features that require FDS.
❑
Data Management Service — Provides your application with data synchronization, real-time data updates, data replication, data paging, and occasionally connected applications. You
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 246
Part II: Developing in Flex 2.0 can manage large collections of data and nested data relationships, such as one-to-one and one-to-many relationships. You can also use data adapters to integrate with data sources, or even create your own. ❑
Message Service — Enables Flex clients to use publish-subscribe messaging to integrate with enterprise backends that use message-oriented middleware, such as Java Messaging Service (JMS) systems. Flex Message Service offers data-push capability, enabling data to automatically be pushed to the client application without polling the server. You can create applications that collaborate or share data with other clients or other servers.
RPC Services RPC services allows you to make asynchronous calls to remote services that process the request and return the data back to the application. You define an RPC component in MXML using the , , or tag. The client RPC component calls a remote service, which then stores the response in an ActionScript object from which you can access the data. Figure 11-1 shows how RPC components interact with RPC services.
Client Tier User Interface
HTTP Service component - Send and receive data using HTTP GET or POST WebService component - Interact with Web services using SOAP over HTTP RemoteObject component - Invoke methods on remote objects Request
Result
Data format: AMF, SOAP, or HTTP
RPC service implementations: Java object, Web service, other
Resource tier Server Tier
Figure 11-1: RPC components interact with RPC services
246
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 247
Chapter 11: Data Access RPC Components with Flex 2 SDK You can use the Flex 2 SDK without FDS to create applications that call HTTP or Web services without a going through a proxy service. The and components send data either using HTTP or SOAP format. If you want to call remote services using the RemoteObject components, you should use FDS for Java objects or ColdFusion MX 7.0.2 with the Remoting Update. The data format for these two solutions would be Action Message Format (AMF) version 3. Following are some third-party solutions that achieve functionality similar to FDS or ColdFusion: ❑
WebORB — Midnight Coders (http://www.themidnightcoders.com) offers a product called WebORB, which is a platform-enabling development, deployment, and run-time execution of Rich Internet Applications. The product facilitates connectivity between rich clients created with Flex, Flash, or Ajax, and server-side applications developed with .NET, Java, Ruby on Rails, PHP, or XML Web Services. They all implement AMF0 and AMF3 protocols, and FDS. As of this writing, the full implementation of the Flex Data Management Services functionality will be available only in the commercial edition of the WebORB products.
❑
AMFPHP — AMFPHP is a free Open Source Flash Remoting gateway that is fast and reliable. You can check it out at http://www.amfphp.org.
❑
OpenAMF — The OpenAMF project (http://www.openamf.com) is a free Open Source alternative to Macromedia’s Java Flash Remoting. It is as capable of providing application services to Flash MX as Macromedia’s proprietary solution. This project began as a Java port of AMF-PHP.
❑
RemoteObject component for AMF0 — If you would like to use AMFPHP or OpenAMF, you must download a modified version of the RemoteObject components that Flex 2 provides for RPC services. This will allow you to call PHP or Java remote objects using the AMF0 protocol. The RemoteObjectAMF0 component, which was written by Renaun Erickson (http://renaun.com/ blog/flex-components/remoteobjectamf0), provides functionality to connect Flex 2 applications with AMF0 remoting servers.
RPC Components with FDS RPC components and FDS provide you with enterprise functionality, such as client authentication, proxying of services from different domains, white lists of permitted RPC service URLs, server-side logging of data, localization support, and centralized management of RPC services. Instead of contacting services directly, RPC components contact their relevant destinations, which are service endpoints that you can manage through a server-side XML file.
Data Management Service Data Management Service contains features such as data synchronization, which removes the complexity and error potential by providing a robust, high-performance synchronization engine between client and server. In addition to that, you also have functionality for data replication, occasionally connected applications, and for managing large datasets and nested relationships.
247
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 248
Part II: Developing in Flex 2.0
Messaging Service The Data Management Service consists of ActionScript libraries, which talk to Java libraries running under a J2EE server. This provides the capability to call Java methods running in your J2EE server, and use publish-and-subscribe messaging to enable push messaging to Flex 2 clients. You can create the messaging components on the client, either in MXML or ActionScript, which connect to server-side message destinations, send messages to those destinations, and receive messages from other messaging clients. Components that send messages are called producers, and those that receive messages are called consumers. The messages are sent over channels using the Real-time Messaging Protocol (RMTP) and AMF. A good example of using the messaging service feature in a Flex application would be a real-time stock ticker or a weather station application. These two applications would require regular updates provided by the messaging service.
Data Ser vices Configuration To use FDS, you must configure the Remoting Service, Proxy Service, Message Service, and Data Management Service in the tag of the Data Services services-config.xml configuration file.
Service Configuration Files The following table contains the files needed in configuring FDS. Commented versions of these files are available in the resources/configuration subdirectory of the FDS install directory. You can use those files as a template for your own configuration.
248
Filename
Description
service-config.xml
This is the main FDS configuration file. This contains security constraints, channel definitions, and logging settings for each service. The services can be defined inline, or you can reference them in other files.
remoting-config.xml
The Remoting Service configuration file defines the Remoting Service destinations to work with remote objects.
proxy-config.xml
The Proxy Service configuration file defines the Proxy Service destinations for working with Web services and HTTP services (REST services).
messaging-config.xml
The Message Service configuration file defines Message Service destinations for performing publish-subscribe messaging.
data-management-config.xml
The Data Management Service configuration file defines the Data Management Service destinations for working with Data Management Service destinations.
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 249
Chapter 11: Data Access The following example shows you how to include a file by reference into the services-config.xml:
The file-path attribute is relative to the location of the services-config.xml file.
Message Channels Messages are transported to and from service destinations over message channels that are part of the Flex messaging system. You can take any service and pair it with any type of channel. The channels that are supported are HTTP, AMF, and RMTP, and all of them can be used securely. The AMF and HTTP secure channels transport data using HTTP over Secure Socket Layer (HTTPS) and the RMTP secure channel uses RMTP over Transport Layer Security (TLS). The following example is an AMF channel definition. Below the channel definition is a destination that references it.
Channels can also be assigned on the client at run-time by using the ChannelSet object. This object contains one or more Channel objects. var channelSet:ChannelSet = new ChannelSet(); var myChannel:Channel = new AMFChannel(“my-polling-channel”, endpointURL); channelSet.addChannel(myChannel); // Assign the ChannelSet object to the RemoteObject instance myRO.channelSet = channelSet;
249
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 250
Part II: Developing in Flex 2.0 You can add as many Channel objects to the ChannelSet as you like. The ChannelSet object will search through the list of channels to find one it can connect to successfully. The endpointURL is a read-only property, and is calculated depending on the value of the uri property. The process of connecting to a channel involves searching for the first channel and trying to connect. If this fails and the channel has failover URIs defined, it will try all of those before searching for the next available channel.
Data Serialization This section describes the serialization to and from ActionScript objects on the client and Java objects on the server. It also contains information about serialization to and from ActionScript objects on the client and SOAP and XML schema types.
ActionScript-to-Java Conversion When sending arguments from a Flex application to a Java object, the data is converted automatically from an ActionScript data type to a Java data type. An ActionScript Array can be indexed in two ways: a strict Array (in which the indexes are Numbers), or an associative Array (which has at least one index that is a String). It is very important that you know which Array you are sending to the server, because the data type changes in the arguments when used to invoke the Java object method. The following table shows simple data type conversions from ActionScript (AMF 3) to Java. ActionScript Type (AMF 3)
Deserialization to Java
Supported Java Type Binding
Array (dense)
java.util.List
java.util.Collection, Object (native array)
A custom collection implementation is bound to the relative type. Array (sparse)
java.util.Map
java.util.Collection, native
array Boolean
java.lang.Boolean
String “true” or “false”
250
flash.utils.ByteArray
Byte
flash.utils.IExternalizable
java.io.Externalizable
Boolean, Boolean, String
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 251
Chapter 11: Data Access ActionScript Type (AMF 3)
Deserialization to Java
Supported Java Type Binding
Date
java.util.Date
java.util.Date, java.util.Calendar, java.sql.Timestamp, java.sql.Time, java.sql.Date
int/uint
java.lang.Integer
java.lang.Byte, java.lang.Double, java.lang.Float, java.lang.Long, java.lang.Short, java.math.BigDecimal String, primitive types of byte, double, float, long, and short
null
null
Primitives (0, false, ‘’, and so on)
number
java.lang.Double
java.lang.Byte, java.lang.Double, java.lang.Float, java.lang.Long, java.lang.Short, java.math.BigDecimal String, 0 (zero) if null is sent, primitive types of byte, double, float, long, and short
Object (generic)
java.util.Map
If a Map interface is specified, FDS creates a new java.util.HashMap for java.util.Map and a new java.util.TreeMap for java.util.SortedMap.
String
java.lang.String
java.lang.String, java.lang.Boolean, java.lang.Number
typed Object
Typed Object when you use [RemoteClass] metadata that specifies remote class name. Bean type must have a public no args constructor.
Typed Object
Continued
251
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 252
Part II: Developing in Flex 2.0 ActionScript Type (AMF 3)
Deserialization to Java
Supported Java Type Binding
undefined
null
null for Object, default values
for primitives XML
org.w3c.dom.Document
org.w3c.dom.Document
XMLDocument
org.w3c.dom.Document
org.w3c.dom.Document
Primitive values cannot be set to null in Java, and so Flex interprets null values as the default primitive types. Note that a Java Collection can contain any number of Object types, but a Java Array must be the same type.
Java-to-ActionScript Conversion The following table shows simple data type conversions from Java to ActionScript (AMF 3). Java Type
ActionScript Type (AMF 3)
java.lang.String
String
java.lang.Boolean, boolean
Boolean
java.lang.Integer
int
If i < 0xF0000000 || i > 0x0FFFFFFF, the value is promoted to Number. java.lang.Short
int
If i < 0xF0000000 || i > 0x0FFFFFFF, the value is promoted to Number. java.lang.Byte
int
If i < 0xF0000000 || i > 0x0FFFFFFF, the value is promoted to Number.
252
java.lang.Byte[]
flash.utils.ByteArray
java.lang.Double
Number
java.lang.Long
Number
java.lang.Float
Number
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 253
Chapter 11: Data Access Java Type
ActionScript Type (AMF 3)
java.lang.Character
String
java.lang.Character[]
String
java.util.Calendar
Date
Dates are sent in the Coordinated Universal Time (UTC) time zone. Clients and servers must adjust time accordingly for time zones. java.util.Date
Date
Dates are sent in the UTC time zone. Clients and servers must adjust time accordingly for time zones. java.lang.Object (other than previously listed types)
Typed Object
java.util.Collection
mx.collection.ArrayCollection
java.lang.Object[]
Array
java.util.Map
Object (untyped)
Objects are serialized using Java Bean introspection rules. Fields that are static, transient, or nonpublic are excluded.
In Flex 1.5, java.util.Map was sent as an associative or ECMA Array. This is no longer a recommended practice. You can enable legacy Map support to associative Arrays, but Adobe recommends against doing this. For more information, see “Providing legacy AMF serialization on a channel” (http://127.0.0.1:52419/help/topic/com.adobe.fle xbuilder.help/html/00001105.html#268711). java.util.Dictionary
Object (untyped)
org.w3c.dom.Document
XML object
You can enable legacy XML support for the XMLDocument type on any channel defined in the services-config.xml file. For more information, see “Providing legacy AMF serialization on a channel.” null
null
253
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 254
Part II: Developing in Flex 2.0 You use the [RemoteClass(alias=”the.package.and.class.name”)] metadata tag to create an ActionScript object that maps directly to the Java object found on the remote server. The data converted to the relevant ActionScript class must be referenced or used in the MXML file. The typical way of casting the result object is shown in the following example: var result:MyCustomClass = MyCustomClass(event.result);
The following example shows you how to use the [RemoteClass(alias=””)] metadata tag: package com.mycompany.vo.User { [RemoteClass(alias=”com.mycompany.vo.User”)] [Bindable] public class User { public var id:Number; public var username:String; public var password:String; public var emailaddress:String; } }
Note that you can use the [RemoteClass] metadata tag even if you do not have an alias or Java object to map to on the server, but you do send back a typed version from the server. If you send your typed ActionScript object to the server, it is serialized to a Map object. However, if the typed object on the server is sent back, it will be serialized to the original ActionScript type.
ActionScript to Schema and SOAP types Sending SOAP requests using Flex requires that the information be appropriately represented in the corresponding ActionScript types. Complex types and SOAP-encoded Array types are supported. The following table shows type mappings between SOAP types and ActionScript types.
254
SOAP Type
ActionScript Type
Supported Java Type Binding
base64
flash.utils.ByteArray
Typed Object
number types
Number
boolean
Boolean
null for Object, default values for primitives
Array
Array
org.w3c.dom.Document
string
String
org.w3c.dom.Document
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 255
Chapter 11: Data Access Custom Serialization You may find that the standard serialization and deserialization between ActionScript on the client and Java on the server do not meet your requirements. Instead, you can implement the flash.utils .IExternalizable interface on the client and the corresponding Java java.io.Externalizable interface on the server. The typical use of custom serialization is to avoid passing all the properties of either the client or serverside object across the network. The use of the standard serialization process means that all public properties are passed back and forth between the client and the server. If performance is your main goal, use custom serialization instead of the default serialization. For example, in a real-time stock application, the size of the serialized objects should be very small. The longer the variable names, the larger the footprint will be during serialization, which will, in turn, slow down the application. Renaming the variables to something like var1, var2, and so on will help tremendously when sending custom objects to and from the server. The writeExternal() and readExternal() methods must be used in the class that implements the flash.utils.IExternalizable interface. The methods control how the contents of the class are formatted for the serialization stream. Also note that these methods supersede the native AMF serialization behavior. Listing 11-1 shows an ActionScript class called User, which maps to a Java User class on the server (Listing 11-2). The client User class implements the IExternalizable interface, and the server User class implements the Externalizable interface.
Listing 11-1: User.as package com.mycompany.vo { import flash.utils.IDataOutput; import flash.utils.IDataInput; import flash.utils.IExternalizable; [RemoteClass(alias=”com.mycompany.vo”)] [Bindable] public class User implements IExternalizable { public var id:Number; public var username:String; public var password:String; public var emailaddress:String; public var isAdmin:Boolean; public function readExternal(input:IDataInput):void { id = input.readInt(); username = input.readUTF(); isAdmin = input.readBoolean(); }
255
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 256
Part II: Developing in Flex 2.0 public function writeExternal(output:IDataOutput):void { output.writeInt(id); output.writeUTF(username); output.writeBoolean(isAdmin); } } }
Listing 11-2: User.java package com.mycompany.vo; import import import import
java.io.Externalizable; java.io.IOException; java.io.ObjectInput; java.io.ObjectOutput;
public class { private private private private private
User implements Externalizable int id; String username; String password; String emailaddress; boolean isAdmin;
public String getEmailaddress() { return emailaddress; } public void setEmailaddress(String emailaddress) { this.emailaddress = emailaddress; } public int getId() { return id; } public void setId(int id) { this.id = id; } public boolean isAdmin() { return isAdmin; } public void setAdmin(boolean isAdmin) { this.isAdmin = isAdmin; }
256
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 257
Chapter 11: Data Access public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public void readExternal(ObjectInput input) throws IOException, ClassNotFoundException { id = input.readInt(); username = input.readUTF(); isAdmin = input.readBoolean(); } public void writeExternal(ObjectOutput output) throws IOException { output.writeInt(id); output.writeUTF(username); output.writeBoolean(isAdmin); } }
You may notice how similar the implementation of the writeExternal() method of the client User class is to the corresponding method on the server User class. Following is the writeExternal() method of the client (ActionScript) User class: public function writeExternal(output:IDataOutput):void { output.writeInt(id); output.writeUTF(username); output.writeBoolean(isAdmin); }
Following is the writeExternal() method of the server (Java) User class: public void writeExternal(ObjectOutput output) throws IOException { output.writeInt(id); output.writeUTF(username); output.writeBoolean(isAdmin); }
257
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 258
Part II: Developing in Flex 2.0
Destinations and Security You can restrict access to destinations to a privileged group of users by applying a security constraint in a destination definition. This ensures that a user must be authenticated either by custom or basic authentication before accessing the destination. The following example shows a security constraint that is declared inline in a destination definition: SomeAuthMethod destUser
There is also a way to declare a global security constraint to use with several destinations. You define one security constraint in the security section of the FDS configuration file and refer to it in each destination definition. The following example shows a global security constraint that is referenced in three destination definitions: CustomAuthMethod trustedUsers
258
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 259
Chapter 11: Data Access In Flex, there is a way to send user credentials to a destination that uses a security constraint. You specify the username and password as parameters of the setCredentials() method of the HTTPService, WebService, RemoteObject, DataService, Publisher, or Consumer component that you are using. Note that the setCredentials() and setRemoteCredentials() methods don’t do anything when the service component’s userProxy property is set to false. The following example shows you how to use the setCredentials() method to send a username and password from a WebService component to a destination: var wSrv:WebService = new WebService(); wSrv.destination = “SecureWSDest”; wSrv.setCredentials(“myUsername”, “myPassword”); wSrv.getWeather(“27596”);
The setRemoteCredentials() method is used to pass credentials to a remote HTTP service or Web service. The username and password are sent to the destination in the message headers. You can also use the setRemoteCredentials() method for a Remoting Service destination that requires a username and password for authentication, such as a ColdFusion component (CFC). The following example shows you how to use the setRemoteCredentials() method to send a username and password from a RemoteObject component to a destination: var rSrv:RemoteObject = new RemoteObject(); rSrv.destination = “SecureRODest”; rSrv.setRemoteCredentials(“myUsername”, “myPassword”); rSrv.getWeather(“27596”);
Another alternative to setting remote credentials is to define them in the FDS configuration file. The following example shows destination with remote username and password defined inline: http://www.server.com/secure_service.cfm sbarber password
Configuring Logging In FDS, you can configure server-side logging for requests and responses. This can be done in the logging section of the Flex services configuration file. The default setting is sent to System.out.
259
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 260
Part II: Developing in Flex 2.0 The following table shows several logging levels that are available. Logging Level
Description
all
Designates that all messages should be logged.
debug
DEBUG messages indicate internal Flex activities.
Select the debug logging level to include Debug, Info, Warn, and Error log messages in your log files. info
Info messages indicate general information to the developer or administrator.
Select the Info logging level to include Info, Warn, and Error log messages in your log files. warn
Warn messages indicate that Flex encountered a problem with the application, but
it does not stop running. Select the warn logging level to include warn and error log messages in your log files. error
Error messages indicate when a critical service is not available, or a situation has
occurred that restricts use of the application. Select the Error logging level to include Error log messages in your log files. none
Designates that no messages should be logged.
string
String
The filter pattern elements are defined to specify the categories of information to log. The class attribute of the target element can define the flex.messaging.log.ConsoleTarget to log messages to the standard output, or the flex.messaging.log.ServletLogTarget to log messages to the application server’s default logging system. The following example defines a logging configuration that uses the Info logging level: [Flex ] false false false false Endpoint
260
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 261
Chapter 11: Data Access
Software Clustering In FDS, a software clustering feature handles failover when using stateful services and non-HTTP channels (such as RMTP channels). So, the process starts with a particular service on one host in a subnet, and if that host fails, the client has the ability to send messages to another host in the same subnet. This feature is available to all services defined in the FDS configuration file. In most scenarios, clustering for FDS does not use software clustering. Instead, a set of load balancers are used in the form of hardware, and are positioned in front of the HTTP servers. These load balancers direct requests to individual HTTP servers. This can also work in conjunction with the software clustering feature. The software clusters are defined in the clusters section of the FDS configuration file. You can define multiple clusters, and each must have an id and a path to a JGroups properties file. JGroups is the Open Source software that FDS uses to provide software clustering. You can find out more at the following URL: http://www.jgroups.org/javagroupsnew/docs/index.html
Note that the jgroups.jar and jgroups-*.xml properties files are located in the resources/ clustering folder of the FDS installation. You will need to copy the jgroups.jar to the WEB-INF/ lib and the jgroups-*.xml files to the WEB-INF/flex directory before you define any clusters. The following example shows the configuration of a cluster in the services-config.xml file:
The following example shows a reference to a cluster in a service destination:
261
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 262
Part II: Developing in Flex 2.0
Custom Error Handling In some cases, you may want to return additional information to the client as part of a message exception. You can use the extendedData property of the flex.messaging.MessageException class. This property is a HashMap that provides a flexible way to return additional data to the client in the event of a failure occurring. Note that FDS provides bean serialization of any Throwable type. The following example shows a Java test class that adds extra information to an exception: package errorhandling; import java.util.HashMap; import java.util.Map; import flex.messaging.MessageException; public class MyCustomException { public String generateMessageException(String extraData) { MessageException me = new MessageException(“Testing extendedData.”); Map extendedData = new HashMap(); extendedData.put(“extraData”, extraData); me.setExtendedData(extendedData); me.setCode(“999”); me.setDetails(“Some custom details go here.”); throw me; } }
The following example calls the previous Java object to return an exception with extra data:
RPC Ser vice Components Flex supports an architecture that interacts with remote data sources by calling different kinds of services and receiving responses from them. In a typical Flex application, a client-side RPC service sends asynchronous requests to a remote service, which returns the results back to the client.
Defining RPC Components RPC components can be defined in MXML or ActionScript, depending on your requirements. They can be used to connect to HTTP services and Web services without configuring FDS destinations. The RemoteObject components send and receive data in AMF format over HTTP. You can either use FDS and define destinations in your services-config.xml file, or use a third-party solution that supports either AMF0 or AMF3 binary format. You can use the HTTPService and WebService components to send and receive data without configuring FDS destinations. This means that you must set the url property of the HTTPService component or the wsdl property of the WebService component, instead of using the destination property. Note that the RPC service must be in the same domain as your application, or a crossdomain.xml file must be installed on the Web server hosting the RPC service. The following example shows two MXML tags: one is an HTTPService component and the other a WebService component. These components directly reference an RPC service using the url and wsdl properties, respectively.
263
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 264
Part II: Developing in Flex 2.0
To ensure HTTP codes are returned correctly, you must use the Flex proxy in FDS. If a service returns any status code other than 200, the Flash Player cannot read the body of the response. The proxy gets around this by forcing the status code to 200, and then the player passes the body with the fault intact. If you decide to use FDS, you can specify the destination property of the RPC components, instead of using the direct reference. This means you do not have to worry about security sandbox issues with the Flash Player, and no crossdomain.xml file must be on the server of the RPC service. The following example is the same example as previously shown, except that a RemoteObject component has been added, and the url and wsdl properties of the HTTPService and WebService components have been replaced with the destination property:
These destinations are configured in the FDS service-config.xml file.
Calling a Service and Handling Results The process of calling a service and returning results starts off when you call an RPC service on a remote server, which handles the request, does some processing on the remote server (such as retrieving data from a database), and returns the results back to the client. To achieve this, you declare an RPC component and call the service using MXML or ActionScript. The calls to the services are asynchronous, so you must declare an event listener to handle the results and faults. If you need to pass parameters to the service, that can be done explicitly or by using binding. The data is returned in some format that can be controlled using the resultFormat property of the HTTPService or WebService component. The default value for this property is object, so the data is returned as a simple tree of ActionScript objects.
264
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 265
Chapter 11: Data Access The HTTPService and WebService components return anonymous Objects and Arrays for complex types. By default, Objects are wrapped in mx.utils.ObjectProxy instances, and Arrays are wrapped in mx.collections.ArrayCollection instances. The following example converts a temperature in Fahrenheit into Celsius. The farenheitTextInput instance’s text property is passed into the getCelsius() method of the RPC service using parameter binding. The result is handled inline and sets the celsiusLabel instance’s text property to the result from the remote server.
RPC Ser vices Configuration This section describes how to set up a destination or destinations for your RPC services. As you know, you can call an actual URL or WSDL URL of an HTTP service or Web service, or define a destination. These are configured in the FDS configuration file either directly or by reference within another file.
Destination Configuration When defining a destination, you reference one or many messaging channels to contact the corresponding server-side service. One or more adapters must also be defined, and that is the server-side code that interacts with the service directly. Default adapters can be defined to avoid explicitly referencing them in each case. The following example is a Remoting Service definition that contains a destination, one adapter, and one messaging channel:
265
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 266
Part II: Developing in Flex 2.0 com.company.business.UserDelegate application
The following example declares an HTTP service destination with a dynamic-url value, which means that you can use more than one HTTP service url property in the client-side service tags and still go through the Proxy Service: http://www.somedomain.com/services/*
Destination Properties The Remote object, Web service, and HTTP service components contain properties that you may find useful when defining destinations in the FDS configuration file. The following table shows Remote object properties. Element
Description
source
Fully qualified class name of the Java object (Remote object).
scope
Indicates whether the object is available in the request scope, the application scope, or the session scope. Objects in the request scope are stateless. Objects in the application scope are available to the Web application that contains the object. Objects in the session scope are available to the entire client session. The valid values are request, application, and session. The default value is request.
string
266
String
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 267
Chapter 11: Data Access The following table shows Web service properties. Element
Description
wsdl
(Optional) Default WSDL URL.
soap
SOAP endpoint URL patterns that would typically be defined for each operation in the WSDL document. You can use more than one SOAP entry to specify multiple SOAP endpoint patterns. Flex matches these values against endpointURI property values that you specify in client-side service tags or ActionScript code.
string
String
The following table shows HTTP service properties. Element
Description
url
(Optional) Default URL.
dynamic-url
(Optional) HTTP service URL patterns. You can use more than one dynamic-url entry to specify multiple URL patterns. Flex matches these values against url property values that you specify in client-side service tags or ActionScript code.
string
String
Flex Messaging Flex Messaging provides a client-side API and a server-side Message Service for creating Flex messaging applications, and enables participation in Java Messaging Service (JMS) messaging. ColdFusion supports sending messages to a CFC using the ColdFusion Event Gateway Adapter.
The Basics of Flex Messaging In Flex Messaging, the applications communicate asynchronously by passing packets of data called messages back and forth through a Message Service. The message normally contains a header and a body. The header consists of an identifier and routing information, and the body contains application data. Applications that send messages are called producers, and, as mentioned previously, the applications that receive messages are called consumers. You will find in most messaging systems that the producers and consumers do not need to know anything about each other. The basic process is one in which a producer sends messages to a specific destination, and the Message Service routes the messages to the appropriate consumers.
267
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 268
Part II: Developing in Flex 2.0 A message channel connects consumers and producers to message destinations. A message endpoint encodes data into messages and decodes them into a format that consumers can understand. A message adapter allows you to connect to other messaging systems with Flex Message Service. For example, a JMS adapter will allow your Flex application to connect to JMS topics and queues. Figure 11-2 shows the flow of data from a producer to consumer.
Channel
Data
Message producer
Destination
Channel
Data
Message data flow
Message consumer
Figure 11-2: Flow of data from a producer to consumer
Flex supports publish-subscribe messaging or topic-based messaging, as well as point-to-point messaging or queue-based messaging. Publish-subscribe messaging is used for a one-to-many relationship between producer and consumers. Point-to-point messaging is used for a one-to-one relationship between producer and consumer. A topic or queue is represented by a message service destination. Producers publish a message to a specific topic on the message server, and consumers subscribe to those topics to receive messages. Figure 11-3 shows a publish-subscribe messaging flow. This is a one-to-many relationship with one producer and two or more consumers.
Producer/ Publisher
Message
Channel
Channel
Message
Consumer/ Subscriber
Channel
Message
Consumer/ Subscriber
Destination
Figure 11-3: Publish-subscribe messaging flow
Flex Messaging Architecture The Flex messaging architecture allows your Flex application to connect to a message destination, send messages, and receive messages from other messaging clients. The messaging clients can consist of other Flex applications, or other types of clients such as JMS clients. JMS clients can subscribe and publish to the same message destinations as Flex applications. In other words, Flex applications can communicate with Java clients using messages.
268
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 269
Chapter 11: Data Access Flex Message Service Flex Message Service contains four components: channels, destinations, producers, and consumers. You can configure Flex Message Service to transport messages over one or more channels. The channels correspond to a specific transport protocol such as AMF, RTMP, or XML socket.
Message Channels Flex Message Service can be accessed by your Flex application over several different messaging channels. Each channel corresponds to a specific network protocol. On the client, there is code that corresponds to each channel. Any time a message arrives at an endpoint, the message is decoded and passed along to a message broker. This determines where the message must be sent. The message broker does the same for the RPC service and Date Management Service features.
JMS Message Adapter JMS is a Java API that lets your application create, send, receive, and read messages. The JMS adapter allows Flex messaging to communicate and interact with external messaging systems. The JMS adapter is a very important component of Flex Message Service because it allows Flex applications to subscribe to JMS topics and queues.
Producer Components Producer components are defined in MXML or ActionScript. You create an AsyncMessage object and call the send() method of a producer to send the message. A producer component contains an acknowledge and fault event. The acknowledge event is dispatched when a destination successfully receives a message from the producer component. The fault event is dispatched when a destination cannot successfully process the message because of some error.
Creating a Producer Component in MXML and ActionScript The MXML tag is used to create an instance of the producer component. The tag must contain an id tag and should also specify a destination that is defined in the services-config.xml file located on the server. The following example shows an tag that defines a destination and acknowledge and fault event handlers:
The following code example is the same as the previous one, except it is written in ActionScript within the tags:
269
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 270
Part II: Developing in Flex 2.0
Sending a Message To send a message to a destination you must create an AsyncMessage object, populate it with data in the body property, and pass it into the Producer object’s send() method. The following code example shows how these steps are accomplished:
270
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 271
Chapter 11: Data Access The body property of the AsyncMessage object can be set to a custom ActionScript class CustomBody, as the following example shows:
Adding More Information to a Message In the AsyncMessage object, there is a headers property in which you can include strings and numbers. The headers property is an associative array where the key is the headers name. The following example calls header1 and sets its corresponding value:
271
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 272
Part II: Developing in Flex 2.0
Consumer Components The Consumer components in Flex allow you to subscribe to a destination of the Consumer component. The Consumer component contains a message and fault event to which you can assign event handlers. The message event dispatches when a message is received from the destination. A fault event is broadcast when the channel the Consumer component is connected to cannot establish a connection.
Creating a Consumer Component in MXML and ActionScript The MXML tag is used to create an instance of the Consumer component. You must specify an id property and should also have a destination defined that matches the relevant one in the services-config.xml. The following code shows in tag that defines a destination and message and fault handlers:
The following code example creates a Consumer component instance in ActionScript within the tag:
Subscribing to a Destination To subscribe to a destination, the Consumer component’s subscribe() method must be called to receive messages. The following code example creates a Consumer object and calls the subscribe() method. You can unsubscribe by calling the unsubscribe()method of the Consumer instance.
Filtering Messages Use the selector property of the Consumer component to filter out messages that the component should receive. A selector property uses a string formatted in SQL92 syntax. The Consumer component receives only messages with the headers that match the selector property’s criteria.
273
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 274
Part II: Developing in Flex 2.0 The following code example defines the selector property of the Consumer component: 10” />
In this example, the selector property is set to an expression of “property1 > 10”. This means that the consumer will process only messages containing a header of property1 with a value that is greater than 10. You may wonder where these headers are defined. Well, before a producer sends a message to a destination, you can define multiple headers in the AsyncMessage headers array property, as the following example shows: private function sendMessage():void { var message:AsyncMessage = new AsyncMessage(); message.headers = new Array(); message.headers[“property1”] = 11; message.body = input.text; producer.send(message); }
This message will be accepted by the consumer because the headers array property of the AsyncMessage instance contains a property1 value of 11.
Message Ser vice Configuration To get messaging to work, you must declare a connection to the server-side destination in the and tags. A Message Service destination is the endpoint that you send messages to and receive messages from when performing publish-subscribe or point-topoint messaging.
Message Service Configuration Common tasks that you will perform in configuring the Message Service are defining message destinations, adding security to message destinations, and modifying logging settings. Message Service destinations can be configured in the FDS configuration file, or a file that is included by reference. The following example shows a basic Message Service configuration file:
274
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 275
Chapter 11: Data Access 0 1000 0 true flex.messaging.durability.FileStoreManager
Message Service Destination Configuration Channels are used to transport messages to and from a destination. A destination can reference one or more channels that are defined in the FDS configuration file. Only one channel can be used to conduct a destination. The following example shows two channels being referenced in a destination:
A destination can contain network properties for defining client-server messaging behavior. The following example shows the network properties defined within a destination: 0
275
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 276
Part II: Developing in Flex 2.0 Message Service destinations use the network properties shown in the following table. Property
Description
session-timeout
Idle time in minutes before a subscriber is unsubscribed. When the value is set to 0, subscribers are not forced to unsubscribe automatically.
throttle-inbound
The max-frequency attribute controls how many messages per second the server can receive. The policy attribute indicates what to do when the message limit is reached. A policy value of ERROR indicates that an error should be returned if the limit is reached. A policy value of IGNORE indicates that no error should be returned if the limit is reached.
throttle-outbound
The max-frequency attribute controls how many messages per second the server can send. The policy attribute indicates what to do when the message limit is reached. A policy value of ERROR indicates that an error should be returned if the limit is reached. A policy value of IGNORE indicates that no error should be returned if the limit is reached. A policy value of REPLACE indicates that the previous message should be replaced when the limit is reached.
A destination can contain server-related properties for controlling server-related parameters. The following example shows the network-related properties defined within a destination: 1000 0 true flex.messaging.durability.FileStoreManager
Message Service destinations use the service-related properties shown in the following table.
276
Property
Description
max-cache-size
Maximum number of messages to maintain in memory cache.
message-time-to-live
This is how many milliseconds a message is kept on the server. A value of 0 means the message lasts forever.
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 277
Chapter 11: Data Access Property
Description
Durable
Boolean value that indicates whether messages should be saved in a durable message store to ensure that they survive connection outages and reach destination subscribers.
durable-store-manager
Durable store manager class to use when not using the JMS adapter. By default, the flex.messaging.durability.FileStoreManager, included with FDS, stores messages in files in the /WEB-INF/flex/ message_store/DESTINATION_NAME of your Flex Web application. You can change this location by setting the file-store-root property.
batch-write-size
(Optional) Number of message files to write in each batch.
file-store-root
(Optional) Location for storing message files.
max-file-size
(Optional) Maximum file size in kilobytes for message files.
In Message Service, you can specify an adapter to use (such as ActionScript, JMS, or ColdFusion Event Gateway adapter). You reference the adapter in the destination definition, or use the default configured adapter. The following example shows two adapter definitions referenced inside a destination:
Building a Custom Message Service Adapter If you find that the standard adapter does not provide the desired functionality, you can create a custom Message Service adapter. The custom adapter must extend the Flex Message Service Adapter class. The primary method of any Message Service adapter is the invoke() method. This method is called when a client sends a message to a destination. In the invoke() method, you can include code to send to all the subscribing clients or consumers, or to specify clients by evaluating the selector statements included in the message.
277
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 278
Part II: Developing in Flex 2.0 The MessageService.PushMessagesToClients() method is used to send messages in the invoke() method. This method takes a Message object as a parameter. The second parameter is of type Boolean and indicates whether to evaluate the message selector statements. The MessageService .PushMessagesToPeer() method in the invoke() method is used to broadcast messages to peer server nodes in a clustered environment. package custompackagename; import import import import
flex.messaging.services.ServiceAdapter; flex.messaging.services.MessageService; flex.messaging.messages.Message; flex.messaging.Destination;
public class SimpleCustomAdapter extends ServiceAdapter { public Object invoke(Message message) { MessageService msgService = (MessageService)service; msgService.pushMessageToClients(message, true); msgService.sendPushMessageFromPeer(message, true); return null; } }
If you want the Message Service adapter to manage its own subscriptions, override the ServiceAdapter .HandleSubscriptions() method. You must also override the ServiceAdapter.Manage() method, which is passed command Messages for subscribe and unsubscribe operations. To use the custom adapter class, you specify it in the adapter-definition element in the FDS configuration. The following example shows this:
Data Management Ser vices The Data Management Service feature uses client-side and server-side functionality to distribute data among multiple clients and server tiers. The client-side contains the DataService component in ActionScript that works in conjunction with the server-side Data Management Service to provide distributed data. The Data Service component manages data on the client, while the server-side Data Management Service manages the distribution of data among multiple clients and server-side data resources.
Data Management Service vs. RPC Features The Data Management Service employs a different approach to data than the RPC approach. Data Management Service supports automatic and manual synchronization of a common set of data on multiple clients and server-side data. It also supports offline client-side data persistence for occasionally connected clients.
278
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 279
Chapter 11: Data Access RPC components invoke operations on a remote service that return static results that you bind into an object. Data Management Service is different. The set of data is replicated to multiple clients from the Data Management Service and data is changed. The changes are automatically set to the Data Management Service, which updates the data resource and client applications.
Data Management Service Data Flow A Data Management Service application uses the Flex messaging framework, discussed earlier in this chapter. Instead of having a client application as the producer and another client application as a consumer, Data Management Services client applications act as both producers and consumers. Figure 11-4 shows the flow of data between the server-side data resource and an Array Collection object. A Data Management Service uses an adapter to update a data store. If data in one or more clients changes, the Data Management Service automatically synchronizes all client and server versions of the data. Any changes to database or directories do not automatically propagate back into the Data Management Service and client applications. The Data Management Service also provides functionality for server-side and client-side conflict resolution (APIs for handling data synchronization conflicts). Flex client application
DataService component
Network tier fill () gets data from server.
Server tier
Network endpoint
Data Management Service Adapter
Data messages Managed ArrayCollection
commit () sends updates to server.
Remote data resource
Figure 11-4: Flow of data between the server-side data resource and an Array Collection object
Data Synchronization Conflicts When one or more clients change the same piece of data at the same time, data synchronization conflicts can occur. There is an API for detecting and handling data synchronization conflicts, and ensuring the integrity of distributed data by limiting any further changes until conflicts are resolved. The Data Management Service can detect when a data update from a client is out-of-date and inform the client of the conflict.
279
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 280
Part II: Developing in Flex 2.0
Distributed Data As you know by now, Data Management Service allows you to distribute and synchronize data among multiple clients. This section describes how to create client-side Flex applications that can show and distribute data.
Distributed Data Application A Flex application uses a Data Service component to receive data and send data to the server-side Data Management Service. The data travels over a protocol-specific message channel to and from the Data Management Service. You can manage an ArrayCollection object on multiple clients by using a Data Service component. Any changes made to the data synchronize with the rest of the clients. The following example creates and fills an ArrayCollection object in ActionScript. The fill() method populates the Array Collection object with data from the Data Management Service destination.
The following example shows a manual update of an item in an Array Collection object. The commit() method of the Data Service object sends the changes to the Data Management Service destination. var users:ArrayCollection = new ArrayCollection(); var userDS:DataService = new DataService(“myUserDestination”); userDS.autoCommit = false; var user:User = users.getItemAt(10); user.firstname = “Simon”; userDS.fill(users); userDS.commit();
280
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 281
Chapter 11: Data Access Call the DataService.disconnect() method to disconnect connected clients. The Data Service component keeps a copy of its managed data and will resubscribe to pick the changes when you reconnect.
Class Mappings To map a server-side Java object to a client-side ActionScript object, you use the [RemoteClass(alias=” “)] metadata tag. You must specify the package and class name of the Java object in the alias value. This is the same technique used when you map client and Java objects using RemoteObject components. If you do not want to map the ActionScript object to the Java object, but do want it mapped from the server to client, just specify the [RemoteClass] metadata tag without the alias value. The following example shows an ActionScript object that is mapped to a Java object called com.mycompany .vo.User: package com.learningpc.livecourse.vo { [Bindable] [RemoteClass(alias=”com.mycompany.vo.UserVO”)] public class UserVO { public var id:Number; public var sessionkey:String; public var username:String; public var password:String; public var firstname:String; public var middlename:String; public var lastname:String; public var photo:String; public var emailaddress:String; public var logincount:Number; public var lastlogindate:Date; public var lastlogoutdate:Date; public var homepage:String; public var usertype:String; public var lastIp:String; public var active:Number; } }
The following shows the corresponding Java object contact: package com.learningpc.livecourse.vo; import java.io.Serializable; public class User implements Serializable { private static final long serialVersionUID = 4832904328320999999L; private int id; private String username; private String password;
281
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 282
Part II: Developing in Flex 2.0 private String firstname; private String lastname; private String emailaddress; public static long getSerialVersionUID() { return serialVersionUID; } public String getEmailaddress() { return emailaddress; } public void setEmailaddress(String emailaddress) { this.emailaddress = emailaddress; } public String getFirstname() { return firstname; } public void setFirstname(String firstname) { this.firstname = firstname; } public int getId() { return id; } public void setId(int id) { this.id = id; } public String getLastname() { return lastname; } public void setLastname(String lastname) { this.lastname = lastname; } public String getPassword() { return password; }
282
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 283
Chapter 11: Data Access public void setPassword(String password) { this.password = password; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String toString() { StringBuffer sb = new StringBuffer(); sb.append(username); sb.append(“ “); sb.append(password); sb.append(“ “); sb.append(firstname); sb.append(“ “); sb.append(lastname); return sb.toString(); } }
Data Synchronization Handling When working with distribution data, there are often times that clients try to make changes already made. The following example displays an Alert box when a client conflict occurs:
Data Management Ser vice Configuration To connect to Data Management Service using the tag, you must configure a destination in your service-config.xml file. The section describes how to configure the destinations and data adapters they use, and also how to push data to clients.
Data Management Service Destination Configuration As mentioned previously, messages are transported over message channels. You can define one or more message channels for a destination definition. If one channel cannot be reached, the next one in the list is tried. The following example shows a destination definition with two message channels defined: dev.contacts.ContactAssembler
284
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 285
Chapter 11: Data Access application true 20 loadContacts loadContacts java.lang.String syncContacts
Configure Network-Related Properties The network-related properties are the same as configuring the Flex Message Service, except that there are two additional properties, cluster and paging, as shown in the following table. Element
Description
cluster
The ref attribute of the cluster element references the name of a software cluster, which is configured in the clusters section of the services-config.xml file. For information about clusters, see the earlier section, “Software Clustering.”
paging
The enabled attribute of the paging element indicates whether data paging is enabled for the destination. When you enable paging, the pageSize attribute indicates the number of records to be sent to the client when the client-side DataService.fill() method is called. This element is optional; the default value is false.
Transactions All client changes are handled as one unit and, if the value cannot be changed, all changes are rolled back. Your J2EE server must support J2EE transactions (JTA) for distributed transactions to work.
285
02671c11.qxd:02671c11
4/20/07
3:04 PM
Page 286
Part II: Developing in Flex 2.0 The following defines the use of transactions within a destination definition:
Item Caching The default setting in Data Management Service is set to true for items returned from fill() and getitem() calls. This means a complete copy of the managed state of all active clients is kept in each server’s memory. The following example turns off the cache of items in the destination definition: false
Data Push from Servers to Client To push data from server to client, you use the Flex.data.DataServiceTransactions Java class. The object is used on the server-side to push changes to managed code stored on clients that have the AutoSyncEnabled property of the DataService component set to true. The Data Management Service creates an instance of the DataServiceTransaction class when you make changes to a sync method. With the instance, you can call the getcurrentDataServiceTransaction(), deleteitem(), and createitem() methods to trigger additional changes. If the current transaction is rolled back, these changes are not pushed to clients. Note that when you compile code that uses the FDS Java APIs, you must include the messaging JAR and flex-messaging-common.jar files in your class path.
Summar y FDS adds a new dimension to Rich Internet Applications with publish-subscribe messaging, data synchronization, being able to push data to clients, and much more. With these features, you can build enterpriseclass applications that take full advantage of the rich presentation layer provided by Adobe Flex. Chapter 12 discusses creating MXML components in your Flex applications. MXML components are MXML files or documents that are referenced using MXML tags within your other MXML files. Chapter 12 teaches you about creating MXML components to reuse in your Flex applications.
286
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 287
Part III: Creating and Extending Flex Components Chapter 12: Creating MXML Components Chapter 13: Flex Component Properties Chapter 14: Flex Components Chapter 15: Custom Frontmatter, Validator, and Effect Components
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 288
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 289
Creating MXML Components Creating components is one of the most important features of Flex because it allows for the reuse of code created either by you or by other developers. Once a component is created, it can be reused by simply including it within your application. This chapter shows you how to create simple, composite, and advanced components. You learn how to scope and style your components, as well as how to create interfaces and template components.
Creating Simple MXML Components To create a component, you simply create a new MXML file and add a visual component as the root tag. Ensure that you add the mx namespace to the root tag. If you are using Flex Builder, you can accomplish this by selecting File ➪ New ➪ MXML Component. Simply give it a unique name and choose a Based On tag and you should end up with something like this:
Now, add anything you want to the custom component and use it within your application. To use a custom component, you will need to add it as an xml namespace in the parent’s root tag. Assuming the component created is named Test.mxml and is in a folder named components, this is what the main application file would look like when the component is added:
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 290
Part III: Creating and Extending Flex Components Take a look at a real-world example of where you may want to use a very simple custom component. Imagine that you are building an application where the user needs to select his or her birthday and you want the user to choose the month from a ComboBox rather than allowing him or her to free-type the value (which will result in inconsistent data). You could add a ComboBox to your application and create an array of months as the dataProvider, or you could create a very simple custom component that could then be reused within the same application or any application you will build in the future. Selecting the ComboBox to base the component on is the same as extending ComboBox. It just makes it easier to extend a ComboBox, rather than creating a composite component with a ComboBox and its data wrapped in a Canvas. The component would look something like that shown in Listing 12-1.
Listing 12-1: SimpleMonths.mxml January February March April May June July August September October November December
Listing 12-2 shows the new component being included in the application.
Listing 12-2: SimpleMonthsMain.mxml
Figure 12-1 shows the SimpleMonths component.
290
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 291
Chapter 12: Creating MXML Components
Figure 12-1: The SimpleMonths component
Scoping Your Components Scoping within a Flex application refers to the value that will be returned from the this keyword. When this is accessed from within the application’s main file, it will be returned as the reference that Flex has assigned to mx.core.Application.application. When this is accessed from any Flex component, it will be returned as the full path from the root of your application to the component. In other words, this will always refer to the file you are working within. Take a look at Listing 12-3 and Listing 12-4.
Listing 12-3: Index.mxml
Listing 12-4: MyHBox.mxml
In these examples, this is being accessed from the Index.mxml file (Listing 12-3) within the Label component, and this is also being accessed within the Label component of the MyHBox custom component (Listing 12-4). The results can be seen in Figure 12-2. Notice that when this is called from the custom component, the ID of the component is returned. If there is no ID supplied, Flex assigns an ID.
291
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 292
Part III: Creating and Extending Flex Components
Figure 12-2: The this being accessed in multiple ways
Styling Your Components Components are self-contained and can be styled individually, or they can simply accept the style properties defined by the parent application’s style settings. Components can be styled inline by adjusting the style properties within the MXML code. They can be styled using CSS within an tag, or they can be skinned. Listing 12-5 shows SimpleStyledMonths.mxml. In the example shown in Figure 12-3, the properties of the MXML root tag were updated to take on a purple style and square corners. Figure 12-3 shows the original custom component, as well as the styled version.
Listing 12-5: SimpleStyledMonths.mxml January February March April May June July August September October November December
292
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 293
Chapter 12: Creating MXML Components
Figure 12-3: SimpleMonths and SimpleStyledMonths components
Advanced MXML Components The SimpleMonths example was a very basic implementation of a custom component. More advanced components include custom properties, methods, and even additional components combined together to create what is known as a composite component.
Adding Custom Properties and Methods to a Component The SimpleMonths example created previously is limited to showing only the name of the month. But what if the application calls for the display to show only the number or the abbreviation of the months? Should you then create new components called MonthsByName, MonthsByNumber, and MonthsByAbr? he answer is no, because you can very easily build this functionality into one simple component. This can be accomplished by adding properties to your component, which can be set when the component is included in the parent document. The example shown in Listing 12-6 adds a property named labelFieldVar to determine what value to show within the ComboBox. The values that can be set are full, abr, and num, which will display the full month name, the month’s three-letter abbreviation, or the month’s number (1–12), respectively.
Listing 12-6: AdvancedMonths.mxml
Notice that labelFieldVar is set as a public property. This is important because only public variables and methods can be accessed from the parent, and only public properties can be set from within the custom MXML tag that is used to add the component to the parent. The labelFieldVar is also set to be bindable, which allows the property to be bound to the component root tag’s labelField property. Also notice that, when the variable is bound, it is accessed by scoping the variable name with this using dot notation. It is not necessary to scope it, because it is a local property, but it is a best practice to do so. If you do not use this, the variable is scoped to this by default. To set the labelFieldVar, simply add the property to the new MXML tag. Following is an example showing all three versions of this component within a single application. Figure 12-4 shows all three versions of the AdvancedMonths component.
294
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 295
Chapter 12: Creating MXML Components The AdvancedMonths component also has a public function added to demonstrate how methods can be added to component. In this example, the method will be called when the component’s change event occurs, passing in the type of month that should be returned. An Alert will show the current value of the component. Although this example may not have any use in the real world, it is simply meant to show the process of calling a method within a component. In the next section, you see the value of calling methods on components within a more detailed example. Figure 12-5 shows the custom component’s method being called from the parent.
Figure 12-4: All three versions of the AdvancedMonths component
Figure 12-5: The custom component’s method being called from the parent
Creating Composite Components A composite component is a component that is made up of multiple components. In the example shown in Listing 12-7 and Listing 12-8, a composite component has been created to capture a user’s birth date.
Listing 12-7: Birthdate.mxml
Listing 12-8: BirthdateMain.mxml
The component consists of an HBox as the root element with three nested ComboBox components representing the month, day, and year of a birth date. The new component reuses the AdvancedMonths component that was created earlier in this chapter to represent the birth date month. It contains its own labelFieldVar
296
02671c12.qxd:02671c12
4/20/07
1:27 PM
Page 297
Chapter 12: Creating MXML Components property, which is passed along to the AdvancedMonths labelFieldVar property. Two new Arrays were added to create the dataProviders for the new ComboBox elements. The new component also contains a public method named getBirthdate that returns a Date object representing the current values of the month, day, and year. The results of this component can be seen in Figure 12-6.
Figure 12-6: The results of the Birthdate component’s getBirthdate method
Template Components Template components are a unique type of component where the variables are typed in a more general way, allowing for flexibility in design. By creating a template component, you can control the layout of the component but still give another developer who implements your template component the freedom to use whatever UI components are desired. The following example illustrates this.
Creating a Template Component To create a template component, you must first create properties to act as placeholders for the components. In Listing 12-9, four properties are created. They are header, menu, and footer (all of which are typed as UIComponent), and content (which is an Array of UIComponents). Next, run the init function, which adds the components into whatever order and layout you would like.
Listing 12-9: TemplateLayoutComp.mxml Template Component
In this particular example, the header is added to the root VBox. An HBox named body is created to hold the menu and the mainContent, which is a VBox that was created to hold the contents of the content Array. The mainContent is created by looping over the content Array and adding each component as a child of mainContent. Finally, the footer is added to the root VBox, and the function is complete.
Using a Template Component To use a template component, you must add it to your MXML file (just as you would add any other custom component) and then define the content sections by name, scoped with the component namespace.
298
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 299
Chapter 12: Creating MXML Components Take a look at the examples shown in Listing 12-10 and Listing 12-11. Both use the TemplateLayoutComp that was defined earlier in this section. The namespace is defined as comps, so this is what is used to scope the inclusion of the TemplateLayoutComp. Nested within this component tag are the definitions of the component properties.
Listing 12-10: UseTemplate1.mxml
299
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 300
Part III: Creating and Extending Flex Components Listing 12-11: UseTemplate2.mxml
Notice that the first example header is defined as a Canvas with a Label nested within. Looking further, you will see the menu defined as a LinkBar, the content defined as a ViewStack with nested Label and Canvas components, and, finally, a footer defined as a Label. The results of this example can be seen in Figure 12-7. Now, take a look at the second example using the same TemplateLayoutComp and you will see that the header has been replaced by an Image, the menu has changed from a LinkBar to a ToggleButtonBar, and one of the Label components in the content section has been changed to a TextInput. These changes are all valid because they still meet the requirements of the TemplateLayoutComp, which had all of these areas typed as UIComponent. The results of the second example can be seen in Figure 12-8.
300
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 301
Chapter 12: Creating MXML Components
Figure 12-7: The results of UseTemplate1.mxml
Figure 12-8: The results of UseTemplate2.mxml
301
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 302
Part III: Creating and Extending Flex Components
MXML Interfaces As in most object-oriented languages, MXML allows the use of interfaces to define component functionality. Interfaces are a great way to decouple function definitions from implementations. Interfaces are created to act as a blueprint for any object that implements them. The interface declares public method and property definitions that must be included in the class that implements the interface.
Creating Interfaces To create a Flex interface, you must simply create a new ActionScript file and define it as an interface. You can also create an interface in Flex Builder. Click File ➪ New ➪ ActionScript Interface. A dialog box will ask for the package, interface name, and whether it extends any other interface. The basic syntax for an interface looks like Listing 12-12.
Listing 12-12: IBirthdate.as Interface Example package { public interface IBirthdate { function getBirthdate():Date; } }
You cannot define interface methods as public or private. Interfaces are typically used only to define methods. However, in the event that you want the interface to enforce a property, you can add implicit getters and setters to an interface. This example shows how a single function must be defined by all classes that implement this interface.
Using Interfaces To use an interface within an MXML component, you simply need to use the implements property of the component’s root tag. You will also need to define the necessary properties and methods that are outlined in the interface. To use the IBirthdate interface shown in Listing 12-12 within the Birthdate custom component that was shown in Listing 12-7, you simply add implements=”IBirthDate” to the component’s root HBox tag. Listing 12-13 shows what it would look like.
Listing 12-13: Birthdate.mxml Component Using IBirthdate as the Interface
302
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 303
Chapter 12: Creating MXML Components
Using IMXMLObject When creating custom components, it is often necessary to run a function when the component is initialized to manipulate data or visual components within the component. To do this, you would usually add a call to a function using the component’s initialize or creationComplete properties. However, if you are building a nonvisual component by extending Object (using as the root tag), you will not be able to do this, because these properties are not available for type Object. The solution is to implement mx.core.IMXMLObject. When implementing IMXMLObject, you are required to define a function named initialized. The initialized function will be called automatically after the properties of the component are initialized. The examples in Listing 12-14 and Listing 12-15 show a component implementing IMXMLObject. It has two properties, a and b, that are public, and a private property named total.
Listing 12-14: MyObjectComp.mxml
Listing 12-15: IMXMLObjectExample.mxml
303
02671c12.qxd:02671c12
4/20/07
1:28 PM
Page 304
Part III: Creating and Extending Flex Components
Figure 12-9: The results of the getTotal method
When the component is initialized the function runs and sets the value for total, which is then returned and shown in the Alert. Figure 12-9 shows the results.
Summar y This chapter covered many subtopics, but all had to do with creating MXML components. The ability to extend the built-in Flex components, as well as create composite components, interfaces, and templates, creates limitless possibilities for developers to build components that suit the needs of their projects. It also opens the doors to third-party companies creating new components for Open Source or commercial use to further expand the base that Adobe has provided. The next couple of chapters show additional ways to extend Flex. Chapter 13 examines all of the pieces that make up a component, including the package statement, import statements, the class name, the default constructor, properties, getters and setters, and methods. It also demonstrates how to create simple and advanced components using ActionScript rather than MXML.
304
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 305
Flex Component Proper ties This chapter examines the many properties of a custom ActionScript component. The first half of this chapter discusses how to create a full ActionScript component, starting with a package statement and finishing with overriding of methods. The second half of the chapter shows additional examples of ActionScript components.
Elements of a Component ActionScript components are made up of many elements, some of which are required and others of which are optional. The package statement, class name, and constructor are required, whereas the import statements, properties, and methods are optional.
The package Statement The first thing to define in a custom ActionScript class is the package statement. The package statement includes the full folder path from the root of your application to the class, using dot notation to navigate the folder path, as shown here: package com.mydomain.components { // Class definition }
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 306
Part III: Creating and Extending Flex Components
import Statements The first section of the class definition includes the import statements. This is the area where you define all of the classes that you will need to import to meet the requirements of your class. To add the import statements, simply use the import keyword, followed by the path to the class you would like to import. Following is an example of importing a single class: package com.mydomain.components { // import statements import mx.controls.Button; }
You can also import a package of classes using the asterisk in place of a single class name. Following is an example of importing a package of classes: package com.mydomain.components { // import statements import mx.controls.*; }
Both of these examples will give access to the Button class. However, the second example will also give you access to all of the classes in the mx.controls package.
Defining the Class Name The next piece of a custom class is the section where you would define the class name. The class name must match the name of the file. For example, if you name your class UCaseTextInput.as, the class name must be defined as UCaseTextInput. Following is an example of naming the class: package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { } }
The Default Constructor The default constructor is the method that Flex uses when it initializes an instance of the class. It should always be declared as public, and it may contain optional arguments if the class will be initialized using ActionScript. If you intend to initialize your class using MXML, you must have
306
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 307
Chapter 13: Flex Component Properties a zero argument constructor. The default constructor should not have a return type and should be named the same as the class name. Although not required, it is good practice to make a call to the super method, which calls the default constructor of the parent class. Following is an example of adding a default constructor: package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { // default constructor public function ValidateButton(){ // a good practice is to include a call to super(). super(); } } }
Defining Properties Properties are the variables that will be used within the class to hold data. They can be defined as public (which will allow access of their data from outside the class), or they can be defined as protected or private (which restricts their access). Protected properties can be accessed from other classes that extend the custom class, and private properties cannot be accessed from outside the class. Adding getters and setters will allow your private properties to be accessed from outside the class, but you gain the control of how the private data is stored and returned.
Standard Properties Standard properties are defined as [Access type] var [property name]:[property type]. The following example includes two properties, checkIcon and xIcon. Both are defined as private, which means they will only be accessible from within the class itself. package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { // define properties [Embed(source=”good.png”)] private var checkIcon:Class; [Embed(source=”bad.png”)] private var xIcon:Class;
307
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 308
Part III: Creating and Extending Flex Components // default constructor public function ValidateButton (){ // a good practice is to include a call to super(). super(); this.setStyle(“icon”,xIcon); } } }
Getters and Setters A property that is typed as private can only be accessed from within the containing class. To allow this property to be accessed, you will need to add getters and setters. Listing 13-1 has a property named _isValid, which is a private Boolean. Naming the property with a leading underscore will allow you to use implicit getters and setters. Implicit getters and setters allow the variable to be set or retrieved by property name rather than method call. The methods are named with get, followed by a space and then the property name, and set, followed by a space and the property name. The getter returns the class variable (in this case, _isValid), and the setter sets the _isValid variable. Using private properties with get and set methods allows you to have more control over the data.
Listing 13-1: Adding Private Properties with Getters and Setters package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { // define properties [Embed(source=”good.png”)] private var checkIcon:Class; [Embed(source=”bad.png”)] private var xIcon:Class; private var _isValid:Boolean; // default constructor public function ValidateButton (){ // a good practice is to include a call to super(). super(); this.setStyle(“icon”,xIcon); } // getters and setters public function get isValid():Boolean{ return this._isValid; }
308
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 309
Chapter 13: Flex Component Properties public function set isValid(b:Boolean):void{ this._isValid = b; if(b){ this.setStyle(“icon”,checkIcon); }else{ this.setStyle(“icon”,xIcon); } } } }
Listing 13-1 shows that the set isValid method does more than simply set the _isValid property; it also changes the button’s icon to a check or “x” mark. The results of this class in its current state can be seen in Figure 13-1 and Figure 13-2.
Figure 13-1: The ValidateButton component in an invalid state
Figure 13-2: The ValidateButton component in a valid state
Defining Methods You can add private methods to your class to perform operations within the class, public methods that can be called from outside the class, or protected methods that can only be called from child classes. Listing 13-2 now includes a method named getProperties, which returns a few properties of the custom Button component. The results of this new method can be seen in Figure 13-3.
309
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 310
Part III: Creating and Extending Flex Components Listing 13-2: Adding a Custom Method package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { // define properties [Embed(source=”good.png”)] private var checkIcon:Class; [Embed(source=”bad.png”)] private var xIcon:Class; private var _isValid:Boolean; // default constructor public function ValidateButton (){ // a good practice is to include a call to super(). super(); this.setStyle(“icon”,xIcon); } // getters and setters public function get isValid():Boolean{ return this._isValid; } public function set isValid(b:Boolean):void{ this._isValid = b; if(b){ this.setStyle(“icon”,checkIcon); }else{ this.setStyle(“icon”,xIcon); } } // a method to return propeties public function getProperties():String{ var s:String = “Label = “ + this.label + “\n” + “Width = “ + this.width + “\n” + “Height = “ + this.height; return s; } } }
310
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 311
Chapter 13: Flex Component Properties
Figure 13-3: An Alert with the results of a call to the getProperties method
Overriding Methods Using super To override a method, you will need to use the keyword override. You can also access the parent’s properties and methods using the super keyword. Listing 13-3 now contains a new function that overrides the label property by overriding the implicit public get label method. The new method adds parentheses before and after the original label, which is accessed using super.label. The results of this class with the added override method can be seen in Figure 13-4.
Listing 13-3: Overriding a Method package com.mydomain.components { // import statements import mx.controls.Button; // class name public class ValidateButton extends Button { // define properties [Embed(source=”good.png”)] private var checkIcon:Class; [Embed(source=”bad.png”)] private var xIcon:Class; private var _isValid:Boolean; // default constructor public function ValidateButton (){ // a good practice is to include a call to super(). super(); this.setStyle(“icon”,xIcon); }
311
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 312
Part III: Creating and Extending Flex Components // getters and setters public function get isValid():Boolean{ return this._isValid; } public function set isValid(b:Boolean):void{ this._isValid = b; if(b){ this.setStyle(“icon”,checkIcon); }else{ this.setStyle(“icon”,xIcon); } } // a method to return propeties public function getProperties():String{ var s:String = “Label = “ + this.label + “\n” + “Width = “ + this.width + “\n” + “Height = “ + this.height; return s; } // an override to add parentheses to the label override public function get label():String{ return “(“+super.label+”)”; } } }
Figure 13-4: The button label with the parentheses added by the override method
The custom class is now complete, and although it may not be the most useful component, it does demonstrate all of the key elements of an ActionScript component. The following discussion further explores the creation of ActionScript components.
312
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 313
Chapter 13: Flex Component Properties
Creating a Simple ActionScript Component Listing 13-4 is an example of a simple ActionScript component. It is a simple example that creates a TextInput component that self-validates the text property for a valid e-mail address.
Listing 13-4: EmailTextInput Component package com.mydomain.components { import mx.controls.TextInput; import mx.events.ValidationResultEvent; import mx.validators.EmailValidator; import flash.events.Event; public class EmailTextInput extends TextInput { private var emailValidator:EmailValidator = new EmailValidator(); private var validator:ValidationResultEvent; public function EmailTextInput(){ super(); this.addEventListener(“change”, this.validate); this.emailValidator.source = this; this.emailValidator.property = “text”; } private function validate(event:Event):void{ validator = emailValidator.validate(); if (validator.type==ValidationResultEvent.VALID){ this.errorString=””; } else { this.errorString = validator.message; } } } }
The class is defined within the com.mydomain.components package and imports the needed classes (including TextInput), as well as the necessary validation and event classes. The class extends TextInput and declares EmailValildator and ValidationResult properties that will be used in the validate function. The default constructor creates a listener that calls the validate function when the text property changes. It also assigns the source and property properties of the emailValidator. Finally, the validate function calls the validate function of the emailValidator and sets the errorString. The results of this component can be seen in Figure 13-5.
313
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 314
Part III: Creating and Extending Flex Components
Figure 13-5: The EmailTextInput component in action
Implementing and Overriding UIComponent Methods When creating a custom component, you may find it necessary to override public or protected methods to accomplish your needs. Fortunately, Flex makes this a very simple thing to do. The CircleLabel example shown in Listing 13-5 overrides the updateDisplayList function and uses the graphics class to draw an ellipse around the label’s text property.
Listing 13-5: CircleLabel Component package com.mydomain.components { import mx.controls.Label; public class CircleLabel extends Label { public var circleColor:uint = 0x000000; public function CircleLabel(){ super(); } override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void { super.updateDisplayList(unscaledWidth, unscaledHeight); // Draw a circle around the label text graphics.lineStyle(1, this.circleColor, 1.0); graphics.drawEllipse(-5,-5,this.width+10,this.height+10); } } }
The updateDisplayList function was selected as the function to override because it is called before the component appears onscreen. The results of the CircleLabel component can be seen in Figure 13-6.
314
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 315
Chapter 13: Flex Component Properties
Figure 13-6: Two instances of the CircleLabel component
Creating Advanced Components in ActionScript Listing 13-6 shows an example of an advanced ActionScript component that includes many UIComponents, private variables, getters, setters, styles, and events. The class extends Canvas and is named MultiRowTabs. It has several import statements to give access to Flex containers, controls, and collections. There are also import statements to allow the use of the TabSkin and MouseEvent classes.
Listing 13-6: MultiRowTabs.as package com.mydomain.components { import mx.containers.Canvas; import mx.containers.HBox; import mx.containers.ViewStack; import mx.controls.Button; import mx.collections.ArrayCollection; import mx.skins.halo.TabSkin; import flash.events.MouseEvent; public class MultiRowTabs extends Canvas { // declare class properties public var myViewStack:ViewStack; public var tabsPerRow:Number = 4; public var rowHeight:Number = 22; public var tabRows:Array = new Aray(); private var _dp:ArrayCollection; private var buttonArray:ArrayCollection; // default constructor public function MultiRowTabs(){ }
315
02671c13.qxd:02671c13
4/20/07
12:02 PM
Page 316
Part III: Creating and Extending Flex Components // getters and setters public function get dp():ArrayCollection{ return _dp; } public function set dp(a:ArrayCollection):void{ _dp=a; this.removeAllChildren(); buttonArray = new ArrayCollection(); var start:Number = 0; var end:Number = tabsPerRow; var currentY:Number = 0; // add rows for(var i:Number=0; i
Figure 14-5 shows the results of Listing 14-7 and Listing 14-8.
Figure 14-5: The custom event being dispatched
[Effect] The Effect metadata tag is used to define a custom effect that will be dispatched when an event occurs. This can be easily demonstrated by building on the earlier Event examples. By simply changing a single line to the ButtonLabel class (Listing 14-9), an effect is defined that can be assigned to an Effect instance (Listing 14-10).
326
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 327
Chapter 14: Flex Components Listing 14-9: Adding the Effect Metadata Tag ... // Define the custom event [Event(name=”labelChanged”, type=”flash.events.Event”)] [Effect(name=”labelChangedEffect”, event=”labelChanged”)] public class ButtonLabel extends Button { ...
Listing 14-10: Adding labelChangedEffect to the Component Instantiation MXML Tag
[IconFile] IconFile is used to identify the filename of a jpg, gif, or png file that will be used as the icon for your custom class. Whereas the [Embed] metadata tag can be used to embed image files, SWF files, music files, video files, and so on, IconFile is only used to embed a file that will be used as the icon for the custom class. Here is the example of the IconFile syntax: [IconFile(“icon.png”)] public class CustomButton extends Button { }
[Inspectable] The Inspectable metadata tag is used to define the attributes of your custom component that you would like to display within the code hints and property inspector of Flex Builder 2. The example shown in Listing 14-11 defines a variable named ccType that is inspectable. It defines a defaultValue of Visa, a category of Credit Card, and enumeration values of Visa, Mastercard, Discover, and American Express.
Listing 14-11: MyComponent.mxml
327
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 328
Part III: Creating and Extending Flex Components Figure 14-6 shows an example of the code hints being displayed as the component is added to an application. Figure 14-7 shows the same example, but this time in Design view, which exposes the property inspector. You can see that the category of properties is Credit Card with the property showing as ccType and the available values within the drop-down list.
Figure 14-6: Code hints
[InstanceType] The InstanceType metadata tag is used to declare the type of object that will be allowed when declaring a variable as IDeferredInstance within a template object. The syntax of InstanceType looks like this: [InstanceType(“package.className”)]
[NonCommittingChangeEvent] The NonCommittingChangeEvent is a metadata tag that will prevent a change from occurring when a specified event occurs. Listing 14-12 demonstrates how this works. A private variable named s of type String is created and bound to the ti2 TextInput component. The other TextInput component
328
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 329
Chapter 14: Flex Components
Figure 14-7: Code hints when in Design view
with the id of ti1 sets the value of s equal to the value of its text property whenever the text changes. Additionally, the Binding metadata tag attached to the s variable is set to bind when the triggerBinding event is dispatched. The triggerBinding event is dispatched only when the Enter key is pressed while typing in the ti1 TextInput component.
Listing 14-12: NonCommittingChangeEventSample.mxml
[RemoteClass] RemoteClass is used to bind an ActionScript class to a Java class. This will allow for automatic data type conversions. Following is an example of an ActionScript class named MyClass in package com.mydomain being bound to a Java class named MyClass in package com.mydomain: package com.mydomain { [Bindable] [RemoteClass(alias=”com.mydomain.MyClass”)] public class MyClass { public var id:int; public var myText:String; } }
[Style] The Style metadata tag is used to define custom style properties for your components. Simply add the Style metadata tag or tags to your class definition, and then use the getStyle method to retrieve its value. Listing 14-13 and Listing 14-14 show examples of how to define two styles named borderColor and fillColor, both of which are defined as uint data types. The styles are set within the component tag when the class is instantiated. The updateDisplayList function is overridden and the custom styles are used to draw the circle border and fill.
Listing 14-13: CustomCircle.as package { import mx.core.UIComponent; [Style(name=”borderColor”,type=”uint”,format=”Color”,inherit=”no”)]
330
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 331
Chapter 14: Flex Components [Style(name=”fillColor”,type=”uint”,format=”Color”,inherit=”no”)] public class CustomCircle extends UIComponent { public function CustomCircle(){ super(); } override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void { super.updateDisplayList(unscaledWidth, unscaledHeight); graphics.lineStyle(1, getStyle(“borderColor”), 1.0); graphics.beginFill(getStyle(“fillColor”),1.0); graphics.drawEllipse(0,0,100,100); } } }
Listing 14-14: StyleSample.mxml
Figure 14-8 shows the results of Listing 14-13 and Listing 14-14.
Figure 14-8: Using the Style metadata tag
331
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 332
Part III: Creating and Extending Flex Components
Compiling Components To allow components to be easily shared between applications and developers, components can be compiled to SWC files and distributed as SWC files or Runtime Shared Libraries (RSLs). Components can be compiled using the free Flex SDK or Flex Builder. The following examples demonstrate how to compile components in these methods, as well as how to use these compiled components.
Compiling Components with Flex SDK The Flex SDK uses the compc compiler to compile your custom components into SWC files.
SWC To create an SWC file with a single class, simply open the compc compiler command window and change directory to the root of your class path. The following command compiles an SWC file named EmailTextInput to c:/jrun4/servers/flex2/flex/WEB-INF/flex/user_classes/ EmailTextInput.swc: compc -source-path . -output c:/swcs/ValidateButton.swc -include-classes com.mydomain.components. ValidateButton
To create an SWC file that contains multiple files, simply add additional –include-classes statements. To include assets, simply add –include-file, followed by the filename and its path. compc -source-path . -output c:/swcs/ValidateButton.swc -include-classes com.mydomain.components.ValidateButton -include-file bad.png com/mydomain/components/bad.png -include-file good.png com/mydomain/components/good.png
RSL To compile the component to a simple library.swf file, you can use the following syntax within the compc compiler. The library.swf within the ValidateButton folder can now be renamed and deployed as an RSL. compc -source-path . -output c:/swcs/ValidateButton -include-classes com.mydomain.components.ValidateButton -directory=true -debug=false
Create a folder named RSLSample at C:\RSLSample and copy the ValidateButton folder to this folder. The example at the end of this chapter demonstrates how to compile your application with this new RSL.
Compiling Components with Flex Builder Flex Builder makes compiling your components to SWC files a very easy procedure. Simply follow the directions here and your SWC will be created automatically.
SWC To compile an SWC file within Flex Builder, you must first create a Flex Library project by selecting File ➪ New ➪ Flex Library Project (Figure 14-9). Next, name your project the same name as you would like your SWC to be named, as shown in Figure 14-10.
332
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 333
Chapter 14: Flex Components
Figure 14-9: Creating a Flex library project
Figure 14-10: Naming the project
Once you have named your project, you must either copy your component files into the new project, or link to them as source files. After you have done this, you can add your classes and assets to your build path. You can open this view by right-clicking the Project and selecting Properties, as shown in Figure 14-11 and Figure 14-12.
333
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 334
Part III: Creating and Extending Flex Components
Figure 14-11: Adding classes to the library build path
Figure 14-12: Adding assets to the library build path
334
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 335
Chapter 14: Flex Components After you have added your classes and assets, the SWC file will be created automatically (assuming you have your project set to build automatically) within the bin folder of your project, as shown in Figure 14-13. You can now distribute your compiled SWC file to other projects or developers. An SWC file is a file that you can open to show its contents. By renaming the SWC as a zip, you can open and see the contents of the SWC, as shown in Figure 14-14.
Figure 14-13: The compiled SWC file in the bin folder
Figure 14-14: The contents of the compiled SWC file
335
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 336
Part III: Creating and Extending Flex Components RSL To extract the SWC that was just created to a Runtime Shared Library, simply follow these directions. The first thing you must do is to add the ValidateButton SWC file that was created earlier to the library path of the Flex build path of the project, as shown in Figures 14-15 and 14-16. Next, highlight the RSL URL property and click the Edit button. Change the link type to “Runtime shared library (RSL)” and check “Auto extract to swf to RSL URL,” as shown in Figure 14-17. Because the RSL URL was left as a local reference, this will create a new SWF file named ValidateButton.swf in the bin folder of your project.
Figure 14-15: Adding an SWC file to the project’s library path
336
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 337
Chapter 14: Flex Components
Figure 14-16: The SWC file after being added
Figure 14-17: Changing RSL URL properties
337
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 338
Part III: Creating and Extending Flex Components You can now include any components within this library file in your application, just as you would when working with components that are in a local folder path. To demonstrate this, copy the ValidateButton Main.mxml file from Chapter 13 into your project and compile it. The results of the compiled SWF from Chapter 13 and the same compiled SWF from this chapter can be seen in Figure 14-18 and Figure 14-19. Notice the large difference in file size of the compiled SWFs. The benefits of RSL are very dramatic. However, they are only useful if you will be using the components compiled within your RSL in multiple applications, because the RSL still must be downloaded. The benefits are only realized when a second application loads using the RSL, and this time it will not need to download the RSL, because it has already cached the RSL it downloaded when running the first application. Another advantage is that the end developer, using an RSL, will always have the latest component when compiling the application.
Figure 14-18: Compiled with the components embedded
Figure 14-19: Compiled using an RSL for the components
Deploying Components Components can be deployed in more than one method. The first method is to simply include the folder path of your component within your project build and compile a single SWF. This is the method that has been demonstrated many times throughout this book. Other methods include deployment as an RSL, or an embedded SWC merged into your code.
338
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 339
Chapter 14: Flex Components RSL with SDK If you haven’t already done so, create a folder named RSLSample located at C:\RSLSample, and copy the ValidateButton folder that was compiled earlier in this chapter in the section “Compiling Components with Flex SDK” and the subsection “RSL.” Also copy the ValidateButtonMain.mxml file that was created in Chapter 13 into C:\RSLSample. Your folder structure should now look like Figure 14-20. Open the command window and navigate to C:\RSLSample (using cd C:\RSLSample) and run the following command to compile the ValidateButtonMain.swf with the RSL. The results of this can be seen in Figure 14-21. To include more than one RSL, simply supply a comma-separated list. mxmlc -runtime-shared-libraries=ValidateButton/library.swf -ex ternal-library-path=ValidateButton -file-specs ValidateButtonMain.mxml
Figure 14-20: C:\RSLSample before compiling the ValidateButtonMain with RSL
Figure 14-21: The newly compiled ValidateButtonmain.swf
RSL with Flex Builder If you are using RSLs with Flex Builder as shown earlier in this chapter, the RSL SWF will be automatically created and moved to the bin folder of your project. It will then be deployed along with your application SWF when you run your application from Flex Builder.
339
02671c14.qxd:02671c14
4/20/07
3:24 PM
Page 340
Part III: Creating and Extending Flex Components SWC with SDK Create a new folder directly under C:\ and name it SWCExample. Copy the ValidateButtonMain.mxml file that was created in Chapter 13 and also used in the earlier RSL examples in this chapter. Open the command window and navigate to the SWCExample folder (using cd C:\SWCExample) and run the following command: mxmlc -library-path+=C:/swcs/ValidateButton.swc --file-specs ValidateButtonMain.mxml
As opposed to the earlier RSL examples, this will compile an SWF file that will include all of the files needed to deploy by itself. You will notice that the file size for this SWF is larger, but you can deploy the SWF as a single file without the need to deploy the SWC file. To include more than one SWC file, simply supply a comma-separated list.
SWC with Flex Builder Compiling an application when using an SWC that has been defined in the library path of the Flex build path of your project and not set to be an RSL will automatically embed all of the files needed in the compiled application SWF. You will be able to deploy the SWF without deploying the SWC file.
Summar y This chapter included information of how to create custom events in components. It provided examples showing custom events being dispatched based on logic within a custom component. It included examples on how to use the [ArrayElementType], [Bindable], [DefaultProperty], [Embed], [Event], [Effect], [IconFile], [Inspectable], [InstanceType], [NonCommittingChangeEvent], [RemoteClass], and [Style] metadata tags. Lastly, this chapter covered creating SWCs and RSLs, using both the free Flex SDK and Flex Builder. It also provided examples on how to deploy your applications using SWCs and RSLs, using both the free Flex SDK and Flex Builder. Chapter 15 discusses nonvisual Flex components. These types of components include custom formatters, custom validators, and custom effects. Examples are provided to show how to use the SwitchSymbolFormatter class, how to extend the Formatter class and create custom formatters, and how to create custom validators, as well as examples of how to extend the Effect class.
340
02671c15.qxd:02671c15
4/20/07
3:27 PM
Page 341
Custom Formatter, Validator, and Effect Components Flex 2 provides RIA developers with the ability to extend the factory base classes and override functions to create custom classes that fit better with the needs of the application being created. This chapter shows you how to customize some of these factory classes. You learn how to use SwitchSymbolFormatter and also how to create a custom formatter. This chapter also shows you how to create custom validators and custom effects.
Custom Formatters Many built-in formatter classes are used to format phone numbers, dates, currency, and so on. However, there will be occasions when it will be necessary to format a string to a format that is not covered by any of the built-in formatter classes. The way to do this is by creating a custom formatter.
Customizing the SwitchSymbolFormatter Class The SwitchSymbolFormatter class is a very flexible formatter that allows custom format strings as well as custom format characters. Listing 15-1 creates an instance of the SwitchSymbolFormatter on creationComplete as well as on change of the ComboBox component. The formatValue method has two arguments passed in. The first argument is the format string, which, in this example, uses the selected value from the ComboBox. The second argument is the string that will be formatted.
02671c15.qxd:02671c15
4/20/07
3:27 PM
Page 342
Part III: Creating and Extending Flex Components Listing 15-1: Customizing the SwitchSymbolFormatter Class #-######## ###-###### ##-###-#### #######-##
By selecting a new value from the ComboBox, you will see that the new format string will be applied that will reformat the string. The default format character is the pound (#) symbol. Wherever Flex encounters a pound symbol, it places the corresponding character form the string being formatted. If there are other characters in the format string (such as –, as in this example), they will be included in the formatValue results. So a string such as 123456789 with a format string of ###-###-### will be formatted to 123456-789, as shown in Figure 15-1.
342
02671c15.qxd:02671c15
4/20/07
3:27 PM
Page 343
Chapter 15: Custom Formatter, Validator, and Effect Components
Figure 15-1: Formatting a string with the # symbol
There will probably be occasions where the results you would like in your formatted string should include the # symbol. The SwitchSymbolFormatter can accommodate this by allowing the format character to be a custom character rather than the default # symbol. Listing 15-2 is the same as Listing 15-1, except that the constructor of the SwitchSymbolFormatter is now being passed the asterisk symbol * as the format character. The format string would now use * symbols instead of # symbols, which allows you to now use # in the format string and it will be included in the newly formatted string.
Listing 15-2: Passing the * Character as the Format Character
343
02671c15.qxd:02671c15
4/20/07
3:27 PM
Page 344
Part III: Creating and Extending Flex Components # *-******** # ***-****** # **-***-**** # *******-**
So a string such as 123456789 with a format string of #***-***-*** will result in #123-456-789, as shown in Figure 15-2.
Figure 15-2: Formatting a string with the * character
Extending the Formatter Class Formatters have also been built to be easily extendable, so you have the ability to create custom formatters to meet your needs. To write a custom formatter, you must simply extend the mx.formatters.Formatter class and override the format method.
344
02671c15.qxd:02671c15
4/20/07
3:28 PM
Page 345
Chapter 15: Custom Formatter, Validator, and Effect Components
Custom Formatter Example Listing 15-3 is admittedly a rather useless example in the real world, but it does demonstrate how easy it is to create a custom formatter. The ReverseFormatter overrides the format method, which accepts an argument of type Object that contains the data to be formatted. It then checks to see if the Object has length and loops over the data and returns it in reverse.
Listing 15-3: Custom Formatter that Will Reverse the Text package { import mx.formatters.Formatter // Custom formatters must extend mx.formatters.Formatter public class ReverseFormatter extends Formatter { public function ReverseFormatter() { super(); } // Custom formatters must override format(). override public function format(formatObj:Object):String { if(formatObj.length == 0) { // return empty string and set error property if string has zero length. error=”Cannot format an empty String”; return “” } else { error=null; var returnString:String = “”; // loop through value and build string in reverse for(var i:Number=formatObj.length; i>=0; i--){ returnString = returnString + formatObj.charAt(i); } return returnString; } } } }
Figure 15-3 shows the ReverseFormatter from Listing 15-4.
Figure 15-3:ReverseFormatter in action
345
02671c15.qxd:02671c15
4/20/07
3:28 PM
Page 346
Part III: Creating and Extending Flex Components Listing 15-4: Sample Application Running the Custom Formatter
Formatter Errors Formatters also contain an error property that allows you to get information on the status of the formatter. In the ReverseFormatter example shown in Listing 15-3, the error property is being set to “Cannot format an empty String” when the Object coming into the format function has a length of zero. It is set to null when the Object has a length greater than zero. The sample application will show the error property when it is not null as an Alert. You can see the results of this in Figure 15-4.
Figure 15-4: Displaying a formatter error
346
02671c15.qxd:02671c15
4/20/07
3:28 PM
Page 347
Chapter 15: Custom Formatter, Validator, and Effect Components
Custom Validators Like most of the Flex 2 objects, Validator is extendable. To create your own custom validator you will simply need to extend Validator and override the doValidation method. The class shown in Listing 15-5 is a custom password validator that will apply certain rules to a string to ensure it complies with a predetermined standard. In this example, you are requiring a password to have at least 1 uppercase letter, 1 lowercase letter, 1 number, and a length of between 6 and 10 characters. Looking at the code, you will see a results Array is defined and then appended to when the validation fails. Determining whether the validation passes or fails is handled by the doValidation method. Within the doValidation method, you will see a series of conditional tests that check the length, as well as searching for specific characters. If the condition being tested returns false, a new ValidationResult object is created with a custom errorCode and errorString, which is then appended to the results array and returned.
Listing 15-5: PasswordValidator.as package { import mx.validators.Validator; import mx.validators.ValidationResult; public class PasswordValidator extends Validator { private var results:Array; public function PasswordValidator() { super(); } // Override the doValidation() method. override protected function doValidation(value:Object):Array { results = []; // Call super’s doValidation(). results = super.doValidation(value); // Return if super’s doValidation contains errors (required would be an example). if (results.length > 0){ return results; } // Check for min length var dataString:String = String(value); if (dataString.length < 6){ results.push(new ValidationResult(true, null, “Short”, “Password must be at least 6 characters.”)); return results; } // Check for max length (this can be set in the text component’s maxChars property). if (dataString.length > 10){ results.push(new ValidationResult(true, null, “Long”, “Password must be no larger than 10 characters.”)); return results;
347
02671c15.qxd:02671c15
4/20/07
3:28 PM
Page 348
Part III: Creating and Extending Flex Components } // Check for at least 1 uppercase letter. if (dataString.search(“[A-Z]”) 0 1 1
The content-size node contains the maximum number of files that FDS puts in the cache. When the set limit is reached (which is, by default, 10), FDS removes the least recently used files from the cache. An important issue to remember about caching in Flex is the value assigned to the production mode. In fact, by setting the production mode as enabled, changes to compiled files are only recognized at server startup. In the file flex-webtier-config.xml, it is possible to modify the value of the production-mode property: true
When the production-mode is set to true, the FDS does not automatically recompile the application when the source files become updated or changed. Furthermore, not all the debug activities are flagged by the compiler. It is for this reason that, by default, the production-mode is set to false.
484
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 485
Chapter 20: Deploying Flex Applications Ample space is dedicated to this topic later in this chapter. To conclude the discussion of the caching of Flex, it is necessary to also consider fonts and glyphs. To reduce the loading time required, it could be useful to force the caching on the part of Flex to asset as fonts and glyphs on a Flex Data server. By default, Flex puts a maximum number of fonts in the cache, but it is possible to check and change this value in the flex-config.xml file: 20 1000 .... cut by author ....
This value is to be used cautiously, because by setting a high value number of fonts that can be loaded in the cache, it is possible to occupy a lot of space on the disk, which, of course, depends on the dimension of every single TrueType Font (TTF) file.
Deployment Options There is no option of standard deployment that could be applied indifferently to any Flex application. In fact, deployment options depend on the version of Flex that you have used in the creation of the application, and they vary from a Web application written using only Flex 2 SDK to an enterprise application that instead uses FDS. Using Flex 2 SDK, it could be sufficient to migrate the SWF, HTML, and the dependent files from the development server or staging to that of production, to verify the functioning of the application and, therefore, render it publicly accessible to the final user.
RSL Deployment In the case in which the application uses an RSL, it is necessary to copy the library to the deployment server and to use its RSL parameters on the Flex compiler to specify the directory that will contain the RSL at compilation time. The location that is specified is relative to the deployment location of the application: ❑
web_root/myApp.swf — The Flex application is found in the root of the server.
❑
web_root/assets/runtimeLibraries — This is the directory where you store the RSL file.
485
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 486
Part V: Building and Deploying Flex 2.0 Applications The parameter to pass from RSLs to the compiler is assets/runtimeLibraries/myFile.swf: mxmlc -runtime-shared-libraries=assets/runtimeLibraries/myFile.swf
Or, you can directly input the parameter in the options of the internal compiler of Flex Builder, as shown in Figure 20-2. If you prefer, in the flex-config.xml file, it is possible to indicate the path of the RSLs that are compiled from inside the application: assets/runtimeLibraries/myFile.swf
The RSL’s default node is obviously noted. This is also valid for the external-library-path option that permits you to specify the location of the SWC file: mxmlc -external-library-path=assets/runtimeLibraries/myDataGrid
In this case, on the deployment server, a myDataGrid.swc must exist within the following path (assuming that the application is located in Web root): web_root/assets/runtimeLibraries
Figure 20-2: Flex Compiler property settings
486
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 487
Chapter 20: Deploying Flex Applications In the flex-config.xml file, this option is found in the external-library-path node: libs/playerglobal.swc assets/runtimeLibraries/myDataGrid .swc
The playerglobal.swc file represents the external library that defines the base classes made available by Flash Player. If, on the deployment server, the application you launch cannot find the folder or directly access the RSL file that will be used, you receive an error that blocks the application from compiling. For this reason, it is important to pay maximum attention to the paths inside the production server.
Flash Player Sandbox and Cross-Domain Consideration Another delicate aspect for the deployment of an application that uses Flex 2 SDK is that of the target domain. The Flash Player sandbox does not permit for the loading of data from a different domain respective to that on which the SWF of the application is published. In this case, it is necessary to use the crossdomain.xml policy file. This file is XML-formatted and simply contains a list of domains that indicates to the server which could be used. The crossdomain.xml file must be copied onto the root directory of the server that is serving the data. In the following scenario, the cross-domain file is located in the root directory of http://www.comtaste.com/ crossdomain.xml and allows for access to Flash documents that originate from casario.blogs.com and www.augitaly.com:
It is also possible to specify the IP address and the ports such as the domain in the node. In some cases, it is necessary to be able to load assets that reside on the client’s local file system. To guarantee that a Flex application can access the assets in the local sandbox, the application must be in localwith-filesystem or local-trusted. It is, therefore, necessary to set a false option for the usenetwork compiler (which, by default, is set to true): mxmlc use-network =false
The use-network option can also be set in the flex-config.mxml configuration file in the following node: false
However, the generic rule is that remote SWF files cannot load local SWF files, and local SWF files cannot load remote SWF files.
487
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 488
Part V: Building and Deploying Flex 2.0 Applications
Deploying a Flex 2 SDK Application that Uses RSL A scenario that you may come across in the deployment of an application that uses Flex 2 SDK is that of an application using an image reference relative to the application and to an RSL. Let’s now reproduce this scenario, starting at the very beginning of the creation of a Flex Library Project in the Flex Builder 2. Select File ➪ New ➪ Flex Library Project (Figure 20-3). Create a new project to which you assign the name Flex_2_RSL. Now create an MXML component with the name myVideo.mxml, with a VideoDisplay control setting the following properties: source=”http://88.149.156.198/develop/mediaportal/upload/videos/test.flv” autoPlay=”false” bufferTime=”0.5” maintainAspectRatio=”false” click=”myVid.play();” width=”100%” height=”100%” x=”0” y=”0”
Figure 20-3: Creating a Flex Library Project in Flex Builder 2
488
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 489
Chapter 20: Deploying Flex Applications The final code for myVideo.mxml will be the following:
To export the library as an SWC file, you must add and define the elements that will be included in the compilation phase of the project (custom components, ActionScript classes, and other assets) by selecting them from the Flex Library Build Path window, which is reachable from Project ➪ Properties ➪ Flex Library Build Path. As shown in Figure 20-4, in the Tab classes, you select the checkbox of the component myVideo.mxml, because this is the only element that you want to include in the SWC file.
Figure 20-4: Adding and defining elements for the compilation phase
489
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 490
Part V: Building and Deploying Flex 2.0 Applications Before having it compile the SWC file set the Output Folder to assets. Therefore, the structure of the Flex Library Project is the following: Flex_2_Deploy_Rsl | |--. settings |-assets |.actionScriptProperties |.flexLibProperties |.project |myVideo.mxml
Click OK, and Flex Builder automatically compiles the library within the assets folder (Figure 20-5). This operation takes place automatically because the Build Automatically option of Flex is active. You have created an RSL to import into a Flex project. At this point, you create the application by defining a new project in the Flex Builder workspace:
1. 2. 3.
Create a Basic Flex Project: File ➪ New ➪ Flex Project. Assign a name of Flex_2_Deploy. Terminate the operation by clicking Finish.
At this point, you import the SWC file that you intend to use in the project, adding it to the library path. Flex provides you with three different methods of importing an SWC in a project: ❑
Add SWC — Directly adds the SWC file.
❑
Add SWC Project — Adds an SWC Library Project.
❑
Add SWC Folder — Allows a folder containing SWC files to be added.
Figure 20-5: Compiling the library within the assets folder
490
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 491
Chapter 20: Deploying Flex Applications For this example, you will use the Add SWC Project method. Therefore, from the Project ➪ Properties ➪ Flex Build Path menu, you add a library project by clicking the Add Project button. You select a single listed Library Project (the just-created Flex_2_Deploy_Rsl) and click OK (Figure 20-6). The Library Project is added in the Library Path. There are different options for the method with which an SWC should be used by the application: ❑
Merge into Code — In the compilation phase, the SWC library is added to the SWF file. This, however, involves an increase in size of the final application.
❑
External — This allows you to maintain the SWC file outside of the compiled SWF file.
❑
Runtime Shared Library — The SWC file is used at run-time like a shared library, which is a useful option when more projects will be used by that library component.
From the Project ➪ Properties ➪ Flex Build Path menu, you select the Library tab and expand the Flex_2_Deploy_Rsl project. Double-click the Link Type option and set the following options: ❑
Link Type — Runtime Shared Library (RSL)
❑
RSL URL — Assets/Flex_2_Deploy_Rsl.swf
Figure 20-6: Selecting the Library Project
491
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 492
Part V: Building and Deploying Flex 2.0 Applications Select the “Auto Extract SWF to RSL URL” option. The importation method of the SWC file that you have used is, therefore, Runtime Shared Library. This method is also called dynamic linking. You leave the options of Flex Builder for extracting the SWF file in the defined folder in the RSL URL selected. With these simple operations, your library will be automatically included in the View Component (visible when Flex Builder is in Design mode). In this view, a custom folder will exist that, when opened, will contain the Library Component my Video. You also import the images that have intentionally been put in the assets folder, using relative reference for the property source:
You import the library into the main application by dragging it from the Component panel and obtaining the following code:
Once the project has run, the Flex_2_Deploy.mxml becomes compiled in the bin folder, together with the RSL compiled as Flex_2_Deploy_Rsl.swf in the assets folder.
Figure 20-7: Folder structure on the deployment server
492
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 493
Chapter 20: Deploying Flex Applications The files to be transferred are those indicated in the table that follows. However, the structure of the folders on the deployment server, as shown in Figure 20-7, must be respected. Now comes the deployment phase of the application on the production server, during which you transfer the SWF file and all of the dependent files. The following table lists all of the standard files that usually must be deployed on the server for the applications that use Flex 2 SDK. Application
Files
Description
History Manager
history.swf, history.js
Handles the Back button of the browser
Player Detection
playerProductInstall.swf, AC_OETags.js
Detects client browser type
Main Application
myApp.html, myApp.swf
Files containing the application itself
Compiling for Deployment Compiling for the deployment is different from compiling for the developing and testing phase. Many options and characteristics of compilation are very useful in the development phase of a Flex application, but lose significance in the production phase of the application. Flex makes three different application compilers available: ❑
Flex Builder project compiler — This is the compiler used in Flex Builder.
❑
MXMLC command-line compiler — This is the compiler that is followed by using the command line and to which various parameters become passed for the compilation.
❑
Web-tier compiler — This is a set of servlets that are followed by the J2EE application server, which passes the requests to the MXML file at the servlet container, which compiles SWFs on the fly, which is then sent back to the application.
All three of the application compilers use a set of options that are very similar, and, for this reason, the compilation options for the deployment phase are also very similar. Because the compilation options for the deployment are often used for many projects, it is possible to save time by using a configuration file to apply to each deployment. The configuration file is an XML file containing the options that can be passed to the various application compilers (MXMLC command-line compiler, Flex Builder project compiler, and Web-tier compiler). Flex uses the flex-config.xml default configuration file that has been discussed previously.
493
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 494
Part V: Building and Deploying Flex 2.0 Applications This section contains just a few of the options made available by the compiler. This discussion concentrates on the options that usually come into play in the deployment phase, and that are summarized in the following table. Options
Description
accessible
Accepts true and false values. Allows you to enable or disable the accessibility features of the Flex application. Default value: false.
benchmark
Accepts true and false values. Prints the compilation time. Default value: true.
contributor
Accepts a string. Sets the metadata in the SWF file.
creator
Accepts a string. Sets the metadata in the SWF file.
date
Accepts a string. Sets the metadata in the SWF file.
title
Accepts a string. Sets the metadata in the SWF file.
description
Accepts a string. Sets the metadata in the SWF file.
language
Accepts a string. Sets the metadata in the SWF file.
publisher
Accepts a string. Sets the metadata in the SWF file.
debug
Accepts true and false values. Generates a debut file in SWF format. Default value: true (false for the mxmlc compiler).
headless-server
Accepts true and false values. Allows you to set the headless implementation of the compiler.
default-script-limits
Accepts the values max recursion depth and max recursion time. Indicates the depth of the Flash Player call stack and the time in seconds before the Flash Player stops.
incremental
Accepts true and false values. Allows for the incremental compilation, which reduces the compilation time.
production-mode
Accepts true and false values. Used for Flex Data Services when the application is live on a public-facing server. Default value: false.
Creating a custom configuration file means writing an XML block using tags that are used by the compiler. Every configuration file must begin by defining an XML declaration tag and a root tag, , followed by a tag, which contains the options that you intend to send to the compiler. Begin by writing the file in the program that you created earlier in this chapter. Assign to that file the name Flex_2_Deploy-config.xml.
494
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 495
Chapter 20: Deploying Flex Applications The frame of the configuration file is as follows:
You begin by defining the values for accessibility, the benchmarks, and the metadata, useful for the search of search engines: true false Flex 2 Professional Compiling for deployments Dicembre 2006 Comtaste Marco Casario EN
You insert the settings for the debug options and the default-script-limits: false 1200 40
You must now deal with the incremental option, which allows you to check (through the compiler) the changes to byte code between the different revisions of the re-compiler (therefore, only the sections that are changed). Considering that the default option is set to true, you will often want to disable this option in the deployment phase. You write it in the configuration file as follows: false
In this way, you also obtain a reduction of the memory used by the FDS Web-tier compiler. If the Web-tier complier incremental option is used, it is found in the flex-webtier-config.xml file. Finally, you should consider the properties of the headless server and production mode. A headless server is a server that doesn’t have a graphical subsystem (that is, a graphics card and monitor). Usually, these are servers that allow you to maximize the use of memory and of the system itself (Unix or Linux). When you follow the deployment of a Flex application on a server of this type, it is necessary to set a true option: true
495
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 496
Part V: Building and Deploying Flex 2.0 Applications This communicates to the Flex server that SVG fonts and images in a nongraphical system should be used. If you want to delve deeper into this argument, you should read following TechNote from Adobe: “Configuring non-graphics-enabled servers TechNote” (http://www.adobe.com/cfusion/ knowledgebase/index.cfm?id=tn_19252). The production-mode option operates exclusively like a Web-tier compiler and compiles an FDS application like MXML and ActionScript files. Setting production-mode to true will automatically set all of the debugging options to false and the compiler will, therefore, not generate any information from the debug: true
The configuration file, in the end, will look as follows: true false Flex 2 Professional Compiling for deployments Dicembre 2006 Comtaste Marco Casario EN false 1200 40 false false true
To be able to send the file to the compiler, you can simply add the following parameters to the command line of the compiler: -load-config+=Flex_2_Deploy-config.xml
Using the += operator, the configuration file is loaded in addition to the flex-config.xml file and not in its place. The mxmlc compiler can use a local configuration file. This is a configuration file that resides in the same folder as the application and that shares with it the same name. If, for example, the Flex application is named myCoolFlexApp.swf, Flex will automatically search for a configuration file with the name myCoolFlexApp-config.xml.
496
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 497
Chapter 20: Deploying Flex Applications The Flex Builder project compiler does not use the configuration file flex-config.xml, but instead uses internal settings. It is possible, however, to send a custom configuration file to the compiler using the load-config option sent to the Additional Compiler arguments field. To conclude the discussion on the compilation phase of deployment, it is certainly necessary to mention the possibility of yielding the source code of the application itself, which is also available in the deployment phase. You will be able to share and render as Open Source the source code of your application to the community. To render this feature active, simply set (from code) the property viewSourceURL and send the URL that will contain the source code for the application. In Flex Builder the Publish Application Source is set from the Project ➪ Publish Application menu.
Troubleshooting T ips and Common Deployment Problems At this point, it should be apparent that no fixed steps apply in the deployment phase of an application. It is possible, however, to outline the guidelines to follow for different types of application that will be developed. This section provides a checklist of problems that can be encountered in the migration of a development project to the deployment environment.
Asset and Dependent Files A Flex application can be modularized in multiple MXML files, ActionScript classes, and RSLs. Furthermore, images and audio and video elements loaded in run-time can be used. In these scenarios, it is essential to respect the structure of directory of the application, replicating exactly the one that is used in the development environment. Errors in loading the RSL, of images, or of ActionScript classes not found can be resolved by paying attention to the transfer of the files. To reduce the possibility of error, make a list of all the external resource files and the path in which they should be found, as shown in the following table. Name
Type
Location
logo.gif
Image
assets/logo.gif
myVideo
RSL
Assets/ Flex_2_Deploy_Rsl.swf
History.js
Wrapper
Web_root
This type of table allows you to have a reference of all the external resources used in the application and how they can be found.
497
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 498
Part V: Building and Deploying Flex 2.0 Applications
Run-time Data Access In the building and testing phase of an application, you may come across a corporate firewall, which, of course, has its own security restrictions. These settings can be much more restricting to the final user who is outside the firewall. This common change of location could cause more than a few problems for the project. It could make that part of the application impossible to access from the outside, causing the access attempts (to data services, to resources found on the application server, or the readdressing on the part of the proxy server) to fail. Therefore, it is fundamental to test all of the run-time data access functions once the deployment phase has been carried out. It can also be useful to make a list of the following: ❑
All the IP addresses of the server that the application can access
❑
IP and DNS of the Web service proxy of FDS
Proxy Server The definition given by Wikipedia of proxy server (http://en.wikipedia.org/wiki/Proxy_server) is simple and effective: A proxy server is a computer that offers a computer network service to allow clients to make indirect network connections to other network services. A client connects to the proxy server, then requests a connection, file, or other resource available on a different server. The proxy provides the resource either by connecting to the specified server or by serving it from a cache. In some cases, the proxy may alter the client’s request or the server’s response for various purposes. When the Flex applications or the proxy of the FDS handle a request to data services, it is necessary to ensure that, in the future, it will be possible to access the same data services of the deployment environment through the proxy. The proxy service contains a list of the destinations of the Web service and the HTTP service. The file in which these options are configured is the flex-proxy-service.xml file. The following are two examples of a configuration to declare an HTTP and a SOAP proxy adapter destination: http://www.comtaste.com/com/services/myservlet http://www. comtaste.com/com/services/*
498
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 499
Chapter 20: Deploying Flex Applications http://{server.name}/flex/myService.cfc?wsdl http://{server.name}:*/flex/echo
It is also possible to define an external proxy before accessing the Internet by defining the IP of the server, the username, and the password: 10.10.10.10 3128 mycompany flex flex
Accessing Server-side Resources from Different Domains Flash Player 7 introduced a security sandbox that implemented rigid restrictions on loading data accessed via the exact same domain from which a movie was loaded. If a Flex application tries to access a URL from outside of the exact residence domain of the SWF, the request will fail. A practical example might be that an application published on www.domainA.com requests data or an RSL from an SWF on the www.domainB.com domain. In this case, the operation would fail. Fortunately, however, by creating a cross-domain policy file and copying it onto the destination server (www.domainB.com), it is possible to indicate to the server which data and assets may be needed by the SWF caller. A cross-domain policy file is an XML file that allows access from your application’s domain and is installed on the Web server hosting the RPC service. Follow these steps to create a crossdomain.xml file:
1. 2.
With Flex Builder 2 (or any other text editor) create a new file. Assign to it the name crossdomain.xml and pay attention to also declare its XML extension. Add the following XML code to the file:
The file is ready to be transferred to the root directory of yoursite.com (that is, the root directory of the server that is serving the data). It is also possible to insert IP addresses in the allow-access tag:
499
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 500
Part V: Building and Deploying Flex 2.0 Applications Or you can use the * symbol in the domain attribute to allow every domain. Flash Player does not perform DNS resolution. The Flash Player ignores any policy file that is served using a cross-domain redirect. For example, if a Flash Player request for http://www.mysite.com/crossdomain.xml redirects to http:// elsewhere.mysite.com/crossdomain.xml, Flash Player ignores that policy file. Ensure that you do not use cross-domain redirects to serve policy files. (You can use redirects within the same domain.)
Deploying a Flex Data Ser vice Application Under Tomcat Developing and deploying an application using Flex Data Services (FDS), to a large extent, is very similar to developing and deploying applications that use Flex 2 SDK. However, FDS offers greater functionality to the developer, and being a server-side application, it must be installed under a Java 2 Enterprise Edition (J2EE) application server. This involves a more complicated development phase, because it involves the use of more advanced and complex functions and a deployment phase that involves more tasks. For example, FDS offers two different methods for the deployment of an application. One method is common to the projects that use Flex 2 SDK: the deployment of a single compiled SWF file. The second method instead uses the Web-tier compiler, and deploys all the MXML and ActionScript files that together form the application. At each HTTP request, the Web-tier compiler will recompile the application. Furthermore, for projects that use FDS in the deployment phase, two delicate aspects (which can take up a lot of time) are those relative to configuration and to security. Being large applications (enterprise applications) that use remote data services, the security aspect can be crucial. During the installation phase, FDS offers the option of using the JRun Web server (Figure 20-8). Adobe advises that this Web server should be used, installed by default as a development server, and not as a production server. In the case in which JRun is used as a Web server, the context root will have the following URL: http://localhost:8700/flex/
However, usually in the deployment phase, a compliant Web server J2EE (on which FDS and the application to be run will be installed) should also be installed on the production machine, as shown in Figure 20-8. In this section, you see how to carry out the deployment of an application using the FDS under Tomcat. Tomcat is a servlet container. A servlet container controls the servlets that are deployed within the Web server. It is also responsible for forwarding the requests and responses for them.
500
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 501
Chapter 20: Deploying Flex Applications
Figure 20-8: Selecting the J2EE Web application option
Tomcat is part of the Jakarta project and is Open Source. You can find more detail on this topic by visiting the Jakarta site (http://jakarta.apache.org) and the Tomcat site (http://tomcat.apache.org/). This discussion does not go into the installation of Tomcat. For this, you can refer directly to the official documentation (http://tomcat.apache.org/tomcat-5.5-doc/index.html) and follow the instructions. However, some advice should be followed to ensure the correct functioning of FDS. First, Tomcat is, in effect, a Java application and, for this reason, you must have the Java Development Kit (JDK) installed on the machine. You can download this from the Sun Web site (http://java.sun.com/ j2se). Note that it is not sufficient to have Java Runtime Edition (JRE) installed on the machine. To process the Java Server Pages (JSPs), Tomcat requires a compiler that is included only in the JDK. The Windows operating system should automatically define the environment variable %JAVA_HOME% during the installation of the JDK. The path contained in %JAVA_HOME% is required to load the Java SDK executable files from any directory without referring to the complete path. You can refer to the installation procedure, as illustrated on the Sun Web site: http://java.sun.com/j2se/1.4.2/install-windows.html
To install Tomcat, leave the options as default. For extra security, you could change the installation path from drive:\Program Files\Apache Software Foundation\Tomcat 5.5 a to drive:\Program Files\Apache Software Foundation\Tomcat_5_5, because the spaces can cause problems in some plugins. Once the installation is completed, you can start the Web server and test that everything functions by launching the following URL, as shown in Figure 20-9: http://127.0.0.1:8080/
501
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 502
Part V: Building and Deploying Flex 2.0 Applications
Figure 20-9: Starting the Web server
The directory structure of Tomcat is not complex. Following are the folders involved in an FDS application: ❑
bin directory — This directory contains the executable files used to start and stop Tomcat.
❑
conf directory — This is the Tomcat configuration directory.
❑
logs directory — Contains all the logs.
❑
webapps directory — This is the default directory for Web applications. This is the directory
where you will copy the Web application archive (WAR) Flex files. Now that you have installed Tomcat on the deployment machine, you can now move on to the installation of FDS and follow its deployment onto the Web server. As mentioned, FDS is a J2EE Web application and can be installed with the integrated JRun or as J2EE Web applications under a Web server. In the first case, you should install only in the development phase. For the deployment on the production environment, you should install the FDS J2EE as a Web application. At this point, the following folders will be created in the fds2 directory: ❑
Files — The installation root that includes the WAR files (flex.war, samples.war, and flex-admin.war)
❑
flex_sdk_2 directory — Contains the Flex Framework, framework source code, and
command-line compilers
502
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 503
Chapter 20: Deploying Flex Applications ❑
resources directory — Contains installers for Flash Player 9 and the files used for the HTML wrapper, clustering, Hibernate, and so on
❑
UninstallerData directory — Contains the uninstaller
To complete the installation on the deployment environment, you must copy the three WAR files taken from the Files folder of the Fds2 directory in the webapps folder of Tomcat (yourDrive:\Program Files\Apache Software Foundation\Tomcat_5_5\webapps). WAR is a ZIP file used to distribute a set of Java classes. The Flex.war is basically a Web application directory that contains Java classes, filters, and listeners to interpret the Flex applications written in MXML and ActionScript. By copying the three WAR files into the webapps of Tomcat, the Web server automatically recognizes the file, unpacks it, creates an expanded Web application, and deploys it. There are now three other folders in the webapps: Flex, Flex-admin, and Samples. You can now test the correct installation and functioning of the FDS by launching the examples contained in the Samples folder at the following URL (Figure 20-10): http://127.0.0.1:8080/samples/
Figure 20-10: Launching the examples
503
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 504
Part V: Building and Deploying Flex 2.0 Applications If your FDS application used the DataService feature, Tomcat needs the Java Open Transaction Manager (JOTM) package installed and correctly configured. JOTM is a JTA-compliant transaction manager that implements the Extended Architecture (XA) protocol. It provides full distributed transactions support for Enterprise Java Bean (EJB) or servlet containers projects. You can download the latest version of JOTM at the following URL: http://forge.objectweb.org/projects/jotm/
Unzip the file and copy the JAR files from jotm-root/lib to tomcat-root/common/lib. All you must do is configure the definition of the Transaction in the node of the application configuration file.
Restart the Apache Tomcat service, and you have now followed all of the steps necessary for the deployment of FDS under Tomcat on a production machine. To delve deeper into the installation procedure of FDS on Tomcat, see the Adobe support documentation at http://www.adobe.com/support/documentation/en/flex/2/install.html#tomcat. At this point, the production machine phase is ready to host the Flex application. During the deployment phase of a project, it is possible to use two different directory structures that define the location of the application: ❑
In the FDS Web application
❑
In its own Web application
Let’s begin with the publication of the project in the directory of the FDS Web application. In the flex folder in webapps (under Tomcat), there is a folder called WEB-INF, which is the root directory for the Flex applications. In this directory, you will copy all the files necessary for the application (SWF, MXML, ActionScript, CSS, JSP, and so on), as shown in Figure 20-11. In the flex folder, you can create as many folders as you have applications using folders for external elements defined in the application’s root directory. In the case in which external assets are shared or sharable by different applications, it is convenient to create a folder to contain them, established on the main root. It is best practice to copy all of the shared files (images, MXML, ActionScript, and RSLs) into the yourDrive:\Program Files\Apache Software Foundation\Tomcat_5_5\webapps\flex\ WEB-INF\flex\user_classes folder, which automatically includes all the applications that you
have developed in the source path. In the case in which the C files become copied in different
504
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 505
Chapter 20: Deploying Flex Applications directories, the path must be specified in the node in the flexconfig.xml file (or sent as parameters to the compiler): Tomcat (or J2EE web server) | Flex |-- myApp_1 | -- localAsset_1 |-- myApp_2 |-- my App_3 |-- sharedAssets | WEB-INF
The second approach to creating a directory structure for the application is to isolate the application from the FDSWeb application. Following this approach, it is more convenient to distribute the application separately: Tomcat (or J2EE web server) | Flex | WEB-INF |-- myApp_1 | -- localAsset_1 |-- myApp_2 |-- my App_3 |-- sharedAssets
Figure 20-11: Copying all the necessary files
505
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 506
Part V: Building and Deploying Flex 2.0 Applications The following table shows the contents of the Flex directory in webapps (taken from the official Adobe Flex documentation). Directory
Description
/flex
This is the root directory. It contains the WEB-INF directory.
/WEB-INF
The web.xml configuration file is hosted into this folder. If you use other Web applications, this directory could contain other deployment descriptors.
/WEB-INF/flex
Contains the following folders: jars — Contains all the JAR files libs — All the SWC files used by Flex locale — SWC localization resource file themes — Contains the haloclassic.swc file for the look and feel of Flex
components user_classes — This is the folder where you put your custom classes, SWC
files, and components Having defined the directory structure of the application and having executed/carried out the transfer from the development environment to the deployment environment, you must configure FDS on the new machine to complete the deployment process.
Configuring for FDS An application developed using the advanced functions of FDS requires the configuration of different external files: Remoting Service, Proxy Service, Message Service, and Data Management Service. These different configuration files are the same files that were configured on the machine in the development phase. The configuration of the destinations is the most basic task in the configuration of FDS. Assigning an unambiguous ID to a service (named service) and using it in the MXML page allows Flex to have information on how some named services must be thought of as an authenticated service. Usually, it is sufficient to simply transfer the files from one environment to the other, overwriting he original files on the deployment environment. The folder in which these files are located is the yourDrive:\Program Files\Apache Software Foundation\Tomcat_5_5\webapps\flex\ WEB-INF/flex directory of your FDS Web application (Figure 20-12).
The configuration files involved in the configuration phase obviously depend on the features that have been used in the FDS application. One important aspect in the configuration of the files that can differ greatly between the development phase and the deployment phases is relative to the level of security you want to set on the application.
506
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 507
Chapter 20: Deploying Flex Applications
Figure 20-12: Location of files
In the development environment, you usually do not apply a security constraint because you are not interested in restricting access to a group of privileged users by means of authentication. However, this changes in the deployment environment, where access to an application must not be open to everyone, but must be accessible only by the users authorized to do so. Flex does not automatically apply a method of authentication or authorization to users. For this reason, it is necessary to apply security constraints in a destination definition in the FDS configuration in the deployment environment. A Remote Procedure Call (RPC) service destination is the object or the service to which you connect through the classes RemoteObject, WebService, or HTTPService. Through these configurations, it is possible to authenticate the use of a remote service like RemoteObject and to permit only authorized users to make use of the service. To restrict access to a privileged group of users, you apply the rules of security constraint in a destination definition in the FDS configuration file. There are two methods of configuration: inline and global. The inline method is applied in the destination for which it should be valid, and by configuring the security-constraint property as follows: classes.comtaste.Employee application Custom DestinationUser
507
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 508
Part V: Building and Deploying Flex 2.0 Applications In this case, the security-constraint is valid only for the destination with id=“myDest”. The method of global declaration allows you to share more destinations with the same security settings: classes.comtaste.Employee application classes.comtaste.Employee_2 application ... ... Custom DestinationUser
In this example, the two destinations, myEmployee and myEmployee_2, refer to and share the same security-constraint, securedUser, which is defined outside of the two destinations. The configuration phase of FDS is obviously crucial to the correct functioning of the application and attention must be paid when configuration files are transferred from the development environment to the deployment environment. Routing out and correcting malfunctions caused by incorrect configuration can be time-consuming.
Creating a Wrapper Flex applications that use only Flex 2 SDK instead of FDS are compiled in an SWF file in the end. The client loads the SWF file of the Flex application in the HTML file on the browser, which imports the SWF and the JavaScript files to support the History Manager and the Flash Player detection. These files are together defined as the wrapper. Flex offers different wrappers, ready to use in the compilation phase. In Flex SDK 2\resources\htmltemplates there are six HTML templates that can be implemented and that support different features: ❑
508
Client-side-detection — Includes the index.template.html and AC_OETags.js files. These provide support for the detection of the Flash Player on the client and load alternative contents if the browser does not find the required version.
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 509
Chapter 20: Deploying Flex Applications ❑
Client-side-detection-with-history — Includes the index.template.html, AC_OETags.js, history.js, history.swf, and history.htm files. In contrast to the preceding template, this adds support to the History Management in the history.js and history.swf files.
❑
Express-installation — Includes the index.template.html, AC_OETags.js, and playerProductInstall.swf files. This template is used to support the Express Install, which is discussed in detail later in this chapter.
❑
Express-installation-with-history — Includes the index.template.html, AC_OETags.js, history.js, history.swf, history.htm, and playerProductInstall.swf files. Aside from providing the support of Express Install, this also adds History Management.
❑
No-player-detection — Includes the index.template.html and AC_OETags.js files. This basic template offers the option of simple importation of an SWF file using an external JavaScript.
❑
No-player-detection-with-history — Includes the index.template.html, AC_OETags.js, history.js, history.swf, and history.htm files. The importation of the SWF file adds History Management.
These templates represent the starting point for creating a custom wrapper for Flex applications.
Migrating and Transferring Files In the deployment phase of a project, all the files imported and used from the wrapper must be migrated and transferred onto the deployment environment, respecting the location of every file. Flex Builder and FDS generate a wrapper by default that includes the support of History Management and of Express Install. The features of the wrapper created by default can, however, be changed and configured to suit individual requirements. Flex Builder 2 displays these settings in the Flex Compiler dialog box. Following are the options that are possible to set: ❑
Generate HTML wrapper file — By disabling this checkbox, the file wrapper will not be generated. Flex Builder will only compile the SWF file of the application.
❑
Detect Flash Player version — In these fields, you can specify the exact version that should be checked and verified on the clients. It is also possible to disable this option to choose to not use the support of the detection of Flash Player.
❑
Use Express Install — Provides support for Express Install.
❑
Enable history management (browser Back button) — Provides support for History Management.
When you run the project and Flex Builder compiles the application, it reads the settings for the HTML wrapper and inserts the wrappers generated in the bin folder of the project. All the file templates necessary for the creation of the wrapper are contained in the html-template that is established at the project level in Flex Builder. If you manually modify these files in the template (for example, inserting the TITLE tag in the HTML page), these changes will be saved in the wrapper generated. On the other hand, the FDS applications that use the Web-tier compiler compile the MXML file requested by the client on the fly. To see the wrappers generated by FDS, open the HTML file resulting from the call with the view source user of the browser and save it. In this way, it is obviously not possible to save the
509
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 510
Part V: Building and Deploying Flex 2.0 Applications contents of all the other files involved in the HTML wrapper. To see the contents of these files, you can do the following: ❑ ❑
Use a browser toolbar such as the Web Developer Extension for Firefox, which permits you to see and save all the contents used in an HTML page. Use a sniffer, a program that traces the request and response flow of HTTP traffic. In the Flex _istall_dir/jrun4/bin folder, there is a TCP Monitor application, which is a Java applica-
tion that listens to a port and passes this request to the resource on the target port.
Defining Features By modifying the settings in the flex-webtier-config.xml file, it is possible to define the features supported by the wrapper generated by the FDS compiler. Following are the nodes in the XML file that become involved in the creation phase of the wrapper: true true true 9 0 0
Get Flash]]>
The deployment phase of a flex-webtier-config.xml file must be transferred to the production server. When using the Web-tier compiler with FDS, it is also possible to directly access the Flex application pointing directly to the compiled SWF file. In this way, the server does not generate the HTML wrapper files, but only carries out the compilation of the MXML file in SWF. To force the request of an MXML file without the wrapper, simply add .swf to the request string, as shown below: http://www.yourdomain.com/myFlexApp.mxml.swf
In this way, however, the possibility of managing History Management, Express Install, and any type of communication between the Flex application and JavaScript will be omitted.
510
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 511
Chapter 20: Deploying Flex Applications For applications that provide for the use of ExternalInterface API or of Flex/AJAX Bridge, it is not necessary to make the request to the server without the use of the wrapper. The final compiler to discuss is the mxmlc.
mxmlc Compiler The mxmlc command-line compiler does not automatically generate a wrapper. It is necessary to manually write it, taking as an example one of the templates found in the Flex SDK 2\resources\ html-templates folder. When you launch mxmlc for the compilation, the wrapper will be sent as an advanced option to compile the SWF and the relative HTML wrapper. Aside from using the Flex wrapper template, it is possible to create its own custom wrapper. The creation of a wrapper provides for the production of an HTML file composed of one block (which imports the JavaScript file and defines the and tags to include the SWF file) and a block (which defines the code for all the browsers that do not support JavaScript). Begin by defining the code in the HTML file:
Immediately after the declaration of the root tag in the first HTML page, a JavaScript file is imported:
And, immediately after that, the imported SWF file, using both (for Internet Explorer) and (for Netscape), is inserted in the tag:
511
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 512
Part V: Building and Deploying Flex 2.0 Applications
The code in the tag is required to guarantee the loading of the Flex application even for the browsers that have disabled JavaScript in their preferences. If JavaScript is disabled, all communication between the application and JavaScript using the ExternalInterface API class will not work. For this reason, messages, or the loading of appropriate content to advise the users that the application they are about to load will be limited in some functions, are usually inserted in this tag. The JavaScript file embedFlash.js simply contains a series of document.write() requests that write the and tags for the importation of the application. This same and block defined in the HTML page is used in the JavaScript file: document.write(“”); document.write(“”); document.write(“”); document.write(“”);
In this case, you have loaded the Flex_2_Deploy.swf application, created earlier in this chapter, but you can use this wrapper as a starting point for personalization. You could, for example, add a personalized header or footer in the HTML document, adding information relative to your company or copyright. Be aware that this basic wrapper does not manage History Management, grant the functioning of the Back button of the browser, or Express Install to control the minimum requisites of Flash Player and, in such case, the automatic installation of the plugin.
Adding Features to the Wrapper The wrapper that was created in the preceding section deals only with the importation of the Flex application into the HTML document. The features for History Management or for Express Install are not dealt with. It is possible to add features to the wrapper by simply adding properties to the and tags by importing new JavaScript files or by adding content to the HTML page. It is possible, for example, to insert the Flex application in a structured layout that uses CSS positioning techniques by defining a simple CSS file and the layer structure (using the tag) in the HTML document.
512
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 513
Chapter 20: Deploying Flex Applications Begin by modifying the content of the customWrapper.htm file that you will save with the new name custom Wrapper_2.htm: Flex 2 Profesional - Customizing the Wrapper © Developed by Marco Casario Blog: http://casario.blogs.com
Following are the only modifications made in this HTML file: ❑
The importation of the CSS file in the tag with the method .
❑
This file deals with the pagination of the structure of the content.
❑
The insertion of the structure of the layout through the tags, which define the following structure:
Flex 2 Profesional - Customizing the Wrapper
513
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 514
Part V: Building and Deploying Flex 2.0 Applications The main.css file will contain a few lines of code, but will define a monolith layout. With Dreamweaver 8 or with a simple text editor, create a CSS document that you save with the name main.css. The final code of the CSS document is the following: /* main.css Document */ html,body{margin:0; padding: 0} body{font-family: arial,sans-serif; font-size: 76%;background-color:#869CA7;} h1{margin: 0;padding:0} div#content{padding:0 1.5em} div#footer{padding:0.5em; color:#000; text-align:center}
Customizing a wrapper is a very simple task, which, in the end, modifies an HTML page and its contents. There are, however, a few rules that must be kept in mind to avoid malfunctioning: ❑
To avoid an annoying prompt to the user for the loading of the contents in Flash Player in Internet Explorer, avoid inserting the JavaScript directly in the HTML page. In fact, as part of the XP SP2 Local Machine Zone lockdown, Internet Explorer on Windows XP SP2 blocks active content and scripting that tries to run in the Local Machine zone. For more information on this, consult the Microsoft Web site:
http://www.microsoft.com/windows/ieak/techinfo/deploy/60/en/appendix.mspx
❑
As far as the use of the and tags is concerned, for the importation of the SWF file, use the same parameters and values so as not to have a difference between the loaded application on different browsers. Furthermore, do not insert periods or special characters in the “id” and “name” properties of the tags, because this could cause problems in the use of an ExternalInterface class.
❑
To add support to the History Management and the Express Install in the custom wrapper, you can refer to the files contained in the Flex SDK 2\resources\html-templates folder (in the express-installation-with-history folder).
❑
In the deployment phase, remember to transfer all the defined and used files into the wrapper. For example, for the functionality of Express Install and History Management, it is necessary to transfer the following files (aside from the HTML file and the SWF file) to the deployment environment: AC_OETags.js, history.js, history.swf, history.htm, and playerProductInstall.swf.
In the following section, you create a custom wrapper to render the Flex application compliant with the XHTML 1.0 validators.
Creating a Wrapper that Supports Web Standards The validity and the coherence of the HTML code is an important aspect, especially when the application must respect norms of quality and accessibility. In fact, one of the first rules is that of producing the XHTML code (HTML is by now a deprecated language) valid according to specific World Wide Web Consortium (W3C) reports. As far as the Flex and Flash applications are concerned, the code necessary to import an SWF file does not produce a document that is valid according the XHTML 1.0 language with Document Type Definition (DTD) of a transitional or strict type. Different techniques exist to produce documents that import SWF standard-compliant files. In this section, you will use the technique known as Flash Satay (http://
514
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 515
Chapter 20: Deploying Flex Applications www.adobe.com/devnet/dreamweaver/articles/flash_satay.html), first created, discussed,
and put into action by Drew McLellan. Carefully look at the HTML code that you created in the preceding sections or through that written in the templates in the Flex SDK 2\resources\html-templates folder. To import an SWF, you use the following code:
The two and (nested in the ) tags are used with the values necessary for the loading of the SWF file. The first tag is one needed by Internet Explorer, and the second is for all Netscape browsers. But whereas the tag forms part of the XHTML specifics (http://www.w3.org/TR/xhtml1/), the tag does not form part of the standard and this is one of the first causes of nonvalidation of code when the validator of the W3C (http://validator.w3.org/) is launched. It is, in fact, said that the tag is not standard-compliant. Therefore, in the creation of a standard-compliant wrapper, the first task to carry out is that of removing the tag from the HTML code. The SWF file will be loaded equally well by browsers other than Internet Explorer because the recent versions of browsers all support the tag, being a known standard. The code you obtain will be the following:
This code, however, will continue to render the file visible only in Internet Explorer and is not valid (that is, XHTML-compliant). The problem is in seeking the classid attribute, which is created exclusively for the use of ActiveX in Internet Explorer and which is, therefore, not interpreted by different browsers. The role of this attribute is not a light one, and it is required to specify the type of browser to use to load this content. Flash Player, however, also responds to the following MIME type application/ x-shockwave-flash, defined in the type attribute:
515
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 516
Part V: Building and Deploying Flex 2.0 Applications In the code, you have also removed the codebase attribute that contains the path to copy the Flash plugin to its Adobe servers. This attribute in Internet Explorer specifies the version of the plugin that the server should deliver, whereas in other browsers it blocks the execution of the SWF content. Finally, you have added the data attribute to specify the location of the object’s data, permitting any browser to load the SWF content:
It all functions well on all browsers and becomes perfectly validated by the W3C XHTML validator. You can test this by loading the following HTML code in the Validate by Direct Input field at the address of http://validator.w3.org/ (Figure 20-13):
You have, therefore, created a wrapper that perfectly conforms to XHTML standards and is correctly validated by W3C. One last thing is to remedy a problem that appears for SWF film segments of large dimension on Internet Explorer. The Microsoft browser waits for the SWF file to load before showing any contents. To remedy this inconvenience, simply create an empty Flash movie that on frame 1 will have the following code: _root.loadMovie(_root.path,0);
516
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 517
Chapter 20: Deploying Flex Applications
Figure 20-13: Validating the code
The loadMovie() method loads the defined file in the variable path that is sent to it as a parameter of the tag:
The film segment emptyFlash.swf has the usual task of loading the SWF of the application by taking its defined value in the variable path. emptyFlash.swf?path=Flex_2_Deploy.swf
In this section, you have created an XHTML wrapper that is compliant with the Flex application. You can add support to History Management and Express Install by referring to the template in the Flex SDK 2\resources\html-templates folder.
517
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 518
Part V: Building and Deploying Flex 2.0 Applications
and The and tags allow for the insertion of a Flex application in the wrapper that will be used to create the final HTML page and to render the SWF contents visible on the users’ browsers. More generally, these elements allow you to specify the data and parameters for multimedia objects inserted into HTML documents, and the code that can be used to manipulate that data. The tag is used by Internet Explorer on Windows (that uses an ActiveX control) and the tag is used by Netscape Navigator (Macintosh and Windows) and Internet Explorer (Macintosh) to tell the browser to load the content using the Adobe Flash Player. In terms of compatibility, the tag is for Internet Explorer 3.0 or later on Windows 9x/2000/ NT/ME/XP platforms, or any browser that supports the use of the Flash ActiveX control. The tag is for Netscape Navigator 2.0 or later, or browsers that support the use of the Netscape-compatible plugin version of Flash Player. Both tags support the attributes that change according to the contents that must be loaded. As far as the Flex applications and, therefore, the SWF contents are concerned, the properties allow you to change the appearance of the file in the page. You can add and modify these settings in the customizing of the wrapper phase. The following table shows the principle attributes of default for and . Attribute
Description
data
This attribute can be used to specify the route of the object to be introduced in the page
classid
Gives indications on the route of the object and is useful to identify the type of plugin with which the object will run
codebase
Is needed to indicate the base URL, to which the code indicated in “data” or in “classid” refers
type
Is the type of object to insert (more precisely it is the MIME type of the object)
archive
Indicates a list of URL, separated by a comma, content resources relative to the inserted object
width, height
If necessary, indicates width and height
The following table provides descriptions for parameters.
518
Parameter
Description
allowScriptAccess
Specifies how to perform outbound scripting from within the SWF file. It accepts the following values: always, never, and same domain.
pluginspace
The location of the Flash Player plugin.
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 519
Chapter 20: Deploying Flex Applications Parameter
Description
border
The width (in pixels) of the SWF file.
declare
Setting the declare property to true tells the SWF to be instantiated by a subsequent object definition referring to this declaration.
devicefont
A Boolean that specifies how the static text objects (for which the deviceFont option is not selected) are drawn using a device font.
standby
Specifies a message displayed by the browser while loading the object’s implementation and data.
style
Defines the style information for the SWF file.
supportembed
A Boolean that specifies if Netscape’s tag is supported.
tabindex
Specifies the position of the SWF file in the tabbing order for the current document.
id
Identifies the SWF file to be referenced by using JavaScript (or any scripting language) for the tag.
name
Identifies the SWF file to be referenced by using JavaScript (or any scripting language) for the tag.
menu
A Boolean that specifies if the context menu displays the full menu.
quality
Specifies the quality of the SWF file. Accepts the following values: low, high, autolow, autohigh, and best.
scale
Defines how the browser fills the screen with the SWF file. Used values are: showall, noborder, and exactfit.
align
Specifies the position of the SWF content. Supports the following values: Left, Right, Top, Middle, and Bottom.
allowNetworking
Restricts browser communication. Supports the following values: all, internal, and none.
wmode
Sets the Window Mode property. Accepts the following parameters: Window, Opaque, and Transparent.
bgcolor
The background color of the movie specified in hexadecimal RGB value. In order to make it work with Flex applications, you must clear the application’s backgroundImage style property.
base
Specifies the base directory or URL used to resolve all relative path statements in the Flash Player movie.
Continued
519
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 520
Part V: Building and Deploying Flex 2.0 Applications Parameter
Description
flashVars
Sends root-level variables to the Flex application. The format of the string is a set of name=value combinations separated by ‘&’.
hspace
Specifies the amount of white space inserted to the left and right of the SWF file.
vspace
Specifies the amount of white space inserted at the top and bottom of the SWF file.
lang
The base language of an element’s property values and text content.
Flex does not support the following parameters, which are, on the other hand, supported by ordinary Flash applications: ❑
loop
❑
play
❑
swliveconnect
Using Express Install It may not be sufficient to carry out a detection of the Flash Player on the client that is loading the Flex application. For example, you may have been able to use one of the features that functions only at the beginning of a “search for a version later” of Flash Player. In this case, it becomes crucial to check the exact version of the plugin installed on the client. If the response that you get from this check does not match your requirements, you can proceed with the relative upgrade of Flash Player and be sure that the client is able to load the Flex application. With the Flash Player 6r65 version, Adobe has added the support of the Express Install feature for designing the best Flash Player detection experience. Express Install provides the capability for the Flash Player to update itself to a more current version. This has made the upgrade process much simpler for the user. Flex includes the code of all the files necessary to developers to not only detect when users do not have the latest version of Flash Player, but also to start an update that securely installs the latest version of the Player from the Adobe Web site. This feature offers many benefits to Flex developers, which can be summarized in the following points:
520
❑
Assuring and guaranteeing Flash Player loads the Flex application correctly.
❑
Allowing users not to be redirected from your site to the Adobe.com site in order to upgrade the player.
❑
Providing a consistent way for upgrading the system across platforms and operating systems.
❑
If the player on the client does not respond to the defined requirements, it is possible to load an alternative content.
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 521
Chapter 20: Deploying Flex Applications In the SDK 2\resources\html-templates folder, there are two default HTML templates that implement and support Express Install: ❑
express-installation — Includes the index.template.html, AC_OETags.js, and playerProductInstall.swf files.
❑
express-installation-with-history — Includes the index.template.html, AC_OETags .js, history.js, history.swf, history.htm, and playerProductInstall.swf files. Aside
from the support of Express Install, it adds History Management. Therefore, to manage Express Install, it is necessary in the deployment phase to also transfer the AC_OETags.js and playerProductInstall.swf files in order to be able to run the Flex application
(aside from the HTML and main application SWF file). If you also operate History Management, it is necessary to also transfer the history.js, history.swf, and history.htm files. Sometimes, the Auto Update of Flash Player and the Express Install features become confused. There is a substantial difference between the two options. Auto Upgrade forces the Flash Player to periodically check for new versions, and asks the user to upgrade when a new version is detected. The Express Install is managed and set by the developer who decides on the requirements that must be checked, and the actions that must be interpreted in the case of a mismatch of these.
Editing Your Wrapper Earlier in this chapter, you learned how the default wrapper used by Flex Builder or by FDS manages Express Install. It is, therefore, possible to customize the wrapper of the compiler to include or exclude the Express Install option. For applications that use the Web-tier compiler of FDS, it is possible to modify the settings in the flexwebtier-config.xml file by modifying the node. Retrieve the custom wrapper that was created in the previous sections and that you saved under the name customWrapper.htm. The HTML code was the following:
521
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 522
Part V: Building and Deploying Flex 2.0 Applications
To manually add support to Express Install, you must add the JavaScript file to the HTML document inserting it between the head tags:
This file is located in the folder that contains the Flex SDK 2\resources\html-templates\expressinstallation templates, and will be transferred (in the deployment phase) to another location accessible to the wrapper. Following this, add the Global section with the declaration of the three variables to define the minimum version of Flash Player that the users must be running. This code will be added immediately under the importation of the script AC_OETags.js:
You can write this code by hand, or simply copy it from the index.template.html file that you will find in the same folder as the AC_OETags.js file. You now insert the second block of JavaScript code into the page, which sends the information from the SWF file to load to the script AC_OETags.js: Get Flash’; document.write(alternateContent); // insert non-flash content } // -->
523
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 524
Part V: Building and Deploying Flex 2.0 Applications In this block of code, you define the properties “ïd”, “name”, and “src”, which correspond to those assigned in the and tags: AC_FL_RunContent( “src”, “playerProductInstall”, “FlashVars”, “MMredirectURL=”+MMredirectURL+’&MMplayerType=’+MMPlayerType+’&MMdoctitle= ’+MMdoctitle+””, “width”, “100%”, “height”, “100%”, “align”, “middle”, “id”, “Flex_2_Deploy”, “quality”, “high”, “bgcolor”, “#869ca7”, “name”, “Flex_2_Deploy”, “allowScriptAccess”,”sameDomain”, “type”, “application/x-shockwave-flash”, “pluginspage”, “http://www.adobe.com/go/getflashplayer” );
These are also defined a little lower down inside the same function: else if (hasRequestedVersion) { // if we’ve detected an acceptable version // embed the Flash Content SWF when all tests are passed AC_FL_RunContent( “src”, “Flex_2_Deploy”, “width”, “100%”, “height”, “100%”, “align”, “middle”, “id”, “Flex_2_Deploy”, “quality”, “high”, “bgcolor”, “#869ca7”, “name”, “Flex_2_Deploy”, “flashvars”,’historyUrl=history.htm%3F&lconid=’ + lc_id + ‘’, “allowScriptAccess”,”sameDomain”, “type”, “application/x-shockwave-flash”, “pluginspage”, “http://www.adobe.com/go/getflashplayer” );
If you want to manage an alternate content to load in the case that the version of Flash Player installed on the client does not correspond to that defined in the minimum requirements, you can do so in the else cycle shown here, defining the contents in the variable alternateContent: else { // flash is too old or we can’t detect the plugin var alternateContent = ‘Alternate HTML content should be placed here. ‘ + ‘This content requires the Adobe Flash Player. ‘ + ‘Get Flash’; document.write(alternateContent); // insert non-flash content }
524
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 525
Chapter 20: Deploying Flex Applications The final HTML file can be seen in the customWrapper.htm example file. In the deployment environment, do not forget to transfer the files necessary to detect the Express Install (AC_OETags.js and playerProductInstall.swf). In the case in which History Management was also to be managed, it would be necessary to define the flashvars variable as follows: “name”, “Flex_2_Deploy”, “flashvars”,’historyUrl=history.htm%3F&lconid=’ + lc_id + ‘’, “allowScriptAccess”,”sameDomain”,
It is also necessary to transfer the history.js, history.htm, and history.swf files in the deployment phase.
Configuring Express Install on Flex Data Ser vices When an application is developed with FDS, it is possible to use the Web-tier compiler that compiles the Flex application and its assets in SWF at run-time once the .mxml file is requested by the client: http://www.yourdomain.com/myFlexApp.mxml
The compiler, at this point, returns the wrapper that embeds the resulting SWF file to the client. You configure the Web-tier compiler by editing the flex-config.xml files (which contain the same defined nodes for the compiler command line) and the flex-webtier-config.xml file (which allows for the production mode to be enabled and to configure player version detection and caching). Both of these files are located in the flex_webapp_root/WEB-INF/flex directory. To modify the options for Express Install, you can edit the settings in the flex-webtier-config.xml file, in which it is possible to define features supported by the wrapper generated by the FDS compiler. Following are the nodes in the XML file that are involved in the creation phase of the wrapper: ❑
true — Allows you to enable or disable
the use of Express Install. ❑ ❑
9 — Required major player version. 0 — “Dot” release of the required
player. ❑
0 — Minor version revision
number of the required player.
525
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 526
Part V: Building and Deploying Flex 2.0 Applications These settings are located in the node: true true 9 0 0
Get Flash]]>
The last node manages the loading of the alternative content for the case in which the version of Flash Player installed on the client does not meet the minimum requirements.
Upgrading Without Express Install Though Express Install is user-friendly, it is not the only possibility that a developer of Flex applications has available for managing the updating of Flash Player. Through the properties of the and tags, it is possible to define a path to upgrade and install Flash Player. The tag displays the codebase property that controls the version of the plugin in Internet Explorer. In the tag, two attributes become defined: the classid (which identifies the ActiveX control used by the browser to read the film segment) and the codebase. The classid specifies the base path used to resolve relative URIs specified by the classid, data, and archive attributes:
In this case, the following line of code, aside from indicating the download URL of Flash Player, also establishes the minimum requirements defining the version: codebase=”http://download.macromedia.com/pub/shockwave/cabs/flash/ swflash.cab#version=9,0,0”
526
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 527
Chapter 20: Deploying Flex Applications Therefore, the browser loads the Flash-defined film segment from this tag. If, on the client, it does not find version 9 of the Flash Player, it will request that the user perform an upgrade of the plugin. Similarly, for the Firefox, Netscape 8, and all other Mozilla-based browsers, the pluginspace property of the tag functions in the same way:
The only difference with respect to the tag object is that it is not possible to specify a version of the plugin, and, therefore, it can only verify the presence of Flash Player on the client. Using these two methods does not always obtain the desired results. Depending on the type of browser and the version, the user may not be able to load the exact version of Flash Player requested for the Flex application to function. In addition to the Flash Player–detection techniques described here, you can always provide alternative content that displays the version information and contains a link to the Flash Player download page. This content should be put in the block. To examine more detail about the Flash Player detection, Adobe has created the Flash Player Detection Kit (located at http://www.adobe.com/products/flashplayer/download/detection_kit/), which includes the following: ❑
The documentation describing the requirements, methods, and procedures for detecting and updating the end user’s Flash Player version
❑
Client-side detection sample files
❑
ActionScript-based detection sample files
Summar y This chapter provided a comprehensive guide on the different methods of application deployment, as well as the consequences of each. It demonstrated the use of the wrapper file and all of the ways this file can be edited for Web-standard compliance, as well as to suit the individual needs of the application being deployed. The History Manager and Express Install were also discussed, and examples demonstrated how to deploy an application using either or both of these. Chapter 21 is dedicated to the Cairngorm micro-architecture developed by the Adobe Consulting team. Examples on the implementation of Cairngorm and all of the pieces that make up the Cairngorm framework are demonstrated.
527
02671c20.qxd:WroxPro
4/20/07
1:46 PM
Page 528
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 529
Part VI: Advanced Flex 2.0 Chapter 21: Using the Cairngorm Framework Chapter 22: Using the Flex-Ajax Bridge Chapter 23: Using the ActionScript 3.0 Libraries Chapter 24: Using ColdFusion/Flex Connectivity
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 530
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 531
Using the Cairngorm Framewor k Cairngorm is a framework used to develop Rich Internet Applications (RIAs) in Adobe Flex. It was originally developed by iteration::two, which was acquired by Macromedia (now Adobe) in 2005. The framework was released for Flex 1.5 and later updated to version 2 to work in conjunction with the newly released Flex 2.0. The latest version of the Cairngorm Framework, version 2.1, was released at Adobe MAX 2006 in Las Vegas by the Adobe Consulting Team. The example used in this chapter uses Cairngorm 2.1, which is currently as of this writing the latest version of the framework.
The Cairngorm Framewor k The framework is an adaptation of Sun’s core J2EE patterns and was first applied to Flash development and then to Flex. Iteration::two also played a significant role in helping shape the Flex Framework. Over the years, iteration::two developed the Cairngorm Framework through considerable research and development using best-practice techniques from the field of design patterns. The framework was then applied to the emerging technology of RIAs using Flex. At the MAX 2004 conference in New Orleans, iteration::two announced the release of the Cairngorm Framework as an Open Source project for the Flex development community. For more information on the Cairngorm Framework, Steven Webster has a great series of articles on “Developing Flex RIAs with Cairngorm Micro-Architecture.” The series is comprised of the following six parts: ❑
Part 1: Introducing Cairngorm
❑
Part 2: Keeping state on the client
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 532
Part VI: Advanced Flex 2.0 ❑
Part 3: Architecting the view
❑
Part 4: Feature-driven development
❑
Part 5: Server-side integration
❑
Part 6: Rapid and consistent development with Cairngorm and Flex
You can find the series of articles at http://www.adobe.com/devnet/flex/architecture.html. It is a must-read if you want to learn more about the Cairngorm Framework and how it works with Adobe Flex. To get to grips with Cairngorm, this chapter takes you through the framework while building a Flex weather application. This seems to be the most efficient way in learning something new.
Understanding Framewor ks It is important to understand what a framework is before you start using one for the first time. The word “framework” is often misunderstood in the software development field. There are two different types of frameworks, one being application frameworks and the other being architectural frameworks. For a more in-depth explanation of frameworks, refer to part 1 of Steven Webster’s series of articles at http://www.adobe.com/devnet/flex/articles/cairngorm_pt1_02.html.
Application Frameworks Application frameworks usually refer to a set of libraries and classes used to implement the standard structure of an application. Flex 2.0 is a great example of an application framework. The Flex 2.0 Framework provides a set of rich class libraries that provide functionality for developers to create custom applications. For example, Flex 2.0 provides a competent framework that allows you to develop custom components to be reused in your Flex applications. Application frameworks have become more popular with the rise of graphical user interfaces (GUIs), which seem to promote a standard structure for applications. Object-oriented programming (OOP) techniques usually are used to implement frameworks such as the unique part of an application that can inherit from preexisting classes in the framework.
Architectural Frameworks Architectural frameworks refer to a set of tools that can be used to provide a structure where the business layer of the application can be defined. In other words, an architectural framework is the internal structure on which an application is built.
532
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 533
Chapter 21: Using the Cairngorm Framework
Building an Application Using the Cairngorm Framewor k In the remainder of this chapter, you build an application from the ground up, utilizing the Cairngorm micro-architecture. The Flex Weather application showcases the basics of a Flex application framework, and demonstrates data binding, navigator containers, and controls and effects. The Weather application is a great way for you to become familiar with the Cairngorm Framework. Figure 21-1 shows the completed Flex Weather application using the Cairngorm Framework.
Figure 21-1: Example Weather application using the Cairngorm Framework
533
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 534
Part VI: Advanced Flex 2.0
Value Object and Model Locator Pattern Developers who come from a Web application background must change the way they think about RIAs. The reason is because Flex applications are stateful, rather than the stateless HTTP request-and-response model of an HTML Web application. To overcome this, developers require ways to maintain state on the client. This is done by using either cookies or sessions on the server to achieve a stateful client. RIAs work in the same way that desktop applications work in that their state is maintained on the client. So the principles of building Web applications must be changed when designing and developing RIAs.
Value Object When developing applications in Flex (or any enterprise application, for that matter), you should create classes or objects that represent an entity. For example, in the Weather application, the one thing that you must represent is the weather for that location. Each location has a number of weather attributes, such as temperature, date, conditions, longitude, latitude, wind, and so on. Useful structures can be exchanged or transferred between tiers in your application. On the server side, you could run a query in SQL that returns a result set and then converts it into a collection of custom value objects (VOs) to return to the client. Flex can then deserialize each VO in the collection into the corresponding VO on the client. VOs are used to create a layer of business objects that can be transferred between tiers, instead of using records, results sets, and datasets. Using VOs also allows stricter typing on the client. This is great when compiling your Flex applications because any references to properties that do not exist, or types that do not correspond, will throw a compiler error. Listing 21-1 shows a representation of a location’s weather forecast in a VO.
Listing 21-1: WeatherVO.as package com.wiley.proflex2.chapter23.vo { import com.adobe.cairngorm.vo.IValueObject; [Bindable] public class WeatherVO implements IValueObject { public var location:String; public var humidity:Number; public var visibility:Number; public var conditions:String; public var code:String; public var temp:String; public var date:String;
534
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 535
Chapter 21: Using the Cairngorm Framework public public public public public public public
var var var var var var var
link:String; sunrise:String; sunset:String; windspeed:String; units:UnitsVO; highTemp:Number; lowTemp:Number;
public function WeatherVO() { units = new UnitsVO(); } } }
Contained inside the WeatherVO is another value object called the UnitsVO, shown in Listing 21-2. This contains all the units for distance, pressure, speed, and temperature. You may find it easier to manage your code by moving some of the properties in one VO into another one, such as in this scenario.
Listing 21-2: UnitsVO.as package com.wiley.proflex2.chapter23.vo { import com.adobe.cairngorm.vo.IValueObject; [Bindable] public class UnitsVO implements IValueObject { public var distance:String; public var pressure:String; public var speed:String; public var temperature:String; } } WeatherVO is simply a set of properties that describes the weather for a specific location. Once the weather data has been downloaded, you set it to an instance of a WeatherVO and store it in the model or state of your application. This means you can access the WeatherVO instance anywhere in your Flex application.
The Model Locator The Model Locator pattern is a singleton and was created purely to be used with Flex application development. In this case, a singleton is a design pattern that allows for only one instance of the Model Locator to be present within your application’s memory. Any data that you think is required to live in the application’s state should be stored inside the Model Locator. The Model Locator creates a central area where all the states can be held in your Flex application. This allows the view components to bind to the model or state of the application and keep everything up to date. Listing 21-3 shows the Model Locator of the Flex Weather application.
535
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 536
Part VI: Advanced Flex 2.0 Listing 21-3: ModelLocator.as package com.wiley.proflex2.chapter23.model { import com.adobe.cairngorm.model.ModelLocator; import com.wiley.proflex2.chapter23.vo.WeatherVO; import mx.events.IndexChangedEvent; [Bindable] public class ModelLocator implements com.adobe.cairngorm.model.ModelLocator { private static var modelLocator:com.wiley.proflex2.chapter23.model .ModelLocator; public static function getInstance():com.wiley.proflex2.chapter23.model .ModelLocator { if (modelLocator == null) modelLocator = new com.wiley.proflex2.chapter23.model .ModelLocator(); return modelLocator; } public function ModelLocator() { if ( com.wiley.proflex2.chapter23.model.ModelLocator.modelLocator != null ) throw new Error( “Only one ModelLocator instance should be instantiated” ); } // Store the location id public var location:String; // The current weather for that location id public var weather:WeatherVO; public var showWeatherDetail:Boolean = false; public var backgroundColor:uint = DAYTIME_COLOR; public const DAYTIME_COLOR:uint = 0x93BCF6; public const NIGHTTIME_COLOR:uint = 0xB6B3C1; } }
While reviewing the code for the Model Locator, you will notice two properties: the locationid property and the weather property (which is an instance of the WeatherVO class). These are stored in the state of the client so that the relevant views can bind to those properties.
536
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 537
Chapter 21: Using the Cairngorm Framework Later on in this chapter, you will see that the WeatherView component requires the current location’s weather forecast so that it can display the details. The weather property in the Model Locator can be passed in to the WeatherView component, as shown here:
The view is updated accordingly because a reference is passed from the weather instance in the Model Locator to the weather instance in the WeatherView component.
The View The view of your application represents the elements that the user sees and interacts with. You will learn how to create and build the view using the Cairngorm Framework. As mentioned earlier, the Model Locator pattern was designed specifically for Flex development. The main reason for its existence is so that you can use the powerful data-binding capabilities of the Flex Framework to update the view of your application. To use binding, you need a source and a destination. The source is the point where the data comes from and the destination is where the data is sent to. The source property has one or many destinations. Any time the source is updated, one or more destinations that are bound to the source are updated by copying the contents of the source to one or many destinations. This is a very powerful capability that most Flex developers cannot live without. The entry point for the Flex Weather application is the Main.mxml file (shown in Listing 21-4), which contains one other component view, WeatherView.mxml (shown in Listing 21-5). The WeatherView.mxml file contains all the components that make up the view of the application.
Listing 21-4: Main.mxml Application { backgroundColor: #000000; } Label { fontFamily: Arial; fontSize: 11; }
537
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 538
Part VI: Advanced Flex 2.0 Button, ComboBox { highlightAlphas: 0.37, 0.73; fillAlphas: 0.6, 0.53, 0.88, 0.63; borderColor: #EEEEEE; themeColor: #0099cc; cornerRadius: 3; } LinkButton { color: #FFFFFF; borderStyle: solid; borderColor: #FFFFFF; } @font-face { src: url(assets/fonts/arial_fonts.swf); fontFamily: Arial; } @font-face { src: url(assets/fonts/arial_fonts.swf); fontFamily: Arial; fontWeight: bold; }
Listing 21-5: WeatherView.mxml
539
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 540
Part VI: Advanced Flex 2.0
In the WeatherView.mxml file, you can view the implementation of the component. As you can see, a lot of Flex visual components are bound to the properties of the weather instance. Any changes to the weather instances held in the Model Locator cause the binding to execute in the instance, updating the weather property of the WeatherView component. Cairngorm ensures that dynamic data displayed in MXML comes from the Model Locator and nowhere else. The Main.mxml file contains the tag, which is the entry point for all Flex applications. The styles for the application are defined inline within the tag. Also contained here are the Service Locator and Front Controller, which are discussed in the next few sections. They are defined here so that the compiler includes them in the application. Otherwise, the Cairngorm Framework would not be able to access them.
540
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 541
Chapter 21: Using the Cairngorm Framework
The Front Controller, Cairngorm Event Broadcaster, and Command Patterns In this section, you learn about the design patterns Cairngorm uses to listen to user actions and convert those into something meaningful to the user of the application. You will also come across the most important and innovative patterns in the Cairngorm Framework. The Front Controller, Cairngorm Event Broadcaster, and Command patterns work together to help you develop consistent RIAs using Flex.
The Command Class In the Flex Weather application, you have one feature: retrieving the weather by location. This feature gets executed once the user has filled in the location and clicks the button to retrieve the weather by location. For every feature or use case in your application, a corresponding custom command and event must be created. Each command contains an execute() method that is run by the framework when the user action has been executed. These classes are occasionally referred to as worker classes because they carry out the work for an application. Consider the only feature in the Flex Weather application: being able to retrieve weather for a specific location. To implement this feature, you create a Command class called GetWeatherByLocationCommand. Listing 21-6 shows the GetWeatherByLocationCommand.as file.
Listing 21-6: GetWeatherByLocationCommand.as package com.wiley.proflex2.chapter23.commands { import com.adobe.cairngorm.commands.ICommand; import mx.rpc.IResponder; import com.adobe.cairngorm.control.CairngormEvent; import com.wiley.proflex2.chapter23.business.WeatherDelegate; import com.wiley.proflex2.chapter23.events.GetWeatherByLocationEvent; import mx.utils.ObjectUtil; import mx.controls.Alert; import com.wiley.proflex2.chapter23.model.ModelLocator; import com.wiley.proflex2.chapter23.vo.WeatherVO; public class GetWeatherByLocationCommand implements ICommand, IResponder { public function execute( event : CairngormEvent ) : void { var delegate : WeatherDelegate = new WeatherDelegate( this ); var initialEvent : GetWeatherByLocationEvent = GetWeatherByLocationEvent( event ); delegate.getWeatherByLocation(initialEvent.locationId, initialEvent.unit); }
541
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 542
Part VI: Advanced Flex 2.0 //------------------------------------------------------------------------public function result( event : Object ) : void { trace(ObjectUtil.toString(event.result.rss.channel)); var item:Object = event.result.rss.channel; var weather:WeatherVO = new WeatherVO(); weather.location = item.title; weather.sunrise = item.astronomy.sunrise; weather.sunset = item.astronomy.sunset; weather.link = item.link; weather.conditions = item.item.condition.text; weather.date = item.item.condition.date; weather.code = item.item.condition.code; weather.temp = item.item.condition.temp; weather.humidity = item.atmosphere.humidity; weather.visibility = item.atmosphere.visibility; weather.windspeed = item.wind.speed; weather.units.distance = item.units.distance; weather.units.pressure = item.units.pressure; weather.units.speed = item.units.speed; weather.units.temperature = item.units.temperature; weather.highTemp = item.item.forecast[0].high; weather.lowTemp = item.item.forecast[0].low; model.weather = weather; model.showWeatherDetail = true;
} //------------------------------------------------------------------------public function fault( event : Object ) : void { Alert.show(event.fault); } [Bindable] public var model:ModelLocator = ModelLocator.getInstance(); } }
As you can see, the GetWeatherByLocationCommand class implements the ICommand and IResponder interfaces. The ICommand interface means that any class that implements this interface must contain an execute() method to act as an entry point, which allows Cairngorm to execute each and every command. In the execute() method, an instance of the WeatherDelegate class is created and the initialEvent instance is cast from a CairngormEvent to type GetWeatherByLocationEvent. The WeatherDelegate class is a business delegate that creates a mapping between the client and server side. In other words, it is an API that maps to the server-side methods of your application.
542
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 543
Chapter 21: Using the Cairngorm Framework The GetWeatherByLocationEvent class extends the CairngormEvent class. The CairngormEvent is a base event class that developers are encouraged to extend to create application-specific events. Each execute() in a command takes a CairngormEvent as a parameter, which you can then cast to your custom-implemented event. Every time you create a command, a corresponding event must be created. The events broadcast using the Cairngorm Event Dispatcher. Listing 21-7 shows the implementation of the GetWeatherByLocationEvent.as.
Listing 21-7: GetWeatherByLocationEvent.as package com.wiley.proflex2.chapter23.events { import com.adobe.cairngorm.control.CairngormEvent; import com.wiley.proflex2.chapter23.control.ApplicationController; public class GetWeatherByLocationEvent extends CairngormEvent { public function GetWeatherByLocationEvent(locationId:String, unit:String) { super( ApplicationController.EVENT_GET_WEATHER ); this.locationId = locationId; this.unit = unit; } public var locationId : String; public var unit : String; } }
The GetWeatherByLocationEvent class contains two properties: locationid and unit. When the event is broadcast, there are two values that must be passed into the constructor of the GetWeatherByLocationEvent. These values are critical in returning the correct weather data to your Flex application. The following example shows this:
Now, let’s go back to the rest of the implementation of the execute() method. The getWeatherByLocation() method of the WeatherDelegate is called and requires two parameters, locationid and unit. These are passed in via the initialEvent instance, which is of type GetWeatherByLocationEvent. The result() and fault() methods are part of the IResponder interface. These methods wait for the asynchronous call to return results from the server. The result() method handles the results if the call was successful, and the fault() method handles the results if they were not successful.
The Front Controller The Front Controller is a central place where all the commands are mapped to the relevant events. Once an event is dispatched, the Front Controller finds the corresponding command to execute. Listing 21-8 shows the Front Controller pattern in the Flex Weather application.
543
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 544
Part VI: Advanced Flex 2.0 Listing 21-8: ApplicationController.as package com.wiley.proflex2.chapter23.control { import com.adobe.cairngorm.control.FrontController; import com.wiley.proflex2.chapter23.commands.*; public class ApplicationController extends FrontController { public function ApplicationController() { addCommand( ApplicationController.EVENT_GET_WEATHER_BY_LOCATION, GetWeatherByLocationCommand ); } public static const EVENT_GET_WEATHER_BY_LOCATION : String = “getWeatherByLocation”; } }
First, all the events are named as constants on the ApplicationController instance. This means the compiler can catch any mistyped events at compile time rather than at run-time. In the constructor, the command class is added to the list of commands. In a larger application, there will be many more of these commands. It is important to ensure that they are all added when the Front Controller is first created by adding them in the constructor. The addcommand() method takes the event name as type string and the name of the command of type string: addCommand( ApplicationController.EVENT_GET_WEATHER_BY_LOCATION, GetWeatherByLocationCommand );
You may have noticed that the ApplicationController extends FrontController. This is so that you can create a FrontController specifically for your application’s needs. By extending the FrontController, you have access to the addCommand() method of its superclass. This allows you register events with their corresponding command classes. You create your controller in the base file of your application. In this example, it is the main.mxml file between the tag, as follows:
This means that your application has a Front Controller that responds to events and invokes all the commands that you registered with the addCommand() method.
Cairngorm Event Dispatcher Cairngorm provides a singleton Cairngorm Event Dispatcher that works with the Front Controller class. Whenever you want to dispatch Cairngorm events, you use the Cairngorm Event Dispatcher.
544
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 545
Chapter 21: Using the Cairngorm Framework The following code shows how to broadcast a Cairngorm event using the Cairngorm Event Dispatcher: CairngormEventDispatcher.getInstance().dispatchEvent(new GetWeatherByLocationEvent (locationId.text, units.selectedItem.data))
The dispatchEvent() method of the Cairngorm Event Dispatcher singleton takes a parameter of type flash.events.Event. This event is dispatched and the corresponding command is executed. This is how the Front Controller, Cairngorm Event Dispatcher, Command patterns, and Cairngorm Events work together with the Cairngorm Event, the Model Locator, and VO patterns to create an immersive experience for the user of an RIA.
Business Delegate and Service Locator This is the last part of the Cairngorm Framework that allows the functionality to connect between the client and the server side.
Flex RPC Services In Chapter 11, you learned about RPC services and the three RPC components that come with Flex — the HTTP service, the Web service, and Remote object components. You will find that as your applications get bigger, the calls to these services will increase. With the Cairngorm Framework, you can call a mixture of all these services. To accomplish this, Cairngorm offers the Service Locator, where you can accommodate all the three services.
Service Locator The Service Locator contains all the services that are required by your RIA in one central place. This is great because you can reuse them throughout your application. By using the Service Locator, you don’t need to know which service you are using to retrieve the results from a remote server. In essence, the Service Locator hides all the implementation of the services from the developer, so they can all be treated the same. The Service Locator is a singleton for service access, and you typically extend the base class in MXML, as the following example shows:
As you can see, there is a weather service that fetches the weather for a specific location. It is an instance of an HTTP service, which contains a URL to Yahoo’s servers. If you were using Flex Data Services, you
545
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 546
Part VI: Advanced Flex 2.0 could define the destination in the services-config.xml file and hide the implementation in the Flex application from a hacker. You would need to replace the url property with the destination property.
Business Delegate The Business Delegate delegates all the responsibility for the business logic that must locate a service, and then invokes a method on the service. In the Flex Weather application, there is one Business Delegate called WeatherDelegate. You can have as many delegates as you think appropriate, probably one for each service. Listing 21-9 shows the WeatherDelegate.as.
Listing 21-9: WeatherDelegate.as package com.wiley.proflex2.chapter23.business { import com.adobe.cairngorm.business.ServiceLocator; import mx.utils.ObjectUtil; import mx.rpc.IResponder; public class WeatherDelegate { public function WeatherDelegate( responder : IResponder ) { this.service = ServiceLocator.getInstance().getHTTPService ( “weatherService” ); this.responder = responder; } public function getWeatherByLocation(locationId:String, unit:String): void { var call : Object = service.send({p: locationId, u: unit}); call.addResponder(responder); } private var responder:IResponder; private var service:Object; } }
If you remember, the GetWeatherByLocation class calls the getWeather() method in its execute() method: public function execute( event : CairngormEvent ) : void { var delegate : WeatherDelegate = new WeatherDelegate( this ); var initialEvent : GetWeatherByLocationEvent = GetWeatherByLocationEvent( event ); delegate.getWeather(initialEvent.locationId, initialEvent.unit); }
546
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 547
Chapter 21: Using the Cairngorm Framework These two classes work together in the following way. The Command class creates an instance of the Weather Delegate passing itself (this) to the constructor of the delegate. The Command class then takes responsibility as the responder and, as such, implements the IResponder interface in the Flex Framework. This ensures that the developer adds the result() method and fault() method. Take a look at the result() method of the GetWeatherByLocation. It extracts the values from the XML object and sets them into a WeatherVO value object. That instance of the WeatherVO is set to the Model Locator’s weather instance.
Summar y This chapter has discussed all the design patterns that contribute to the Cairngorm Framework. Cairngorm is lightweight and makes it easier for developers to create large-scale applications and scale them accordingly. Adobe Consulting is always refining the Cairngorm Framework and will be supporting it as long as Adobe Flex is still around. If you need any support regarding Cairngorm, visit the FlexCoders mailing list (http://tech.groups .yahoo.com/group/flexcoders/). The Cairngorm Committee is a regular contributor, and many Flex developers are now familiar with the framework. So you should find answers to your questions regarding the Cairngorm Framework. Chapter 22 discusses the Flex-Ajax Bridge and describes how to integrate HTML applications with Flex applications. In essence, it shows how to communicate back and forth using JavaScript.
547
02671c21.qxd:02671c21
4/20/07
2:25 PM
Page 548
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 549
Using the Flex-Ajax Bridge The release of Flash Player 9 included a new External API using a class file called the ExternalInterface that allows for the communication between JavaScript and Flash applications. To create the communication link and pass data between JavaScript and Flex, the developer must create custom code to handle each call. You can see examples of this covered in the “Communicating with the Wrapper” section of Chapter 8. The Flex-Ajax Bridge has simplified the usage of this API. By simply including the necessary classes, the bridge exposes all of the classes within the Flex application to JavaScript. It will also allow you to create almost anything in your Flex application using JavaScript instead of ActionScript.
Why Use Flex with JavaScript? Following is a short list of the many reasons why Flex and JavaScript are a good fit with each other: ❑
Combining the built-in (as well as custom) classes of Flex, and also the large collection of JavaScript libraries, creates a very complete collection of source code.
❑
The Flex-Ajax Bridge allows existing JavaScript developers the ability to create Flex content using the syntax they are accustomed to.
❑
Creating a hybrid application is now easier than ever. Because all of the Flex classes are now accessible through JavaScript, you can script the creation Flex components in real time.
❑
Flex has an excellent set of rich components that can now easily be included within your HTML application.
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 550
Part VI: Advanced Flex 2.0
Requirements for the FA Bridge You can download the Flex-Ajax Bridge from the Adobe Labs site located at http://labs.adobe.com/ wiki/index.php/Flex_Framework:FABridge. The download includes all of the necessary files, as well as a sample application. When using the Flex-Ajax Bridge, there are a few requirements. After unpacking the download, you will find a folder named bridge that should be included within the root of your application. Within this folder, there is a single ActionScript file named FABridge.as, which must be instantiated in your Flex application. If you have defined the namespace (xmlns:bridge=”bridge.*”) within the mx:Application tag, you can choose to instantiate the FABridge using the following standard syntax:
Or you can do it all in one line, using the following syntax:
That is all that is needed on the Flex side. On the JavaScript side, there are additional requirements. You will first need to include a JavaScript file named FABridge.as that is included within the bridge folder. Simply add a JavaScript include to the HTML page that will be including your SWF. Here is the syntax for the JavaScript include:
Next, you will need to include a few additional parameters to the script and noscript code blocks used to include the SWF in your HTML page. The flashvars property named bridgeName must be included in two places, as in Listing 22-1. You can name the bridge whatever you want because it will be used as an ID when making calls to the SWF file. In Listing 22-1, the bridgeName is set to myBridge.
Listing 22-1: Including the SWF in the HTML Page
550
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 551
Chapter 22: Using the Flex-Ajax Bridge
Using the flashvar named myBridge as shown in Listing 22-1 will allow you to access the content of the SWF using FABridge.myBridge.root(). For additional information on using the bridgeName, please see the examples at the end of this chapter.
Memor y-Consumption Issues As of this writing, there are some memory-consumption issues that may evolve because of the limitations in the integration between the JavaScript and ActionScript garbage collectors. Once an ActionScript object has been accessed from JavaScript, it will remain in memory. To release the objects from memory, you can call FABridge..releaseASObjects(). This will cause all references to be invalid and will free up the memory. Adobe has stated that it hopes to make the bridge more efficient and will only cache the objects throughout the life of each call.
Flex-Ajax Bridge Samples The following examples show two different uses of the Flex-Ajax Bridge. The first uses the Flex Validator classes to validate an HTML form. The second example is a simple one showing how to create Flex components using JavaScript.
Using Flex Validators from JavaScript Flex has a great set of data validators that are very simple to use and have custom error messages predefined. Listing 22-2 shows how you can take advantage of these validators within your HTML form validation. The source code in Listing 22-3 shows both the HTML wrapper file and the Flex root application file that is loaded into the wrapper.
551
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 552
Part VI: Advanced Flex 2.0 Listing 22-2: ValidateSample.html — the HTML Wrapper File Flex Bridge Validate Example body { margin: 0px; overflow: hidden }
| e-mail Address: | |
| Telephone Number: | |
|
552
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 553
Chapter 22: Using the Flex-Ajax Bridge
553
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 554
Part VI: Advanced Flex 2.0 Listing 22-3: Validate.mxml — the Source for the Validation SWF Library
The Validate.mxml file in Listing 22-3 includes two functions to validate both a phone number and an e-mail address, and it also instantiates the Flex-Ajax Bridge. The HTML wrapper file includes the necessary JavaScript files, as well as the validation SWF. The bridgeName is defined as flexValidate within a Flash variable. The HTML form validates the form fields on submission of the form by calling the checkForm JavaScript function. This function then make calls to the validateEmail and validatePhone functions that are part of the embedded Validate SWF. These two calls are made by creating a local JavaScript variable to hold the ActionScript that will be run using the JavaScript eval function. An example of the syntax to make the call looks like this: ‘with (FABridge.flexValidate.root()) getMessage( validateEmail(email) )’
554
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 555
Chapter 22: Using the Flex-Ajax Bridge The call is made using the with keyword to set the scope, and then setting a JavaScript handler function to interpret the results. The scope is set to the root of the SWF using FABridge..root(). The getMessage function interprets the results of the Flex validators and then builds the errors string, which is returned to the checkForm function. The results are shown in Figure 22-1. There are many additional Flex validators (as well as formatters) that could be added to the Validate SWF, creating a full library of functions that can be used within your HTML forms.
Figure 22-1: A JavaScript alert showing the Flex validation messages
Create Flex Components Using JavaScript The Flex-Ajax Bridge also provides the ability to create Flex components at run-time from JavaScript. You can create any base component by simply setting up an empty SWF as a Flex-Ajax Bridge, or any other component, as long as you have imported the necessary classes. Listing 22-4 and Listing 22-5 show basically an empty SWF with only a panel to hold the created content and the setup of the FA Bridge.
Listing 22-4: Component.mxml
Listing 22-5: CreateComponent.html Flex Bridge Create Component Example body { margin: 0px; overflow:hidden }
| Button Label: | |
| Button Width: | |
| Button Height: | |
|
| Code sent to Flex |
|
The JavaScript function createButton is executed when the form button is clicked. This function accepts a form object and builds the ActionScript needed to create a Flex Button. It also sets the Button label, width, and height properties by filling in the form values. Notice that the last line of the newButton string says panel().addChild(btn). The panel() is not actually a Flex function. It is the syntax that is used to access a component within the embedded SWF. The ID of the Panel that the button is being added to is actually named panel, but when accessing it from JavaScript, the parentheses are required. Once the ActionScript String has been created, the JavaScript eval function is run, which creates the button within the embedded SWF. Figure 22-2 shows the page when it loads, and Figure 22-3 shows the page after the createButton method has been run. Figure 22-3 also shows the JavaScript that was created and passed to Flex.
Figure 22-2: Page when it loads
558
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 559
Chapter 22: Using the Flex-Ajax Bridge
Figure 22-3: Page after the createButton method has been run
Summar y The Flex-Ajax Bridge will find its way into the development of Web 2.0 applications because it ties the two leading RIA solutions together into a new hybrid application with hundreds of JavaScript and Flex code libraries. This chapter provided an overview of why you would use the Flex-Ajax Bridge, requirements, and installation, as well as demonstrations of how the FA Bridge can be used in different ways. Information on possible memory issues was provided as well. Chapter 23 discusses the ActionScript libraries that are freely available from Adobe Labs. Descriptions are included for all of the available libraries, as well as a fully functioning example showing the YouTube library.
559
02671c22.qxd:02671c22
4/20/07
2:27 PM
Page 560
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 561
Using the ActionScript 3.0 Libraries The ActionScript 3.0 libraries are a free set of libraries that Adobe’s Developer Relations Team has released to the public. These libraries help developers get started when building Flex 2.0 applications. The libraries are split up into seven separate projects with their own distinctive functionalities. The libraries are available on Adobe Labs, which is a Web site that provides you with the opportunity to experience and evaluate new and emerging technologies and products from Adobe. At Adobe Labs, you have access to resources such as the following: ❑
Prerelease software and technologies
❑
Code samples
❑
Early versions of products and documentation
❑
Forums and wiki-based content to help you interact with like-minded developers
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 562
Part VI: Advanced Flex 2.0
Types of Libraries The following is list of libraries that have been updated to work with the final release of Flex Builder 2.0 and MXMLC. Note that these libraries are of beta quality and that Adobe does not officially support them. ❑
Corelib — The Corelib library consists of several basic utilities for MD5 hashing, JavaScript Object Notation (JSON) serialization, advanced string and date parsing, and more. Authors of this project are Christian Cantrell, Mike Chambers, Daniel Dura, and Darren Schall.
❑
FlexUnit — The FlexUnit library is a unit testing framework for Flex and ActionScript 3.0 applications. It copies the functionality of JUnit (a Java unit-testing framework), and includes a graphical test runner application built in Flex 2.0. Authors of the project are Matt Chotin, Daniel Dura, Alistair Mc Lead, Tom Ruggles, Steven Webster, and Jason Williams. All projects use the FlexUnit framework to test the libraries and ensure that they are working correctly.
❑
Flickr — The Flickr library is an ActionScript 3.0 API for use with the popular online photo-sharing Web application, Flickr. This library provides access to the entire Flickr API. The author of this project is Darren Schall.
❑
Mappr — The Mappr library is an ActionScript 3.0 API that provides access to Mappr’s geo-tagged image data. Mappr is a service that combines images from Flickr with geographically located information. The author of this project is Mike Chambers.
❑
RSS and Atom — The RSS and Atom libraries are used to parse Atom and all versions of RSS easily. You can parse any type of feed without knowing what kind of feed it is. The author of this project is Christian Cantrell.
❑
Odeo — The Odeo library is an ActionScript 3.0 API for searching and retrieving podcasts from Odeo. Odeo is a service that provides functionality to listen to, upload, and record your own podcasts. The author of this project is Mike Chambers.
❑
YouTube — The YouTube API provides an ActionScript 3.0 API to search for videos from YouTube. The author of this project is Daniel Dura.
How to Include the SWC in Your Application To include the SWC in your application, you must first download a library, such as the Corelib library that is used here for reference. Open the ZIP file and you will find three folders inside the corelib folder: bin, docs, and src. The bin folder contains the binary SWC file for use within your application. Be sure you know from where you extracted the files, and make a note as to where the binary SWC is. Open up Flex Builder 2 and select File ➪ Flex Project to see the screen shown in Figure 23-1. Follow the wizard and create a Flex project with a name and path, as shown in Figure 23-2. Then, click Next.
562
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 563
Chapter 23: Using the ActionScript 3.0 Libraries
Figure 23-1: New Flex Project opening screen
Figure 23-2: Assigning a name and path
As shown in Figure 23-3, you can either change the Main application file to whatever you like, or leave it as is. Select the Library Path tab and click the Add SWC button (Figure 23-4). Locate the binary SWC file in the bin directory of the unzipped Corelib library on your hard disk. You should see that it has been added to the build path libraries tree. Click the Finish button and you should be ready to use the Corelib library in your Flex application.
563
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 564
Part VI: Advanced Flex 2.0
Figure 23-3: Set build paths
Figure 23-4: Add SWC button
564
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 565
Chapter 23: Using the ActionScript 3.0 Libraries
Building a Simple Application Using One of the Libraries In Chapter 21 you learned how to build an application in the Cairngorm Framework. This example uses the Cairngorm Framework and the YouTube ActionScript 3 library. Figure 23-5 shows the completed application running in Flex.
Figure 23-5: Completed application
Listings 23-1 through 23-8 show the files that make up the application structured using the Cairngorm Framework. The only difference is that there is no Server Locator or any Business Delegates.
Listing 23-1: Main.mxml Application { backgroundColor: #888888; } Label { fontFamily: Arial; fontSize: 11; } Button, ComboBox { highlightAlphas: 0.37, 0.73; fillAlphas: 0.6, 0.53, 0.88, 0.63; borderColor: #EEEEEE; themeColor: #0099cc; cornerRadius: 3; } @font-face { src: url(assets/fonts/arial_fonts.swf); fontFamily: Arial; } @font-face { src: url(assets/fonts/arial_fonts.swf); fontFamily: Arial; fontWeight: bold; }
566
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 567
Chapter 23: Using the ActionScript 3.0 Libraries
Listing 23-2: GetVideosByTagCommand.as package com.wiley.proflex2.chapter25.commands { import mx.rpc.IResponder; import mx.utils.ObjectUtil; import mx.controls.Alert; import com.adobe.cairngorm.control.CairngormEvent; import com.adobe.cairngorm.commands.ICommand; import com.adobe.webapis.youtube.YouTubeService; import com.adobe.webapis.youtube.methodgroups.Videos; import com.adobe.webapis.youtube.events.YouTubeServiceEvent; import com.wiley.proflex2.chapter25.events.GetVideosByTagEvent; import com.wiley.proflex2.chapter25.model.DataModel;
public class GetVideosByTagCommand implements ICommand { public function execute( event : CairngormEvent ) : void { var youTubeService:YouTubeService = new YouTubeService(); youTubeService.apiKey = model.API_KEY; youTubeService.addEventListener(YouTubeServiceEvent .VIDEOS_LIST_BY_TAG, result); var videos:Videos = new Videos(youTubeService); videos.listByTag(GetVideosByTagEvent(event).tag); } //------------------------------------------------------------------------public function result( event : YouTubeServiceEvent ) : void { model.videos.source = event.data.videoList; } //------------------------------------------------------------------------public function fault( event : Object ) : void { Alert.show(event.fault); } [Bindable] public var model:DataModel = DataModel.getInstance(); } }
567
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 568
Part VI: Advanced Flex 2.0 Listing 23-3: ApplicationController.mxml package com.wiley.proflex2.chapter25.control { import com.adobe.cairngorm.control.FrontController; import com.wiley.proflex2.chapter25.commands.*; public class ApplicationController extends FrontController { public function ApplicationController() { addCommand( ApplicationController.EVENT_GET_VIDEOS_BY_TAG, GetVideosByTagCommand ); } public static const EVENT_GET_VIDEOS_BY_TAG : String = “getVideosByTag”; } }
Listing 23-4: GetVideosByTagEvent.as package com.wiley.proflex2.chapter25.events { import com.adobe.cairngorm.control.CairngormEvent; import com.wiley.proflex2.chapter25.control.ApplicationController; public class GetVideosByTagEvent extends CairngormEvent { public function GetVideosByTagEvent(tag:String) { super( ApplicationController.EVENT_GET_VIDEOS_BY_TAG ); this.tag = tag; } public var tag : String; } }
Listing 23-5: DataModel.as package com.wiley.proflex2.chapter25.model { import com.adobe.cairngorm.model.DataModel; import mx.collections.ArrayCollection; import com.adobe.webapis.youtube.Video; [Bindable] public class DataModel implements com.adobe.cairngorm.model.DataModel { private static var dataModel:com.wiley.proflex2.chapter25.model.DataModel; public static function getInstance():com.wiley.proflex2.chapter25 .model.DataModel
568
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 569
Chapter 23: Using the ActionScript 3.0 Libraries { if (dataModel == null) dataModel = new com.wiley.proflex2.chapter25.model.DataModel(); return dataModel; } public function DataModel() { if ( com.wiley.proflex2.chapter25.model.DataModel.dataModel != null ) throw new Error( “Only one DataModel instance should be instantiated” ); initCollections(); } private function initCollections():void { videos = new ArrayCollection(); } // The list of videos public var videos:ArrayCollection; public var videoId:String; public const API_KEY:String = “YOUR-YOUTUBE-API-KEY”; } }
Listing 23-6: SearchForm.mxml
569
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 570
Part VI: Advanced Flex 2.0 Listing 23-7: VideoListView.mxml
Listing 23-8: VideoPlayer.mxml
570
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 571
Chapter 23: Using the ActionScript 3.0 Libraries
Summar y The YouTube application built in this chapter shows how you can easily integrate Cairngorm and other Open Source libraries. The YouTube library added functionality to the application so that you can search for the latest videos on YouTube by tag. Integration with rich media was also very easy because the Flex Framework provides all the components and libraries required to do this. Chapter 24 examines how newer versions of ColdFusion and Flash Remoting can be used to share structured data.
571
02671c23.qxd:02671c23
4/20/07
2:29 PM
Page 572
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 573
Using ColdFusion/Flex Connectivity The combination of Flex 2 and ActionScript means new standards. The Flash Player’s ability to connect and share structured data with ColdFusion predates Flex, with the introduction of Flash Remoting in 2002. ColdFusion 7 introduced event gateways that allowed ColdFusion to communicate in ways that went beyond what the browser has to offer: talking Short Message Service (SMS), instant messaging, and interacting with Java Messaging Services (JMS). ColdFusion 7.0.2 was released at the same time as Flex 2. It introduced a new version of Flash Remoting that featured a new standard, Action Messaging Format version 3 (AMF3), which offers compatibility with ActionScript 3 and support for new data types. ColdFusion 7.0.2 also included the Flex Messaging Event Gateway, which allows ColdFusion applications to send and receive messages with Flex Data Services (FDS). Flex Builder 2 is new from the ground up, built on top of Eclipse. It doesn’t support ColdFusion directly, but has included with it a number of wizards and plugins bundled together as the ColdFusion Extensions for Flex Builder. These offer secure connectivity to the ColdFusion server for data maintenance, file management, and query building.
Using the Flash Remoting Update Flash Remoting has been available to developers since 2002 with the release of ColdFusion 6 and JRun 4. It allows the Flash Player and the ColdFusion server to communicate with each other, sending data in both directions using Action Messaging Format (AMF), a protocol developed by Macromedia (now Adobe). One of the great advantages of Flash Remoting is the ease of communication between Flex and ColdFusion. The original structure of data is preserved during that communication, converted by
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 574
Part VI: Advanced Flex 2.0 a Flash Remoting API on the client side and automatically handled by ColdFusion on the server side. AMF translates between ColdFusion and ActionScript native data types in both directions automatically. The data’s structure is represented using an XML schema inspired by the Simple Object Access Protocol (SOAP). It is transported via HTTP as a binary file to improve the packet size for transmission (offering packets up to 75 percent smaller than SOAP packets with equivalent data). The ColdFusion 7.0.2 Flash Remoting Updater is available as an update installer for ColdFusion, or you can download the latest release of ColdFusion (version 7.0.2). Updating to 7.0.2 means that you have a version of Flash Remoting that can talk to applications via AMF3, the latest version of AMF (required for Flex 2 applications). AMF3 makes use of ActionScript 3.0, sending data more efficiently over a network connection than its predecessor, and supporting new data types introduced with ActionScript 3.0 (ByteArray and XML, for example). Following are third-party plugins for other application servers that also offer Flash Remoting: ❑
AMFPHP (http://www.amfphp.org/) — This is a free community project that currently only supports the original AMF0 protocol, meaning that you are unable to take advantage of ActionScript 3 features.
❑
FLUORINE (http://fluorine.thesilentgroup.com/) — This is an Open Source .NET Remoting gateway that supports AMF3.
❑
WebOrb (http://www.themidnightcoders.com/weborb/) — This is also a gateway for .NET, the commercial version of which supports AMF3.
The ColdFusion server is configured for Flash Remoting via an XML file, services-config.xml. This is located in {ColdFusion webroot}\WEB-INF\flex\. Flex Builder uses project properties to dynamically fill a number of variables in the configuration file (such as the location of the ColdFusion server). A new feature of ColdFusion 7.0.2 is a separate panel in the ColdFusion Administrator for managing Flex integration. Looking under the Data & Services category of tools, you will find that it offers control for both Flash Remoting and FDS support. These two options are switched on by default. It’s important to select the right kind of Flex project in Flex Builder 2 for your ColdFusion Flash Remoting application. There are additional settings for Flash Remoting, including additional compiler arguments that point to services-config.xml on the ColdFusion server. Follow these steps to create a new Flex Builder project that will be deployed on ColdFusion:
1. 2. 3. 4. 5.
Choose File ➪ New ➪ Flex Project. Choose ColdFusion Flash Remoting Service (Figure 24-1). Enter the root folder and root URL of the ColdFusion server. Enter a project name and the root folder of the ColdFusion server. Select the output folder that will be used by the ColdFusion server.
If you check the properties of a ColdFusion-based project after it’s been created, you can see that an argument locating the services-config.xml file has been added to the compiler settings, as shown in Figure 24-2.
574
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 575
Chapter 24: Using ColdFusion/Flex Connectivity
Figure 24-1: ColdFusion Flash Remoting Service option
Figure 24-2: The additional compiler arguments for ColdFusion Flash Remoting
You should be familiar with the RemoteObject component, discussed in Chapter 11. The RemoteObject component is used to access ColdFusion via Flash Remoting. Set the RemoteObject component’s destination attribute to ColdFusion, and the source attribute to the location of the ColdFusion Component (CFC) that you’re accessing for data.
575
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 576
Part VI: Advanced Flex 2.0 The location of the CFC is called in the same way that you would invoke the CFC within your ColdFusion Markup Language (CFML). You locate it by its position under the server Web root. Use dot notation instead of slashes to indicate the directory structure, and omit the extension at the end. The following example code is calling a CFC called FlexData.cfc located in the directory {Web root}/ components/data. This directory can be either physically under the Web root, or a Web server virtual directory. The important thing to note is that to the server, the directory resides under the Web root.
The server’s XML configuration file can be edited to include the location of a CFC as a mapping, or named resource. The named resource entry has the location of the CFC and the name for the mapping. Following is an example of an entry for the CFC called in the preceding example of the RemoteObject component: components.data.FlexData true
This mapping is then used as the value for the destination argument of the RemoteObject component. You would also omit the source argument of the component call because its value is defined in the named resource.
The RemoteObject components must be called by an event (either system- or user-generated). In this case, use the creationComplete event of the Application tag to fetch data from a CFC for the application once it’s ready to run:
576
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 577
Chapter 24: Using ColdFusion/Flex Connectivity The results handler is a function that you will build to handle the results returned by the CFC. How you construct that will depend on your business requirements. It should receive one argument data typed as ResultEvent. You will need to import the ResultEvent class to handle the result.
The handler in the preceding example code will accept the response from the RemoteObject component call and access the result property of the object that’s called. This example receives a string value. Notice that the value has been data typed as String to ensure that it’s compatible with the Label component’s attribute that it’s being assigned to. Following is the complete code for the MXML file:
source= fault=
The CFC being used for this example is quite simple. The following example has a single function that returns a string variable. What’s needed to make this work for Flash Remoting is to set the access property of the CFFunction tag to “remote”, as shown here:
577
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 578
Part VI: Advanced Flex 2.0
ColdFusion will send data to Flex preserved in its original structure, with the exception of queries. There’s no equivalent native data type to query in Flash. The previous version of Flash Remoting basically had a hack to process a query into an array of untyped objects, which Flash could then understand. This meant that data conversion had to occur on the client side as it was received, resulting in performance problems with large record sets of data. The solution to this problem is the introduction of the ArrayCollection, a new data type analogous to an array of objects. ColdFusion 7.0.2 will handle the conversion of queries to ArrayCollections and reverse as it transmits data backward and forward via Flash Remoting. The following example code calls a method on a CFC that returns a query, converted by Flash Remoting into an ArrayCollection:
Notice that the ArrayCollection class has been imported and a bindable variable has been created to store the result, data typing it as an ArrayCollection. In the result handler method, the variable has been set to the result, again casting it to ArrayCollection to ensure that it’s the proper data type. For now, the data is being bound as the dataProvider property of a DataGrid component so as to dump it temporarily while performing the development work.
578
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 579
Chapter 24: Using ColdFusion/Flex Connectivity Following is an example of the CFC for this data: SELECT * from employees
The RemoteObject tag can be modified so that you can call multiple methods on the CFC. This is done by nesting method tags containing the details of each method on the CFC that you will connect to.
Notice that there are two methods in this example, each with a different result handler. You will call them on an event in exactly the same way as previously described. Data can be passed to the CFC as part of the call so that you can do things such as handling form submission or doing parameterized searching. Multiple values can be passed as a comma-separated list: myService.insertEmployee(fname,lname,email);
The argument could instead be passed as a complex object. The following sample code takes the values from a form, makes them properties of a value object (VO), and passes that object as an argument in the last line of the function:
579
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 580
Part VI: Advanced Flex 2.0 Following is the class for the VO used in the preceding example code. The VO allows you to data-type the properties of the structured data that you are passing back to the CFC via Flash Remoting. package { [Bindable] public class EmployeeVO { public var fname:String = “”; public var lname:String = “”; public var email:String = “”; public var mobilePhone:String = “”; public var department:int = 0; public function EmployeeVO() { } } }
Each of the properties of this object match arguments within the CFC’s method that you are calling. Following is the code for the method: INSERT INTO employees (fname,lname,email,mobilePhone,department) VALUES (“#fname#”,”#lname#”,”#email#”,”#mobilePhone#”,#department#)
You are taking the object that’s passed to the CFC’s method and inserting the values into the database as a new record, returning a Boolean based on whether or not the database activity is a success, using a simple CFTRY/CFCATCH technique for the database activity trapping. Back in the MXML file, you will handle the result of the database with an Alert component to notify you if the action was a success. Following is the complete MXML file. Notice that there are two methods on the CFC that you are calling. The first is called by the creationComplete event of the Application tag, pulling data back from the CFC to populate a ComboBox component in the form. The second result handler is for the Boolean that the insert method on CFC will return. It uses an Alert component to inform you if the insert action was a success.
580
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 581
Chapter 24: Using ColdFusion/Flex Connectivity
581
02671c24.qxd:02671c24
4/20/07
4:00 PM
Page 582
Part VI: Advanced Flex 2.0
Following is the CFC that is being called via Flash Remoting. It has two methods: one that will be used to populate the form’s ComboBox component, and the other to insert a new record in the database using the data from the form. SELECT * from departments INSERT INTO employees (fname,lname,email,mobilePhone,department) VALUES (“#fname#”,”#lname#”,”#email#”,”#mobilePhone#”,#department#)
582
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 583
Chapter 24: Using ColdFusion/Flex Connectivity Although the cftry/cfcatch method of error trapping is simple and effective, you should not implement it until the method is fully tested, because it will suppress database error messages. This makes it a little difficult to debug. Tools available to developers allow for the monitoring and testing of Flash Remoting applications. ServiceCapture (http://kevinlangdon.com/serviceCapture/) is for Windows only, and Charles (http://www.xk72.com/charles/) is a Java-based application that will run on Windows, Mac OS X, and Linux. Both were developed for the monitoring and analysis of Flash Remoting, and do this by capturing and interpreting HTTP traffic on your computer.
Using the Flex Messaging Event Gateway The release of ColdFusion 7 introduced a number of event gateways for going beyond browser protocols. Included with its initial release were gateways for communicating with Short Message Service (SMS), instant messaging, Java Messaging Service (JMS), sockets, and server directory monitoring. ColdFusion 7.0.2 includes a Flex Messaging Event Gateway that allows ColdFusion applications to send and receive messages with FDS. Event gateways are only supported in the ColdFusion Enterprise edition. Flex can use ColdFusion CFCs to send messages as part of a Flex publish-subscribe messaging application. Flex publish-subscribe messaging applications have the following named elements: ❑
Producer — The term given for the file that originates either the message or message request. It’s likely to be the MXML file being viewed. The message would be created here and sent to a destination.
❑
Destination — The destination is the file that is listening for messages on the server.
❑
Consumer — The consumer is the logic (either contained within a page or incorporated into a CFC) that processes any messages sent to it via the producer. It would then respond to the producer via the gateway.
The producer and consumer do their thing by exchanging messages between each other via the destination. Both ColdFusion and Flex are capable of commencing the messaging process, because ColdFusion can broadcast to Flex, or Flex could send a message to ColdFusion. Flex Messaging Event gateways are created on the ColdFusion Administrator. They can be configured to control IP access, specify a separate server machine for FDS, or control access to code while processing a gateway request. This configuration is done either in the calling message, or with the use of a configuration file. The configuration file is in the form of a Java properties file. It will have the following properties: ❑
destination — Allows you to specify a destination. Overrides any destination information within the message.
❑
host — The host name or IP address of the FDS server.
❑
allowedIPs — A comma-delimited list of IP addresses that the gateway is allowed to accept
messages from.
583
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 584
Part VI: Advanced Flex 2.0 Here’s an example of what a configuration file would look like: # # Flex event gateway configuration # # Destination destination=Flex2CF702emailPopApp # Hostname or IP address of the Flex Enterprise Server. host=127.0.0.1:8700 # IP addresses from which the application will accept messages. allowedIPs=198.162.0.2,198.162.0.7
Configuration files are saved to the ColdFusion server in the {CF directory}/gateway/config/ directory with a .cfg extension. There are a number of template configuration files there by default that would be worth having a look at before making your first configuration. FDS must be configured to communicate via the Flex Messaging Event Gateway with ColdFusion. It uses the XML file messaging-config.xml to configure it for all messaging. There is an section in the file to which you add the following to enable communication with ColdFusion:
You can find an example of a messaging-config.xml that includes the ColdFusion definition in FDS at C:\fds2\resources\config\flex. You will need to locate the messaging-config.xml for the Web application that you wish to add the configuration to. Using the samples directory from the standard FDS install as an example Web application, the messaging-config.xml would be found in the directory located at C:\fds2\jrun4\servers\default\samples\WEB-INF\flex. The next step in preparing to work with the Flex Messaging Event Gateway is to add to the messagingconfig.xml file a destination definition for the ColdFusion gateway. The example version of messaging-config.xml mentioned previously has a detailed sample of a ColdFusion Flex Messaging tag to copy from, if required. The definition looks like this: *
Each Web application should have its own unique destination ID. The example being used here creates a destination ID for the Samples Web application. You should assign a different destination ID for the Flex Web application to ensure that ColdFusion doesn’t have two choices. It is possible to create VOs on ColdFusion and transfer objects to Flex via the gateway with the data typing of the various properties of the VO intact. You must include the necessary configuration details
584
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 585
Chapter 24: Using ColdFusion/Flex Connectivity in the services-config.xml file of your Web application. Following is an example of these. You can also find an example in the sample services-config.xml in the C:\fds2\resources\config folder. false true 8
The Structure of Messages The process of using a Flex Messaging gateway passes data between ColdFusion and FDS in a predetermined structure. You must be familiar with the structure and its elements so that you can ensure that data is read and transmitted in the right format. The following elements are required when constructing a structure to send in a message from ColdFusion to FDS via the Flash Gateway: ❑
body — The body of the message (required).
❑
CorrelationID — The Correlation identifier of the message.
❑
Destination — The Flex destination of the message (required if not in the configuration file).
❑
Headers — A CFML structure that contains the header keys and values. Used if the message
contains any containers. ❑
LowercaseKeys — Forces the structure key names to be lowercase when the ActionScript types are created. ActionScript 3 is case-sensitive. This would allow for a constant lowercase to be used.
❑
TimeToLive — The number of milliseconds that the current message is valid.
The messaging gateway will also add on the following additional elements: ❑
MessageID — A Universally Unique Identifier (UUID).
❑
Timestamp — The time that the message was sent.
❑
ClientID — The ID of the Flex Messaging gateway instance (equal to the ColdFusion
session ID).
585
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 586
Part VI: Advanced Flex 2.0 Messages can be sent from CFML to Flex via the Flex Messaging Gateway using one of two methods. The typical way would be to use the cfreturn tag within a CFC function. There is also a SendGatewayMessage function specifically for sending messages via the gateway. The following example creates a ColdFusion structure with two of the keys listed previously (body and Destination) and uses the SendGatewayMessage function to send the values back to FDS:
The data that ColdFusion will receive via the gateway will be structured in a specific structure as well. Its key/value pairs are similar to the outgoing packet and are as follows: ❑
body — The body of the message.
❑
ClientID — The ID of the client that sent the message (equal to the ColdFusion session ID).
❑
CollectionID — The Collection identifier of the message.
❑
Destination — The Flex destination of the message (required if not in the configuration file).
❑
Headers — A CFML structure that contains the header keys and values. Used if the message
contains any containers. ❑
Timestamp — The time that the message was sent.
The gateway will also add on the following: ❑
messageID — A UUID.
❑
timeToLive — The number of milliseconds that the current message is valid.
Armed with the knowledge of how the data will be structured, you can now construct the CFML to process the data that comes through the gateway. Your CFC should have a function called onIncomingMesage. This is the default that will be called by the Flex Messaging Gateway when a message is transmitted to the CFC. The actual structure of the message will be embedded within the data property of an object called event. Your code would be calling the value at event.data.body.username if you needed to access a username property that was passed from the transmitting Flex file. In the following example CFC, you will notice the single argument event in the onIncomingMessage function. The code creates a variable formDetails set equal to event.data.body.
Web applications built with FDS, ColdFusion, and the Flex Messaging Event Gateway can be secured by either restricting IP addresses, or by making use of remote credentials. With a configuration file, you can restrict which IP addresses the ColdFusion server will accept messages from. The configuration file (mentioned previously) allows the administrator to nominate the host and destination addresses, as well as the IP addresses, that messages can be accepted from. Flex has a built-in function to handle user authentication with ColdFusion. Using the setRemoteCredentials method before sending a message through the gateway allows you to transmit values for username and password, allowing ColdFusion to then utilize its cflogin tag within Application.cfm or Application.cfc. Following is an example of the setRemoteCredentials method: var msg:Message = new AsyncMessage(); msg.body = {fname:fname.text,lname:lname.text,email:email.text}; msg.headers.gatewayID = “Flex2CF702”; msg.setRemoteCredentials(myUserName, myPassword);
Using the ColdFusion Event Gateway Adapter FDS has a number of Message Service adapters that provide you with the means to create a publishsubscribe messaging system. FDS has adapters for ActionScript Messaging, JMS Messaging, and ColdFusion. With the ActionScript Messaging adapter, you could have two Flex-based applications communicate with each other (for example, have an order UI communicating directly with the fulfillment UI, both running in different locations on separate clients). The JMS Messaging adapter could be used to build a live stock feed, utilizing Java to fetch the required data, and displaying it in a Flex application either via charting, tabular format, or a combination of both. ColdFusion 7.0.2 includes a Flex Messaging Gateway that you can call from FDS, thus allowing you to build Flex applications that can communicate directly with ColdFusion to produce publish-subscribe messaging applications. ColdFusion 7.0.2 has a number of other gateways, including a directory watcher to monitor changes to a specific directory and its contents on the file system. Another ColdFusion Gateway is an SMS gateway that allows an application to send a text message to a mobile phone. The idea behind this kind of architecture is that a producer (in this chapter’s examples, an MXML file) creates a message and sends it to a destination (the gateway). The destination has a consumer configured that is listening for messages being sent to it, which can respond to the producer via the destination. The producer and consumer exchange messages through the destination.
587
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 588
Part VI: Advanced Flex 2.0 Applications that are built with the two gateways described here are accessed via the MXML file that is deployed on FDS, which, in turn, calls the CFC on the ColdFusion server as required. While ColdFusion’s various gateways can then provide access to a variety of services not available on FDS, the developer should also realize that there is functionality offered by ColdFusion that is not available in FDS itself. Two examples are ColdFusion (being a Java application) accessing Java objects and the numerous tags that ColdFusion has to offer (CFMAIL, for example, can send e-mail via an SMTP server). FDS has a ColdFusion Event Gateway adapter that communicates with ColdFusion’s Flex Messaging Event gateway. An instance of the ColdFusion Event Gateway must be enabled on FDS before you can start communication with any gateway on the ColdFusion server. The messaging-config.xml file holds all the details of the ColdFusion server. It is stored in the WEB-INF\flex directory of your FDS server. If you choose to create a ColdFusion Event Gateway–based application using the samples server provided with FDS, you’d find the file located at C:\fds2\jrun4\servers\default\samples\WEB-INF\flex. Take a look at building an application that exchanges data between FDS and ColdFusion via the two gateways. This application will retrieve and display a list of e-mails from a Post Office Protocol (POP) server. Following are the tasks at hand: ❑
Create an instance of the ColdFusion Event Gateway adapter on FDS
❑
Create an instance of the Flex Messaging Gateway on ColdFusion
❑
Create the necessary ActionScript, MXML, and CFML for the application
The application itself is relatively simple. On the MXML side, you must have a form that takes the URL, username, and password of a POP mail server. When the user submits the form, FDS will talk to ColdFusion, requesting that it use the form data to retrieve messages from a POP server. ColdFusion will fetch the results as a query and then send that to FDS and the MXML page as an ArrayCollection. The results will be displayed within the MXML using a DataGrid as a simple form of data dump. There is a sample messaging-config.xml with ColdFusion Event Gateway settings that you can use to copy the settings from. It’s preinstalled into the C:\fds2\resources\config directory. Take a look at using the applicable tag from it to build a sample application. In that file, you’ll find a tag with the attribute id=”ColdFusionGateway”. Copy that tag into the existing messaging-config.xml found at C:\fds2\jrun4\servers\default\samples\ WEB-INF\flex and save the file to update it. Following is an example: *
You must have a CFC ready to go before you can create an instance of a Flex Messaging Event Gateway on your ColdFusion server. The form that you’re about to use requires you to nominate a CFC as one of
588
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 589
Chapter 24: Using ColdFusion/Flex Connectivity the required details when the instance is created. If you’re keen to get started, you can create an empty file. You can work on its contents later. Save that CFC into the ColdFusion directory that the application will call it from. For the sake of this exercise, create a CFC called PopGateway.cfc, and save it to a new directory at C:\CFusionMX7\wwwroot\flexgatewaypop. Now, you must configure the Flex Gateway setting in the ColdFusion Administrator. From Event Gateways, choose Gateway Instances. Enter Flex2CF702 as the value for Gateway ID and select Flex Messaging – Flex as the Gateway Type. Specify the full path to the CFC you’ve just created as the CFC Path. Select Automatic as the Startup Mode and choose Add Gateway Instance. The next thing you must do is create the MXML page. The form that you’ll use to collect user login details is quite straightforward. It will need to collect the username and password. You also use the form to collect the URL of the POP server so that the application is generic enough to allow users to log in to any server and retrieve a list of mail messages. The last thing to do with the UI will be to set the DataGrid component to display the results once received. In this code, you also have an instance of the Consumer component. This will be used by FDS in a fashion similar to how the RemoteObject tag is used for Flash Remoting. Notice that you use a function to nominate the handler in order to process the result as part of the argument for the message attribute of the Consumer component.
Next, start adding ActionScript to the MXML. Add a pair of Script tags and add to that the import statements. Then define the variables to be used within the application.
In this code, you’ll notice that you’re importing a number of messaging classes. Notice that the first two variables are typed to classes within the messaging packages. The last variable is going to be used in the DataGrid as the dataprovider. The variable is data typed to ensure that it will be compatible with its associated command. It’s bindable so that the DataGrid will be able to use it as the application commences. It’s also bindable because it will store the value returned by the adapter to gateway progress, and so that the DataGrid can update itself once the information has been received from the server. The next thing is to add the functions to the Script, as shown here: public function initApp():void { pro = new mx.messaging.Producer(); pro.destination = “ColdFusionGateway”; consumer.subscribe(); } public function fetchPopMail():void { var msg:AsyncMessage = new AsyncMessage(); msg.headers.gatewayid = “Flex2CF702”; msg.body = new Object(); msg.body.popurl = popUrl.text; msg.body.userName = userName.text; msg.body.password = password.text; pro.send(msg); } private function messageHandler(event:MessageEvent):void { popData = event.message.body as ArrayCollection; }
The functions have now been added. The first, initApp(), will be called by a CreationComplete event on the Application tag. It establishes the location of the destination. The next function, fetchPopMail(), retrieves the location of the ColdFusion Flex Gateway, fetches the contents of the form elements, and sends them to the server as a single object. This will be called when the Submit button in the form is clicked. The last function, messageHandler(), handles the result from the server when it is returned. The result is then assigned to the ArrayCollection, which, because of the binding, will force the DataGrid to refresh and redisplay. The last thing to build is the CFC that will handle the call via the gateways. In this case, it will contain a relatively simple function that will use cfpop to retrieve 10 messages from the POP server. Take a look at the code:
590
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 591
Chapter 24: Using ColdFusion/Flex Connectivity
Notice the name of the function in the CFC: onIncomingMessage. Though Adobe’s documentation doesn’t point this out, this is a reserved function name that the gateway is expecting to call. Also notice the names and structure of the argument used in this function. Again, these are reserved names. In the case of the Flex gateway, you should expect a structure called event with the data you’ve passed to the function nested in structure called body, which, in turn, is nested in a structure called data.
Using the Flex Data Ser vice Assembler The logic behind an application built on top of Flex Data Management Services is a combination of both client side and server side. It’s used to manage data distribution within a Flex application. On the client side in Flex, you use the DataService component to manage data locally, and to communicate about said data with the Flex Data Management Service, which runs on the server side as part of FDS. Data Management Service manages data on the server side, maintaining a distribution of it between both multiple clients and server-side data resources. The Data Management Service is quite different in its approach to handling data when compared to the Remote Procedure Call (RPC) feature of Flex. The Data Management Service can manage both automatic and manual synchronization of application data, broadcasting changes to both server-side managed data and multiple connected clients. It can be also used to manage changes to data for persistence in occasionally connected clients. The DataService component is also different from the RemoteObject component because it does not call methods on the server side, nor does it return a result. Instead, it uses Data Management Service on the server side to replicate the data that it’s managing to multiple clients. Both the Web application and the server-side database would be clients, in this example. Changes made to the data in any of the clients are then broadcast to all the clients currently listening to it using messaging. Changing a value in a DataGrid on the client side would be immediately reflected within the database on the server side. Changes to a value in a table within the database on the server side would push to the dataprovider for a ComboBox component on the client side. There is a need for conflict resolution with changes to data. You can have multiple instances of a Web application being served to multiple user machines. The Data Management Server has its own conflict resolution API to handle this. You can write logic for the client side to handle conflict exceptions.
591
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 592
Part VI: Advanced Flex 2.0
Configuring ColdFusion As mentioned, you use the DataService component on the client side. This can be scripted as either MXML or ActionScript. It would be used as the source of data for a collection like the ArrayCollection, which, in turn, would be used to populate a control like the DataGrid component. The DataService component would then synchronize itself with the Data Management Service, keeping the data up to date with both the server and other clients. The DataService must have a destination for the Data Management Service configured. This would be done in the services-config.xml configuration file. Following is an example of the DataService component:
Here’s the same DataService created using ActionScript, instead:
Notice in this code that you have imported the mx.data.DataService class and declared a variable of type DataService. The DataService component has a number of methods that you call as necessary to synchronize data with the other clients. The fill() method is used to populate a ListCollectionView object with the data that the DataService component is synchronized with (typically an ArrayCollection). The DataService will then manage the specified ArrayCollection. You can use the DataService component’s releaseCollection() method to release an ArrayCollection from being managed by the DataService component. Calling the fill() method again would refresh the ArrayCollection. Following is an example of creating an ArrayCollection from the DataService that you’ve already created. In the example, you’ll see that the initApp() method is used to call the DataService’s fill() method to populate the ArrayCollection. The initApp() method is being called by the Application component’s creationComplete event listener.
Changes to the data that the DataService component is managing will be automatically synchronized with the server-side destination. The DataService has a commit() method that will be called as the data changes in the ArrayCollection object. This is controlled by the autoCommit property of the DataService, which is set to true by default. Depending on your business requirements, you may choose to disable autoCommit by setting its value to false, and, thus, choosing to manually call the commit() method to apply changes according to your business rules. The DataService component is not automatically connected to the server-side destination until the first time that the data it manages is called. It then attempts to connect to the server-side destination. A result event is sent to the DataService component if there is a success; a fault event is sent otherwise. A disconnect from the destination can be forced using the DataService component’s disconnect() method. The DataService component can keep track of changes to the data that it’s managing, and it will attempt to resynchronize when the application is reconnected to the server. Changes to the managed data are tracked by the Data Management Service server-side in an object called DataStore. Calling the DataService component’s commit() method will commit all changes in the DataStore to the managed data. A commit will also be made if the DataService component’s autoCommit property is set to true. The DataStore can be shared by more than one DataService component. Associations between DataService components will cause them to share a DataStore. You can also set the DataService component’s dataStore property to refer to the DataStore of another DataService component. The DataService component is capable of broadcasting a fault event for any errors that may occur, including server connection errors and errors generated as the result of a commit. The DataService is capable of handling errors during the commit process. It is capable of keeping track of uncommitted changes. You can programmatically revert changes by calling the revertChanges() method of the DataService component, referring to a specific item as an argument to the revertChanges() method, or passing no argument to revert all changes. The Flex Data Management Service is designed to monitor and detect changes to data, broadcasting the changes to various clients that hold subscriptions via Flex. It is possible to shift the responsibility of listening for change from the DataService component to the Web application. The DataService component’s autoMerge property can be set to false, disabling the Data Management Service’s ability to detect change.
593
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 594
Part VI: Advanced Flex 2.0 The DataService component can keep track of changes via the mergeRequired property of the DataStore object. Pending changes can be merged by calling the DataService.dataStore.merge() method. You should merge changes from the Data Management Service before modifying local data to avoid conflicts in your data.
Value Object CFC The following example builds a VO CFC to format data into a VO to use within the Data Management Service. Though VOs are not part of standard ColdFusion development, they are used frequently in Flex frameworks. The VO being used for this application has all the properties of a single row from the database table. It allows ColdFusion to map the data to properties defined in Employee.as. Each property is added to the VO CFC using cfproperty tags. The properties will then need to be initialized and assigned default values. Equal to a constructor, you call a method to initialize the object, and then you create getters and setters for each of the object’s properties.
variables.employeeId = 0; variables.fName = “”; variables.lName = “”; variables.email = “”; variables.mobilePhone = “”;
594
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 595
Chapter 24: Using ColdFusion/Flex Connectivity .............
EmployeeAssembler.cfc This is the interface between Flex Data Services and ColdFusion. It’s invoked by Flex as part of the Data Management process. Flex Data Management Service calls a number of methods on the assembler as it manages data. The assembler, in turn, calls the Data Access Object (DAO) to interface with the database. The assembler has the following methods: ❑
fill — This method has been coded to retrieve all the employee records from the database
by default, returned to Flex as an array. The method can optionally filter by a record ID. ❑
get — Retrieves a specific record. It accepts a record ID as its argument.
❑
sync — Uses a change list to manage data synchronization issues. It is an array of change
objects. It calls private methods to create, delete, and update records in the database via an instance of the DAO.cfc. ❑
count — Returns the number of records in a result set.
Following is a simple example of the fill() method:
595
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 596
Part VI: Advanced Flex 2.0
The assembler will, in turn, use a DAO component to perform data management.
596
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 597
Chapter 24: Using ColdFusion/Flex Connectivity
The DAO.cfc The DAO.cfc is the DAO that makes all the calls to the database. In the context of the discussion in this chapter, it is a ColdFusion component with a number of predefined methods. It could also be authored in Java. Following are the methods that the assembler will be calling on the DAO: ❑
read — Retrieves the dataset. The request can be parameterized to filter data.
❑
create — Inserts a new record into the database.
❑
update — Updates an existing record in the database.
❑
delete — Removes a record from the record set.
❑
count — Retrieves the number of records in the dataset.
Any conflicts with the data, duplicate insert records (create), unsuccessful updates, or unsuccessful deletes are passed on to the assembler to handle. The Flex change object can be set to have a conflict. The developer should be aware of this so that the application has the appropriate checks and balances in the methods of both the DAO and the assembler, and so that the correct response is transmitted to Flex Data Management Service.
ColdFusion Extensions for Flex Builder 2 The ColdFusion Extensions for Flex Builder are a number of wizards that help the developer work with Flex and ColdFusion. They give Flex Builder 2 the capability to create ActionScript classes and generate ColdFusion components by interacting with data on both the ColdFusion server and the development environment. The following sections describe what is contained in the ColdFusion Extensions package.
Eclipse RDS Support Plugin This gives Eclipse and Flex Builder 2 the capability to connect to the ColdFusion server over a secure connection via Remote Development Services (RDS), allowing you access to both files and the data sources that have been configured in ColdFusion Administrator. RDS must have been chosen as part of the ColdFusion installation. You must have a valid password for RDS access from within Flex Builder 2. The RDS support plugin will be configured to connect to the ColdFusion Developer edition by default. This is found at local host IP address 127.0.0.1, port 8500. You may need to configure the plugin to suit your development environment. The settings for the RDS plugin are found at Window ➪ Preferences ➪ RDS Configuration. As you can see in Figure 24-3, you either create a new set of connection parameters for another ColdFusion server, or make changes to your existing settings. Settings for the server’s IP address, port number, and context are entered into a form to add or modify an RDS connection. Testing the connection parameters is also done from this form. If you are running ColdFusion on a J2EE server with different ports and context roots to the default values, you may have to modify your server settings. You should leave the Context Root value blank if your ColdFusion server
597
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 598
Part VI: Advanced Flex 2.0 has not been deployed on a J2EE server. All the RDS connections accessed by the RDS plugin will require you to sign in with your password for the first time per session. You will need to switch to Window ➪ Other Views and expand the ColdFusion option, as shown in Figure 24-4. Here you will see three options: RDS Dataview, RDS Fileview, and Services Browser.
Figure 24-3: RDS Configuration
598
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 599
Chapter 24: Using ColdFusion/Flex Connectivity Figure 24-4: RDS view options
Figure 24-5: RDS Dataview
If you are familiar with ColdFusion Studio, you will be familiar with the concept of RDS and the kinds of tools that the RDS plugin offers to the developer. The RDS Dataview (Figure 24-5) provides the ability to explore the ColdFusion server’s datasources via a tree view. Datasources can be expanded so that the tables and their columns (as well as data properties) can be viewed. From the RDS Dataview, you can launch the RDS Query Viewer (Figure 24-6) by using the second button in the toolbar at the top-right of the Dataview. It will launch within Flex Builder 2 immediately above the RDS Dataview. The RDS Query Viewer allows you to construct SQL statements. Double-click the table names within the RDS Dataview to insert them into the SQL. The RDS Query Viewer’s interface is reasonably simple. It assumes that the SQL server and datasource from what tables are selected in the RDS Dataview. You can change these, if required. You can test the SQL before copying it into the ColdFusion query that it’s intended for. The Visual Query Builder (Figure 24-7) allows you to build SQL queries visually by first dragging the tables into the builder, then double-clicking the required columns in their respective tables. Dragging and dropping the relationships easily indicates table joins. Additional SQL-like sort order and aliases are easily added via the interface. The SQL is written for you as you use the Visual Query Builder, and can be tested before deploying in your ColdFusion templates.
599
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 600
Part VI: Advanced Flex 2.0
Figure 24-6: RDS Query Viewer
Figure 24-7: Visual Query Builder
600
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 601
Chapter 24: Using ColdFusion/Flex Connectivity
Figure 24-8: RDS Fileview
With the RDS Fileview (Figure 24-8), you can browse the files on the ColdFusion server that you’re currently connected to via RDS. This is a tool that allows you to view, create, and delete files and folders on the server. Folders are displayed in the upper half, with their contents in the lower half of the screen.
Installation Software updates are not part of the standard Flex Builder install process. Instead, they appear as an option toward the end of the setup as a popup that offers to put an installer into the local system. The wizards are installed as a package via a standard Eclipse process accessed from the Help menu (Figure 24-9). Choose Help ➪ Software Updates ➪ Find and Install to commence, then select Search For New Features To Install. From the options on the right of the dialog box (Figure 24-10), choose New Archived Site. Eclipse (which Flex Builder 2 is built on top of) has the capability to install new plugins from either a location online or a compressed file.
601
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 602
Part VI: Advanced Flex 2.0
Figure 24-9: The first step in the install process
Figure 24-10: Confirmation that CF_FB_Extensions.zip is to be installed
602
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 603
Chapter 24: Using ColdFusion/Flex Connectivity The location that the Flex Builder 2 installer places the required file into is a temp directory buried in the user settings of the computer. A little bit of configuration is required to properly locate the ZIP file that contains the extensions. Browse to C:\Documents and Settings\Your Profile\Local Settings\Temp\ColdFusion Extensions for Flex Builder. You must enable Tools ➪ Folder Options ➪ View ➪ Show Hidden Files and Folders within Windows before choosing to install the ColdFusion Extensions so that you can see this directory. Select the file that you see there, CF_FB_Extensions.zip, and choose Open. You will be asked to confirm the file you’ve selected. Choose OK, ensure that the file is also selected in the next dialog box, and select Finish. Ensure that CF_FB_Extensions.zip is checked on the next dialog box (Figure 24-10) and choose Next. Agree to the license agreement and click Next. Choose Finish on the next dialog box. The necessary files for the ColdFusion Extensions will now be installed, and a verification screen (Figure 24-11) will appear during this process. Choose Install All on this screen. The process will take a few minutes because documentation for the extensions and ColdFusion is also added to the help files as well. You must restart Flex Builder 2 before the extensions can be used. A dialog box will appear asking you if you want to do that. Documentation for both the ColdFusion Extensions and the ColdFusion language are installed into the Flex Builder 2 help system. You might like to take some time looking at what’s been added to familiarize yourself with what the extensions have to offer.
Figure 24-11: Install All option
603
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 604
Part VI: Advanced Flex 2.0
Create CFC Wizard The Create CFC Wizard (Figure 24-12) will create the necessary CFCs and ActionScript files for access to data in tables on the database. You use this wizard by right-clicking the database table required to display from within the RDS Dataview. The wizard will ultimately produce a VO, but in doing so, it will produce the code to access the VO as well. It offers the rapid creation of code with three styles of CFC data access: ❑
Active Record CFC
❑
Bean CFC and DAO CFC
❑
Flex Data Service Assembler CFCs
Figure 24-12: CFC Value Object Wizard
Choosing the type of CFC will then affect the output of the wizard and how many files that it produces. A lot of checks and balances are put in place in the code dynamically for error trapping. Following is an example of the fill() method from a dataAssembler.cfc produced by the wizard:
604
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 605
Chapter 24: Using ColdFusion/Flex Connectivity
ActionScript to CFC Wizard The ActionScript to CFC Wizard builds a CFC based on an ActionScript class. The main purpose of this is to create a DTO or VO for use in applications. This CFC would then be used to cast a complex object of a specific data type with its own properties, as well as getters and setters. Right-click an ActionScript from the list of available files in the Project Navigator to use the wizard. Choose ColdFusion Wizards ➪ Create CFC. Enter the location of where the file is to be saved in the first option of the dialog box that appears. You can either type the location or browse to it. Next, enter the name of the CFC that you’re creating. You may need to verify the overwriting of an existing file. If you are using this wizard to generate a DTO, you must choose the Generate Get/Set Methods option. Set the appropriate property scope (private/public). Click Finish and the generated CFC will display shortly.
CFC to ActionScript Wizard The CFC to ActionScript Wizard builds an ActionScript class based on a CFC VO. Select a ColdFusion CFC VO from the Project Navigator by right-clicking and choose ColdFusion Wizards ➪ Create AS Class. Nominate the project folder to save the file into by either typing the path or using the Browse button to locate it. Give the new class an appropriate packed name with the next option, then give the new class a name. Choose to overwrite any existing versions of the CFC. This will be selected for you by default. The last thing is to nominate the path to the CFC. This value will be used as part of the ActionScript class. This will create an alias for the location of the CFC that will be used as a binding in the ActionScript class, like the following example shows: [Bindable] [RemoteClass(alias=”sandboxes.flexApp.Employee”)]
Click Finish and the wizard will build the ActionScript class.
605
02671c24.qxd:02671c24
4/20/07
4:01 PM
Page 606
Part VI: Advanced Flex 2.0
Services Browser The Services Browser allows the developer to view CFCs and Web services hosted on the ColdFusion server. It displays a full listing of CFCs organized by path, showing the individual CFCs in a chosen location. Expanding a CFC in the view will reveal its methods with the data return type indicated. Methods can be expanded further to show their arguments. Setting a method of a function to remote, public, or private will affect its listing in the Services Browser. WSDL URLs can be added to the Services Browser so that it can be used to manage a list of Web services. The Services Browser can then be used to generate the necessary CFML to invoke a Web service in a ColdFusion page. You can also use it to generate CFML to create a Web service object, instead. The Services Browser can be used to generate the necessary ActionScript to consume a Web service.
Summar y Flex 2 and ColdFusion 7.0.2 are ready partners. Through Flash Remoting, they can seamlessly exchange complex data between each other. ColdFusion can also be used to communicate with Flex applications via Flex Data Services (FDS). Flex can also exchange data with ColdFusion by calling ColdFusion Components (CFCs) via the Flex Messaging Event Gateway. Publish-subscribe messaging applications can be built with a combination of FDS and ColdFusion. The Flex Web application can subscribe to data on the ColdFusion server via FDS and be aware of changes to information via the publish-subscribe managed by the Data Management Service provided by FDS. The ColdFusion Extensions for Flex Builder 2 offer a number of wizards that allow for the creation of ColdFusion Components and ActionScript classes used as part of the process of data connectivity and management. Other tools included in the ColdFusion Extensions give the developer access to information within the database. Chapter 25 discusses how to incorporate video and audio into your Flex application to create a richer experience for your user. The Flash run-time has become the most installed multimedia player with the highest penetration across all major operating systems, and Flex makes it easy to develop multimedia applications for that run-time.
606
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 607
Part VII: Integration Techniques Chapter 25: Rich Media Integration Chapter 26: Integration with External Applications
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 608
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 609
Rich Media Integration Video and audio are fast becoming an important part of business and consumer applications. If you take a look around the Web today, you will notice the influx of Web sites that contain video and audio. You probably find the wrong version of the media player is installed or there are limited options to interact with the video. All of this disrupts the user experience, and this is where Flex and Flash are far more superior. The Adobe Flash Player contains video and audio playback and streaming capabilities. As of this writing, Flash Player 8 is installed on 90 percent of users’ computers. This is the reason companies such as Brightcove, Google, and YouTube have adopted the Flash Player to play back video. With Flex, video is more than just a streaming experience. It can be a more tightly integrated part of the application. During playback of video, events can be triggered and behaviors of other components are driven by the events, all of which creates a much richer experience. The capabilities enable an extensive range of new, innovative, and highly interactive applications. Rich media comes from the term “multimedia,” and is actually audio, video, text, and graphics combined with animation and interactivity. All these kinds of media have been around for years on the desktop, but now the focus is using rich media on the Web. As always with new technology, it does pose a problem with accessibility. If done correctly, however, it can be an even better experience for the user. This chapter introduces you to the integration of rich media into your Flex applications, and shows how easy it is to implement and work with.
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 610
Part VII: Integration Techniques
Integration Before looking at an example application, you must understand how rich media is integrated into a Flex application. This section provides you with the basics of how easy it is to do this in Flex. To integrate rich media such as audio and video into your Flex application, you can use the flash.media .Sound class and flash.media.Video class, respectively. Working with those two lower-level classes might be a bit tedious for a beginner, so the Flex Framework provides easier ways to use audio and video in your application.
Audio To integrate sound (such as an .mp3 file), you can embed the sound file as you would an image, as the following example shows: [Embed(source=”sample.mp3”)] [Bindable] public var soundAsset:Class; public var s:Sound = new soundAsset() as Sound;
This example embeds the .mp3 file into your Flex application and casts the soundAsset instance to a Sound class instance. This allows you to access the sound file’s data and manipulate it as necessary. Doing it this way would increase the file size. For sound effects, it would probably be fine to embed the sound files, as long as they are not too big. For bigger sound files, it would not be recommended to do it this way. Instead, you could download the sound files progressively by using the flash.media.Sound class. The SoundEffect class lets you control the volume and panning of an .mp3 file. You can either specify the .mp3 file from a URL, or embed it and set the source property to the embedded class. This class can pan the .mp3 file from a range of –1.0 to 1.0, where –1.0 uses the left channel, and 1.0 uses the right channel. The following example embeds the .mp3 file and sets the panFrom and panTo properties of the SoundEffect instance:
Video To use video inside Flex, you must use a Flash Video (FLV) file, which is a proprietary file format developed by Macromedia (now Adobe) for use in Adobe Flash Player versions 6, 7, 8, and 9. Flash Player 6 and 7 used a variant of H.263 video standard by Sorenson Spark, and versions 8 and 9 use On2 TrueMotion VP6 codec, which is of a much higher quality. Flex provides a VideoDisplay component that lets you play an FLV file in your application. It contains no controls for the play, pause, or stop actions. So it is up to you to create the user interface for your video
610
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 611
Chapter 25: Rich Media Integration player. The VideoDisplay component supports progressive download over HTTP, streaming from Flash Media Server, and streaming from a Web cam using the Camera object. It is relatively simple to use VideoDisplay. Just set the source property to a relative or absolute path to the FLV file, as shown here:
As mentioned earlier, all you should see is a video playing and nothing else. The layout and interactivity of the VideoDisplay component is up to the developer. The following example defines a VideoDisplay component and two LinkButton components. The first LinkButton instance is used for two actions: play and pause the video. The second LinkButton instance is used to stop the video. The playPause() method checks to see if the label is set to “Play”. If so, it sets the label property of the LinkButton to “Pause” and plays the video. The same happens if the label property is set to “Pause”.
611
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 612
Part VII: Integration Techniques
Using the Camera The Camera class gives access to a Web camera on a client’s workstation. You mainly use the Camera class with Flash Media Server, but you can use it without the server. For example, you could capture a single frame from the camera stream, encode the data, and send it to the server to be stored. The camera can also be used to create cool effects, such as the ones in Apple’s PhotoBooth application. You could apply a blur filter, a sepia effect, or morphing to the streaming video. Some developers have even been able to create effects that interact with the user. The Microphone class again gives you access to a microphone on the client’s workstation. This can be used without the Flash Media Server, but again with limited functionality. The Camera class is used in conjunction with the VideoDisplay control. The following example shows this in action:
The next example uses the VideoDisplay, Image, and Button controls to capture an image from the camera stream and display it in the Image control instance. All the magic lies in this simple, but very powerful, getBitmapData(target:UIComponent) method. The implementation of this method allows you to capture BitmapData of any visual component at run-time.
By clicking the button, you capture the VideoDisplay control with an image from the camera stream. You could extend this application and encode the BitmapData using a compression algorithm such as JPEG or PNG, and send the data to the server to be stored for later retrieval.
Building an Application with Rich Media Integration So far, you have seen how easy it is to integrate rich media into your Flex applications. In this section, you build a simple application that integrates video and audio with some transitions and effects. Figure 25-1 shows the Flex application with video playing on the left-hand side. A reflection effect has been added to make it look more professional. This application did not take long to build, and all the code is housed in the root Main.mxml application file.
613
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 614
Part VII: Integration Techniques
Figure 25-1: Rich media application
Listing 25-1 shows the code for the entire application. Take a look through the code before moving on.
Listing 25-1: Main.mxml Application { backgroundGradientColors: #000000, #000000; paddingBottom: 2; paddingLeft: 2; paddingRight: 2; paddingTop: 2; }
614
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 615
Chapter 25: Rich Media Integration List { fontSize: 40; color: #FFFFFF; backgroundAlpha: 0; borderStyle: none; fontFamily: myFontFamily; rollOverColor: #990000; selectionColor: #0099CC; } @font-face { src:local(“Arial Black”); fontFamily: myFontFamily; flashType: true; }
615
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 616
Part VII: Integration Techniques
616
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 617
Chapter 25: Rich Media Integration
The Inner Workings of the Application Now that you have looked over the code, take a look at the most important parts of the application. Without the VideoDisplay control, this application would be an application lacking rich media and, thus, this is the most important component. However, the application still needs logic to get the right video to display inside the VideDisplay control. To the right of the VideoDisplay control is a List control. This provides the list of trailers by using an inline data provider, for the sake of simplicity. The data provider is a list of objects with a label property and a data property. The label property is displayed in each row of the List control instance, and the data property contains the FLV filename.
617
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 618
Part VII: Integration Techniques
The List instance contains an inline item renderer so that the Label instance can be aligned vertically inside the VBox container. If you do not do this, you will find that the label aligns on the top. The List control instance contains a change event implementation that sets the videoDisplay.source property to the FLV file. So any time a row is selected, a new video starts playing in the VideoDisplay instance to the left. The doubleClick event of the List instance sets the videoPath property to the relative path of the relevant FLV file through the List instance selectedItem.data property. This means that any time a row is clicked in the List instance, the correct video is displayed in the VideoDisplay instance. The second piece of code that is executed in the doubleClick event handler sets the state of the Flex application to a new state. Following is the MXML code for the new state:
The new state removes the mainView instance, which is essentially the base state of the application, and adds a VBox container with the VideoDisplay control as its child. The tag ensures that when the application moves into the new state, the VideoDisplay instance source property in the base state is set to null. This ensures that only the right VideoDisplay instance is playing the FLV file. Figure 25-2 shows the new state of the application with the VideoDisplay control using the full width and height of the browser window. When the VideoDisplay control is double-clicked, the application will return to the base state using transitions and effects.
618
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 619
Chapter 25: Rich Media Integration
Figure 25-2: New state of the application
The following example shows the two transitions used in the application, one from the base state to the new state, and the other from the new state to the base state. Refer to Chapter 8 for more information on transitions.
619
02671c25.qxd:02671c25
4/20/07
2:03 PM
Page 620
Part VII: Integration Techniques
Using transitions in the application means that moving from one state to another looks more elegant and professional. The transition from the base state to the new state fades out the mainView instance, then removes it, adds the new state, and fades it in. The other transition does the exact opposite, and returns the user back to the base state. This application took but a few hours to build and shows just how easy it is to get rich media integration into your Flex application.
Summar y Over the next year or two, you will see more and more Web applications integrating rich media such as video and audio. Flex makes it easy to integrate all of this type of rich media into your application. This is the best time to get on the bandwagon and start developing killer Rich Internet Applications that use rich media. Chapter 26 discusses integrating external applications in Flex, such as using JavaScript to communicate between Flex and HTML applications, integrating with Microsoft Excel, and using the flash.net .LocalConnection class to communicate with a Microsoft Windows application.
620
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 621
Integration with External Applications ActionScript 3.0 supports the External API that defines a method for Adobe Flash Player SWFs to communicate with their container applications. The most common container applications that the Flash Player resides in are the browser or desktop applications with the Flash Player embedded. Along with learning about the newer External API, this chapter explores using LocalConnection as another method of communicating with outside applications. This chapter requires other non-Flex resources and development tools. For the ExternalInterface example, you will need Flash 8 Professional and the ability to create SWFs in the IDE. The LocalConnection example uses C# .NET technology, and was created using the freely available Microsoft Visual C# 2005 Express Edition of the Visual Studio product line. As of this writing, the link to Microsoft Visual C# 2005 Express Edition is located at http://msdn.microsoft.com/vstudio/express/visualcsharp/.
Using the External API The root of the External API stems around the ExternalInterface class. This class defines a standard method of communicating with container applications using the Flash Player. Just as the Remote Procedure Call service classes (HTTPService, WebService, and RemoteObject) provide methods to communicate with external back-end services, the ExternalInterface implements methods to communicate with Flash Player container applications. The External API is a replacement for the older fscommand() functionality. The ExternalInterface is, therefore, the framework and preferred method for talking with JavaScript. The Flex-Ajax Bridge (covered in Chapter 22) is an extension to ExternalInterface
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 622
Part VII: Integration Techniques that helps to solve some of the limitations of the ExternalInterface class. One way to look at it is that the Flex-Ajax Bridge helps you focus on writing JavaScript and not ActionScript, whereas ExternalInterface forces you to build all the communication structure on both sides.
AVM1 and AVM2 SWF Communication A good example to demonstrate how to use the ExternalInterface is to tackle the problem that became apparent with the rollout of a new ActionScript virtual machine (AVM) in Flash Player 9. An SWF created with Flex 2 and ActionScript 3 is AVM2 compatible, and any SWF created for the previous ActionScript virtual machine is called AVM1 compatible. The newer ActionScript virtual machine is quite different, which means AVM1 SWFs loaded into AVM2 cannot talk directly to each other. This is where ExternalInterface comes into to play. Follow these steps to create the AVM1 SWF used in this section:
1. 2. 3. 4. 5.
6. 7. 8.
Open Flash 8 Professional. Create a new Flash document called AVM1.fla. In the timeline, create two layers and call them ActionScript and Controls. Open up the Components window by pressing Ctrl+F7 or clicking Windows ➪ Components. Select the Controls layer and drag the following components onto the Flash Stage, as shown in Figure 26-1: a.
Button
b.
TextInput
c.
TextArea
Click the Button component and give it an instance name of btnSend. Click the TextInput component and give it an instance name of txtMessage. Click the TextArea component and give it an instance name of txtOutput.
Figure 26-1: Button, TextInput, and TextArea on the Flash Stage
622
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 623
Chapter 26: Integration with External Applications 9.
Select the ActionScript layer and copy the following ActionScript into the first frame:
import flash.external.ExternalInterface; import mx.utils.Delegate; // Register callback method for retrieving messages ExternalInterface.addCallback( “retrieveMessage”, this, retrieveMessage ); // Button Click Event btnSend.addEventListener(“click”, Delegate.create( this, sendMessage) ); function sendMessage():Void { ExternalInterface.call( “sendMessage”, “AVM1: “ + txtMessage.text ); } function retrieveMessage( msg ):Void { txtOutput.text += msg + “\n”; }
10.
Publish the AVM1.swf and make note of where it is located. You will need to copy the SWF into the Flex Builder project that you create in a moment.
That’s all for the AVM1 SWF part. The ActionScript code is very straightforward. The btnSend’s click event listener calls the sendMessage function. The sendMessage function executes an ExternalInterface call to the JavaScript sendMessage method, passing text from the txtMessage.text property as its parameter. The next steps revolve around Flex 2:
1. 2. 3. 4.
Open Adobe Flex Builder 2. Create a new Flex Basic Project. Open up the index.template.html page located in the html-template folder. Copy the following HTML code in between the and tags of the default template:
... function thisMovie(movieName) { if (navigator.appName.indexOf(“Microsoft”) != -1) { return window[movieName]; } else { return document[movieName]; } }
623
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 624
Part VII: Integration Techniques function sendMessage(value) { thisMovie(“${application}”).retrieveMessage(value); thisMovie(“${application}”).retrieveMessage2(value); } ...
5.
Open up the project’s properties popup and set the Output folder and Output folder URL (located in the Flex Build Path section) to valid Web server values. This is required because of the security constraints of the Flash Player, which are enforced when using the ExternalInterface from local file system resources.
6. 7. 8.
Copy the AVM1.swf into the root folder of the Flex Builder 2 project. Rename the main.mxml to AVM2.mxml and copy the code from Listing 26-1 into the file. Run the file and see the results.
Listing 26-1: AVM2.mxml 9 ? num.toString() : “0” + num.toString(); } } }
The TracePanel.mxml now can include the new LocalConnectionTraceTarget.as class as a potential target for the loggers. The LocalConnectionTraceTarget class uses the LocalConnection to make a method call called “logMessage” on the “_flex2tracepanel” connection. The updates for the new LocalConnectionTraceTarget and checkbox for starting and stopping are found in Listing 26-3.
628
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 629
Chapter 26: Integration with External Applications Listing 26-3: TracePanel.mxml
Now the CustomLoggerMain.mxml application will execute both the TracePanelTarget and LocalConnectionTraceTarget, once the TracePanel title window has been called. The C# application will constantly look at the memory space for any LocalConnection messages made by calling logMessage on the connection named _flex2tracepanel. Follow these steps to create the C# application:
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.
Open Microsoft Visual C# 2005 (Express Edition). Create a project, selecting the Windows Application project template. Name the project Flex2TracePanel and click the OK button. Change the name of Form1.cs to Flex2TracePanel.cs. Right-click the Flex2TracePanel.cs file and select View Code. Copy the code from Listing 26-4 into the file. Open up the Flex2TracePanel.Designer.cs file. Copy the code from Listing 26-5 into the file. Open up the Program.cs file. Copy the code from Listing 26-6 into the file. Select the Project ➪ Flex2TracePanel Properties menu item. With the project Properties page open, select the Build tab. Click the “Allow unsafe code” checkbox. Save the file by pressing Ctrl+S or selecting File ➪ Save Selected Items. You are now ready to build the project and run the application. Press F5 or select Debug ➪ Start Debugging to run the project application.
631
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 632
Part VII: Integration Techniques Listing 26-4 is rather long, but it helps demonstrate specific code functionality. Explanations appear after the listing. Listing 26-4 also contains in-code comments that help describe specific lines of code.
Listing 26-4: Flex2TracePanel.cs using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Text; using System.Windows.Forms; using System.Runtime.Remoting; using System.Threading; // Used for DllImport using System.Runtime.InteropServices; namespace Flex2TracePanel { public partial class frmMain : Form { private string CONNECTION_NAME = “_flex2tracepanel”; private string METHOD_NAME = “logMessage”; private int DEBUG_LEVEL = (int)MessageLevel.Error; public frmMain() { InitializeComponent(); } private void Flex2TracePanel_Load(object sender, EventArgs e) { txtOutput.AutoScrollOffset = new Point(0, txtOutput.Height); } // Mutex for the Control of process private Mutex mut; // Pointer to the Memory of the Process private IntPtr hMapFile = IntPtr.Zero; private string lastArg1; private int lastArg2; private unsafe void pollMutex() { // false = don’t take ownership // “MacromediaMutexOmega” = name of mutex if( mut == null ) mut = new Mutex(false, “MacromediaMutexOmega”); try { // Wait 5 seconds if (mut.WaitOne(5000, false))
632
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 633
Chapter 26: Integration with External Applications { // Has control of mutex try { // OpenFileMapping method comes from the imported dll hMapFile = OpenFileMapping((int)MapAccess.FileMapAllAccess, false, “MacromediaFMOmega”); // MapViewOfFile method comes from the imported dll IntPtr baseMapAddress = MapViewOfFile(hMapFile, (int)MapAccess.FileMapAllAccess,0, 0, 0); if (baseMapAddress != null) { output(“Reading MapViewOfFile!”, (int)MessageLevel.Info); byte* buffer = (byte*)baseMapAddress.ToPointer(); //String hexStr = “”; // Make sure memory address is valid // Is byte 16 a AMF String (0x02) identifier if ( buffer != null && (int)buffer[16] == 2) { int currentPoint = 16 + 2; /** Find LocalConnection connection name **/ // 16 will always be a AMF String value 0x02 // next 2 bytes define length so we pick up the tail end one int len = (int)buffer[currentPoint]; // Move pointer to start reading string currentPoint++; // Convert bytes into String string connectionName = “”; for (int i = 0; i < len; i++) { // No char check, Assume values are valid connectionName += (char)ushort.Parse(buffer[currentPoint+i] .ToString(“X2”), System.Globalization.NumberStyles.HexNumber); } // Move pointer to next AMF data type currentPoint += len; if (CONNECTION_NAME == connectionName) { // AMF String (0x02) has two Length bytes that are Big Endian // Therefore you will see alot of + 2 pointers to get the Length // I am only reading the last Length byte and assuming the length will not be longer // Skip Protocol String by getting protocal string length and adding 2 bytes for the length output(“ Protocol len: “ + (int)buffer[currentPoint + 2]); currentPoint += (int)buffer[currentPoint + 2] + 3; // Move to Method Name strings length bytes currentPoint += 2;
633
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 634
Part VII: Integration Techniques // Get Method Name int lenMethod = (int)buffer[currentPoint]; // Move pointer to start reading string currentPoint++; string methodName = “”; for (int i = 0; i < lenMethod; i++) { // No char check, Assume values are valid methodName += (char)ushort.Parse(buffer[currentPoint + i].ToString(“X2”), System.Globalization.NumberStyles.HexNumber); } // Move pointer to next AMF data type currentPoint += lenMethod; output(“ConnectionName: “ + connectionName + “ MethodName: “ + methodName + “ len: “ + lenMethod); if (METHOD_NAME == methodName) { // Method arguments are in reverse order // You have to know how many parameters there are // Trace Logging Level int arg2 = 0; // Trace Message string arg1 = “”; // AMF Number (0x00) is Big Endian 64 bit so need to convert // Check to make sure Arg2 is a Number if (0 == (int)buffer[currentPoint]) { // Move to read Number currentPoint++; string strAMFNumber = “”; for (int i = 0; i < 8; i++) { // Reverse Binary String and then do Endian switch string hexValue = buffer[currentPoint + i].ToString(“X2”); string binaryStr = Convert.ToString(Convert.ToInt32 (hexValue, 16), 2).PadLeft(8, ‘0’); char[] chars = binaryStr.ToCharArray(); Array.Reverse(chars); string reversed = new string(chars); strAMFNumber += Convert.ToString(Convert.ToInt32(reversed, 2), 16).PadLeft(2,’0’); ; //output(“1: “ + reversed + “ - “ + binaryStr); } currentPoint += 8; //output(“strAMFNumber: “ + strAMFNumber); UInt64 realNumber = convertAMFNumber (UInt64.Parse(strAMFNumber, System.Globalization.NumberStyles.HexNumber)); arg2 = (int)realNumber;
634
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 635
Chapter 26: Integration with External Applications // Check to make sure Arg1 is a String if (2 == (int)buffer[currentPoint]) { currentPoint += 2; // Get String len int lenArg1 = (int)buffer[currentPoint]; // Move pointer to start reading string currentPoint++; for (int i = 0; i < lenArg1; i++) { // No char check, Assume values are valid arg1 += (char)ushort.Parse(buffer[currentPoint + i].ToString(“X2”), System.Globalization.NumberStyles.HexNumber); } } if (arg1 != lastArg1 || arg2 != lastArg2) { // Prep real message string msg = “”; string levelStr = “MSG”; if (arg2 == 2) levelStr = “DEBUG”; if (arg2 == 4) levelStr = “INFO”; if (arg2 == 6) levelStr = “WARN”; if (arg2 == 8) levelStr = “ERROR”; if (arg2 == 1000) levelStr = “FATAL”; msg = “[“ + levelStr + “]: “ + arg1; // Send message output(msg, (int)MessageLevel.ValidMessage); } lastArg1 = arg1; lastArg2 = arg2; } else { output(“Method level argument must be a Number!”, (int)MessageLevel.Error); } } } } } else { output(“MapViewOfFile failed!”); } }
635
02671c26.qxd:02671c26
4/20/07
2:13 PM
Page 636
Part VII: Integration Techniques finally { // Release ownership of the mutex object. mut.ReleaseMutex(); output(“Release Mutex!”); } } else { // Reached timeout try again output(“Mutex Timed out!”); Thread.Sleep(500); } } catch (AbandonedMutexException ame) { // Mutex was abandoned output(“Mutex was abandoned!”); Thread.Sleep(500); } Thread.Sleep(500); // Infinite Loop, handled by Thread Suspend/Resume pollMutex(); } private void output(string str) { output(str, (int)MessageLevel.Debug); } delegate void OutputCallback(string str, int level); private void output(string str, int level ) { // To Turn on internal code messages change to true if (DEBUG_LEVEL > 56) | ((AMFNumber > 24) & 0x0000000000FF0000) | ((AMFNumber >> 40) & 0x000000000000FF00) | (AMFNumber
Listing A-2: blueCSS.css /* CSS file */ Application { backgroundImage: “”; backgroundColor: #336699; } Panel { cornerRadius: 0; backgroundColor: #DDDDDD; borderStyle: none; } .sLogin { fillColors: #777777,#000000; color: #DDDDDD; }
Listing A-3: redCSS.css /* CSS file */ Application { backgroundImage: “”; backgroundColor: #993333; } Panel { cornerRadius: 6; backgroundAlpha: 0.2; backgroundColor: #DDDDDD; } Label { color: #FFFFFF; fontWeight: bold; fontStyle: italic; }
Create a Flex Builder project and put the Listing A-1, Listing A-2, and Listing A-3 files into the project root folder. Ensure that the CSS files have the Compile CSS to SWF context menu item selected and then run the application. Figure A-1 shows the initial state of the application and the three buttons on the bottom labeled one, two, and three. Button two (center) and button three (far right) are implemented to load the blueCSS.swf and redCSS.swf dynamically when each respective button is clicked. The button two style is shown in Figure A-2, and button three’s style is shown in Figure A-3.
645
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 646
Appendix A: Flex 2.0.1
Figure A-1: Default style
Figure A-2: Button two’s style
Figure A-3: Button three’s style
646
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 647
Appendix A: Flex 2.0.1 It is important to note that if the code did not unload the previous style each time the button were clicked, it would be possible to have leftover styles hanging around. For example, comment out the unloadCSS ( false ) and lastCSS = name; code lines in the RuntimeCSSMain.mxml, as shown here: ... private function changeCSS( name:String ):void { // If you do not unload the last style // previous style settings will be in effect // unloadCSS( false ); var styleEvent:IEventDispatcher = StyleManager.loadStyleDeclarations( name, true ); //lastCSS = name; } ...
Now, run the application and click button three (far right) first, then button two (center). The redCSS.swf sets the Label’s font color style to white and the font weight to bold. When clicking button two, the blueCSS.swf is loaded, but the Label’s style is not defined explicitly. Therefore, it is not reset, and stays bold and white. With the ability to load style resources at run-time, developers now have more options to approach lazyloading SWF applications. This will be a hot new feature.
ASDoc Tool The Adobe Flex 2 Language Reference documentation found on the Adobe Web site was created with a tool called ASDoc. Flex 2.0.1 provides developers the ASDoc command-line tool to create documentation for their own components and classes. The command-line executable is called asdoc and is located in the bin directory, along with the mxmlc and compc compilers. The tool generates HTML files that describe package, property, method, and other class information through syntax written as comments in the code. The syntax uses a number of specific ASDoc tags to tell asdoc how to generate the documentation.
ASDoc Tags and Syntax The following table lists the tags used in this appendix’s example code. The example logging code created in Chapter 19 will be modified to demonstrate ASDoc’s capabilities. ASDoc Tag Syntax
Description
/**
Comment the block starting with /** and ending with */. This syntax tells ASDoc to read text and tags inside the command block.
*/ /**
Text wrapped in a comment block not preceded by a tag will be read as the main description.
Continued
647
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 648
Appendix A: Flex 2.0.1 ASDoc Tag Syntax
Description
Used for each description paragraph that precedes the first paragraph.
Used around text inside the comment blocks to define a specific style for the ASDoc to output for that specific text.
@private
The specific code will not be included in the ASDoc output.
@param paramName
Defines descriptions for each parameter in the method. You can declare multiple @param values in a code block.
description @default value
The text describing the default value for the property.
@see classname [display text]
The classname defines other classes in the documentation that will be linked. ASDoc puts output under the “See also” area.
@return description
Description of the value the method will return.
Documenting the Logger Classes Follow these steps to learn about the process of documenting classes:
1. 2. 3.
4.
5.
648
Open Adobe Flex Builder 2. Create a new Flex Basic Project and call it ProfessionalFlexLogging. Create the following folders in the root of the project: a.
/professional/
b.
/professional/flex2/
c.
/professional/flex2/logging/
Copy the following files from Chapter 19 and Chapter 27 into the /professional/flex2/ logging/ folder: a.
LocalConnectionTraceTarget.as
b.
LogController.mxml
c.
TracePanel.mxml
d.
TracePanelTarget.as
Copy the CustomLoggerMain.mxml file into the root of the project.
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 649
Appendix A: Flex 2.0.1 6.
Open CustomLoggerMain.mxml and change the following line of code:
xmlns:logger=”*”
to xmlns:logger=”professional.flex2.logging.*”
7.
Open LocalConnectionTraceTarget.as and change package to package professional .flex2.logging.
8.
Open TracePanelTarget.as and change package to package professional.flex2 .logging.
The next code snippet outlines code examples highlighting ASDoc comment syntax. The full code listings are located later in the appendix. To start, open the TracePanelTarget.as file and add the following comment block to the constructor method: ... /** * Constructor. * * @param console Reference to a TextArea * object that will display the output * of the messages. */ public function TracePanelTarget( console:TextArea ) { super(); this.console = console; } ...
The first block of text will be picked up as the first paragraph. The @param tag defines the parameter of the constructor. The best way to see what the comment syntax does is to compile the documentation and see what it looks like. Continue on to the next section to learn how to use the asdoc compiler. The second part of learning how to document the logger classes continues in the section after that, “Documenting the Logger Classes – Continued”.
Using the ASDoc Compiler The ASDoc tool is a command-line tool with multiple compile arguments. The important ones to understand are –doc-sources, –doc-classes, and –source-path. The first two give you two options for compiling the documentation, by source file or by class name. If you navigate to the ProfessionalFlexLogging Flex Project created earlier in the appendix, the following are available source files: ❑
CustomLoggerMain.mxml
❑
/professional/flex2/logging/LocalConnectionTraceTarget.as
❑
/professional/flex2/logging/LogController.mxml
❑
/professional/flex2/logging/TracePanel.mxml
❑
/professional/flex2/logging/TracePanelTarget.as
649
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 650
Appendix A: Flex 2.0.1 You would use the full name or directory pattern syntax to determine the value of –doc-sources. The following are the comparable class names: ❑
CustomLoggerMain
❑
professional.flex2.logging.LocalConnectionTraceTarget
❑
professional.flex2.logging.LogController
❑
professional.flex2.logging.TracePanel
❑
professional.flex2.logging.TracePanelTarget
When configured to compile a specific class, the ASDoc tool will also compile all the classes that it references. Finally, the –source-path is needed to tell the ASDoc where to start looking for source files. The –source-path compile argument is like class path values used in other compilers. To run the following example asdoc command-line calls, open up a command prompt and navigate to the ProfessionalFlexLogging project folder on the file system: // Output set to docs folder // Create documentation for class CustomLoggerMain // Classpath set to ./ or the same folder asdoc –output docs –doc-classes CustomLoggerMain –source-path ./ // Output set to targets folder // Create documentation for the two Target classes asdoc –output targets –doc-classes professional.flex2.logging .LocalConnectionTraceTarget professional.flex2.logging .TracePanelTarget –source-path ./ // Output set to logging folder // Create documentation for all sources files under the professional folder // this will not pick up CustomLoggerMain asdoc –output logging –doc-sources ./professional/ -source-path
Documenting the Logger Classes – Continued You are equipped to create the documentation for TracePanelTarget.as and view how the comments look in the outputted HTML. Run the following command: asdoc –output docs –doc-classes professional.flex2.logging.TracePanelTarget –source-path ./
Open up the index.html in a browser. The index.html is located in the docs folder that the ASDoc tool created. The ASDoc tool does provide limited ability to document MXML files as well. The comment syntax blocks are constrained to being processed inside the code tags of an MXML file. Open up the TracePanel.mxml file and add the following ASDoc comments: ... /** * Property used in connection with Popup functionality. * The value defines the popup state of the control.
650
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 651
Appendix A: Flex 2.0.1 * * @default false */ public var isOpen:Boolean = false; ...
The @default comment tag is used to document that the isOpen property is defaulted to false. Run asdoc on the whole project by using the following command and see the results: asdoc –output docs –doc-classes CustomLoggerMain –source-path ./
Open up the index.html and click the TracePanel class located in the panels on the left. You’ll find the isOpen property detail containing the following text: “The default value is false.” You can now add more documentation comments and view the results. Listing A-4, Listing A-5, and Listing A-6 show the source files implemented with ASDoc comments. Copy the source files over to your project and play with different comment tag syntaxes. The best way to find examples of ASDoc comment syntax and usage is to look at the Flex Framework source files.
Listing A-4: LocalConnectionTraceTarget.as package professional.flex2.logging { import flash.events.StatusEvent; import flash.net.LocalConnection; import mx.controls.TextArea; import mx.core.mx_internal; import mx.logging.ILogger; import mx.logging.LogEvent; import mx.logging.targets.LineFormattedTarget; use namespace mx_internal; /** * The LocalConnectionTraceTarget extends the * LineFormattedTarget class to provide * a basic output mechanism. This target uses * LocalConnection to output the trace * messages to any other application using * LocalConnection listening on * _flex2tracepanel. * * @see mx.logging.targets.LineFormattedTarget */ public class LocalConnectionTraceTarget extends LineFormattedTarget { /** * Constructor. */
651
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 652
Appendix A: Flex 2.0.1 public function LocalConnectionTraceTarget() { super(); lc = new LocalConnection(); lc.addEventListener(StatusEvent.STATUS, statusEventHandler); } /** * @private */ private var lc:LocalConnection; /** * @private * @internal Need to keep Flex 2 from throwing unhandled * status errors */ private function statusEventHandler(event:StatusEvent):void { ; // Handles Event Status Calls }
/** * The internalLog method handles the * sending of messages. * * @param event LogEvent sent to a * ILogger from the Log class. */ override public function logEvent(event:LogEvent):void { var level:int = event.level; var date:String = “” if (includeDate || includeTime) { var d:Date = new Date(); if (includeDate) { date = Number(d.getUTCMonth() + 1).toString() + “/” + d.getUTCDate().toString() + “/” + d.getUTCFullYear() + fieldSeparator; } if (includeTime) { date = pad(d.getUTCHours()) + “:” + pad(d.getUTCMinutes()) + “:” + pad(d.getUTCSeconds()) + “.” + pad(d.getUTCMilliseconds()) + fieldSeparator; } } var category:String = includeCategory ? ILogger(event.target).category + fieldSeparator : “”;
652
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 653
Appendix A: Flex 2.0.1 // Connection and Method specific to C# .Net applicaton Flex2TracePanel lc.send( “_flex2tracepanel”, “logMessage”, date + category + event.message, level); } /** * The pad method adds leading 0’s to single digit numbers. * * @return The string representation of two digit leading 0 number. */ private function pad(num:Number):String { return num > 9 ? num.toString() : “0” + num.toString(); } } }
Listing A-5: TracePanelTarget.as package professional.flex2.logging { import mx.core.mx_internal; import mx.controls.TextArea; import mx.logging.targets.LineFormattedTarget; use namespace mx_internal; /** * The TracePanelTarget extends the * LineFormattedTarget class to provide * a basic output mechanism. This target requires a * reference to a TextArea object. The * TracePanelTarget uses the reference to * the TextArea object to output message * line by line. * * @see mx.logging.targets.LineFormattedTarget */ public class TracePanelTarget extends LineFormattedTarget { /** * Constructor. * * @param console Reference to a TextArea * object that will display the output * of the messages. */ public function TracePanelTarget( console:TextArea ) { super(); this.console = console; }
653
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 654
Appendix A: Flex 2.0.1 /** * @private */ private var console:TextArea; /** * The internalLog method handles the * sending of messages. * * @param message The message to be logged by this target. */ override mx_internal function internalLog(message:String):void { console.text += message + “\n”; } } }
Listing A-6: TracePanel.as
To go beyond just basic documentation creation, ASDoc provides a list of optional command-line arguments. These options provide functionality to customize the documentation and metadata. To obtain a list of available options, enter the following at the command prompt: asdoc –help –list or asdoc –help –advanced
Building Modular Flex Applications The needs to break up large application code and reuse code across many applications are key factors that led Adobe to spend the time providing classes that help make creating modular applications very easy. Splitting up an application into separate modular SWFs that can be loaded and unloaded by an application is similar to Runtime Shared Libraries (RSLs). The difference is that RSLs are statically linked at compile time, and module SWFs are loaded at run-time. This allows for smaller initial download sizes and short load times for applications. There is a slight overhead incurred by breaking up the SWFs and loading them separately, but the total size of all the modules compared to a single SWF application is a nominal increase of size. The new classes provided in the mx.modules package make everything happen. Each module SWF is required to extend the mx.modules.ModuleBase class, typically done by creating a new MXML file with a root tag of . The following example shows a application loading and unloading modules with the help of a button. Listing A-7 is the main application, and Listing A-8, Listing A-9, and Listing A-10 are the three modules called RuntimeCSSModule, DateWidget, and PowWidget. The first two modules are loaded when the application is first loaded. After the application is loaded, the user proceeds to click the button. Each button click event calls a method that switches between loading/unloading the RuntimeCSSModule and DateWidget and loading/unloading the PowWidget.
Listing A-7: ModularApplicationMain.mxml
Listing A-8 is a modified RuntimeCSSMain.mxml file from the example code earlier in the appendix. This is to demonstrate how easy it is to take an existing application and modify it to work as a module. The only changes needed are making the root tag and adding horizontalAlign= ”center” to the HBox.
Listing A-8: RuntimeCSSModule.mxml
Listing A-9: DateWidget.mxml
Listing A-10: PowWidget.mxml 1 && Number( exp ) > 1 ) return Math.pow( Number( base ), Number( exp ) ).toString(); else return “invalid value”; } ]]>
660
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 661
Appendix A: Flex 2.0.1
Running the ModularApplicationMain.mxml should produce the applications shown in Figure A-4 and Figure A-5. The example shows the basics of constructing a modular application. The ModuleLoader class also provides events and methods that help with loading and unloading modules. The ModuleLoader supports the following module events: loading, urlChanged, setup, ready, error, progress, and unload. To load a module with ModuleLoader class, all you need to do is set the url property and unload the module calling the unloadModule() method, as shown in the changeWidgets method of Listing A-7. The code in Listing A-11 shows a modified ModularApplicationMain application that sends all events to a single method that outputs trace statements. The trace statements contain information about the control that sent the event and the type of the event itself. The modified application is required to be run in connection with a debug Flash Player. Watching the trace statements in the output console as the modules are loaded and unloaded will give you a good visual of how the events ready, setup, and progress relate to each other.
Figure A-4: Application with the RuntimeCSSModule and DateWidget modules loaded
661
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 662
Appendix A: Flex 2.0.1
Figure A-5: Application with the PowWidget module loaded
Listing A-11: Modifed ModularApplicationMain.mxml
Summar y The first update since Flex 2’s big release has a lot of code fixes, as well has feature upgrades. The need to address load times and the initial user experience are major issues. The new features in Flex 2.0.1 provide developers the tools to approach problems with more options than ever before. This appendix examined three key Flex 2.0.1 features: run-time CSS support, the ASDoc tool, and creating modular applications.
663
02671bapp01.qxd:02671bapp01
4/20/07
2:17 PM
Page 664
4/20/07
12:19 PM
Page 665
Index
02671bindex.qxd:02671bindex
Index
A absolute positioning, 122 accessibility, 189 component, 189 built-in, 189 customizing, 189–190 enabling, 189 accessible option, 494 accordion container, 62, 449, 481 history management in, 177 accordion headers, 62 acknowledge event, 269 action effects, 170. See also specific action effects transitions and, 170 Action Message Format (AMF), 7, 34, 65, 247 security, 433 ActionScript 2.0 Migration page, 366 ActionScript 3.0, 27–30, 75–84, 363–387 adapter, 277 applications, 373 display list object instantiation tree, 375 Flex Builder applications v., 373, 374 object hierarchy in, 375 running, 373–374 classes, 367 Flash Player, 366, 367–371 Flex Framework, 367, 371 code, 363 considerations, 372 collection in, 109–110 compatibility with previous versions, 366–367 components, 305–318 advanced, 315–318 creation, 313–314, 315–318 development, 79–80 elements, 305–312 method invocation, 77 properties, 307–309 simple, 313–315 types, 80 visual, 77–78 control access in, 75–77 error handling, 408–415
Flex 2.0 v., 367 garbage collector, 551 JavaScript garbage collector and, 551 history, 363–364 Flash Player 9 and, 363–364 introspection in, 81–84 JavaScript v., 364 language foundation, 371 for Flash Player, 371 for Flex Framework, 371 Language Reference documentation, 374 libraries, 248, 561–571 methods, 377–381 MXML separation from, 78–79 new features in, 364–366 programming, 363–387 date types and classes in, 389–426 Project, 44, 45 validation with, 207–208 ActionScript Messaging adapter, 587 ActionScript to CFC wizard, 605 ActionScript Virtual Machine (AVM), 363, 622 AVM1, 622 AVM1/AVM2 SWF communication, 622 ExternalInterface and, 622–625 AVM2, 364 compatibility issues, 366–367, 622 ActionScript-to-Java conversion, 250–252 ActionScript-to-SOAP types, 254 activate phase, 480 Active Record CFC, 604 adapters, 268. See also specific adapters FMS and, 268, 277 message, 268 addChild ( ) method, 77, 78, 377 AddChildAction, 170 addChildAt ( ) method, 77, 377 addCommand ( ) method, 544 addEventListener ( ) method, 86 addItem ( ) method, 406 addObject method, 180 addtoCreationQueue method, 457 AddtoCreationQueueExample.mxml, 457–458 Adobe Flash Player 9. See Flash Player 9
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 666
Adobe Flex 2.0 Adobe Flex 2.0. See Flex 2.0 Adobe Labs, 561 ActionScript 3.0 libraries on, 561 resources, 561 Advanced ActionScript 3 with Design Patterns (Lott, Patterson &), 436 AdvancedMonths component, 294, 295 AdvancedMonths.mxml, 293–294 Ajax, 4. See also Flex-Ajax Bridge all logging level, 260 AMF. See Action Message Format AMF0 protocol, 247 AMFPHP, 247, 574 Apache Ant, 441 Apollo. See Engagement Platform technology, Adobe appendChild ( ) method, 421 application deployment, 479 definition, 479 Flex, 435–436, 479–527 methodologies, 479 application(s), Flex, 429–460 building, 435–436 Cairngorm Framework and, 565 code for reusability, 435 deployment environment planning and, 436 design pattern and, 435–436 directory structure determination for, 436 YouTube library and, 565–571 compiling, 439–442 debugging, 461–478. See also debugging. deferred component creation and, 453–455 deferred creation and, 449–451 deployment, 435–436, 479–527 compiling for, 493–497 considerations, 479–481 FDS2 on Tomcat, 500–508 Flex 2 SDK, RSL and, 488–493 options, 485 problems, 497–500 RSL, 485–487 run-time data access and, 498 server-side/client-side caching, 481–485 troubleshooting tips, 497–500 wrappers and, 508–526 directory structure, 429–432 proxy server and, 498–499 rich media integration and, 613 building, 613–617 inner workings of, 617–620 security, 432, 445–447 Flash Player and, 432–433 network, 432–433 open Web technology and, 433
666
startup order, 447–449 startup performance, 447 improvement of, 447–460 SWC files in, 562–564 ActionScript libraries and, 562–564 application frameworks, 532 Application type selector, 133–134 Application.application property, 77 applicationComplete, 447 ApplicationController.as, 544 mx:Application tag, 540 applications. See specific applications architectural frameworks, 532 area charts, 31, 215 high-low areas, 215 overlaid, 215 sample code, 215 stacked, 215 AreaChart component, 215 AreaSeries, 215 array(s), 399–408 adding/removing items from, 400–401 associative, 399, 403–407 constructing, 403–405 sorting keys/values in, 405–407 cloning, 408 filtering, 402, 403 indexed, 399–403 creating, 399 multidimensional, 399, 407 sorting/finding items of, 401–402 Array class, 106, 107, 108 complex data type, 390 ArrayCollection class, 106 ArrayCollection data type, 578 [ArrayElementType] metadata tag, 321 AS3 Corelib, by Adobe, 433 assets, 175 embedding, 175–177 Library Build Path with, 334 associative arrays, 399, 403–407 constructing, 403–405 sorting keys/values in, 405–407 User class and, 404 asterisk symbol, 343, 344 AsyncMessage object, 269, 270, 271 Atom and RSS libraries, 562 attribute identifier (@) operator, 420, 423 Auto Update, Flash Player, 521 Express Install v., 521 automatic positioning, 122 AVM. See ActionScript Virtual Machine AVM2. See ActionScript Virtual Machine AVM2.mxml, 624
4/20/07
12:19 PM
Page 667
CallLaterExample.mxml axis labels, 230–231 column chart with, 230 sample code, 229–230 axis properties, 231. See also specific properties axis renderers, 230–231 sample code, 230–231 axis rotation, 239–240 candlestick chart and, 239, 240 sample code, 239, 240 axis title, 230 sample code, 230 axis types, 231–232
B backgroundImage, 142 backreference group, 417 bar charts, 31, 216–218 clustered, 217 high-low area, 216 overlaid, 216 sample code, 216–217 stacked, 217, 218 BarChart component, 216 BarSeries, 216 batch-write-size property, 277 Bates, Bert, 436 Bean CFC, 604 behaviors, 72, 103, 127 applying, 127 creation, 103 using, 128–131 benchmark option, 494 BI systems. See business intelligence systems [Bindable] metadata tag, 192–193, 321–323 binding, 537 to component properties, 193–194 data, 64–65, 191–199 simple, 322 data model to custom component, 196–198 external XML file and, 195–196 one-way, 191 to variables, 192–193 mx:Binding tag, 191–192 BindWithGettersandSetters.mxml, 322–323 Birthdate component, 297 BirthdateMain.mxml, 296 Birthdate.mxml, 295–296 interface and, 302 Bitmap class, Flash, 376 code example, 381–382 BitmapData, 612 Blue Diamond, 21 body, 33, 267. See also message(s) bookmarks, 57
Boolean data type, 390 Border class, 142 borderMetrics, 142 brackets ([]) operator, 420, 423 breakpoints, 19, 20, 475 stepping and, 475 Breakpoints view, 22, 42, 472, 473, 474 bridgeName, 550, 551, 554, 555 bubble charts, 31, 218–219 sample code, 218–219 BubbleChart component, 218 bubbling phase, 85, 89–90 build tools, 441 Business Delegate, 546–547 business intelligence (BI) systems, 8 busy cursor, 158 Button class, 306 Button control, 63, 80, 124 downSkin and, 104 overSkin and, 104 upSkin and, 104 ButtonBar control, 107 ButtonLabel.as, 325 ByteArray class, Flash, 366, 408
C C icon, 22 caching client-side, 481 deployment and, 481–485 DMS item, 286 server-side, 481 deployment and, 481–485 Cairngorm Committee, 547 Cairngorm Event Dispatcher, 543, 544–545 Cairngorm Framework, 531–547 articles on, 531, 532 design patterns, 541–547. See also specific design patterns. Flex application and, 565 YouTube library in, 565–571 RIAs and, 531 RPCs and, 545 support for, 547 version 2.1, 531 view and, 537 Weather application and, 533–547 CairngormEvent class, 543 Calendar class, 393 date manipulation, 393–395 calendar dates/time values, 391 callbacks, 183 callLater ( ) method, 458–459 CallLaterExample.mxml, 459–460
667
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 668
Camera class Camera class, 612 camera, Web, 612 candlestick charts, 31, 226–227 axis rotation and, 239, 240 close value, 226 fill, 226 high value, 226 low value, 226 open value, 226 sample code, 226–227 CandlestickSeries, 226–227 Canvas container, 80 capturing phase, 84, 88–89 CartesianChart class, 236 Cascading Style Sheets (CSS), 69–70 component styling with, 101–103, 132 case type, of strings, 399 CategoryAxis, 229, 231 categoryField property, axis, 231 cell editing process, 147 events in, 149–150 prevention of, 151–152 CFC to ActionScript wizard, 605 CFCs. See ColdFusion components CFML. See ColdFusion Markup Language Channel objects, 249, 250 channels, 249, 269, 275 message, 249–250, 268, 269 ChannelSet objects, 249, 250 Charles by xk72, 433, 583 charting, Flex, 8, 213–243 advanced features, 232–244 classes, 229–232. See also specific classes. components, 31–32 effects, 240–241 examples, 213–229, 241–244 styling, 232–244 types, 31–32 ChartItem, 232 ChartItemEvent, 232 charts, Flex. See also specific charts events, 232–234 sample code, 233–234 examples, 213–229, 241–244 legend, 232 mx.charts, 31 CircleLabel component, 314, 315 class mappings, 281–283 distributed data and, 281–283 class name, 306 class selector, 69, 70, 133 classes. See specific classes CLI. See Common Language Infrastructure client-side-detection template, 508 client-side-detection-with-history template, 509
668
cloning arrays, 408 cluster element, 285 clustering. See software clustering C#.NET language, 621, 626 C#.NET Windows application LocalConnection and, 627–641 steps to create, 631 co-browsing applications, 7 code assistance, 57 folding, 57 hints, 57, 328 Design view and, 329 managed, 627 unmanaged, 627 ColdFusion 7.0.2, 247, 267, 573 configuring, 591–593 extension package, 597–606, 606 extensions for Flex Builder 2 and, 597–606 Flex 2 and, 573–606 Flex Messaging Event Gateways and, 583–587 structure of messages in, 585–587 Flex Messaging event gateways and, 583 ColdFusion Components (CFCs), 575. See also specific CFCs ColdFusion Event Gateway adapter, 267, 277 using, 587–591 ColdFusion Markup Language (CFML), 576 collection(s), 106, 109–111 in ActionScript, 109–110 change events, 115–117 features of, 109 filtering, 113–114 interfaces, 111–115 in MXML, 109 sorting, 112–113 CollectionEvent class, 115 mx.collections, 30 ColorPicker control, 107 column charts, 31, 220–221 axis labels, 230 clustered, 220, 221 gradient fill, 241–244 code for, 241–243 high-low, 220 mixed series chart and, 237 overlaid, 220, 221 sample code, 220 stacked, 220 ColumnChart component, 220 setAxisLabel function and, 230 COM interoperability. See Component Object Model interoperability ComboBox control, 63, 80, 106, 124, 290 command class, 541
4/20/07
12:19 PM
Page 669
creationIndex property command pattern, 541 command-line debugger, 475–478. See also debugging Commitment pass, 120 Common Language Infrastructure (CLI), 627 communication Flex/JavaScript, 183–187 with wrapper HTML page, 183–187 comparison operators, 396 compc compiler, 332 compc.exe, 430 compilation of Flex applications deployment phase, 493–497 testing phase, 439–442 compilers, 444, 486 compc, 332 deployment options, 494 Flex Builder project, 493 configuration options, 509 MXMLC command-line, 493, 511–512 property settings, 486 types, 493 Web-tier, 493 CompileTest.mxml, 440, 441 compile-time errors, ActionScript, 408–410 SortedMap class and, 409, 410 component(s). See also specific components accessibility, 189 customizing, 189–190 ActionScript, 305–318 advanced, 315–318 creation, 313–314, 315–318 development, 79–80 elements, 305–312 method invocation, 77 properties, 307–309 simple, 313–315 types, 80 visual, 77–78 compiling, 332–340 Flex Builder and, 332–338 Flex SDK and, 332 composite, 293, 295 MXML, 295–297 custom, 106, 163 binding data model to, 196–198 deploying, 338–340 events in, 319–321 extending, 105–106 Flex, 319–340 properties, 305–318 history management, 177 added, 177 built-in, 177 instantiation, 99–101
as item renderer, 146–147 layout, 120–121, 122–123 manual forcing, 123 rules, 122–123 life cycle, 101 events in, 101 metadata tags in, 321–331 method invocation, 77 modification, at run-time, 104–105 panel, 15 positioning, 120, 122–123 printing, 180, 181 properties, 193 binding to, 193–194 sizing, 97–98, 120, 121–124 styling, 101–103, 132 template, 297 creation, 297–298 MXML, 297–301 view, 15, 42 Component Object Model (COM) interoperability, 627 composite components, 293, 295 MXML, 295–297 concat ( ) method, 397, 408 concatenation, 397 Console view, 21, 42 constraint-based layout, 98, 121, 123–124 consumers, 33, 248, 267, 269 components, 272 creation, 272–273 selector property, 273, 274 Contact.xml file, 195, 196 containers, 61. See also specific containers drag-and-drop support for, 172–175 multi-view, 449 contributor option, 494 controls, 61, 124. See also specific controls basic, 124 characteristics, 124 data provider-based, 124 mx.controls, 30, 306 convenience variables, 476 copying arrays. See cloning arrays Corelib library, 562 Create CFC wizard, 604–605 CFC data access styles, 604 Create, Manage, and Run Configurations dialog box, 51, 52 createComponentFromDescriptor, 454–455 CreateComponent.html, 556–558 createComponentsFromDescriptors, 452–453 createCursor ( ) method, 114 creation queuing, 455 creationComplete event, 101, 449 creationIndex property, 456
669
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 670
CreationIndexExample.mxml CreationIndexExample.mxml, 456–457 creationPolicy property, 451 working with, 451–452 CreationPolicyExample.mxml, 449–451 creator option, 494 credentials, 259 CreditcardValidator component, 67, 68 cross-domain, sandboxes and, 487, 499 crossdomain.xml file, 263, 487 cryptographic algorithms, 433 CSS. See Cascading Style Sheets currentTarget property, 87 target property v., 88 cursor(s), 157 adding/removing, 157–158 busy, 158 Cursor Manager, 157 custom effects, 349–359. See also effect(s) custom error classes, 411–414 custom exception classes, 413 SortedMap class with, 413–414 custom formatters, 341–346. See also formatter(s) application running, 346 example, 345–346 reverse text, 345 custom loggers, 463, 464, 465–471, 627 custom tracing utility, 626 building, 626–627 custom validators, 200, 347–349. See also validator(s) CustomCircle.as, 330–331 customDate.parse, 391 CustomEffectApp.mxml, 352 CustomEffect.as, 350–351 CustomEffectInstance.as, 351 CustomLoggerMain.mxml, 465 modified, 470–471 results, 471 results, 469 CustomTweenEffect application results, 356 CustomTweenEffectapp.mxml, 356–357 CustomTweenEffect.as, 354–355 CustomTweenEffectInstance.as, 355–356
D D icon, 22 DAO. See Data Access Object DAO CFC, 604 DAO.cfc, 596–597 data, 191–211. See also message(s); XML, external data access, 245–286 binding, 64–65, 191–199 descriptors, 117 distributed. See distributed data.
670
flat, 108 formatting, 68–69, 208–211 grid, 180 printing, 180, 182–183 models, 194–195 custom component bound by, 196–198 data bound to, 198–199 validation of, 201–203 paging, 33 push, 7, 34, 246, 286 serialization, 250–257. See also serialization. storage, 187 shared objects and, 187–188 synchronization. See synchronization, data. validation, 67–68, 200–208, 446 errorString and, 203–204 simple, 203–204 Data Access Object (DAO), 595 .cfc, 596–597 Data Management Service, 32, 245–246, 247, 278–286 configuration, 284 destination, 284–286 file, 248 network-related properties, 285 data flow, 279 data push from servers to client, 286 distributed data, 280 application, 280–281 class mappings and, 281–283 item caching, 286 RPC v., 278–279, 591 transactions, 285–286 data providers, 106–109, 143 hierarchical, 108–109, 117–119 linear (listed-based), 108 List-based controls and, 106–107 remote, 119–120 XML, 117–119 Data Services. See Flex Data Services data types, 389–390. See also specific data types and classes, 389–426 complex, 389, 390 primitive, 365, 389, 390 DataField control, 107 DataGrid control, 106 data-management-config.xml, 248 DataModel.as, 568–569 dataProvider property, axis, 231 DataService component, 591, 592, 593 Date class, 391 calendar dates/time values, 391 date values, 393 Calendar class and, 393–395 creation of, 391–392
4/20/07
12:19 PM
Page 671
directory structures display methods, 392 manipulation, 393–395 time values, 392 unit retrieval, 392–393 Date complex data type, 390 date option, 494 date values, 393 Calendar class and, 393–395 creation of, 391–392 display methods, 392 manipulation, 393–395 DateFormatter component, 68, 69, 80, 209 DateTimeAxis, 229, 232 deactivate phase, 480 Debug icon, 441, 442 debug option, 494 debugging, 461–478 command-line, 475–478 commands for, 477–478 configuring, 476 invoking, 475–476 fdb, 475–478 Flash Debug Player and, 462–463 Flex Builder tools, 22, 23, 471–475 logging level, 260 view configuration, 42 Debugging perspective, 19, 20, 41, 471, 472–475 breakpoints, 19, 20, 475 stepping and, 475 Breakpoints view, 22, 42, 472, 473, 474 configuring, 472–474 Console view, 21, 42 Debug view, 472, 475 Expressions view, 22, 23, 42, 472, 474 Flex Builder 2 and, 19–23, 36 invoking, 472 Variables view, 21–22, 42, 472, 473, 474 deep copy, 408 default constructor, 306–307 default sizing, 97, 121–122 [DefaultProperty] metadata tag, 324 default-script-limits option, 494 deferred component creation, 453–455 deferred creation, 449–451 DeferringComponents_2.mxml, 454–455 DeferringComponents.mxml, 453 delay time(s), 156 for tooltips, 156 delete operator, 404, 423 deployment, 479. See also application(s), Flex, deployment application, 479 definition, 479 directory structures, 7, 442 basic customized, 443
Eclipse Flex Builder 2 Plugin, 443 Flex Builder 2 and, 443 FDS2, 500–508 configuration, 506–508 integrated Web-compiling environment, 439 precompile environment, 438 Tomcat and, 500–506 Flex 2 SDK, 488–493 components, 339, 340 environment, 437 Flex application, 435–436, 479–527 Flex Builder 2.0, 443–445 components, 339 methodologies, 479 SWC files, 338 Flex Builder and, 340 Flex SDK and, 340 descendant accessor (..) operator, 420, 423 describeType ( ) method, 82–83 description option, 494 design editor, 35 Design mode, 15–19, 41 developing with, 54–58 Properties view, 15–19, 42 design patterns, 435–436 books for, 436 Design Patterns: Elements of Reusable Object-Oriented Software (Gamma, Helm, Johnson, Vlissides &), 436 Design view, code hints and, 329 destinations, 33, 258, 269, 537 configuration, 265–266 Data Management Service configuration, 284–286 FMS, 275 configuration, 275–277 network properties, 276 service-related properties, 276–277 message, 268 properties, 266–267 security and, 258–259 subscribe to, 273 Detection Kit, 481 “Developing Flex RIAs with Cairngorm Micro-Architecture,” 531–532 Development perspective, 14–19, 41 Design mode, 15–19, 41 developing with, 54–58 Source mode, 14–15, 41 Outline view, 14, 15, 41 development view configuration, 41–42 device fonts, 134–135 Dictionary class, Flex Framework, 403, 404, 405 directory structures deployment, 442 basic customized, 443
671
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 672
directory structures (continued) directory structures (continued) Eclipse Flex Builder 2 Plugin, 443 Flex Builder 2 and, 443 FDS2, 439 Flex application, 429–432 determining, 436 installation Eclipse Flex Builder 2 Plugin, 431 FDS2, 431–432 Flex 2 SDK, 430 Flex Builder, 431 Tomcat, 502 dispatchEvent ( ) method, 86, 320 display classes, 381 core, 381 code examples, 381–387 display container, 375 display list, 375 advantages, 375–376 API, 365 manipulation, 377 object instantiation tree, 375 objects, 365 display objects, 374 finding, 379 working with, 376–381 display programming, 374–387 displayName property, axis, 231 DisplayObject class Flash, 75 appearance/spatial properties, 377–379 event handling, 380–381 functionality, 376–380 as UI components base, 376 Flex, 78, 85, 142 class hierarchy and, 96 DisplayObjectContainer class Flash, 375 appearance/spatial properties, 377–379 display list manipulation, 377 event handling, 380–381 functionality, 376–381 Flex, 96 class hierarchy and, 96 Dissolve effect, 129 distributed data class mappings and, 281–283 data synchronization and, 283–284 Document Object Model (DOM), 364 Level 3 event model, 365 Document Type Definition (DTD), 514 doDrag ( ) method, 172 doLater ( ) method, 458. See also callLater ( ) method DOM. See Document Object Model dot (.) operator, 420, 423
672
doubleClickEnabled property, 96 doValidation method, 347 downSkin style property, 70 Button control with, 104, 140–141 drag-and-drop operation, 171–175 containers and, 172–175 custom, 173–174 list controls and, 171–172 dragComplete event, 175 dragDrop event, 175 dragEnter event, 175 DragEvent class, 173 dragExit event, 175 DragManager class, 171, 172 dragOver event, 175 DragSource class, 173 DrawCircles.as file, 47, 48 DrawShapes class, Flash, 373 DrawShapes.as, 373, 374 drill-down charts, 234–236 pie chart and, 236 sample code, 234–235 DropDownEvent class, 85 drop-in method, 144–145 DTD. See Document Type Definition Durable property, 277 durable-store-manager property, 277 dynamic linking, 492 dynamic-url, 267
E E4X, 365, 420. See also XML classes, 420–426 introduction, 420 XML creating/destroying with, 420–423 XML namespaces and, 425–426 XML navigating with, 423–425 XML type conversion and, 426 easing functions, 130–131 Eclipse, 6 Flex Builder 2 and, 9, 10, 36 Navigator panel, 442 RDS support plugin, 597–603 Eclipse Flex Builder 2 Plugin, 10, 36 compiling with, 441–442 deployment directory structure, 443 installation directory structure, 431 ECMAScript Edition 4, 364, 420 standards, 365 editable cell, 147 editable property, 147 editedItemRenderer property, 150 editor, 40 Editor panel, 15
4/20/07
12:19 PM
Page 673
explicit sizing Editor view, 15, 41 debugging, 42 source/design, 41 editorDataField property, 148 editorHeightOffset, 148 editorWidthOffset, 149 editorXOffset, 149 editorYOffset, 149 effect(s), 72, 103, 127. See also specific effects built-in, 349 charting, 240–241 composite, 129–130 creating, 349–359 custom, 349–359 example, 350–352 embedded fonts with, 129 extending, 349 tooltip, 156–157 transitions and, 167 triggers, 357 custom, 357–359 [Effect] metadata tag, 326–327, 357 EffectInstance class, 350 extending, 350 EJB. See Enterprise Java Bean elements. See also user interface(s); specific elements UI, 161–190 XML, 418 EmailTextInput component, 313 in action, 314 [embed] tag, 324–325, 518 attributes, 518 parameters, 518–520 wrappers and, 518–520 embedding, 175–177 assets, 175–177 fonts, 129, 134, 176 benefits, 135 downsides, 135–136 effects and, 129 FlashType, 137–140 images, 175 sound files, 176–177 SWF files, 176–177 EmployeeAssembler.cfc, 595 example, 595–596 methods of, 595 enabled property UIComponent, 96 validator, 200 Engagement Platform technology, Adobe, 626 Enterprise Java Bean (EJB), 504 equality operators, 396 Erickson, Renaun, 247
error(s) ActionScript, 408–415 compile-time, 408–410 complex data type, 390 custom, 411–414 exception handling, 414–415 run-time, 408, 410–411 types of, 408 custom, 262–263 formatter, 210–211, 346 logging level, 260 strings, 211 custom, 211 synchronous, 410 ErrorReportingEnable property, 462 errorString, 203–204 event(s), 84. See also specific events chart, 232–234 class, 85 target property of, 87–88 in components, 319–321 custom, 319–321 dispatching, 319–321 flow (propagation), 84–85, 88–90 bubbling phase, 85, 89–90 capturing phase, 84, 88–89 targeting phase, 85, 89 handling, 84–93, 98–99, 446 Flash DisplayObject class and, 380–381 keyboard, 92–93 listeners, 84, 98 mouse, 85, 93 object, 84, 85 priorities, 90–91 subclassing, 85, 91–92 tooltip, 154–155 usage, 86–87 validation, 204 testing, 204–207 event gateways, 583 [Event] metadata tag, 320, 325–326, 357 EventDispatcher class, 85–86 class hierarchy and, 96 Flash, 377, 380–381 event.preventDefault ( ) method, 151 EventSample.mxml, 325–326 mx.events, 85 every ( ) method, 403 exception classes, custom, 413 SortedMap class with, 413–414 exception handling, 414–415. See also error(s) exec ( ) method, 417 executables, 430 explicit sizing, 97, 121, 122
673
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 674
Express Install Express Install, Flash Player, 520–521 Auto Update v., 521 FDS2 and configuration of, 525–526 using, 520–521 wrapper editing, and, 521–525 on FDS2, 525–526 express-installation template, 509 express-installation-with-history template, 509 expressions, regular. See regular expressions Expressions view, 22, 23, 42, 472, 474 Extended Architecture (XA) protocol, 504 Extensible Application Markup Language. See XAML Extensible Markup Language. See XML External API, 621–622 external application integration, 621–641 ExternalInterface, 26, 183, 366, 367, 549 AVM1/AVM2 SWF communication and, 622 FA Bridge and, 621, 622 LocalConnection v., 625–626 Externalizable interface, 255
F FA Bridge. See Flex-Ajax Bridge Fade effect, 129 failover, 261 fast views, 52 fault event, 269, 272 fdb, 475–478. See also debugging configuring, 476 debugger commands, 477–478 .exe, 430 invoking, 475–476 session, 477–478 FDS. See Flex Data Services FDS2. See Flex Data Services FDS2 Express, 437 file-store-root property, 277 fill, candlestick chart, 226 filter ( ) method, 403 filtering collection(s), 113–114 messages, 273–274 filtering arrays, 402, 403 filters, 170 transitions and, 170–171 financial charting components, 226, 228. See also candlestick charts; HighLowOpenClose charts findAny ( ) method, 115 findFirst ( ) method, 115 finding display objects, 379 finding/sorting array items, 401–402 findLast ( ) method, 115 Flash authoring tool, 367, 374
674
Flash Debug Player, 462–463 locations, 462 properties, 462 Flash Media Server, 612 flash packages, 365, 367 names, 367, 371 classes with, 367–371 Flash Player 9, 5–6 ActionScript as language foundation for, 371 API, 364 changes, 364 features, 365–366 Auto Update, 521 Express Install v., 521 classes, 367–379. See also specific classes. compatibility issues, 366–367 Detection KIt, 527 Express Install, 521–522 wrapper editing and, 521–526 history/timeline, 6 ActionScript 3.0 and, 363–364 process structure, 626 sandboxes. See sandboxes, Flash Player. security/technology concerns, 432 Flex and, 432–433 text updates, 366 updating, 526 without Express Install, 526–527 Flash Professional 9 preview, 367, 371, 372 download, 367 Flash Remoting, 573, 606 monitoring/testing tools for, 583 third-party plugins, 574 Updater, 573–574 using, 573–583 Flash Satay, 514, 515 flash.accessibility.*, 367 flash.display.*, 367, 368 flash.display.Graphics package, 141, 368 flash.errors.*, 367 flash.events.*, 31, 85, 365, 367, 368 flash.external.*, 369 flash.filters.*, 369 flash.geom.*, 369 flash.media.*, 369 flash.net.*, 31, 369, 370 flash.printing.*, 369 flash.profiler.*, 369 flash.system.*, 369, 370 flash.text.*, 370, 371 FlashType fonts, 136–140 embedding, 137–140 SWF creation and, 137–138 flash.ui.*, 370, 371 flash.utils.*, 370, 371
4/20/07
12:19 PM
Page 675
Flex Data Services (FDS2) flash.xml.*, 370 flat data, 108 Flex 2 Framework, 30–31 ActionScript as language foundation for, 371 application directory structure and, 429–432 classes, 371. See also specific classes. Dictionary class, 403, 404, 405 packages, 30–31 Flex 2.0 ActionScript 3.0 v., 367 applications. See application(s), Flex. basics, 25–34 class hierarchy, 95–96 ColdFusion 7.0.2 and, 573–606 earlier versions, 5 event model in, 84–93 features, 5 introduction to, 3–8 JavaScript communication with, 183–187, 549 OpenLaszlo v., 3 programming model, 25 ActionScript, 27–30, 75–84 Flex 2 Framework, 30–31 MXML, 25–26, 61 SDK, 3, 6, 245, 247 building applications for, 436–437 components compiled with, 332 components deployed with, 339, 340 deployment, 488–493 deployment environment, 437 FDS2 v., 437–439 installation directory structure, 430 RPC components with, 247 RSLs and, 332, 339 SWC files and, 332, 340 UI. See user interface(s). visual components, 54, 95–104 class hierarchy and, 96 Flex Builder 2.0, 6, 9 applications ActionScript applications v., 373, 374 compiling, 23 multiple, 45–48 running, 24, 50–52 build tools, 36 code editing in, 57–58 ColdFusion extensions for, 597–606 compiling components with, 332–338 compiling with, 441–442 configuration options, 509 Debugging perspective, 19–23, 36. See also Debugging perspective. debugging tools, 22, 23, 471–475 deploying components with, 339 deployment, 443–445 directory structure, 443
Development perspective, 14–19 Design mode, 15–19, 41 Source mode, 14–15, 41 Eclipse and, 9, 10, 36 features, 35–36 Help system, 36, 37 Dynamic, 38, 40 library, 37, 38 search scope, 38, 39 installation directory structure, 431 introduction to, 9–24 navigation features, 36 perspectives, 14, 40, 41 plugin version (Eclipse), 10, 36. See also Eclipse Flex Builder 2 Plugin. project compiler, 493 project creation, 10–13 automatic/manual, 49 external resources linked in, 49 library in, 13 multiple applications in, 45–48 naming of, 12 storage location in, 11 type of, 11 project types, 44–45 requirements Mac, 9 Windows, 9 RSLs and, 336–338, 339 shortcuts in, 58 stand-alone version, 10, 36 Start Page, 36, 37 SWC files within, 332–335 using, 35–58 workbench, 40–41, 44 customizing, 52–54 Flex charting. See charting, Flex Flex components. See component(s) Flex data. See data Flex Data Service assembler, 591 CFCs, 604 Flex Data Services (FDS2), 7, 32, 245 alternatives, 34 building for, 437–439 components, 7–8 configuration, 248–249 files, 248–249 deployment, 500–508 configuration, 506–508 Tomcat and, 500–508 deployment environment integrated Web-compiling, 439 precompile, 438 directory structure, 439 Express, 437 features, 32
675
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 676
Flex Data Services (FDS2) (continued) Flex Data Services (FDS2) (continued) Flash Player Express Install on, 525–526 Flex 2 SDK v., 437–439 RIAs and, 245, 286 RPC components with, 247 Flex Library Project, 44, 45, 488 creation, 332–333, 488 naming, 333 Flex Messaging Event Gateways, 583 ColdFusion 7.0.2 and, 583–587 structure of messages in, 585–587 Flex projects, 44, 45 creation of, 10–13 Flex Weather application. See Weather application, Flex Flex2TracePanel.as, 632–638 code functionality, 632, 638–639 in-code comments, 632 Flex2TracePanel.Designer.cs, 639–641 Flex-Ajax (FA) Bridge, 549–559 download, 550 examples, 551–555 ExternalInterface and, 621, 622 Flex Component creation, 555–559 JavaScript and, 555–559 Flex Validators and, 551–555 memory consumption issues, 551 requirements for, 550–551 FlexCoders mailing list, 547 flex-config.xml, 464 FlexDisplayObject interface, 142 Flex/JavaScript communication, 183–187 FlexMxmlServlet, 482 FlexPrintJob, 180 FlexUnit library, 562 flex-Webtier-config.xml, 464 Flickr library, 562 Flickr service, 66, 67 FLUORINE, 574 FLV stream, 386, 387 FMS. See Message Service, Flex focusIn, 358, 359 focusOut, 358 font licenses, 136 @font-face declaration, 139 fonts, 135. See also specific fonts embedding, 129, 134, 176 benefits, 135 downsides, 135–136 effects and, 129 FlashType, 137–140 TTF, 176 forEach ( ) method, 403 for...in loops, 81–82 formatString, 68, 69
676
formatter(s). See also specific formatters built-in, 208–209, 341 components, 68–69 custom, 341–346 errors, 210–211, 346 extending, 344 formatting, data, 68–69, 208–211 frameworks, 532. See also Cairngorm Framework; Flex 2 Framework application, 532 architectural, 532 articles on, 532 Freeman, Elisabeth, 436 Freeman, Eric, 436 Front Controller, 540, 543 Weather Application and, 543–544 fscommand ( ) functionality, 621 fully integrated environment (IDE), 35 Function complex data type, 390 Function objects, 402
G Gamma, Eric, 436 garbage collectors, 435, 551 integration between JavaScript and ActionScript, 551 getBirthdate method, 297 getBitmapData method, 612 getChildAt ( ) method, 76 getChildByName ( ) method, 76 getItem ( ) method, 406 getLogger ( ) method, 463 getStyle ( ) method, 128, 133 getters, 308, 309 icon, 22 getText ( ) method, 76 getTotal method, 303 results, 304 GetVideosByTagCommand.as, 567 GetVideosByTagEvent.as, 568 GetWeatherByLocation.as, 541–542 GetWeatherByLocationEvent.as, 543 global security constraint, 258 global type selector, 134 GlowingTextInput.as, 357–358 glowOffEffect, 357 glowOnEffect, 357 Google Code, 433 gradient fill, 241–244 column chart and, 241–244 sample code for, 241–243 graphical skins, 71, 104, 140–141 graphical user interfaces (GUIs), 532 Green Circle, 21
4/20/07
12:19 PM
Page 677
IViewCursor interface Grid container, 61 grid data, 180 printing, 180, 182–183 grid lines, 231 sample code, 231 groups, 417–418. See also specific groups regular expressions and, 417–418 using, 417–418 GUIs. See graphical user interfaces
H hasEventListener ( ) method, 86 HashMap, 262 HBox container, 61, 80 Head First Design Patterns (Freeman, Bates, Sierra &), 436 headers, 33, 267. See also message(s) property, 271 headless server, 494, 495 height property, 96, 105 Helm, Richard, 436 hideDelay property, 156 hideEffect property, 156 HighLowOpenClose (HLOC) charts, 32, 228–229 sample code, 228–229 ticks, 228 history management, 177–180 Accordion, 177 components and adding, 177 components with built-in, 177 TabNavigator, 177 ToggleButtonBar, 177–178 History Manager, 481 disable, 481 HitData, 232 HLOC charts. See HighLowOpenClose charts HorizontalList control, 107 HTML wrapper preferences, 444 HTTP service properties, 267 HTTPService component, 7, 65, 80 defining, 263–264 Flickr service and, 66, 67 YouTube and, 119–120
I ICollectionView interface, 111, 112–114 filtering collections in, 113–114 sorting collections in, 112–113 ICommand interface, 542 [IconFile] metadata tag, 327 Icons C, 22
D, 22 Getter, 22 S, 22 id property, 96 IDE. See fully integrated environment IExternalizable interface, 255 IL. See Intermediate Language IList interface, 111 IllegalOperationError, 411 images, 175 embedded, 175 import statements, 306 IMXMLObject, 303–304 incremental option, 494 indexed arrays, 399–403 creating, 399 Index.mxml, 291 indexOf ( ) method, 397, 402 info logging level, 260 sample code, 260–261 initialize event, 101 inline method, 144, 145–146 insert ( ) method, 115 [Inspectable] metadata tag, 327–328 install phase, 480 [InstanceType] metadata tag, 328 int data type, 365, 390 InteractiveObject class, class hierarchy and, 96 interfaces, 302. See also specific interfaces Intermediate Language (IL), 627 introspection API, 82–84 introspection, in ActionScript, 81–84 Invalidating interface, 142 invoke ( ) method, 277, 278 IResponder interface, 542 item caching, Data Management Service, 286 item editor(s), 147 benefits, 143 returning data from, 148 size/position, 148–149 item renderer(s), 143 component as, 146–147 custom, 144–147 benefits, 143 list control with, 144 drop-in method, 144–145 inline method, 144, 145–146 ItemClickEvent class, 85 itemEditBegin event, 147, 149–150 itemEditBeginning event, 147, 149–150 itemEditEnd event, 147, 149–150 itemEditorInstance property, 150 iteration::two, 531 IViewCursor interface, 114–115
677
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 678
J2EE server
J J2EE server. See Java 2 Enterprise Edition server Jakarta project, 501 Java 2 Enterprise Edition (J2EE) server, 7 Java Development Kit (JDK), 501 Java Flash Remoting, 247 Java Messaging Service (JMS), 7, 33, 246, 269 adapter, 268, 269, 277 messaging, 267 Java Open Transaction Manager (JOTM) package, 504 Java servlets, 482 Java Web applications, 245 java.lang.reflect package, 81 JavaScript, 183 ActionScript 3.0 v., 364 Flex communication, 183–187, 549 Flex Component creation with FA Bridge and, 555–559 garbage collector, 551 ActionScript garbage collector and, 551 Java-to-ActionScript conversion, 252–254 JDK. See Java Development Kit JGroups, 261 JMS. See Java Messaging Service Johnson, Ralph, 436 join ( ) method, 403 JOTM package. See Java Open Transaction Manager package JRun Web Server, 500, 501
K keyboard events, 92–93 KeyNotFoundException.as, 413 KeyNotUniqueException.as, 412–413 keySet ( ) method, 406, 407 keys/values, associative arrays and, 405–407 keywords, 372 list, 372 reserved, 372 special context, 372
L Label control, 65 labelFieldVar, 293, 294 labelFunction property, axis, 229, 231 Langdon, Kevin, 433 language, ActionScript. See programming, ActionScript language option, 494 lastIndex property, 417 lastIndexOf ( ) method, 397, 402 launch configuration, 51 layout controls, 161
678
Layout Manager, 120–121 Layout pass, 121 LayoutManagerClient interface, 142 legals, 3 legend, chart, 232 length property, 395 libraries, ActionScript 3.0, 561–571. See also specific libraries Adobe Labs and, 561 Flex application building, 565 Flex application with building, 565–571 list of, 562 types of, 562 Library Build Path, 333 assets/classes added to, 334 line charts, 31, 222–223 sample code, 222 LinearAxis, 232 LineChart control, 107 LineFormattedTarget, 463 LineSeries component, 222 LinkBar control, 107 LinkBar navigator, 62, 63 list control, 106, 143 with custom item renderer, 144 drag-and-drop functionality, 171–172 List-based controls, 106–107 data providers and, 106–107 listener property, validator, 200 Loader class, Flash, 365, 376 code example, 382–383 loadMovie ( ) method, 517 localCompare ( ) method, 396 LocalConnection, 621, 638 C#.NET Windows application and, 627–641 ExternalInterface v., 625–626 LocalConnectionTraceTarget.as, 627–628 local-trusted sandbox, 434 local-with-filesystem sandbox, 434 local-with-networking sandbox, 434 “Log4j error on Flex startup,” 461 log4j tool, 461 LogAxis, 232 LogController.mxml, 469–470 LoggerButton.mxml, 466 loggers, 463, 464 custom, 465–471, 627 logging, 259 API, 463–464 using, 465 client-side, 464–465 compiler, 464 configuration, 259 Flash Debug Player and, 462–463
4/20/07
12:19 PM
Page 679
MXML levels, 260. See also specific logging levels. overview, 461 Web-tier, 464 LoginEvent class, 91 lookahead groups, 417 Lott, Joey, 436 low-level data access, 366
M Macromedia Flash Player 9. See Flash Player 9 MacromediaFMOmega, 626, 627, 638 MacromediaMutexOmega, 626, 627 main class, 375 Main.mxml, 537–538 “man in the middle” attack, 432 managed code, 627 mx.managers.IHistoryClient, 177 map ( ) method, 403 Mappr library, 562 MaskedTextInput, 80 match ( ) method, 398 max-cache-size property, 276 max-file-size property, 277 maxRadius property, 218 MaxWarnings property, 462 McLellan, Drew, 515 MD5, 433 Measurement pass, 120 Menu control, 107 MenuBar control, 107 message(s), 33, 267 adapter, 268. See also adapters. adding info to, 271–272 body, 33, 267 broker, 269 channels, 249–250, 268, 269. See also channels. destinations, 268. See also destinations. endpoint, 268 event, 272 filtering, 273–274 flow of, 268 header, 33, 267 sending, 270–271 message agents, 33 Message Service, Flex (FMS), 7, 33, 245, 246, 248, 269 adapters, 268, 277 custom, 277–278 configuration, 274–275 file, 248, 274–275 destinations, 275 configuration, 275–277 network properties, 276 service-related properties, 276–277 message services, 267
MessageLevel.ValidMessage value, 639 MessageService.PushMessageToClients ( ) method, 278 MessageService.PushMessageToPeer ( ) method, 278 message-time-to-live property, 276 messaging, Flex architecture, 268–274 basics, 267–268 messaging-config.xml, 248 metacharacters, 416 metadata tags, 321. See also specific metadata tags in components, 321–331 list, 340 metasequences, 416 method closures, 364 methods, 309–311. See also specific methods ActionScript, 377–381 defining, 309–311 override, 311–312 Microphone class, 612 Midnight Coders, 34, 247 MiniDebugTarget, 463 mixed series charts, 236–237 column chart and, 237 sample code, 236–237 Model Locator pattern, 535 Weather application with, 535–537 modeling, data, 194–195 ModelLocator.as, 536 mx:Model tag, 194–195 MouseEvent class, 85, 93, 315 Move effect, 169 moveNext ( ) method, 114 movePrevious ( ) method, 114 MovieClip class, Flash, 375, 376 multidimensional arrays, 399, 407 multiple axis charts, 237–239 sample code, 238, 239 multiple pages, printing, 181–182 MultipleExample, 384 MultiRowTabs component, 318 MultiRowTabs.as, 315–317 mutex, 626, 638, 639 MXML, 25–26, 61 ActionScript separation from, 78–79 collection in, 109 components, 73 advanced, 293–295 composite, 295–297 creation, 289–304 custom, 73 properties/methods added to, 294–295 scoping, 291–292 simple, 289–290 styling, 292 template, 297–301
679
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 680
MXML (continued) MXML (continued) interfaces, 302 creating, 302 using, 302 naming conventions, 74 request restrictions, 446 syntax, 74 mxmlc.exe, 430, 439 compiling, 440–441 command-line, 440–441 drag-and-drop, 440, 441 wrappers and, 511–512 MyButton.as, 324 MyCustomItemRenderer.mxml, 146, 147 MyHBox.mxml, 291 myIcon class, 325 myLableStyle, 103 MyObjectComp.mxml, 303 myTextInput, 77 myVideo.mxml, 488, 489
N name qualifier (: :) operator, 420, 425 named groups, 417 Namespace class, 420, 425 namespaces, 63–64, 365 navigator containers, 62 Navigator view debugging, 42 source/design, 41 negative lookahead group, 417 network security, 432–433 new operator, 77 nextPage ( ) method, 182 nodes, 418 noncapturing group, 417 [NonCommittingChangeEvent] metadata tag, 328–330 NonCommittingChangeEventSample.mxml, 329–330 none logging level, 260 nonvisual components, 80 no-player-detection template, 409 no-player-detection-with-history template, 509 Null data type, 390 null operator, 404 NullKeyException.as, 412 Number data type, 365 NumericAxis, 229
O Object class, class hierarchy and, 96 object introspection, 81 [object] tag, 518 attributes, 518
680
parameters, 518–520 wrappers and, 518–520 object types, 364 object-oriented programming (OOP), 532 ObjectUtil’s getClassInfo ( ) method, 83–84 Odeo library, 562 OOP. See object-oriented programming open definition feature, 53 Open Source Flash Remoting gateway, 247 open Web technology, 433 OpenAMF project, 247 OpenLaszlo, 3 Flex 2.0 v., 3 operators. See specific operators optional views, 42, 43 Orange Box, 21 ordered creation, 455–458 outline view, 14, 15, 41, 53 output ( ) method, 639 OutputCallback, 639 override methods, 311–312 overSkin style property, 70 Button control with, 104, 140–141
P package statements, 305 paging element, 285 panels, 41. See also specific panels Parallel effect, 129, 130 parentApplication property, 77 parentDocument property, 77 PasswordValidator, 347 results, 348 sample application with, 348–349 PasswordValidator.as, 347–348 patterns, string, 398 Patterson, Danny, 436 percentage-based sizing, 97, 121 percentageHeight property, 97 percentageWidth property, 97 perspectives, 14, 40, 41. See also Debugging perspective; Development perspective changing, 52 PhoneBooth application, Apple, 612 PhoneFormatter, 210 pie charts, 32, 223–224 doughnut, 224 drill-down chart and, 236 sample code, 223–224 stacked, 224 standard, 224 PieChart component, 223 play ( ) method, 128, 350, 352 playerglobal.swc file, 487
4/20/07
12:19 PM
Page 681
remote sandbox plot charts, 32, 225–226 sample code, 225 PlotChart component, 225 point-to-point messaging, 268 pollMutex ( ) method, 638 pop ( ) method, 400 PopUpMenuButton control, 107 positive lookahead group, 417 preinitialize event, 101, 447, 449 preventDefault ( ) method, 151 primitive data types, 365, 389, 390 PrintDataGrid component, 182 printing, 180–183 components, 180 grid data, 180, 182–183 multiple pages, 181–182 private methods, 309 private properties, 307, 308, 309 Problems view, 42 producers, 33, 248, 267, 269 components, 269 creation, 269–270 production-mode option, 494 Program.cs, 639, 641 programmatic skins, 71–72, 104, 141–143 superclass for, 142–143 ProgrammaticSkin class, 141, 142 programming, ActionScript 3.0, 363–387. See also ActionScript 3.0 coding considerations, 372 core language features, 364–365 data types and classes in, 389–426 display programming in, 374–387 getting started with, 367–374 introduction, 363–367 properties, ActionScript component, 307–309. See also specific properties defining, 307–309 private, 308, 309 standard, 307–308 Properties view, Design mode, 15–19, 42 Alphabetical property view options, 17, 19 Category property view options, 17, 18 Standard property view options, 15–17 Common section, 15, 16 Layout section, 17, 18 Style section, 17 PropertyChangeEvent class, 116 protected methods, 309 protected properties, 307 proxy server definition, 498 Flex application deployment and, 498–499 Proxy Service configuration file, 248 proxy-config.xml, 248
public methods, 309 public properties, 307 Publish Application Source Wizard, 49, 50 publisher option, 494 Publish-subscribe messaging, 7, 33–34, 245, 268 flow, 268 push ( ) method, 400
Q QName class, 420, 424
R RDS. See Remote Development Services RDS support plugin, Eclipse, 597–603 readExternal ( ) method, 255 Real-time Messaging Protocol (RMTP), 248 RectangularBorder class, 142 Red Square, 21 reflection, 80–81 reflective programming, 81 RegExp, 415 class, 415 using, 416–417 complex data type, 390 regular expressions, 365, 415 ActionScript, 415–418 groups and, 417–418 strings and, 415–416 release phase, 479 Remote Data Services (RDS) configuration, 597, 598 Dataview, 599 Fileview, 601 Query Viewer, 600 view options, 598 Visual Query Builder, 600 Remote Development Services (RDS), 597 Remote object properties, 266 Remote Procedure Call (RPC) services, 7–8, 34, 65–66, 245, 246–247 Cairngorm Framework and, 545 calling, 264 handling results and, 264–265 components, 7–8, 65, 119–120, 263–264 defining, 263–264 with FDS, 247 with Flex 2 SDK, 247 with RPC services, 246 configuration, 265 destination, 265–266 file, 248 Data Management Service v., 278–279, 591 remote sandbox, 434
681
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 682
[RemoteClass] metadata tag [RemoteClass] metadata tag, 330 RemoteObject components, 7–8, 34, 65, 119, 575, 576 for AMF0, 247 defining, 263, 264 remoting-config.xml, 248 removeAllChildren ( ) method, 78 removeBusyCursor ( ) method, 158 removeChild ( ) method, 78, 377 RemoveChildAction, 170 removeChildAt ( ) method, 78, 377 removeCursor ( ) static method, 157 removeItem ( ) method, 406 Repeater component, 107, 161 execution process, 162–165 using, 161–162 replace ( ) method, 398 request restrictions, MXML, 446 required property, validator, 200 requiredFieldError property, validator, 200 Resize effect, 167, 169 restricted tags, MXML, 446 reverse ( ) method, 352 ReverseFormatter, 345–346 RIAs. See Rich Internet Applications Rich Internet Applications (RIAs) benefits, 4–5 Cairngorm Framework and, 531 definition, 3 FDS and, 245, 286 history, 4 rich media and, 620 Web applications v., 534 rich media, 609 RIAs with, 620 rich media integration, 609–620 audio, 610 Flex application with, 613 building, 613–617 inner workings of, 617–620 video, 610–611 RMTP. See Real-time Messaging Protocol rollout event, 352 rollOver event, 352 root node, 418 Rotate effect, 129, 169 RPC services. See Remote Procedure Call services RSLs. See Runtime Shared Libraries RSS and Atom libraries, 562 Run configuration panel, Flex, 445 Run icon, 441, 442 run-time errors, ActionScript, 408, 410–411 run-time exceptions, 364 ActionScript, 414–415 Runtime Shared Libraries (RSLs), 332 Flex applications and deployment of, 485–487
682
Flex Builder and, 336–338, 339 Flex SDK and, 332, 339 URL properties, 337
S S icon, 22 sandboxes, Flash Player, 434 cross-domain consideration and, 487, 499 local-trusted, 434 local-with-filesystem, 434 local-with-networking, 434 types, 434 sans device font, 135 Scale-9, 71, 141 scaleX property, 350 scaleY property, 350 scope, 266 scoping, 291 MXML components, 291–292 scrubDelay property, 156 SDK. See Flex 2.0, SDK; software development kit sealed classes, 364 Search dialog box, 54 search ( ) method, 398 Search view, 42 SearchForm.mxml, 569 Secure Socket Layer (SSL), 433 securities, 226 security constraint, 258 global, 258 destinations and, 258–259 Flash Player, 432–433, 434–435 Flex applications, 432, 445–447 Flash Player and, 432–433 network security and, 432–433 open Web technology and, 433 security sandbox, 434, 499 Security.allowDomain ( ), 446 seek ( ) method, 115 Sequence effect, 129, 130 serialization, 250 ActionScript-to-Java conversion, 250–252 ActionScript-to-SOAP types, 254 custom, 255–257 data, 250–257 Java-to-ActionScript conversion, 252–254 SeriesInterpolate event, 240 SeriesSlide event, 240 SeriesZoom event, 240–241 serif device font, 135 Service Capture, 433, 583 service configuration files, 248–249 Service Locator, 540, 545–546
4/20/07
12:19 PM
Page 683
style(s) ServiceAdapter.HandleSubscriptions ( ) method, 278 ServiceAdapter.Manage ( ) method, 278 Services Browser, 606 servlets, 482 container, 500 Java, 482 session-timeout property, 276 setAxisLabel function, 230 setBusyCursor ( ) method, 158 setChildIndex ( ) method, 377 setCredentials ( ) method, 259 setCursor ( ) static method, 157 SetPropertyAction, 170 setRemoteCredentials ( ) method, 259 setSelection ( ) method, 77 setStyle ( ) method, 102, 128, 133 SetStyleAction, 170 setters, 308, 309 SHA-1, 433 shallow copy, 408 Shape class, Flash, 365, 376 code example, 382–383 shared objects, 187–188 saving/reloading data from, 187–188 SharedObject, 434 shift ( ) method, 400 showDelay property, 156 showEffect property, 156 Sierra, Kathy, 436 Simple Object Access Protocol (SOAP), 65 SimpleBinding.mxml, 322 SimpleButton class, Flash, 376 code example, 383–384 SimpleMonths component, 291 SimpleStyledMonths component and, 293 SimpleMonthsMain.mxml, 290 SimpleMonths.mxml, 290 SimpleStyleClient interface, 142 SimpleStyleMonths.mxml, 292 singleton pattern, 535 sizing, 97–98, 120, 121–124 default, 97, 121–122 explicit, 97, 121, 122 percentage-based, 97, 121 properties, 121 skinning, 140 skins, 70, 104 graphical, 71, 104, 140–141 programmatic, 71–72, 104, 141–143 superclass for, 142–143 mx.skins package, 142 mx.skins.halo package, 142 slice ( ) method, 397, 400, 408 sniffer program, 510 SOAP. See Simple Object Access Protocol
soap, 267 Socket class, Flash, 365 software clustering, 261 sample code, 261 software development kit (SDK), 3. See also Flex 2.0, SDK some ( ) method, 403 Sort class, 112 sort ( ) method, 401, 402 SortedMap class, 406 compile-time errors, 409, 410 with custom exception classes, 413–414 SortField class, 112 sorting keys/values, 405–407 sorting/finding items, of arrays, 401–402 sortOn ( ) method, 401, 402 Sothink SWF Decompiler, 432, 447 sound files, 176 embedding, 176–177 source, 266, 537 Source mode, 14–15, 41 source property, validator, 200 splice ( ) method, 400 functions of, 400–401 split ( ) method, 398 Sprite class, 365, 374 class hierarchy and, 96 SSL. See Secure Socket Layer stage, 374, 375 standard properties, 307–308 startup order, Flex application, 447–449 StartUpOrder.mxml, 447–448 states, 165. See also view states States panel, 15 States view, 15, 42 StateSelector.mxml, 73 stepping, breakpoints and, 475 string(s), 395–399 case type of, 399 characters in, 395–396 combining, 397 comparison of, 396 length property, 395 patterns within, 398 regular expressions and, 415–416 representations of objects, 396–397 substrings within, 397–398 uppercase/lowercase conversion, 399 String class, 395. See also string(s) String data type, 390 string logging level, 260 style(s), 131 applying, 131 chart, 241 examples, 241–243
683
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 684
style(s) (continued) style(s) (continued) tooltips and, 154 using, 132–133 [Style] metadata tag, 330–331 mx:Style tag, 70, 540 styleName property, 97 StyleSample.mxml, 331 subclassing events, 85, 91–92 substr ( ) method, 397 substring(s), 397 by character position, 397–398 by delimiter, 398 within strings, 397–398 substring ( ) method, 397 Sun Web site, 501 super keyword, 311–312 superclass, 142 programmatic skin with, 142–143 super.play, 350 swapChildren ( ) method, 377 swapChildrenAt ( ) method, 377 SWC files, 12, 27, 28 creation, 332 Flex Builder and, 332–335 Flex SDK and, 332 deploying, 338 Flex Builder and, 340 Flex SDK and, 340 Flex application with, 562–564 ActionScript libraries and, 562–564 SWF files, 137 AVM1/AVM2 ExternalInterface and, 622–625 creation, 137 FlashType fonts and, 137–138 embedding, 176 mx:SWFLoader, 446 SWFObject, 481 switching workspaces, 43–44 SwitchSymbolFormatter class, 341 customization, 341–344 # symbol, 343 * symbol, 343, 344 synchronization, data, 32, 279 conflicts, 279 distributed data and, 283–284 synchronous errors, 410
T Tab container, 481 TabBar container, 62 TabBar control, 107 TabNavigator container, 62, 449 history managment in, 177
684
mx:TabNavigator, 449 TabSkin class, 315 tags. See metadata tags Tamarin, 364 Tamper Data add-on, 433 target node, 84 target property, 88 currentTarget property v., 88 targeting phase, 85, 89 targets, 463, 464 Tasks view, 42 TCP Monitor application, 510 template components, 297 creation, 297–298 MXML, 297–301 testing. See also debugging debugging and, 461 validation events, 204–207 text editor, 35 TextEvent class, 85 TextField class, Flash, 376 code example, 386–387 TextInput component, 313 extension, 319–320 TextInput control, 63, 80, 124 tooltip for, 153 TextInputLengthEventSample.mxml, 320–321 TextInputWithCountEvent custom component, 320 TextInputWithCountEvent.as, 319–320 this keyword, 76 multiple access, 291, 292 Thread.Sleep, 639 throttle-inbound property, 276 throttle-outbound-property, 276 ticks, 228 TileList control, 106 time values, 392 unit retrieval, 392–393 title option, 494 title property, axis, 231 ToggleButtonBar container, 62 history management added to, 177–178 ToggleButtonBar control, 107 toLowerCase ( ) method, 399 Tomcat, 500–501 directory structure, 502 FDS2 deployment on, 500–508 installation, 501 Website, 501 tooltip(s), 152–153 creation, 153 delay times for, 156 effects, 156–157 enabling/disabling, 155 events, 154–155
4/20/07
12:19 PM
Page 685
value objects (VOs) manager, 155 styles with, 154 for TextInput control, 153 toolTip property, 97, 153 ToolTipEvent class, 154 ToolTipManager class, 155 top node, 418 toString ( ) method, 396 toUpperCase ( ) method, 399 trace ( ) methods, 446, 464, 465 deletion, 446–447 TraceOutputFileEnable property, 462, 463 TraceOutputFileName property, 462, 463 TracePanel.mxml, 466–468, 628 checkbox for starting/stopping in, 629–631 updates for, 629–631 TracePanelTarget.as, 468 TraceTarget, 463 transactions, Data Management Service, 285–286 transition(s), 167 action effects and, 170 effects as, 167 filters and, 170–171 using, 167–171 view states with, 167–169 Tree control, 106 trigger(s), 103, 127 custom effect, 357–359 trigger property, validator, 200 triggerBinding event, 329 triggerEvent property, validator, 200 TrueTypeFont (TTF) families, 135 embedded, 176 try...catch...finally statements, 411, 414, 415 TTF families. See TrueTypeFont families TweenEffect class, 353 custom, 354 example, 354–357 extending, 353 TweenEffectInstance class, 353 extending, 353–354 type selector, 69, 70, 133 typewriter device font, 135
U UFO. See Unobtrusive Flash Objects UI. See user interface(s) UIComponent class, 80, 95 class hierarchy and, 96 properties, 96–97 methods, 314 implementing/overriding, 314 uint data type, 365, 390
undefined value, 390 Uniform Resource Identifier (URI), 365, 425 uninstall phase, 480 UnitsVO.as, 535 unmanaged code, 627 Unobtrusive Flash Objects (UFO), 481 unshift ( ) method, 400 update phase, 480 updateComplete event, 101 updateDisplayList ( ) method, 142 upSkin style property, 70 Button control with, 104, 140–141 URI. See Uniform Resource Identifier url, 267 URL properties, RSL, 337 URLLoader class, Flash, 365, 366 URLStream class, Flash, 366 User class, 255 associative arrays and, 404 user interface(s) (UI) building, 95–125 components, 80, 124 controls, 63 customizing, 127–159 elements, 161–190 userVO property, 91 UseTemplate1.mxml, 299 results of, 301 UseTemplate2.mxml, 300 results, 301 mx.utils, 31
V ValidateButton component, 309 Validate.mxml- Source for Validation SWF Library, 554 validateNow ( ) method, 123 ValidateSample.html- HTML Wrapper file, 552–553 validation ActionScript and, 207–208 data, 67–68, 200–208 data model, 201–203 events, 204 testing, 204–207 validator(s). See also specific validators built-in, 200–201 components, 67–68 custom, 200, 347–349 extending, 347 FA Bridge, JavaScript and, 551–555 properties, 200 Value Object CFC, 594 value objects (VOs), 534 Weather application and, 534–535
685
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 686
value types value types, 389–390 complex, 389, 390 primitive, 389, 390 values. See specific values values ( ) method, 407 values/keys, associative arrays and, 405–407 variables, 192 binding to, 192–194 Variables view, 21–22, 42 VBox container, 61, 63, 80, 197 Video class, Flash, 376 VideoDisplay control, 612 VideoListView.mxml, 570 VideoPlayer.mxml, 570–571 view, 537 Cairngorm Framework and, 537 view states, 165 transitions applied to, 167–169 using, 165–166 views, 41. See also specific views viewSourceURL property, 446 disable, 446 ViewStack navigator container, 62, 63 mx:ViewStack, 449 visible property, 97 Visual C# 2005 Express Edition, Microsoft, 621 IDE, 627 link, 621 visual components ActionScript, 77–78 Flex 2.0, 54, 95–104 class hierarchy and, 96 Visual Studio development tools, Microsoft, 626 Vlissides, John, 436 void data type, 390 VOs. See value objects
W W3C reports. See World Wide Web Consortium reports WAR file, 503 warn logging level, 260 Weather application, Flex, 533 Cairngorm Framework and, 533–547 entry point for, 537 Front controller pattern in, 543–544 Model Locator of, 535–537 VO and, 534–535 weather property, 536, 537 WeatherDelegate class, 542, 546 WeatherDelegate.as, 546 WeatherView component, 537 WeatherView.mxml, 538–540 WeatherVO.as, 534–535
686
Web applications, RIAs v., 534 Web Developer Extension for Firefox, 510 Web service properties, 267 Web technology, open, 433 WebORB, 34, 247, 574 WebService component, 7, 65, 80, 119 defining, 263–264 Webster, Steven, 531, 532 while loop, 182 width property, 97, 105 Wikipedia, 441 Windows Presentation Foundation (WPF), 4 Windows Presentation Server Everywhere (WPF/E), 4 workbench. See Flex Builder 2.0, workbench worker classes, 541 working sets, 53 workspaces, 41, 43–44 switching, 43–44 World Wide Web Consortium (W3C) reports, 514 WPF. See Windows Presentation Foundation WPF/E. See Windows Presentation Server Everywhere wrapper(s) creation, 508–509 Web standards support and, 514–517 definition, 508 editing, 521 Express Install option and, 521–525 [embed] tag and, 518 attributes, 518 parameters, 518–520 features, 509 configuration, 509, 510 defining, 510–511 features added to, 512–514 Flex application deployment and, 508–525 HTML page, 178–179 communication with, 183–187 migrating/transferring files and, 509–510 MXMLC compiler and, 511–512 [object] tag and, 518 attributes, 518 parameters, 518–520 XHTML, 514–517 writeExternal ( ) method, 255, 257 wsdl, 267
X x property, 97, 104 XA protocol. See Extended Architecture protocol XAML (Extensible Application Markup Language), 4 XHMTL 1.0 language, 514 code, 514 wrapper, 514–517
4/20/07
12:19 PM
Page 687
Zoom effect xk72, 433 XML (Extensible Markup Language), 3, 418 data provider, 117–119 documents, 418 parts, 418, 419 E4X, 365, 420 classes, 420–426 introduction, 420 XML creating/destroying with, 420–423 XML namespaces and, 425–426 XML navigation with, 423–425 XML type conversion and, 426 external data, 195 external file binding to, 195–196 introduction to, 418–419 namespaces, 63–64 XML complex data type, 390 XML User Interface Language (XUL), 4 XMLList class, 420
XMLList complex data type, 390 mx:XML tag, 195, 196 XUL. See XML User Interface Language
Y y property, 97, 104 Yellow Diamond, 21 YouTube API, 562 HTTP service component and, 119–120 library, 562, 571 Cairngorm Framework and, 565 Flex application with, 565–571
Z zero argument constructor, 307 ZipCodeValidator, 200 Zoom effect, 129, 176
687
Index
02671bindex.qxd:02671bindex
02671bindex.qxd:02671bindex
4/20/07
12:19 PM
Page 688
02671badvert.qxd:02671badvert
4/20/07
12:20 PM
Page 689
02671badvert.qxd:02671badvert
4/20/07
12:20 PM
Page 690
