Creating a custom rich text editor Flex 2 component with Fireworks CS3

Fireworks CS3 ships with an assortment of dynamic rich symbols. One category of rich symbols represents the visual mx.controls of Flex 2. The Flex 2 mx.controls included with Fireworks CS3 do not contain a rich text editor—a useful feature when developing Flex applications.

Using Fireworks CS3, you can extend the Flex 2 components by creating the desired functionality you want. In this article, I'll describe how to create a rich text editor Flex 2 component using the rich symbols in Fireworks CS3.

Let's get started by setting up the project files. Download the sample files provided at the beginning of this article and uncompress the ZIP archive. Notice that the sample files are separated into two folders: the starter files and the completed version of the project.

Next copy the two files from the Starter_files folder (RichTextEditor.graphic.png and RichTextEditor.jsf) to the following location, based on your operating system:

• Windows: C:\Documents and Settings\[User]\Application Data\Adobe\Fireworks CS3\Common Library\Custom Symbols
• Mac OS: HD\Users\[User]\Library\Application Support\Adobe\Fireworks CS3\Common Library\Custom Symbols

Now you're ready to launch Fireworks CS3. Make sure you are working with this version of Fireworks.

Note: When you modify the starter JSF script file, be sure to remove the old symbol instance from the Library panel and click the Reload icon command from the Common Library panel. This will allow any script modifications to be reflected in the Symbol Properties panel.

From the default Fireworks CS3 splash screen, click Create New > Fireworks Document (PNG) or select File > New. Create a document large enough to contain the custom graphic symbol. For this example, the Canvas is set to 550 width x 500 height with a white Canvas color (see Figure 1). Click OK.

At this point, it is helpful to arrange the panels in Fireworks to easily access the items you'll need. Select Window > Common Library (or press F7) to display the Common Library panel. Then select Window > Library (or press F11) to also display the Library panel. Finally, select Window > Symbol Properties to display the Symbol Properties panel.

Activate the Common Library panel by clicking its title bar and review the list of available rich symbols. You can double-click the Flex Components folder to expand its list of default symbols. If you double-click the Custom Symbols folder, you'll see the new RichTextEditor graphic symbol (see Figure 2), which was added to the Fireworks CS3 Common Library when you copied the files from the Sample_files folder into the Custom Symbols directory.

Now that you've successfully added RichTextEditor to the Common Library, proceed to the next section of this tutorial and begin customizing the symbol.

In the previous section of this tutorial, you updated the Common Library to include a new symbol called RichTextEditor. Now you can begin editing the symbol to create a custom Flex 2 component. Start by adding the RichTextEditor symbol to the Canvas.

Drag and drop the Custom Symbols > RichTextEditor symbol onto the Canvas of the new document. In the Layers panel you'll see a graphical representation of the Flex 2 Rich Text Editor control and a single Layer 1 element titled "RichTextEditor" (see Figure 3).

Double-click the RichTextEditor symbol to view the individual Fireworks symbol/widget elements; the Layers panel will display the corresponding symbol elements.

The Fireworks CS3 rich symbol/widget elements represent some (if not all) of the user-based element interactivity via the new Symbols Property panel. The symbol/widget elements of the rich symbol provide direct access to updating interactions with specific properties and/or styles of a particular Flex 2 visual component.

In this example, you can edit the symbol's elements to update the Rich Text Editor. The RichTextEditor symbol is comprised of four elements, listed the Layers panel (see Figure 4).

1. Bitmap symbol/widget Layer element is simply the background graphic and is a noninteractive element

   Note: The RichTextEditor Flex 2 component is a complex control with many subcontrols (TextArea, Container, Buttons, ColorPicker, HBox, and TextInput). For the purposes of this tutorial, the simple bitmap image provided in the downloadable sample files is sufficient. You can use the drawing tools to create your own background image for the interface of the Rich Text Editor Flex component, as desired.

   However, the next three Layer 1 symbol elements are Fireworks text objects that can be updated to provide user interactivity.

