1. Open the Contact Manager app.
2. Change the columns that are visible by using the "column chooser" button, as below:
    
3. Quit the browser.
4. Re-open the browser and visit the app again.
5. Notice how the visible columns are the same ones as before you closed the browser!

The View component I've been developing recently now uses the Flex equivalent to the cookie - the SharedObject - to remember your choice of columns across sessions.

Note that the same column preferences are shared across all browsers on your PC as the SharedObject is per Flash player install rather than per browser.

For now it won't remember your preferred order of columns (did you know you can drag and drop columns to change the order!?). I'll work on that. Nor does it remember the width of them. I'll work on that too.

In the mean time here's the updated source code for both the Domino database and the Flex source code. Enjoy. More to come...

...can anybody think of anything else this View component is lacking before I can consider it a universal solution for all your Notes-to-Flex migration tasks?

The idea is simple. You click the icon in the column to toggle a field value on the back end document. The icon in the view is either on or off and is dictated by the value stored in the field. It's an idea I've mentioned before which I've now made into a re-usable and customizable component.

In this example I'm using the idea of being able to mark certain contacts as favourites and you can see a working example in the Contact Manager app. The component itself can be re-used in almost any scenario though.

Adding a toggle column to a View is as simple as adding one line of XML to the View's configuration, which is specified in the backend Domino database, as discussed previously.

The XML looks like this:

As you can see it's fairly easy to configure and customize. You can easily change the icon, field name and what the "on"/"off" values should be for the field. You can also add a tooltip for the column.

The Column value of "starred" refers to the name of the XML node of each document which holds the field value we're interested. When the grid is first loaded it will show the icon as on or off depending on the value in the "starred" node.

Clicking on the toggle column on sets the value of the field called "Favourite" to "1". Clicking it again sets the value to "".

To see the XML used in the demo open the Contacts view as XML. This is the XML format that defines the structure and data of the View component. Simple, no?

Taking It Further

If you want to go further than simply modifying a single field at a time and want to perform a more involved action then you can do what I tend to always do and add a self-referencing "computed for display" field to the backend Domino form called something like "Action". In the WQS agent you can then check the value of this field. If the value is something like "Approve" then you can run a set of actions against the document.

In this scenario the XML data for each row just needs to define a true/false value to let Flex know whether to show the icon as on or off depending on whether it's approved or not. The value for the fieldValueOn would be "Approve" and for fieldValueOff it would be "Unapprove". The actual XML data for approved documents would be "Unapproved" and for unapproved documents the column value would be "Approve". If that makes sense.

Summary

It's the simple little components like this that show how powerful Flex can be once you get going with it. With the View component and the components I'm adding to it I feel like this is getting to the point where it's a viable product that can be re-used in live applications. In fact I already am using it in live applications for paying customers.

In the next couple of days I'll update the downloadable version of the app with updated Flex source code. Before I do I want to blog about another addition to the code -- the ability to store a user's choice of columns across sessions using the Flash/Flex equivalent of cookies - the SharedObject. Give me a day or three.

Update: Here's the updated source code and Domino db.

First, imagine the code below:

While i<100                 
        j = 0
        html =""
        While j<i
                html = html + "split string "
                j=j+1   
        Wend
                                
        Set mail = New Email()
        mail.Subject = "Test " + CStr(i)
        mail.HTML = html
        mail.Send("jake howlett")       
                
        i=i+5
Wend

What this does is send me 20 test emails. Each email is increasingly longer than the one before it and they all just repeat the words "split string" over and over.

The code to send the email is based on my Email class. All it does is create a multi-part MIME message. Nothing out of the ordinary. If you're using the MIME classes to send emails then this probably applies to you.

At some point in the loop the length of the message will get to such a size that something very worrying happens, as you can see below:

Notice the missing p?!

The Problem

From my investigations I've concluded the following:

If you use a 3rd party mail client (like Thunderbird) to download a multi-part HTML email from a mail file on a Domino server using POP3 then the POP3 server will remove the 655th character and put a line break in its place.

