Let's take another look at the src folder of our Flex app. Notice I've added a folder called "forms" to keep each different form in -- one for the documents in the contacts view and one for the companies view.

These two forms are based on the Form.mxml component that you can see in the net.codestore.flex.* package/folder. This Form component contains all the things common between both the forms based on it. Things like the layout of the fixed-position button bar, the validation routine, the HTTP service to fetch and post the data from the server.

Let's look at the Contact.mxml code, as below:

Notice how the main root tag is a Form. This means it is based on the Form component I mentioned. In the Form component I've defined 3 different objects that can be used to define the form -- content, buttons and the validators. Using these three properties of the Form we can quickly build a form without worrying about adding all the bits that are already in Form.mxml.

It's inside Form.mxml that we add the buttons and content in to the right place. It's also where we loop the array of validators at the point the form is submitted and prevent submission on failure.

Here's the code that runs when the Form element is first opened:

[Bindable]
public var validators:Array;

[Bindable]
public var content:Container;

[Bindable]
public var buttons:Array;

private function initForm():void{

 //Add each of the buttons passed to the form in to the action bar
 buttons.forEach(function(element:*, index:int, arr:Array):void{
  bar.addChild(element);
 });

 //Add the main form container in to the right place.
 formContainer.addChild(content);
}

That should give you an idea how it works. Notice the three public bindable properties, which we used to define the main elements of the form.

How To Open a Form

From some place in our script, say in the double-click event of the view, all we have to do in order to open a document using one of our forms is run code like this:

import forms.*;

private function openDocumentInTab(id:String):void{
 var form:Contact = new Contact();
 form.isNewDoc = false;
 form.documentUnid  = id;
 
 //Add it to the tabbed navigator
 tabs.addChild(form);
}

Because we've told it to import everything in the src/forms/ folder we can then create objects of the type "Content" (or "Company") as if they were built-in components. Thus we have access to the public properties of the objects, such as isNewDoc and documentUnid.

Obviously there's more to it than this, but hopefully you'll get the idea? The concept it quite simple and works quite well. If you need to alter the behaviour of the underlying Form element then you can do and the change will apply to all "forms" built on it.

What Next?

I think I've had enough of this Flex App Basics series of articles and I'm sure you probably have. I'm not even sure they've followed enough of a pattern to call them a series anything. They're more like random jottings that don't really piece together too well. Hopefully they'll have given you ideas on different methodologies though.

On Monday I'll package all the Contact Manager code together and upload it here. While it's nowhere near being a finished app it's good enough for you to rip apart and learn from. If I get the time to I'll try to keep adding on top of it.

While this works, it can get messy and cumbersome maintaining the set of icon files. Especially if you change your folder structure and all embedded images break. Not only that but if you embed the same icon in more than one place it takes up extra space (or so I believe) as each instance of the image is stored separately in the SWF.

A better idea is to have an icon library. This an idea I've adapted from this one. Once you get used to using a "library" there's no going back.

Here's the folder structure for the Contact Manager app. Notice the folder structure for the net/codestore/flex package, which contains all the reusable custom components I've come up with, such as the View, SearchField and FileManager.

Within this "codestore" package is a resources folder, which contains an icons folder, which, in turn, contains the silk folder with all 700+ Silk icons from FamFamFam.

Then there's the IconLibrary.as file, which looks a bit like this:

package net.codestore.flex
{
    [Bindable]
    public class IconLibrary
    {               
                        
        [Embed (source="resources/icons/silk/disk.png")]
        public static const SAVE_ICON:Class;
        
        [Embed (source="resources/icons/silk/bullet_disk.png")]
        public static const SAVE_SMALL_ICON:Class;
        
        [Embed (source="resources/icons/silk/cross.png")]
        public static const CROSS_ICON:Class;
        
        [Embed (source="resources/icons/silk/exclamation.png")]
        public static const ERROR_ICON:Class;
        
        [Embed (source="resources/icons/silk/error.png")]
        public static const WARNING_ICON:Class;
        
        [Embed (source="resources/icons/silk/information.png")]
        public static const INFO_ICON:Class;
    }
}

What this gives us a quick and easy way to get to just the Silk icons we want. The LinkButton from above would now look like this:

No need to remember if they're there or what they're called as Flex provides us with type-ahead on the IconLibrary class. If the icon you're after isn't in the library you just add a new entry for it in the IconLibrary.as file. It's then available across the whole app.

Taking it Further

You're not limited to the Silk icons, of course. Remember the attachment manager component I talked about? Notice how each file has an associated icon:

To do this I added a set of icons to a "filetypes" folder you can see above -- one for each of the common files types. In the library code I then added a method called getIconForFileName() which looks a bit like this:

public static function getIconForFileType(type:String):Class{
 var icon:Class;
 type = type.toUpperCase();
                
 if (type=="DOC" || type=="DOCX"){
  icon = IconLibrary.FILE_DOC_ICON;     
 } else if (type=="XLS" || type=="XLSX" ){
  icon = IconLibrary.FILE_XLS_ICON;     
 } else {
  icon = IconLibrary.FILE_DEFAULT_ICON;
 }
                
 return icon;   
} 