2. title symbol element corresponds to the control Label
3. htmlText symbol element is an interactive property and reflects the TextArea subcontrol of the Rich Text Editor
4. defaultLinkProtocol symbol element reflects the default linkProtocol TextInput subcontrol of the Rich Text Editor

Click Done at the top of the Edit Symbol window pane to exit and return back to document view.

After examining the elements in the symbol, you are ready to create or edit the starter script so that the three Fireworks text object elements can be configured through the Symbol Properties panel (see Figure 5).

Browse to the Common Library/Custom Symbols folder location of the copied files and open RichTextEditor.jsf in the text editor of your choice. The RichTextEditor.jsf file can be located in the following directory, based on your operating system:

• Windows: C:\Documents and Settings\[User]\Application Data\Adobe\Fireworks CS3\Common Library\Custom Symbols
• Mac OS: HD\Users\[User]\Library\Application Support\Adobe\Fireworks CS3\Common Library\Custom Symbols

As you view the base script file in a text editor, you'll see the following code:

Let's take a moment to analyze the code. Essentially, the base script is fueled by two functions. The first function sets (declares) an array of values that holds the object name, property type, and default value. The second function applies the values back to the Fireworks widget (symbol) object via the Symbol Properties panel.

The customData of flexClassName dictates the type of Flex component for the Fireworks Widget (symbol). In this example, it is RichTextEditor.

Values are pushed to the end of an array and the function returns the new length of the array. Your code will have three values in the array (starting at 0, 1, and 2 index positions):

1. name represents the interactive property element
2. type dictates Object type and, in the below three cases, just happens to be a text object (String); other property types include Boolean (true or false), Number, Color, etc.
3. value is the literal default value for the component's property name

Copy and paste the following modification into RichTextEditor.jsf (completely replacing the original code), and then save the file:

In the code above, GetObjectByName() passes the equivalent array default values [] back to the symbol (widget) as textChars type.

You've finished using the text editor to update the JSF file. Let's return to Fireworks CS3 and see how you can use the Symbol Properties panel to add interactivity to your Flex component.

Launch Fireworks CS3 if it is not already open.

In the Library panel, delete the current instance of the RichTextEditor symbol. Click the Reload icon at the bottom of the Common Library panel. Click the Custom Symbols folder to expand it and then drag a new instance of the RichTextEditor symbol onto the Canvas of your document.

In the previous section of this tutorial you updated the RichTextEditor.jsf file. After making changes to the code and reloading the symbol in the Common Library, you can see that there is now communication between the RichTextEditor custom component (RichTextEditor.graphic.png) and the Symbols Property panel. When a new instance of RichTextEditor is placed on the Canvas, the default values are reflected in the Symbols Property panel (see Figure 6).

After communication is established, any modifications to the symbol's default values in the Symbol Properties panel are automatically reflected in the symbol (see Figure 7).

In the previous section of this tutorial, you examined how updates made to the Symbol Properties panel are reflected in the symbol. After you experiment with editing the symbol in Fireworks and are satisfied with the content changes and the Symbol Properties values, navigate to the Quick Export > Flex > MXML document tab command and save the file as a new somefilename.mxml file. (Alternately, you can select the File > Export > MXML and Images menu command).

Launch Flex Builder 2 (or your favorite MXML editor) and open the exported MXML file. Take a look at the code and you'll see that the three property names and their associated property values are now appended to the mx:RichTextEditor control tag. The code looks like this:

If you compile the MXML file now using Flex Builder 2 or Flex Builder 2.0.1 SDK, you will get a functional rich text editor, although there are no event triggers.

Applying further customizations

You can make additional updates to the property values via the mx:RichTextEditor tag by configuring the x, y, width, and height values. The default property values correspond to the active object or symbol as they were captured in the Fireworks Property inspector (see Figure 8). It is important to note that after you export the Fireworks symbol to MXML, you can still make changes to the property settings.