Looking at the very same email in the original mail file - using the Notes client - there's no missing character.

What I've also noticed is that it only removes the first 655th char. Not every subsequent 655th char in the whole string.

Obviously this can be very, very bad. At it's least worst, like in this example, it just looks like a typo. However, I've had numerous bug reports because it's broken the string inside an HTML tag, resulting in un-clickable links or -worse still - emails that just show raw HTML.

The problem seems only to occur when sending emails where the HTML content is made up of one very long string. I guess using very long strings is generally a bad idea in any case, but there's nothing actually wrong with it, and nothing half as wrong as the server removing characters.

The Solution

What we need to do is avoid very long lines of HTML code in the email. The obvious solution is to add line breaks in the HTML as you build it in your code.

Unfortunately, in my case, I have way too many instances of code sending HTML email to make it practical to go and add new line breaks in to each email. Instead, what I did was put a fail-safe in to the Email class which sends the email. At the point it adds the HTML to the email it adds a new line at every point an HTML tag is closed, like so:

Call stream.WriteText(Replace(Me.str_HTMLPart, ">", ">"+Chr(10)))

There's still a slight chance that there could be a long string that avoids this rule, but it's unlikely enough for me to feel happy this has resolved the issue for now.

Summary

So, you've been warned. If you're sending HTML emails to a Domino server, make sure you split the HTML string down in to sizeable chunks so that users who access their email via POP3 don't see broken HTML.

It all leaves me wondering why on earth the POP3 server would replace the 655th character in the first place. Assuming it does of course. My investigation wasn't exactly extensive but, from what I can tell, it definitely looks like it does. Why though? What's significant about 655? It's not like it's a base 2 number or anything.

While I'm sure the amount of knowledge currently stored in my head doesn't even come close to pushing the limits of the human brain I do sometimes feel a bit over-whelmed when I consider how much knowledge I need to retain in order to do my daily job.

It all makes me think of the age-old saying:

Jack of all trades, master of none.

Does adding yet another skill to my tool belt mean I'll be just a little less able at one of those I already use?

Or, just as worrying, does learning something new mean something else is forgotten. Gotten rid of to make space. I remember reading that Einstein used to try and forget the phone numbers of people he no longer called, so that space was freed-up for something else.

Perhaps we each have our own amount of RAM that can be used. Perhaps this decreases with age. Perhaps I should consider stopping trying to learn more than I really need to and concentrate on getting better at the ones I do know.

Anybody ever think like this or, as I expect, am I just weird?

It was a good job I called so soon, as it had snowed during the night and the midwife on call had to come from a town about 14 miles away, which took her an hour. An hour after she arrived, so did Evelyn.

Here's a photo of her in the style of the one of Felix and of Minnie on the days they were born. She looks a lot more like her brother than her sister.

The birth was all very straight-forward, which I guess it's easy for me to say. Mother and baby are doing well.

My plan is to work from the house for at least this week and just spend an hour or so at the laptop each day to keep on top of things. At least that's the plan.

First time it happened (just outside of its 1 year warranty) they came and fixed it within a couple of weeks (and charged us for it). I remember it well, as the Hoover-supplied "engineer" left all the concrete pieces, the old drum, boxes and various other bits on our doorstep as he left. I pointed out he'd forgotten them only to be told they're not Hoover's property so not their responsibility to dispose of. Yeah, thanks for that.

But anyway, forward on just over a year later and it's happened again. The concrete that makes up the weight is in bits. Lots of bits. Oh, and lots of dust. It's everywhere. It's now obvious it's an inherent problem with the machine. Looking at the ballast it appears to be concrete of the grade you'd expect in a breeze block. Now I'm now engineer (well, actually I do have a degree in it) but even I know that's not going to last very long.

Whether the machine has an inherent problem or not the fact is Hoover's customer service is truly terrible.

Here's what happened in the five weeks since it broke:

