What field type should you use when creating number based site columns as part of a SharePoint feature?

Windows SharePoint Services 3.0 provides you with an extensible and flexible method of developing and deploying Site Columns and Content Types (both of which are required for most SharePoint projects requiring list or library based data storage) via the feature framework (more on this in my next full article.) However there is an interesting behaviour when working with a column or field which is required to hold a number, which I thought I would blog about today.

When creating Site Columns in the browser you get a nice rich UI in order to choose the properties of this field:

However when you are recreating this as a feature defined in CAML (Collaborative Application Mark-up Language), which is a type of XML (more on this in my article) then you do not get such a rich experience.  You would need to add something like this to the element manifest defined in your feature:

<Field SourceID="http://schemas.microsoft.com/sharepoint/3.0"
       ID="{C272E927-3748-48db-8FC0-6C7B72A6D220}"
       Group="My Site Columns"
       Name="MyNumber"
       DisplayName="My Number"
       Type="Numeric"
       Commas="FALSE"
       Decimals="0"
       Required="FALSE"
       ReadOnly="FALSE"
       Sealed="FALSE"
       Hidden="FALSE" />

OK, its not as nice as the browser UI but I can deal with this.

Hang on.

Commas="FALSE" and yet for my number 1234 I get 1,234.  That is not what I wanted or expected.  What gives?

The answer lies in the difference between a type of "Numeric" which is an implementation of the SPFieldNumber class and "Integer" which does not correspond to a given SPField class but rather represents a positive or negative integer.  The numeric type does not respect the settings of Commas or NegativeFormat (which defines how to display negative numbers.)  So we can set the Type to Integer and we are good to go.  Yes?

Sadly no!

You will notice at this point that if you deploy your site column into SharePoint something has gone wrong.  Your site column is not listed in the Site Column Gallery.  The deployment must have failed then?  But no, a quick look at the site columns via the API reveals that the column is there.  What new evil is this?  Unfortunately the base type for integer fields has this lovely attribute set on it:

UserCreatable = FALSE

So WSS 3.0 accordingly hides your field in the gallery as you cannot create fields of this type.

However!

You can use them in content types just like any other field (except not in the browser UI), and if you add them to the content type as part of your feature then they will show up in the UI as a field on that content type. 

Most of the time you are not going to be too concerned that your site columns are not listed in the gallery as you will know that they are there and that they are still useable. So not as bad as you thought after all.  Just a little quirky.  But that is SharePoint for you.

If your looking at the public beta of SharePoint 2010 and thinking, "We are going to need to upgrade, but where do I start?" then hopefully this basic guide should help you on how to plan and what action to take in preparation for an upgrade.

Upgrade vs. Migration

In my view there are two significantly different approaches to an upgrade.  One would be a traditional upgrade where you are upgrading your existing infrastructure and then upgrading your binaries and content.  The other would be creating a new infrastructure entirely and then migrating all your content from one to the other (upgrading it in the process.)  The benefit to this approach being that you are not taking any excess baggage with you (see below.)  Both approaches have significant advantages and disadvantages and will probably come down to issues of budget or politics or both any way.  I am going to look at preparing your environment for a traditional upgrade.

Planning, planning, planning and more. you guessed it!

1. Document your environment thoroughly.  You cannot upgrade effectively if you don't know what you have to begin with.  If you already have documentation then make sure it is up to date.
   
   
2. Initiate some thorough performance analysis on you hardware.  If it's not performing great then this is the time to be putting in budget requests for new kit and planning your infrastructure upgrades.  Management like figures so get some raw stats in place to back up your requests.
   
   
3. Customisations - ensure they are documented thoroughly (as above) check your infrastructure for rogue customisations that you might not be aware of.  Look in the GAC, 12 Hive, Add/Remove Programs, Solutions store, and anywhere else for undocumented customisations.   If you use 3rd party tools/add-ons then contact your ISV.  What are their plans for 2010?  What is their roadmap for these?  Does it fit in with your plans?
   
   
4. Put together an Upgrade Strategy.  It will make more sense if you get it all down on paper and it will allow you to see any gaps or issues.  Show it to other stakeholders and get some feedback you are guaranteed to have missed something.
   
   
5. There are lots of stakeholders and interested parties who are going to need to know what is happening when.  Create a communications plan. Who will be told what and when.
   
   
6. An upgrade to 2010 is going to have an impact on end users (obviously), so create a training plan.  Who will be trained when and to what level, and who will deliver that training.  Costs should be built into budget plans for this year.
   
   
7. Consider some of the other issues at this time:
   • Are you going to install a sand box for the developers to play with?
   • Are you going to run a pilot scheme?
   • Are you going to run concurrent 2007/2010 environments?
     

Preparing your environment

