Function

$().SPServices.SPRequireUnique

Certification

Certified for SharePoint 2007 Certified for SharePoint 2010

Functionality

Checks to see if the value for a column on the form is unique in the list. The idea for this function came from testing $().SPServices.SPCascadeDropdowns. When using lists like relational tables, you want to be sure that at least one column contains unique values. Currently, the function works only with Single line of text columns, and will generally be used with the Title column. There is considerable flexibility in the use of this function based on the combination of options and the ability to change the messages and their formatting.

Note that this function will work on the NewForm and EditForm for a list, but not in the datasheet view. The intent is to put some rigor around the normal item creation process. Because this is a client-side function, it does not pervasively enforce the uniqueness rule.

Prerequisites

None

Syntax

$().SPServices.SPRequireUnique({	
  columnStaticName: "Title",
  duplicateAction: 0,
  ignoreCase: false,
  initMsg: "This value must be unique.",
  initMsgCSSClass: "ms-vb",
  errMsg: "This value is not unique.",
  errMsgCSSClass: "ms-formvalidation",
showDupes: false,
completefunc: null });

columnStaticName
The StaticName of the column on the form. The default value is "Title".

duplicateAction
This indicates what should happen if the user enters a value which already exists. The default is 0 (warn).

  • 0 = warn means that a warning message will be placed on the screen, but the user can save the item
  • 1 = prevent means that a warning message will be placed on the screen and the user will be prevented from saving the item (the OK button will be disabled until a unique value is entered)

ignoreCase
If set to true, the function ignores case, if false it looks for an exact match. The default is false.

initMsg
The initial message to display after setup. The message is displayed below in input control, but above the column description, if any. The default value is "This value must be unique."

initMsgCSSClass
The CSS class for the initial message specified in initMsg. The default value is "ms-vb".

errMsg
The error message to display if the value is not unique. The message is displayed below in input control, but above the column description, if any. (This is the same location as the initMsg.) The default value is "This value is not unique."

errMsgCSSClass
The CSS class for the error message specified in errMsg. The default value is "ms-formvalidation".

showDupes
If true, the function will show the other items in the list which are duplicates as links so that one can easily research what they are and potentially clean them up.

completefunc
If specified, the completefunc will be called upon successful completion of the call to SPRequireUnique. Potential uses for the completefunc: consistent default formatting overrides, additional lookup customizations, image manipulations, etc. You can pass your completefunc in either of these two ways:

completefunc: function() {
  ...do something...
},

or

completefunc: doSomething,                  // Where doSomething is the name of your function

Example

The following example will require the Title column to be unique.

<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.3.2.min.js"></script>
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.4.6.min.js"></script>
<script language="javascript" type="text/javascript">
	$(document).ready(function() {
		$().SPServices.SPRequireUnique({	
			columnStaticName: "Title",
			duplicateAction: 0,
			ignoreCase: "false",
			initMsg: "This value must be unique.",
			initMsgCSSClass: "ms-vb",
			errMsg: "This value is not unique.",
			errMsgCSSClass: "ms-formvalidation"
		});
	});
</script>


This screenshot shows how the initMsg is displayed below the State column (State is the DisplayName for the Title column in this list):


This screenshot shows the errMsg being displayed because the value 'Alabama' already exists in the State column of an existing item. Note also that the OK buttons are disabled, preventing the user from saving the duplicate value.

And with showDupes set to true:

SNAGHTMLe833657

Last edited Mar 15, 2011 at 12:32 AM by sympmarc, version 11

Comments

jmaysnc Jan 30 at 6:16 PM 
I am trying to get SPRequireUnique to work on a page with a customized Data Form Web Part without success. Any ideas on that?

To further complicate things, on the same page I am using SPServices 0.7.2 and jQuery 1.8.3 to prefill fields based on the current user, and I am unable to get the two processes to work with the required jQuery and SPServices versions for each.

I would appreciate any assistance in helping troubleshoot and finding a solution.

Tiac Oct 16, 2013 at 11:55 AM 
Hello,
here are some more inforamtion. I'm working with SharePoint 2010 standard version. I add the following code with a content editor webpart on the EditForm of our library:
<script language="javascript" src="http://ajax.microsoft.com/ajax/jQuery/jquery-1.4.2.min.js" type="text/javascript"></script><script language="javascript" src="/[mySite]/[LibraryName]/jquery.SPServices-0.5.6.js" type="text/javascript"></script><script>
$(document).ready(function() {
$().SPServices.SPRequireUnique({
columnStaticName: "Rechnungs-Nummer",
duplicateAction: 0,
ignoreCase: "false",
initMsg: "This value must be unique.",
initMsgCSSClass: "ms-vb",
errMsg: "This value is not unique.",
errMsgCSSClass: "ms-formvalidation"
});
});</script>
But it's like i told in my post before. I don't get the "warning" message although the title isn't unique.
If i tested the code for a list instead for a library it works perfect. I don't get why i won't work for a library.

Tiac Oct 15, 2013 at 8:19 AM 
Hello, this post is great. But it won't work in my Edit Form. I wanna use this solution in a library. So i added the code on my Edit Form with a CEWP. But the only message i saw was the "his value must be unique" although the values of the column aren't unique. I didn't get the "red message". What did i do wrong? Hope someone give me a advice.

Siva250478 Jan 10, 2013 at 5:34 AM 
Good article.

how do i implement same validation for combination of fields in list?

Siva Kumar

jbrown052861 Jan 3, 2013 at 6:31 PM 
how do I implement this using a dropdown list which is actually a lookup column?

sash2021 Nov 7, 2012 at 9:24 AM 
Hi,

Can i do this validation for dropdown field?(which has cascading with another dropdown)

cabbascia Jul 4, 2012 at 6:20 PM 
Hi Marc, you mention at the top that it only works with single line of text fields, so i'm going to ask you this silly question (just in case) - will it work with a "calculated" text field?

sp4des Jun 21, 2012 at 4:12 PM 
Dynasign, I´m new in this, please tellme where you have to change the code

Dynasign Nov 4, 2011 at 9:24 AM 
For everyone who is struggling with the option: duplicateAction: 0 (only warn not prevent, the OK button should be enabled). When using jQuery 1.6 or higher this would not work. Change the following code:
$("input[value='OK'], input[value='Save']").attr("disabled", "");
into:
$("input[value='OK'], input[value='Save']").prop("disabled", false);

and further the code:
$("input[value='OK'], input[value='Save']").attr("disabled", "disabled");
into:
$("input[value='OK'], input[value='Save']").prop("disabled", true);

BTW: Nice library...it works great!

Harmjan

cvgandhi Jul 20, 2010 at 7:05 PM 
wow!! wow!! wow!!! deserves a standing ovation..

agautam123 Jun 1, 2010 at 6:01 PM 
Awesome. I just needed this