• Rang Hoover "customer services" to tell them it had broken.
• Told them it was the exact same issue as before but they said an "engineer" would need to visit anyway.
• Before this first visit I am forced in to paying for either a £110 labour charge or taking a £159 policy with Domestic & General (D&G) to cover the labour charge and any other repairs for a year. Made sense so I went for the £159 option.
• Wait a week for a man to visit, who takes one look inside the utility room door and say "It's your concrete's gone, love". Yeah, you don't say.
• Man then puts parts on order.
• Wait a week and call. Parts still on order.
• Trouble just about every neighbour on the road to do a load of washing for us.
• Wait a week and call. Parts still on order.
• Trouble just about every neighbour on the road to do a load of washing for us.
• Wait a week and call. Parts still on order.
• Trouble just about every neighbour on the road to do a load of washing for us.
• Decide enough is enough and that we might as well buy a new one for the same cost of the policy.
• Call D&G to cancel policy. They say we can but that we'd be liable to a £90 call-out charge for the man who was charged with coming to point out the obvious.
• Realise they have us by the short and curlies and there's little we can do but wait.
• Wait a week and call. Parts still on order.
• Trouble just about every neighbour on the road to do a load of washing for us.
• Karen calls and get very irate. Not until she point our her 3rd child is due any day now does the lady take pity and decide to lodge an internal complaint and to waiver the call-out fee.
• Three days later they confirm they've cancelled and we have nothing to pay.
• We go to Argos and order the cheapest washing machine we can find.
• Due for delivery next Tuesday. Well over 6 weeks since we stopped using the other.

So we got the refund for the policy, but who won? It certainly doesn't feel like we have! We're just back where we started. No better off and certainly worse off, as we owe all our neighbours a lot of favours.

What we've learnt is that buying a top of the range branded domestic appliance is a complete waste of money. I can't remember exactly what we paid for the washing machine but it was in the region of £400. We did this in the naive belief that it was better and would last.

The machine that it replaced cost Karen about £200 and lasted her about 10 years! When I buy things I have an expected life-span for them. With something like a washing machine it's in the region of 10 years. Certainly not three.

So, what we've done (aside for vowing never to buy Hoover again) is buy a cheapo one instead. As has been pointed out to us recently "They're all just the same plastic crap inside nowadays anyway".

We've bought this new cheap one on the premise that if it breaks outside of the warranty then it is, in effect,  disposable. When the cost to repair it equals the cost of a new one what are you supposed to do? As much as I hate the idea of sending the "old" one to the tip, what am I supposed to do?

There are some things in life you take for granted until they break. I didn't realise how much we relied on a washing machine until now. Well, not so much me, but my very pregnant wife who was way more patient with this whole saga than I would have been.

It all leaves me thinking extended warranties and the like are a complete waste of money. Just buy cheap and replace it when broke. I never thought I'd be suggesting such a wasteful idea, but it's the only real option here. Hoover should be ashamed of the terrible, terrible customer service.

Let's take this one step further and allow the user to download any one of the attachments straight from the view, without having to open the document.

If you re-open the demo app you should see a new option in the columns-to-show dropdown called Attachments:

If you enable this column you'll see a dropdown box in the last column of any row that contains attachments. Clicking on a file name will launch/save it (depends on your browser preferences).

Not an essential feature in every app but a nice example of something simple to achieve that adds value in certain circumstances.

How Did I Do It?

First thing I did was change the XML that defines both the columns and the data for the grid/view. Here it is:

Notice theirs a column of type "download" which has a value of "files" and an attribute called "separator". This tell it to look for the "files" node of each document node and explode it using the value passed as a separator.

In the XML above it would give us an array of two file name strings - one for a PDF and one for a Word doc. It should be fairly obvious how this XML is produced in a Notes view, no?

In Flex, from within my View component, when looping the <columns> XML to build each column for the grid I added the following code:

if (column.hasOwnProperty("@type") && column.@type=="download"){
 var dlRenderer:ClassFactory = new ClassFactory(net.codestore.flex.DownloadColumnRenderer);

 dlRenderer.properties = {
  columnName: column.valueOf(),
  itemSeparator: column.@separator||"; ",
  view: this
 };

 col.headerRenderer = new ClassFactory(net.codestore.flex.DownloadHeaderRenderer);
 col.itemRenderer = dlRenderer;
 col.resizable = false;
 col.width=55;
}

The code for the DownloadColumnRenderer class looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Box xmlns:mx="http://www.adobe.com/2006/mxml" horizontalAlign="center" verticalAlign="middle">
        
        <mx:Script>
                <![CDATA[
                        import net.codestore.flex.View;
                        
                        [Bindable]
                        private var _columnName:String;
                        
                        [Bindable]
                        private var _separator:String;
                        
                        [Bindable]
                        private var _view:View;
                        
                        public function set columnName(colName:String):void{
                                _columnName = colName;
                        }
                        
                        public function set view(view:View):void{
                                _view = view;
                        }
                        
                        public function set itemSeparator(separator:String):void{
                                _separator = separator;
                        }
                        
                        override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void {
                super.updateDisplayList(unscaledWidth, unscaledHeight);
             
                if (data && data.hasOwnProperty(_columnName) && data[_columnName].toString().length>0){
                        button.visible = true;
                        button.dataProvider = data[_columnName].split(_separator);
                } else {
                        button.visible=false;
                }
                        }
                        
                ]]>
        </mx:Script>
        
        <mx:PopUpMenuButton id="button" icon="{IconLibrary.PAPER_CLIP_ICON}"
                click="_view.openDocumentAttachment(data.@id, button.dataProvider[0])"
                itemClick="_view.openDocumentAttachment(data.@id, event.label)"
                height="20" width="45" cornerRadius="2"/>
</mx:Box>

Notice that we've passed to the DownloadColumnRenderer the instance of the View component in which it lives. It's this instance of the View that we call the openDocumentAttachment() method on. This method looks like this and lives inside View.mxml:

public function openDocumentAttachment(docId:String, fileName:String, save:Boolean=false):void{
 var _fileRef:FileReference = new FileReference();

 var urlReq:URLRequest = new URLRequest();
 urlReq.url = parentApplication.basePath + "0/"+docId + "/$file/"+fileName;

 if (save){
  _fileRef.download(urlReq); 
 } else {
  navigateToURL(urlReq, "_blank");
 }
}

All quite straight-forward and a quick example of how useful custom renderers can be in AdvancedDataGrids.

YMMV.

Set item = web.document.GetFirstItem("dspMembers")
                
Forall v In web.document.GetFirstItem("Members").values
 Call item.AppendToTextList( "<li>"+GetUserDetails( Cstr(v), "Formal" ) +"</li>")
End Forall

No prizes for working out what those does. For each member listed in the document it adds a bullet point to the displayed list of members. How the name of the user is displayed is governed by a separate function.

This GetUserDetails() function is a bit like an extended @NameLookup for LotusScript. I keep it in my "CommonRoutines" Script Library and it's accessible from all my agents. It looks like this: 

