SharePoint Checkboxes (Allow multiple selections) – Changing the label text.

Sunday, October 06 2013

This MiniBlog is a quick post to share a little jQuery solution to a requirement.  The user requirement was to provide a way for the end user to add’ ad hoc’ values to multiple choice column and provide a label to specifically identify the user input being requested. 

 

The project was a system change control application based on a customized event calendar.  One of the fields of the event was to define the scope of the impact of the proposed change.  Some of the scope options were easy to define – LAN, WAN, Voice, Domain, but, there was also a requirement to capture the scope of specific applications.  There are hundreds of applications in our enterprise, so capturing them in the checkbox options explicitly was impractical and would have made the form unusable. 

 

The ability to use the “Checkbox – Allow multiple selections” has promise but the standard “Specify your own value:” label is inadequate in identifying the purpose of the Textbox input.  The requirement is that the label should say “Applications - enter below”.

In order to fulfill this requirement with the least amount of effort, it was apparent that a little client-side manipulation of the element label in the DOM using jQuery was a excellent choice.  The challenge is that the checkbox component is generated dynamically by SharePoint on the server.  It retrieves the options from the list choice column and builds the collection of checkboxes and labels, then appends the checkbox for ‘ad hoc’ checkbox and adds the label.  Using this understanding of the Checkbox component, we are able to wrap the SharePoint:FormField with a span and give it an id.  Then we can select the container for the dynamic element, traverse the child option elements to the last element and  dynamically change the “innerText” of this element.

 

Let’s look at the related markup and code.  It should help clarify this very simple solution to what might have seemed like a difficult issue.

First, we need to find the table div (td) that holds our column in the aspx page.  I use SharePoint Designer for this task.    After finding the table div,  I wrap the SharePoint:FormField in a span tag and give that span tag an id, “Impact”, so that we can find it later. We’ll see how with a little  jQuery we can select and manipulate our span and it contents before it is rendered to the page.  For now, it’s most important that we remember the ID  “Impact” that  we gave to our span.

 

For the next step, we’re going to let SharePoint do its magic behind the scenes so that we can analyze the markup generated for the Impact options panel.  The easiest way is to run the page and open the debugger.  I use IE Tools for my debugger for this task, but you can use Firebug or Chrome Developer Tools if you prefer.

 

By selecting the element and looking at the dynamically generated markup, we can define the selector that will be required to select that ‘ad-hoc’ options checkbox label and change its text.  This is accomplished by walking the”" “Impact” span element hierarchy to find the DOM element we need.  Then we can change the label text to anything we like using the innerHTML  property of the element.

 

 

Let’s look at the JavaScript that we will use for our solution.  I’ve included the code to render the choice checkboxes horizontally, rather than SharePoint’s vertical default, but we won’t dive into that code until a later posting.   There is also a chunk of code that you renders checkboxes into a dynamically generated table so that we have more control over the layout and flow of the checkbox panel contents.  This too will be explained in a future post.

The first two lines of our document.ready function is where we need to focus now.  The first line, using our jQuery selector, returns the number of options defined for the column including our ‘ad-hoc’ option.  We use this count of options to select the label of the last option (our ‘ad-hoc’ ).  We used (cnt – 1) because the index is zero based.  Then we simply set the InnerHTML property on the label and the text on the label for the checkbox is changed to “Applications - enter below”.  We fulfill the requirements because the label on the checkbox clearly identifies the type of information being requested for the text field. 

Because I also prefer to render my checkboxes horizontally, I use a little css to manage the spacing of the checkboxes within the panel. The css is also includes the styles  for the next post.

 

The css is pretty self-explanatory.  the ms-RadioText style is generated by the SharePoint:FormField object.  We are simply adding ten pixels before each checkbox to add spacing between the elements and make it apparent to  which label (before or after) the check box is related.

One “take away” point is -- make use of the debugger when building your applications.  Being able to understand what the server-side components are generating on the client (browser) will provide you with a great deal of flexibility and power when you need to change the default appearance or behavior of these elements.  jQuery is a powerful tool to simplify manipulating DOM objects on the client side. If you don’t already use it, get familiar with the library and it’s methods.  They’ll save you a lot of time and stress.

As mentioned previously, in the next post we’ll look at using jQuery to manage some more controlled output of the checkbox panels, including dynamically rendering them into tables and being able to define the number of columns in each row.

Later still, we’ll look at another project and using REST queries on SharePoint lists and building more complex Single Page Applications (SPA) with dynamically filtered lookup lists and related SharePoint lists.  By the time we’re finished, I hope that you’ll will feel unshackled from the limitations of “Out-Of-The-Box” SharePoint.

 

One final step today, though, is to share with you the fruits of our efforts.  I hope you found this helpful  and I hope you stop back for the future posts.