You can manually override the default symbol width and height values by simply changing the values. For example, if you update the width and height values to 350 x 300 and then recompile the Flex application, you will see the code as shown below:

By increasing the dimensions of the component, you can add more space in the interface to allow better horizontal alignment of the Control Bar subcontrols (see Figure 9).

In this example, because the component itself inherits many other subcontrols, the interface looks better after manually overriding the default width and height properties.

The mx:Application tag contains the current Fireworks CS3 Canvas color. The default color settings for a Flex application consists of an array of two colors, so the Fireworks Canvas color property is applied in the two-color array.

You can manually change the colors of the Flex application to create a harmonic color scheme and generate a background gradient color fill. In the code example below, the top gradient color is set to black and the bottom color retains the exported Fireworks Canvas color of white:

Updating the default and public properties

You've only scratched the surface; there are many more changes and updates you could make. Each Flex 2 component consists of defaultproperties, attributeproperties, and customValues.

In this next example, you'll see how to override or update properties, styles, and custom values programmatically. You'll create a new definitionObject variable and then pass its elements back to the symbol/widget as customData. For an in-depth overview of working with definitionObject, please refer to the Developer Center article Creating Rich Symbols for MXML Export by Trevor McCauley.

To override the default width and height settings, create a definitionObject element named defaultProperties. Then use the new object to exclude the width and height properties from the array, as shown in the code example below:

Using a new object to override default properties is an ideal strategy in most situations because the Fireworks Export > MXML command always appends those properties to the component's MXML tag. This approach offers the option of relying on the default Flex 2 component size, rather than the size of the Fireworks CS3 symbol. In this example, the default size of the RichTextEditor control is 325 pixels wide and 300 pixels high.

Add some code to manually display the control bar. The next code snippet illustrates how to access the showControlBar property and add it to the array of values. Declare the array as an "attribute property," as shown below:

To review how this works in more detail, review the final RichTextEditor.jsf file in the Complete_script folder included with the sample files.

If the showControlBar public property is set to false, only the main Panel Label and the TextArea subcontrol will be displayed (see Figure 10).

Another public property that you can update is showToolTips. If desired, you can add the showToolTips property to the array of custom values as a Boolean type (true or false) object. This optional update to the code would look like this:

If you set the showToolTips property to true, each subcontrol within the Flex Rich Text Editor will display a tooltip description (see Figure 11).

Using CSS to update the component's appearance

One of the public styles available to the RichTextEditor control is the cornerRadius style property.

After you have configured the style as a custom value of the definitionObject, the Fireworks CS3 Export to MXML command will generate the appropriate Flex 2 markup and separate the class style from the class properties.

To declare and separate public class styles from attributes, you would also add them to the definitionObject, as shown in the two code examples below:

Script file (JSF)

Flex 2 markup

Note: To get a better understanding of how this works in practice, see the final RichTextEditor.jsf file in the Complete_script folder of the sample files.

By adjusting the values of the cornerRadius style property, you can change the look and feel of the Flex component. Smaller values result in a sharper corner, while higher values display a more rounded interface. To show how updating the cornerRadius values changes the display, the Flex 2 component was created with three different value settings (see Figure 12).

Note: Setting the cornerRadius property value to 0 results in no style output at all.

Where to go from here

Be sure to check out the completed sample file (RTE.png) available for download at the beginning of this article. The completed version of the Fireworks CS3 file includes an extra text layer (Label Control) and an extra button. If you investigate the file, you'll notice that the final MXML has been updated to include an event handler, which transfers the text typed into the Rich Text Editor to the Label control when the button is clicked.

If you'd like to get more information about extending the RichTextEditor class, read the RichTextEditor mx.controls documentation. To learn more about how to extend Flex 2, see the Flex 2.0.1 LiveDocs documentation.

For more information about working with symbols in Fireworks CS3, see the Developer Center article by Trevor McCauley, Creating rich symbols for MXML and Images export in Fireworks CS3.