1. Are your MOSS 2007 (or WSS) environments up to at least SP2?  I would say get them to at least the latest CU (December CU at the moment.)
   
   
2. Run the upgrade check tool that has been provided in SP2 (that is why it is there).  The command is stsadm -o preupgradecheck.  This will generate a HTML report (similar to that shown below) which will details any issues that should be fixed prior to an upgrade.
   
   
   
   
3. Deal with the issues raised above.  The tool has been written for a reason, if you don't deal with all the issues raised by this tool in some way then you are setting yourself up for a fall.
   
   
4. Offload all your excess baggage.  And by this I mean go through your environments and remove any templates, features and site definitions which are not being used.  You can always restore them to the new farm later if need be.  Also check your server event logs and ULS logs.  Ensure that all recurring issues are fixed before you upgrade.  Additionally archive any unused sites (do not delete them though, just in case!)
   

Upgrading the infrastructure

1. All your servers are going to need to be running on 64 bit OS, so the majority of older farms are going to need full OS installations on all the servers.
   
   
2. Look back at the performance analysis you did in the planning phase, can you see any areas that require beefing up.  Need more RAM in your indexing server?  Might it be best to perform your indexing on a physical box where before it coped on a VM?
   
   
3. How are you going to upgrade all this hardware?  The easiest way is to add a new server in to your farm and then 'swing' each of the old servers out one at a time to be blown away and rebuilt as the specifications demand.  The new server is there to handle some of the excess load from the different servers as your remove them.
   

Testing

1. Test every step of your upgrade path in a non-production environment first. 
   
   
2. If you have the resources then build an evaluation farm as an exact replica of your live environment.  You can then use this to test out your upgrade strategy to ensure all works as planned.
   
   
3. Once you have performed an evaluation upgrade then review it and ensure that everything went to plan.  Revise your plans of the back of this evaluation.
   

What about the dev team?

1. Don't forget to plan an upgrade of your dev and testing platforms.
   
   
2. Does you dev team now need 64 bit desktops or are they going to develop on VM?
   
   
3. Will you upgrade the dev team to Visual Studio 2010?  The tooling is significantly improved, so I would say that should be a big 'yes'.
   

Other issues to consider