Function GetUserDetails(username As String, detail As String) As String
        Dim uname As NotesName
        Dim userDoc As NotesDocument
        Dim userView as NotesView
        
        Set uname = New NotesName(username)
        
        If web.directory.IsOpen Then 'web.directory is "names.nsf"
        
                Set userView = web.directory.getView("($VIMPeople)")
                
                If Not userView Is Nothing Then
                        
                        Set userdoc = userView.GetDocumentByKey(uname.Abbreviated, True)
                        
                        If Not userdoc Is Nothing Then
                                
                                If detail = "Long" Then
                                        GetUserDetails = userdoc.Salutation(0) _
                                        + " " + Left(userdoc.FirstName(0), 1) + " " + userdoc.Lastname(0) _
                                        +", " + userdoc.CompanyName(0) + "<br />"+userdoc.OfficePhoneNumber(0) _
                                        +"<br /><a href=""mailto:"+userdoc.MailAddress(0)+""">"+userdoc.MailAddress(0)+"</a>"
                                                    
                                Elseif Lcase(detail) = "formal" Then
                                        GetUserDetails = userdoc.Salutation(0) + " " + Left(userdoc.FirstName(0), 1) + " " + userdoc.Lastname(0)
                                        
                                Elseif Lcase(detail) = "fullname" Then
                                        GetUserDetails = userdoc.Salutation(0) + " " + userdoc.FirstName(0) + " " + userdoc.Lastname(0)
                                                                       
                                Else 'Unknown format. Must want field value?
                                        If userdoc.HasItem(detail) Then
                                                GetUserDetails = userdoc.GetItemValue(detail)(0)
                                        Else
                                                GetUserDetails = uname.Abbreviated
                                        End If
                                End If
                        Else
                                GetUserDetails = uname.Abbreviated
                        End If
                Else
                        GetUserDetails = uname.Abbreviated
                End If
        Else
                GetUserDetails = uname.Abbreviated
        End If
        
End Function

The idea is that, given a name like Jake Howlett/ROCKALL it uses the address book to return a name in the form Mr J Howlett, Rockall Design ltd, Nottingham. Or you can just use it to get a field's value by name. If for any reason it can't find the user document or work out what to return it just returns the user name in abbreviated form.

It all works well, but, after not very long I noticed the WQO agent which used it was taking longer and longer to run. The slowness of the WQO was directly proportional to the number of Members. Most of you can probably see why. If not, then the title of this page should give you a clue.

The problem with my code is, of course, that I'm repeatedly calling the getView() method. Consider this from Julian's list of preformance tips:

If you need to use a reference to a view multiple times in your code, get the view only once and share the reference (either using a global or static variable, or by passing a NotesView object as a parameter in functions/subs/methods). Accessing views using getView is a very expensive operation

It turned out that each call to web.directory.getView("($VIMPeople)") was taking 0.3s. For 100 members that means it takes way, way too long to open. Remember no web page should take longer than 7s to open!

So, taking Julian's advice I turned the user view in the directory in to a global variable as part of the WebSession class. Agents that were taking 20 seconds or more to load are now taking less than one!

I had no idea this was such bad practice. More than ten years with Notes and I'm still learning the basics...

Download the Zip file and extract the NSF to your server and the Zip within the Zip to your PC somewhere. Then, from within Flex Builder, go to File -> Import and browse to this Zip. This will import all the code as a ready-to-compile project.

Before you run it - once it's imported - open the Constants.as file from the root "/src" folder and then change the default path to wherever you put the NSF. Save the file and hit the compile/run/play button (green triangle). It should compile and run. You can then start adding documents to the backend database in Notes. Et voila.

As a recap, here are the ten posts I've made over the last month or so, which describe various aspects of the code:

1. Building Your Views Remotely
2. Extending Basic View Behaviour
3. Using Components To Simplify Your Code
4. Opening Documents From a View
5. Managing Document Attachments
6. Multiple File Uploads (note: read the comments to this post if you plan on using it!)
7. Alert Is To Flex as MessageBox Is To LotusScript
8. Display Column Values As Icons
9. Creating an Icon Library
10. The Form Container

What it's not is a step-by-step guide that let's a beginner get to grips with Flex development. If you're looking for a more in-depth guide to learning Flex basics then you could try this comprehensive series of screencasts.

What it is is an ill-thought-out series of ramblings with very little coercion. By making it a numbered series I may well have given the wrong impression. Sorry. While each of the ten posts has its own merits there's little point reading them in order, really. Although, if you're going to pick apart the Flex app itself it might be worth doing so.

Even if you have no use of a Contact Manager (heck, if you needed a contact manager then this probably isn't of much use anyway) the Flex app represents a conglomeration of as many of my current "best practices" as I could squeeze in. The code contains a lot of the goodness that I've learnt over the past year or more of my love affair with Flex. Primarily it demonstrates the ever-important concept of using re-usable components wherever possible.

Enjoy. If you have any questions, let me know...

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.