public static function getIconForFileName(fileName:String):Class{
 var tmp:Array = fileName.split(".");   
 return getIconForFileType(tmp[tmp.length-1]);
}

The Repeater that displays attachments on the form then has an easy way of getting an icon to show for the tile it represents.

You could take it even further than this if needed. I know I probably will.

Don't leave home without your IconLibrary!

Not sure why I bored you with that bit. You all knew that already, didn't you.

Flex Alternative

How do we do implement a column icon in Flex though? Using a custom column renderer, that's how.

First thing to do is create a new custom Component. I created a file in Flex Builder at /src/net/codestore/flex/ColumnIconRenderer.mxml. The content of the file is below:

<?xml version="1.0" encoding="utf-8"?>
<mx:Box xmlns:mx="http://www.adobe.com/2006/mxml" verticalAlign="middle" horizontalAlign="center">

        <mx:Script>
        <![CDATA[
                import net.codestore.flex.IconLibrary;
                
                [Bindable]
                private var _columnName:String;
                        
                public function set columnName(colName:String):void{
                	_columnName = colName;
                }
                        
                override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void {
                	super.updateDisplayList(unscaledWidth, unscaledHeight);
             
                	var tmp:Class = IconLibrary[data[_columnName].toString().toUpperCase()+'_ICON'];
                 
                	if (tmp is Class){
                         img.visible=true;
                         img.source = tmp;
                	} else { //Icon doesn't exist in library
                         img.visible = false;
                	}
                   
                }
        ]]>
    </mx:Script>
    
    <mx:Image id="img" />
</mx:Box>

The component is nothing more than a Box with an Image in the middle of it. We use the (very useful) method updateDisplayList which (as I understand it) gets called each time Flex renders or refreshes the display. In this method we look for an icon resource that matches the name specified in the column to which the renderer is tied. If the IconLibrary (more on that tomorrow) doesn't contain the icon specified we just hide the image.

Here's an example of the XML I'm sending to the Contact Manager database to use an Icon Column:

Notice the parts I've highlighted. I've defined a column called "Attachments" to go at the end of the view, which is of type "icon" and is tied to the <file_icon> node of each document. For any document that has an attachment the value will be paper_clip and the result looks like this:

The only other part to this is that you need to apply this new custom column renderer to the column of the grid. To do this, in the ActionScript that loads the XML and creates all the columns there's the following bit of code:

if (column.hasOwnProperty("@type") && column.@type=="icon"){
 var iconRenderer:ClassFactory = new ClassFactory(net.codestore.flex.ColumnIconRenderer);
 iconRenderer.properties = {
  columnName: column.valueOf()
 };
 
 col.itemRenderer = iconRenderer;
 col.width=20;
 col.resizable=false;
}

In this bit of code the column object represents the <column> node I mentioned above, where type="icon". Notice that we're passing column.valueOf() to the columnName property of the renderer. The valueOf() the column node will be "file_icon" in this case and tells the renderer which child node to get its value from for each document.

All we need to do then is set the column's width and make it fixed. Hey, presto. It works.

It goes without saying, you're not limited to one type of icon per column or one icon column per view. You can have as many columns showing as many different icons as you choose -- just like in Notes! The beauty of this componentized, server-based XML approach being that it's all controlled from within your NSF and doesn't involve re-compiling any Flash SWFs.

There's a bug in Flex which means you can't use SummaryRows with data grids that use an XMLListCollection as the data provider. Well, at least it seems like a bug to me. I've read a few people mention it online, but had no response to a question I posted on the topic or seen anything official on the matter.

Here's a demo to show what I mean. Use the buttons to load the same data but with different collection types:

Notice how the donation column only gets summarised for the ArrayCollection and not the XMLListCollection. To me this smells like a bug whereby Flex isn't casting the XML strings to a number properly when leaving it as XML, but it does when it converts the XML to Objects.

Retro-fitting an ArrayCollection can be a pain. If there's even the slimmest chance you you'll need to use SummaryRows then make sure to use an ArrayCollection from the off.

If I create a WebQuerySave agent in Java it all works well until out of the blue I'll get an error like this:

If I remove the name of the Java agent from the Form it works fine. It seems to me like Domino is just forgetting the agent exists. Although, obviously, it does still exist. I can see/edit it in Designer.

The only solution I've found is to create a new Agent and paste the code from the forgotten agent to the new one and change the WQS event in the Form to the name of the new Agent. Simple renaming the old Agent doesn't work.

Needless to say this is very annoying. I'm starting to wonder why I didn't just stick with doing everything in LotusScript.

Anybody seen this behaviour before? I'm using Domino Designer 8.5.1 and the server is Domino 6.5.

To rub salt in the wound it's now happening with a Scheduled Java Agent which is telling me "Entry not found in index" in its log. Again, I had to create the agent from scratch.

