Adding hyperlinks with TLF

TLF-based text controls support hyperlinks with the LinkElement class. To insert a hyperlink into the TextFlow, you use the <a> tag in a <s:textFlow> tag or the default property, or create an instance of the LinkElement class.

You can only use hyperlinks in a TextFlow object in the TextArea and RichEditableText controls. The Spark Label, TextInput, and RichText controls do not support hyperlinks.

The default behavior of a LinkElement object in the text object model is to launch a new browser window and navigate to the location specified in the href property of the LinkElement object. The following example shows a basic navigation link:
<?xml version="1.0"?>
<!-- sparktextcontrols/SimpleLinkElement.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

        <s:RichEditableText id="richTxt" 
            editable="false" 
            focusEnabled="false">
            <s:textFlow>
                <s:TextFlow>
                    <s:p>
                        The following link takes you to: <s:a href="http://www.adobe.com">Adobe.com</s:a>
                    </s:p>
                </s:TextFlow>
            </s:textFlow>
        </s:RichEditableText>

        <s:RichEditableText id="richTxt2" 
            editable="true" 
            focusEnabled="false">
            <s:textFlow>
                <s:TextFlow>
                    <s:p>
                        Hold CTRL key down when using the following link: <s:a href="http://www.adobe.com">Adobe.com</s:a>
                    </s:p>
                </s:TextFlow>
            </s:textFlow>
        </s:RichEditableText>
        
</s:Application>

The executing SWF file for the previous example is shown below:

To ensure that your links use the hand cursor when the user mouses over them, set the editable property to false on the RichEditableText object. If you do not, then your user must hold the Control key down while moving the cursor over the link to be able to click on that link.

The LinkElement is the only flow element that supports Flex events. Supported events include click, mouseDown, and rollOut.

While the default behavior of the LinkElement object is to launch a new browser window and open the specified link as a new page, you can also define a custom event handler for the click event. The easiest way to do this is to exclude the href attribute from the anchor tag.

The following example defines custom behavior for the click event of the LinkElement object. It does not specify a destination link in the LinkElement, but instead builds one in the click event handler:
<?xml version="1.0"?>
<!-- sparktextcontrols/CustomLinkElement.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

    <fx:Script>
        <![CDATA[
            import flashx.textLayout.events.FlowElementMouseEvent; 
            import mx.collections.ArrayCollection;
        
            [Bindable]
            public var myArray:ArrayCollection = new ArrayCollection(["Flex", "Flash", "ActionScript"]);

            private function handleClickEvent(e:FlowElementMouseEvent):void {
                var url:String = "http://www.google.com/search?q=" + productList.selectedItem;
                navigateToURL(new URLRequest(url), '_blank');
            }    
        ]]>
    </fx:Script>

    <s:RichEditableText id="richTxt" 
        editable="false" 
        focusEnabled="false">
        <s:textFlow>
            <s:TextFlow>
                <s:p>
                    Search for product info on <s:a click="handleClickEvent(event)">Google</s:a>
                </s:p>
            </s:TextFlow>
        </s:textFlow>
    </s:RichEditableText>

    <s:ComboBox id="productList" dataProvider="{myArray}" prompt="Select one"/> 
    
</s:Application>

The executing SWF file for the previous example is shown below:

You can also suppress the click event in the event handler by calling the stopPropagation() and preventDefault() methods in the click event’s handler.

The stopPropagation() method prevents processing of any event listeners in nodes subsequent to the current node in the event flow. The preventDefault() method cancels the event’s default behavior.

You can then access properties of the LinkElement object to carry out additional actions. The following example presents the user with an option of navigating to the target location or cancelling the action:
<?xml version="1.0"?>
<!-- sparktextcontrols/CustomLinkElementHandling.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

    <fx:Script>
        import flashx.textLayout.events.FlowElementMouseEvent;
        import flashx.textLayout.elements.LinkElement;
        import mx.controls.Alert;
        import mx.events.CloseEvent;
    
        private var linkTarget:String;
    
        private function doSomething(e:FlowElementMouseEvent):void {
            e.stopImmediatePropagation();
            e.preventDefault();

            var le:LinkElement = e.flowElement as LinkElement;
            linkTarget = le.href;

            Alert.show("You are about to navigate away from this page.","Alert",Alert.OK | Alert.CANCEL, this, alertListener, null, Alert.OK);
        }

        private function alertListener(e:CloseEvent):void {
            if (e.detail == Alert.OK) {
                navigateToURL(new URLRequest(linkTarget), '_self')        
            }
        }

    </fx:Script>

        <s:RichEditableText id="richTxt" 
            editable="false" 
            focusEnabled="false">
            <s:textFlow>
                <s:TextFlow>
                    <s:p>
                        The following link takes you to: <s:a href="http://www.adobe.com" target="_blank" click="doSomething(event)">Adobe.com</s:a>
                    </s:p>
                </s:TextFlow>
            </s:textFlow>
        </s:RichEditableText>
        
</s:Application>

The executing SWF file for the previous example is shown below:

The default styling for a LinkElement is underlined, blue text. To style the links in TLF, you can use a SpanElement object and set style properties on that. The following example removes the underline, and makes the link color red rather than blue:
<?xml version="1.0"?>
<!-- sparktextcontrols/StyledLinkElement.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

        <s:RichEditableText id="richTxt" 
            editable="false" 
            focusEnabled="false">
            <s:textFlow>
                <s:TextFlow>
                    <s:p>
                        The following link takes you to: <s:a href="http://www.adobe.com"><s:span color="0xFF0066" textDecoration="none">Adobe.com</s:span></s:a>
                    </s:p>
                </s:TextFlow>
            </s:textFlow>
        </s:RichEditableText>

</s:Application>

The executing SWF file for the previous example is shown below:

You can also use the TextLayoutFormat class to style hyperlinks. For more information, see Applying styles with the TextLayoutFormat class.