1. IE6 support has been dropped in SP2010, this will have a dramatic effect on your content authors /contributors if they are still running on IE6.  Upgrade!
   
   
2. This would be a great time to revisit your Information Architecture using some of the new support for managed meta data and importing taxonomies.  Separate project, but seriously now is the time!
   
   
3. Same goes for look and feel really.   Your sites will upgrade in 2007 rendering mode, but look to upgrade the visuals as soon as you can (it's only one button click, but you'll have to ensure that your CSS and JavaScript is set up to cope with some of the new web part renderings - that's what the evaluation farm is there for though.)
   

Essentially the upgrade path comes down to three things.

1. Plan everything
   
2. Prepare for anything
   
3. Test everything
   

I hope that this little whistle-stop tour of the upgrade path has helped.  If nothing else it means that I have got all this stuff down to refer to myself.

Note: Look here for more information on what is available in SharePoint 2010.

I am going to start with a quote that I want everyone to remember.  It should be in the mind of anyone developing InfoPath solutions for SharePoint.

"Never, ever publish an InfoPath form directly from InfoPath into a production SharePoint environment."

I have seen this too many times and it will make your administrators really rather grumpy.  The reason is that although InfoPath will package your form up in a WSP (that's a good thing), unfortunately it will give the WSP and the associated feature a GUID for a name (although the feature will display an appropriate friendly name in the UI.) 

What's the problem with that?  Well, the problem will come when you try and find the WSP or feature that deploys your form because you want to make some change.  You'll end up trawling through the feature directory to find the folder which contains your template.

A much better solution is to develop your own feature to deploy your form template, and to do this is really rather simple, more information can be found here.

The real benefit to deploying your templates in this fashion is that you can deploy your feature within your own WSP.  Rarely have I come across a SharePoint project which is just a single InfoPath form,  more likely it's a series of forms, or more often a form as part of a wider solution involving workflow, event receivers and other components.  Therefore being able to bundle this feature in with other components in your WSP can prove invaluable.

What happens during feature deployment?

If you have followed the instructions within the article above then you will be using a feature which utilises the XsnFeatureReceiver class from within the Microsoft.Office.InfoPath.Server assembly.  But what does this feature receiver actually do?  It has two functions as far as I can tell:

1. In the FeatureInstalled event of the feature receiver any .xsn files included within the feature are registered to the farm using the RegisterFormTemplate method of the FormTemplateCollection.  These will then show up in Manage Form Templates within Central Administration.
   
2. In the FeatureActivated event of the feature receiver (this is run when you activate the appropriate feature in Site Collection Features) the form template is copied to the FormServerTemplates directory within the root web of the site collection.  At the same time a site content type is created which uses this template and which includes the fields promoted within the template.  It's more difficult to know exactly what this code is doing as the code has been obfuscated.

These are just some insights and thoughts around this process.  There does seem to be a lot of information out there but I cannot find one clear guide on the whole process.  This might be a subject for a future article.

If you have played around with the dialog widget in JQuery UI you may have noticed a couple of things.

1. Like a lot of JavaScript libraries it messes with the DOM (Document Object Model) at what might be unexpected times and therefore it does not play well with SharePoint.
   
   
2. It breaks the web part verb menu (the 'edit' drop down menu)

Actually it (like a lot of the JQuery UI widgets) is an incredibly powerful tool to your client side arsenal, and as long as you adhere to some best practice it will work perfectly happily within SharePoint, or any other ASP.Net site.

1. It messes with the DOM.

Specifically it does not play well with the ASP.Net page post back model. This is fairly well documented across the Interweb (although the actual solution is not).

The dialog widget is initiated via code similar to this:

$('#dialog').dialog();

When JQuery sees this it initiates the widget and actually moves your entire div tag to the root of the DOM (see screenshot below). Therefore outside of the form tag. So any ASP.Net controls which you may have in this div will not be included in any post backs therefore none of their events will fire.

Never fear however as this is easily fixed by moving the parent element of your div, which will be another div which is created by JQuery and putting this at the root of the form instead (see code sample below).

2. It breaks the web part 'edit' menu.

Actually it doesn't. But if you have followed some code examples that are out there then it might. Essentially it may mess with this if your call to initiate the dialog is happening before the page has entirely loaded.

Fortunately JQuery has a handy way of ensuring that no matter where your code is defined on the page it will only run when the page has loaded up. This is simply accessed using:

$(document).ready();

Any function supplied to this method will be loaded in memory and run when the page has finished loading. How great is that!

As long as you follow these two items of best practice you should have no problems using the JQuery dialog widget from within SharePoint.

Code

The following code example is how I would use the dialog widget. At some point you need to run the initiateModalDialog method passing in the id of the div to use as a dialog. This will then run when the page is loaded and will initiate your dialog.

When you want to show it then call openModalDialog and optionally (because JQuery will render a nice close button in the top tight hand corner) you could call closeModalDialog to close it.

Note: If you are using this within a web part then make sure your selector (the id of your div) is unique to your web part in case you have multiple web parts on the same page.

function initiateModalDialog(selector) {

//initiates the dialog when the page has finished loading
$(document).ready(function() {    

    $('#' + selector).dialog({   
        autoOpen: false,   
        bgiframe: true,    
        draggable: false,   
        width: 600,   
        resizable: false,   
        modal: true,   
        show: 'slide' 

    });  

}); 

}

//Opens the selected div as a modal dialog
function openModalDialog(selector) {

    //Opens the dialog
    $('#' + selector).dialog('open');           

    //Appends the dialog to the ASP.Net form to allow postbacks
    $('#' + selector).parent().appendTo($("form:first"));   
}    

//Closes the selected div dialog
function closeModalDialog(selector) {           
    $('#' + selector).dialog('close');  
}

Obviously the options which are passed to the initiation method such as 'draggable' and 'resizable' are up to you, but for this to work you must set autoOpen to false otherwise your dialog will open straight away (unless that is what you intended of course).

For further information please read the JQuery UI dialog widget documentation.

Creating a workflow from SharePoint Designer is limiting in many ways, but it's also very quick and easy, and it covers a large majority of every day scenarios. One of the major flaws for me has always been the inability to select 'Person' as a data type for an initiation variable (assuming that this would render a nice people picker control in the initiation form and maybe pass back the User ID to the workflow).

I have been determined to resolve this and have come up with a quick and easy fix using some bespoke client side code within the initiation form.

First of all create a new SPD workflow. Give it a name and select your list. Ensure that 'Allow this workflow to be started manually' is checked (so we get an initiation form generated for us).

1. Select Initiation. and Add.
   
   
2. In the Add Field dialog enter a Field name, in my case 'email' and select 'Single line of text'.
   
   
   
   
3. Leave Default value blank and click on Finish. Then OK.
   
   
4. Back in your Workflow Designer click Next.
   
   
5. In this simple example I am just going to send an email, so click Actions and select Send an email. Click on 'this message' to define your email.
   
   
6. Click the address book on the To: line and in the Select Users dialog select Workflow Lookup. and click Add >>.
   
   
7. Define your workflow lookup as Source: Workflow Data and Field: Initiation: email (or whatever you called your initiation variable)
   
   
   
   
8. Click OK. Then OK again.
   
   
9. Enter a value in Subject: And also for the body text. Click OK.
   
   
10. Now click Finish as we are done creating this simple workflow.
    
    
11. If you open up the folder structure which SPD has created under Workflows you will see that there should be three files created:
    
    
    1. the xoml file
    2. an xml config file
    3. an aspx page
       
       
       
       
12. The final one is the one we are interested in as this contains the initiation form for our workflow.
    
    
13. Double click on this so we can take a look.
    
    
14. You will note that essentially this is a standard SharePoint page with a DataFormWebPart which is set up to pass the initiation data to our workflow. In this case we should have a single text box for our initiation variable.
    
    
15. If you look at the code view you will see that various assemblies and namespaces have been included within this page already. Including the Microsoft.SharePoint.WebControls namespace which contains the PeopleEditor control. This is the key to getting people data from the users.
    
    
16. In code view if you put some spaces above the DataFormWebPart definition then we can include this control on the page. Just copy the code below:
    
    <sharepoint:peopleeditor
        id="pplPicker"
        runat="server"
        allowempty="False"
        validatorenabled="True"
        onvaluechangedclientscript="SetPeopleValues()"
        allowtypein="False">
    </sharepoint:peopleeditor>
    
    
17. Essentially this is adding the control to the page and setting some properties. The really important properties here are:
    
    OnValueChangedClientScript
    This property allows us to specify some client side JavaScript which we wish to run every time the value in the people picker is changed.
    
    AllowTypeIn
    This property restricts the user from manually typing into the people picker and forces them to use the Browse dialog to select users. See final note.
    
    
18. Next we need to add the JavaScript to our page.
    
    
19. At the very top of your page after all the Page and Register tags you will notice the opening <asp:content> tag for PlaceHolderMain. We need to place the following code above this control on the page:
    
    <asp:Content
        id="Content1"
        runat="server"
        contentplaceholderid="PlaceHolderAdditionalPageHead"> 
        <script type="text/javascript">

            function SetPeopleValues()   
            {         
                //Retrieve the semi-colon separated
                //list of user id's     
                var people = document.getElementById('ctl00_PlaceHolderMain_pplPicker_downlevelTextBox').value;     
                document.getElementById('ctl00_PlaceHolderMain_InitiationForm_ff1_1').value = people;     
                if (people=='')     
                {       
                    alert('No people selected');
                } else {       
                    //Split the list by ; to get an
                    //array of domain user names       
                    var arrPeople = new Array();       
                    arrPeople = people.split(';');
    
                    //Create an empty string to hold the
                    //email addresses       
                    var strEmails = '';
    
                    //Loop through the array of usernames       
                    var arrEndIndex = arrPeople.length - 1;       
                    var i=0;       
                    while (i <= arrEndIndex)       
                    {         
                        //Strip the domain name off and append
                        //the email address elements         
                        var person = String(arrPeople[i]);         
                        person = person.toLowerCase().replace('DOMAIN\\','');         
                        var email = person + '@domain.com';
                        //Add this email address to our string         
                        strEmails = strEmails + email;
    
                        //If this is the final email then add this
                        //value to the text box in our initiation
                        //form control, otherwise add the
                        //semi-colon         
                        if (i == arrEndIndex)         
                        {           
                            document.getElementById('ctl00_PlaceHolderMain_InitiationForm_ff1_1').value = strEmails;         
                        } else {           
                            strEmails = strEmails + '; ';        
                        }
                        i=i+1;
                    }     
                }   
            }

      </script>
    </asp:Content>
    
    

20. This uses the PlaceHolderAdditionalPageHead place holder to 'inject' some JavaScript into the head of the html page.
    
    Essentially this code is retrieving the value from our people picker and inserting it into the text box held on the DataFormWebPart. In my case I am doing some additional processing (to generate a semi-colon separated list of email addresses).
    
    

    NOTE: By default the PeoplePicker control (that is the TextArea html control that is rendered by the PeopleEditor SharePoint control) contains a semi-colon separated list of user names, of the form DOMAIN\UserName, so if you wanted to ignore the string parsing and processing elements of the javascript you could just set this value to the textbox straight away and then do any text processing on these values within your workflow (see below).

    function SetPeopleValues()
    {             
        //Retrieve the semi-colon separated list of user id's   
        var people = document.getElementById('ctl00_PlaceHolderMain_pplPicker_downlevelTextBox').value;   
        document.getElementById('ctl00_PlaceHolderMain_InitiationForm_ff1_1').value = people;
    }
    

21. To tidy up the look and feel of your form select the <tr>
    tag that contains the textbox control from within your DataFormWebPart and set the style tag to:
    
    style="visibility: hidden"
    
    This will mean that the end user does not see the data being passed to this textbox they just select their users and click Start.
    
    If you save all the changes you have made to this form then try and initiate your workflow you will see that you should be able to select your users using the Browse button and then click start, an email containing the details set out in your workflow should be emailed to the users selected in your People Picker.
    
    And that's it!