A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 5 – the SPArrangeChoices Function
Author: Marc D. Anderson
http://mdasblog.wordpress.com
Sometimes it’s the simplest little thing that can make someone’s day. You know how the radio buttons or checkboxes on a Choice column in SharePoint always are displayed vertically? You know how much that annoys everyone? Well, I decided to do something about it.
In v0.5.0 of the jQuery Library for SharePoint Web Services, I snuck in a new function called SPArrangeChoices, partly because I don’t like to do a release without some nice new functionality. (The main focus of v0.5.0 was to support jQuery 1.4+.) The other reason was that I’ve seen a lot of posts out in the forums with folks asking how to rearrange those radio buttons and checkboxes. Most of the solutions I’ve seen suggested are JavaScript-based, or (firmly in the overkill category) custom fields or Web Parts. But, yet again, none of the stuff I saw was really generalized enough for my tastes. Thus, SPArrangeChoices.
Background
When you create a Choice column in a SharePoint list or library, you have several choices on how it can be displayed, as shown here. When you choose Radio Buttons or Checkboxes, you get a vertical arrangement of options, as in these two examples
These arrangements take up a lot of screen real estate and, if the list of options is long, can even lead to poor data quality because it’s hard to see all of the possible choices at the same time to ensure that you are choosing the appropriate one(s).
So the goal of the SPArrangeChoices function is to give you some flexibility on how these options are displayed to make life easier.
The code to manage this isn’t even that complex.
// Rearrange radio buttons or checkboxes in a form from vertical to horizontal display to save page real estate
$.fn.SPServices.SPArrangeChoices = function (options) {
var opt = $.extend({}, {
columnName: "", // The display name of the column in the form
perRow: 99 // Maximum number of choices desired per row.
}, options);
var searchText = RegExp("FieldName=\"" + opt.columnName + "\"", "gi");
$("td.ms-formbody").each(function() {
if(searchText.test($(this).html())) {
var radios = "<TR>";
var choiceCount = 0;
$(this).find("tr").each(function() {
radios += $(this).html();
choiceCount++;
if(choiceCount % opt.perRow == 0) radios += "</TR><TR>"
});
radios += "</TR>";
$(this).find("tr").remove();
$(this).find("table").append(radios);
}
});
}; // End of function SPArrangeChoices
Here’s what’s going on in the code:
- First, we find the column’s control on the page. The radio button or checkboxes controls don’t have any specific Title or ID to key on, so we look for the DisplayName of the column in the comment which SharePoint always puts above it. We rely on SharePoint’s default rendering here; if you’ve customized your controls, then this function probably isn’t for you, anyway.
- Next we collect up the HTML for the available options. If we’ve reached the perRow number of options, we simply end the current row.
- Finally, we remove the existing row (TR) and replace it with the string of HTML which we’ve built up.
Example
Looking at the two examples above, we can rearrange the options based on what will look best for each. For Lead source, we’ll arrange the options such that there are no more than two options per row; for Radio Buttons, we’ll say no more than seven options per row.
$().SPServices.SPArrangeChoices({
columnName: "Lead Source",
perRow: 2
});
$().SPServices.SPArrangeChoices({
columnName: "Radio Buttons",
perRow: 7
});
Simple calls and simple results:
Syntax
As with all of the functions in the jQuery Library for SharePoint Web Services, everything is put in place from the UI or SharePoint Designer. There’s nothing to install server-side. You simply need to add references to the core jQuery library and the jQuery Library for SharePoint Web Services and then call the function. See the documentation on the Codeplex site for more details on how to set things up.
SPArrangeChoices currently takes two options:
$().SPServices.SPArrangeChoices({
columnName: "Lead Source",
perRow: 2
});
where columnName should indicate the column’s DisplayName on the form and the perRow value will limit the number of options per row. Experiment with this to see what works best for your particular options, as the length of the option values and such will have an impact on the overall display of the control’s structure.
Conclusion
This is another function which doesn’t make any calls to the SharePoint Web Services, but again, it seemed too useful not to add to the library. Give it a whirl, and make your forms look a little nicer for your users.
Author: Marc D. Anderson
http://mdasblog.wordpress.com
Marc D. Anderson is a Co-Founder and the President of Sympraxis Consulting LLC, based in Newton, MA. He has over 25 years of experience as a technology consultant and line manager across a wide spectrum of industries and organizational sizes. Marc has done extensive consulting on knowledge management and collaboration and what makes them actually work in practice. Marc is a very frequent “answerer” on the MSDN SharePoint – Design and Customization forum.
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 1 - Why and Why Now?
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 2 - How Does It Work?
- SharePoint: SPCascadingDropdowns Demystified (or Mystified, Depending on Your View)
- jQuery Library for SharePoint Web Services: Interim Update on What’s Coming Up in v0.5.0
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 3 - the SPDisplayRelatedInfo Function
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Real World Example - Part 1
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Real World Example - Part 2
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 4 - the SPSetMultiSelectSizes Function
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Real World Example - Part 3
- A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): Part 5 - the SPArrangeChoices Function
Could you add a second overload to allow designers to rearrange the order of the choices. Maybe they can’t make SharePoint do it. Just use the DisplayName of the choice as its key. I don’t know, I thought it might be useful.
$().SPServices.SPArrangeChoices({
columnName: “Radio Buttons”,
perRow: 7
choiceOrder: ["E","A","C","F","G","I","D",B","L","H","K","M","J"]
});
Very cool. I’ve had this problem before and think there was some ugly JavaScript involved to move things around. That was before JQuery was as popular as it is now. Very well done Marc, thank you!
Brian: Interesting add-on idea. I wonder if the error handling this might require means that this wouldn’t be effective. If anyone else has thoughts about it, please let me know!
Jeff: jQuery certainly looks nicer. ;=)
M.
Funny to see Brian’s comment, because when I read the title that’s exactly what I was expecting. Maybe it’s just me, but I find the name a little bit confusing.
This is what I was after! I was struggling to find a good way to present 10 options without forcing everyone to scroll down.. will give this a go.. thanks a lot!
OK, when Christophe and Brian both think something is a good idea, it’s a good idea. I’m going to add the choiceOrder idea to my list of upcoming enhancements. I’m also going to add a “randomizer”. This can be useful in the case of surveys, where you’d like to remove choice order predjudice.
M.
Love this.
Hi Marc,
Very cool.
Would you please tell me if this works on customized forms and how?
Thanks in advance
Jorge Esteves
Jorge:
Yes, this function will work on a customized form as long as you are still using the standard controls. The syntax would be exactly the same. If you need more info, check the documentation: $().SPServices.SPArrangeChoices
M.
FYI, I haven’t been able to get this working on a customised form “out of the box”. The standard form will give an HTML comment like this:
just before the radio buttons or checkboxes.
However, a custom form has the standard form made invisible (it’s mostly still there in the HTML with style=”display:none;” set on the surrounding table). The custom form is then created using XSL and markup like
When this is rendered in the browser, the comment block shown above is not in the HTML.
The simplest way to get this displayed is to add
FieldName=”Display Name”
just above the .
Now the SPArrangeChoices code will find the comment with the “FieldName” set and will rearrange the radios / checkboxes as desired.
Something that I thought would work… if you want to rearrange a number of radios all in one go, add FieldName=”RearrangeMe” to each that contains the radios to rearrange, and then you will only need one call:
$().SPServices.SPArrangeChoices({
columnName: “RearrangeMe”,
perRow: 5
});
This doesn’t actually work with the current release of SPArrangeChoices. The SPArrangeChoices function needs to be amended with
searchText.lastIndex = 0;
added as the last statement within the if block:
if(searchText.test($(this).html()))
[OR remove the "g" flag from the RegExp object]
Alex – Send me the code and I’ll touch up your comment. — Mark
AlexL:
Wordpress is cutting out your embedded code. Post it over on the Codeplex site discussions and let’s see if we can’t get things running for you.
M.
I’ve posted my comment and code etc on the CodePlex discussion as Marc requested:
http://spservices.codeplex.com/Thread/View.aspx?ThreadId=203960
Marc,
Great article! I have been toying around with some Javascript to achieve this and this is much cleaner. What if I wanted to take this a step farther and group the choices? For example, let’s say I want “A”, “B” and “C” to appear under a “Group A” heading and the remaining choices should appear under “Group B”? How could this be best accomplished?
Hmm. The SPArrangeChoices function doesn’t have that concept built into it. You might want to clone my function and adapt it to your needs.
M.
One other question and please pardon how silly I’m sure this sounds, but what code do I need to drop in via SPD? Well, let me back up for a second. I saved the two .js files to a new document library within the site. In my situation, I want to adjust how the choices appear on the NewForm.aspx page. When I go into the NewForm.aspx page in SPD, what should I be putting in there exactly?
Up until now, I’ve only really dealt with JavaScript and I would drop it into a CEWP on the page (I know, I know – I’m getting better though). Thanks!
Dan:
No silly questions here! Take a look at the documentation for SPArrangeChoices. If you want to put the script into a CEWP (I prefer putting it into the page itself with SharePoint Designer), you’ll want to add this, with your options and file locations, of course:
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.4.2.min.js"></script> <script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.5.5.min.js"></script> <script language="javascript" type="text/javascript"> $(document).ready(function() { $().SPServices.SPArrangeChoices({ columnName: "RadioButtons", perRow: 2 }); </script>M.
Marc,
Thanks for the quick response. Here is the code that I have dropped into my CEWP:
$(document).ready(function() {
$().SPServices.SPArrangeChoices({
columnName: “Choices”,
perRow: 2
});
But the choices are not arranging. I confirmed that I have the correct .js files within a document library in this same site. Did I miss a step? I dropped this CEWP directly on the NewForm.aspx page (once I get this working, I will move to dropping the code in via SPD rather than via a CEWP)
Oops – I guess I don’t know how to embed my code in a nice block like you have above. Most of my code was hidden when I posted that reply
Do you have the references to the js files in place? One quick trick to make sure that the references are right (*THE* most common problem people have in the beginning) is to add an alert inside the $(document).ready. If it fires, then your jquery reference is right; if it doesn’t fire, the references aren’t right yet.
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.4.2.min.js"></script> <script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.5.5.min.js"></script> <script language="javascript" type="text/javascript"> $(document).ready(function() { alert("Hi Dan!"); $().SPServices.SPArrangeChoices({ columnName: "RadioButtons", perRow: 2 }); </script>M.
The alert is not firing for me. All I did was copy/paste your code into a CEWP on the NewForm page. The only change I made to the code was to enter the full URL of where the two .js files are saved. I even tested moving them to another location and still no luck. I’m still not sure how to embed the nice block of code, so here is a link to a screenshot of exactly what is in my CEWP:
http://www.flickr.com/photos/sephiroth0327/4666965110/sizes/l/
Dan:
Sorry. What I gave you was missing the closing brackets. Copy and paste kills me again.
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.4.2.min.js"></script> <script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.5.5.min.js"></script> <script language="javascript" type="text/javascript"> $(document).ready(function() { $().SPServices.SPArrangeChoices({ columnName: "RadioButtons", perRow: 2 }); }); </script>M.
Success!! One last question (I promise!) – To embed this into the page via SPD, I would just open the NewForm page in SPD and insert this code inside PlaceHolderMain, correct?
Thanks for all the help. I really appreciate it!
Great, Dan. Yes, you’ve got it exactly right.
M.