0 Comments    

0 Comments    

• ItemsSource – IList value represents the set of resolved matches in the control. It also supports INotifyCollectionChanged so it can be bound to ObservableCollection allowing external changes to be propagated to the control automatically.
• DisplayMemberPath – I used a similar name here to what the ListBox control uses to determine which property is displayed when the results are shown either in the tags or the search results.
• SearchMethod –a Action dependency property provides the logic for taking the text entered and execting a query/lookup that in turn returns SearchResults. This method can be synchronous or asynchronous, so long as the returned results are placed in SearchResults.
• SearchResults – to support Synchronous or Async searching, when this property is populated search results are shown to the user. Make sure the class to which SearchResults is bound to implements INotifyPropertyChanged so TagBox is aware of SearchResult changes.

<tsm:TagBox SearchMethod="{Binding SearchMethod}" SearchResults="{Binding SearchResults}"
          DisplayMemberPath="DisplayName" ItemsSource="{Binding To, Mode=TwoWay}" />

• ItemsSource -> To (ObservableCollection)
• DisplayMemberPath = “DisplayName” which is a property of Contact
• SearchMethod -> SearchMethod(Action which points to a method FindMatchingContacts(string))
• SearchResults -> SearchResults(IEnumerable)

        #region SearchMethod (INotifyPropertyChanged Property)
        private Action<string> _searchMethod;
        public Action<string> SearchMethod
        {
            get { return _searchMethod; }
            set
            {
                if (value == _searchMethod) return;
                _searchMethod = value;
                base.OnPropertyChanged("SearchMethod");
            }
        }
        #endregion

        public void FindMatchingContacts(string searchText)
        {
            if (searchText.Length >= 1)
            {
                var contacts = from cs in ContactCollection.Members
                               where cs.EmailAddress.StartsWith(searchText, StringComparison.InvariantCultureIgnoreCase) 
                                    | cs.DisplayName.ToLower().Contains(searchText.ToLower())
                               select cs;

                SearchResults = contacts.ToList();
            }
            else
                SearchResults = null;
        }

Fig 1. Code from EmailViewModel.cs demonstrating search method

• Contacts: resolved items that were matched via search
• Text Addresses: unresolved items that may have been entered by the user

UnresolvedValidationMethod property to the TagBox where you can specify your own function for examining the text entered and returning it classed as your bound object type. In the email example I check the format of the address and return a Contact. The great thing about this is that on the ViewModel side you have a single collection that holds all the addresses, and ultimately you could decide how to deal with these newly created contacts. (for example – you could just send a message to them, or you could save them to your Contact repository when you detect that their Ids are 0)

Lastly – there could exist a set of unresolved items that would not validate (if you entered ASDF as an email address for example). These are not included in ItemSource, but can be found in InvalidItems. The logic here is that if we cannot pass the Validation method then they are not robust enough to be included in that set. Instead they are decorated (a dashed underline OOB) and you can decide how to handle them. Common ways would be

1. In an email scenario – do not allow the message to be sent until they are corrected – could present a custom UI for correcting them.
2. Prompt and allow them to be discarded
3. Discard them automatically

Validation Properties

• ValidateUnresolved – boolean property indicates whether or not validation should be performed – if true an UnresolvedValidationMethod must be provided
• UnresolvedValidationMethod – Function takes a text entry and converts it to an object compatible with the objects stored in ItemsSource. Once validated the text entry, now a correctly typed object, is placed in ItemsSource in the correct location.
• VisualState “Invalid” – The UnresolvedTag control template contains an “Invalid” state that can be customized. It is set whenever text cannot be validated.

The following code demonstrates the UnresolvedValidationMethod as implmented in EmailViewModel.cs. Note - asynchronous validation is not supported at this point.

        public Contact IsValidEmailAddress(string email)
        {
            bool valid = Regex.IsMatch(email, @"^([a-zA-Z0-9_\-\.]+)@((\[[0-9]{1,3}" +
                                              @"\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([a-zA-Z0-9\-]+\" +
                                              @".)+))([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$");
            Debug.WriteLine("Valid Email? " + email + " " + valid);
            if (!valid) return null;
            return new Contact() { DisplayName = email, EmailAddress = email };
        }

Fig 2. Code from EmailViewModel.cs demonstating text validation

Customization

TagBox is implemented as a CustomControl, meaning that its templates can be customized very easily to provided a dramatically different looking appearance. There are 3 main templates that can be customized

TagBox – this template is responsible for the actual border around the TagBox and the panels that hold the tags. OOB – it is essentially a ScrollViewer that contains a WrapPanel and a Popup (search results container)

ResolvedTag – after an item is resolved it gets translated into a ResolvedTag. OOB it has a rounded border with an X so you can remove an item from the tagbox with the mouse. A custom template could be used here to display more information about the tag if so desired. DataBinding occurs in the Content field by default.

UnresolvedTag – this holds the text entered prior to being resolved. It is a pretty simple template who’s most important component is a TextBox with very little styling.

The example below has been restyled to be more appropriate to a set of categories. (Templates are included in the sample project)

Licensing

Although I am not releasing the source code for this control, I am allowing folks to make use of the control for use in personal projects. I go back and forth on the free versus paid approach and my general rule of thumb is that if it takes me more than a week to build something, and I intend on supporting it in the future, it is worth a nominal fee. In this case I ended up putting a little under 3 weeks into the project and documenation and I think it has a lot of value.

Watermarked Control – you may use the control for non-commercial purposes so long as the "thesilvermethod.com" watermark is visible.

Business License - a non-watermarked version of the control is available. I haven't gotten my act together yet on setting up the online purchasing, but in the short term if you would like to use this, please contact me directly - bbalmer@setpowersoftware.com.

Updated 2-23-2010 You can now purchase developer licenses for TagBox here. After purchasing a license a link will be emailed to you that will allow you to download a non-watermarked version of the TagBox assembly.

Here are the details of the license.

Demo Code includes TagBox assembly and demo project shown in this blog post.

3 Comments    

Recent Posts

• In Defense of Portrait Mode
• ModalDialogManager - A simple approach to dealing with modal dialogs in MVVM
• SyncToy 2.1 - A very useful and free tool for syncronizing your files
• Connecting XBox 360 MCE to Windows 7 in a Domain
• Introducing TagBox
• Drag and Drop Upload to Azure Storage via Silverlight 4
• Architecting a Blog Engine for Windows Azure
• Hosting Silverlight Accessible WCF Services in an Azure WebRole
• Embedding Silverlight in a Windows Service
• Welcome to The Silver Method

By Month