The edit option simply dispatches the View's custom "openDocument" event back to the parent application, which is where we handle opening the document.

For now the delete option is handled by the View object itself. Although it doesn't work yet I added it in as an example of using the Alert object for more than a simple "Ok" message. As you can see below if you choose the delete option you see an "advanced" Alert.

How did I do this?

Until yesterday I'd assumed that the flex Alert did nothing more than show a popup prompt with a message and an Ok button.

I presumed that, to do anything like asking a Yes/No question, it would involve creating custom components based on the TitleWindow. Doh. Turns out that Flex's Alert is akin to LotusScript's Messagebox. Here's the code for the above delete confirmation prompt:

Alert.yesButton="Delete";
Alert.noButton="Cancel";
Alert.show(
  "Are you sure you want to delete this document?", 
  "Delete", 
  Alert.YES|Alert.NO, 
  this, 
  function(event:CloseEvent):void{
    Alert.show("You pressed " + ((event.detail==Alert.YES)?"delete":"cancel"));
  },
  IconLibrary.WARNING_ICON
);

Notice that before we show the Alert we've changed the labels on the yes and no button. So, in fact it's a bit more powerful than Messagebox ever was.

I can't believe I got this far with Flex without realising this. Things just got a lot easier.

Download?

The download of all the code will come at some point. Be patient. There's just a bit more I want to squeeze in there first.

If you really want a pre-release version then visit my Amazon Wishlist and I'll send a copy over.

In age order we have my daughter, my wife, my mother and my grandmother. Their initials just happen to be M, K, M and K. Maybe there's even another Howlett lady inside Karen. Who knows.

Ask and thou shalt receive!

The vertical lists of files on the left is the "queue".  Files shown there have been selected and are waiting to be uploaded.

Notice that, if you press the Select Files button, the file dialog that appears allow you to select more than one file at a time - unlike with the counterpart HTML file upload control.

Pressing the Upload button sends them, one-by-one, to the backend document. As each file is uploaded it gets removed from the queue and added to the list on the right.

Notice also, that the tiles for existing attachments on the right now include a "Save As" link. Whereas clicking the icon for the file lets the browser decide what to do, the Save As button lets you simply save it to your disk.

It needs a little more refinement, but I think it's ready for you guys to test it.

Replacement For ActiveX?

On Friday Curt Carlson said:

Now if you could choose to upload multiple files in one shot, that would be something Domino has refused to do without active x or some other non-native functionality.

This got me thinking. While this FileManager Flex component is a part of its containing Flex app, there's no reason it can't be used standalone in a normal HTML page.

Rather than needing to install/sign/embed a 3rd party ActiveX component and restrict your users to IE you could just add this component as a Flash SWF file and let it interact with your backend Domino document in the same way you can see it doing in the Flex demo.

If you're interested I'll create a SWF and demo?

Think that looks good? Wait till you see it in action! Forgive me for saying so, but I think it's quite slick.

Open the database and then open an existing document from the view (it could work on a new document, in theory, but doesn't yet). Scroll a bit down the document and you should see the Attachments area. Browse your PC and upload files (size limit of 100kb).

Notice that when you click upload (after a brief pause) the list of file icons should update to include your new one. this isn't trickery - it's actually POSTed the file to the server and then received an updated list of attachments in return. If you see an icon for it on the document then it exists on the backend document. Click to open it if you don't believe me.

In a similar fashion, when you click remove it will update the remove the file from the backend document and receives an updated list of files, which re-renders on the right-hand-side. Not sure I like how final the remove button is. Press it and the file's gone! In the real world I think an "Are you sure?" prompt might be in order.

Note that with both uploading and removing you don't actually need to save the document in order to commit the changes.

With it being a component, adding all this functionality to your form is as easy as this:

<mx:FormHeading label="Attachments"/>
<mx:FormItem width="100%">
 <form:FileManager docPath="{parentApplication.basePath + '0/'+this.doc.@id}"
   files="{XML(this.doc.files)}" width="100%" fileSizeLimit="100000">
  <form:fileFilters>
    <mx:Object extension="*.pdf;*.txt;*.doc*;*.xls*" description="Documents"/>
    <mx:Object extension="*.jpg;*.gif;*.png" description="Images"/>
    <mx:Object extension="*.zip;*.jar" description="Archives"/>
  </form:fileFilters>
 </form:FileManager>
</mx:FormItem>

Here we're adding a new object derived from the FileManager component and passing in to it an array of file types it will allow the user to upload, as well as telling it what files exist now and what the maximum allowed file size is. All the code itself lives inside the component, making it easy to add the same functionality to more than one form.

The code for uploading the files is something I've talked about before and relies on the DominoDisableFileUploadChecks=1 Notes.ini parameter.  The code for removing files uses the %%Detach trick, which I first wrote about exactly 9 years ago to the day (now there's a spooky coincidence!).

Bug reports welcome. As are suggestions for enhancements. It's got some way to got but I think it's stable enough for use.