Function

$().SPServices.SPAutocomplete

Certification

Certified for SharePoint 2007 Certified for SharePoint 2010

Functionality

The SPAutocomplete lets you provide values for a Single line of text column from values in a SharePoint list. The function is highly configurable and can enhance the user experience with forms.

Demo Page

Take a look at the demo page.

Prerequisites

  • Source list contains a column of available values

Syntax

$().SPServices.SPAutocomplete({
	WebURL: "",
	sourceList: "",
	sourceColumn: "",
	columnName: "",
	CAMLQuery: "",
	CAMLQueryOptions: "<QueryOptions></QueryOptions>",
	filterType: "BeginsWith",
	numChars: 0,
	ignoreCase: false,
	highlightClass: "",
	uniqueVals: false,
	slideDownSpeed: "fast",
	processingIndicator: "<img src='_layouts/images/REFRESH.GIF'/>", // NOTE: This option has been deprecated as of v0.6.0
	debug: false
});

WebURL
The URL of the Web (site) which contains the sourceList. If not specified, the current site is used. Examples would be: "/", "/Accounting", "/Departments/HR", etc. Note: It's always best to use relative URLs.

sourceList
The name or GUID of the list which contains the available values. If you choose to use the GUID, it should look like: "{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}". Note also that if you use the GUID, you do not need to specify the WebURL if the list is in another site.

sourceColumn
The StaticName of the source column in sourceList

columnName
The DisplayName of the column in the form

CAMLQuery
The CAMLQuery option allows you to specify an additional filter on the relationshipList. The additional filter will be <And>ed with the existing CAML which is checking for matching items based on the parentColumn selection. Bacause it is combined with the CAML required to make the function work, CAMLQuery here should contain a CAML fragment such as:

  CAMLQuery: "<Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq>"

CAMLQueryOptions
This option can be used to specify additional options for retrieval from the sourceList. See the MSDN documentation for GetListItems for the syntax.

filterType
This option allows you to specify how values should be matched. The available values are [BeginsWith, Contains] and the default is "BeginsWith".

numChars
Wait until this number of characters has been typed before attempting any actions. The default is 0.

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

highlightClass
When a matching value is shown, the matching characters are wrapped in a <span>. If highlightClass is specified, that class is applied to the span. An example might be:

  highlightClass: "ms-bold",
uniqueVals
If set to true, only unique values returned from sourceList will be shown. The default is false.

slideDownSpeed
Speed at which the div should slide down when values match (milliseconds or ["fast" | "slow"]). The default is "fast".

processingIndicator   // NOTE: This option has been deprecated as of v0.6.0
If present, this markup will be shown while Web Service processing is occurring. The default is "<img src='_layouts/images/REFRESH.GIF'/>". Because this library requires no serverside deployment, I wanted to use one of the out of the box images. you can substitute whatever image or text you would like in HTML format.

debug
Setting debug: true indicates that you would like to receive messages if anything obvious is wrong with the function call, like using a column name which doesn't exist. I call this debug mode.

Examples

This is the sum total of what you'll need to add to your page to make the function work as it does in the demo page. The first two lines simply pull the script files into the page, and the $(document).ready(function() line is a jQuery function that says "Run this script when the page has been fully rendered". In the first call to the function, note that we're turning debug mode on by setting debug: true.

<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.4.2.js"></script>
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.5.4.min.js"></script>
<script language="javascript" type="text/javascript">
	$(document).ready(function() {
		$().SPServices.SPAutocomplete({	
			sourceList: "Products",
			sourceColumn: "Title",
			columnName: "Title",
			ignoreCase: true,
			numChars: 3,
			slideDownSpeed: 1000,
			debug: true
		});
	});
</script>

Last edited Mar 13, 2011 at 3:36 PM by sympmarc, version 13

Comments

mmondillo Nov 13, 2015 at 10:37 AM 
With more fields, you can use this work around:
$("input").focus(function() {
$("[id*='SPAutocomplete_undefined']").attr('id','SPAutocomplete_undefinedDisable');
$(this).next('div').children('ul').attr('id','SPAutocomplete_undefined');
});

zeair Sep 9, 2015 at 11:24 PM 
Any idea how to make it work with calculated column as a sourceColumn?

Kousalyaac14 Jun 4, 2015 at 6:08 AM 
Hi, I am using this jquery in sharepoint 2013, and its working fine, but i am not able to select the data fro mthe dropdown list.

Paradajz Mar 4, 2015 at 1:28 PM 
Hi, I have the same problem as gox777. My field with the autocomplete function searches a list with 1000 items and typing is veeeery slow. I tried to add a delay function to keyup, so that the search would start when user pauses for a moment but I couldn't get it to work -> users types, waits and the suggestions appear, users types again but the autocomplete doesnt wait till the pause, it is constantly running. So once it is attached to the field it doesn't 'go away'. Any idea how to solve this? :\

gox777 Feb 11, 2015 at 7:34 PM 
Previously I made mention of an issue where key presses are discarded if a user types too fast. I came up with a solution for this. I ended up modifying the SPAutoComplete function so that the search begins upon a 'click' event rather than the 'keyup' event. 'Keyup' is used to trigger the 'click' after a debounce has expired. (I'm using a separate debounce plugin: https://code.google.com/p/jquery-debounce/ )

Hopefully that strategy may be helpful to others who encounter this issue.

berood001 Feb 4, 2015 at 7:49 PM 
Think I found a bug. I have two fields CurrentServiceCode and PreviousServiceCode. SPAutocomplete uses the source list Service Codes for both fields. Each field has a different title, and the function is called twice for each field.

The drop down for the autocomplete only shows up on the first field on the page. When filling out the second field the drop down shows on the first field. If I double click an option under the dropdown it will still populate the second field.

Thanks for any help. Love this tool.

JavaScript Snippet:
$().SPServices.SPAutocomplete({
sourceList: "Service Codes",
sourceColumn: "Title",
columnName: "PreviousServiceCode",
ignoreCase: true,
numChars: 3,
//slideDownSpeed: 1000,
debug: false
});

$().SPServices.SPAutocomplete({
sourceList: "Service Codes",
sourceColumn: "Title",
columnName: "CurrentServiceCode",
ignoreCase: true,
numChars: 3,
//slideDownSpeed: 1000,
debug: false
});


HTML Snippet
<input title="CurrentServiceCode " type="text" id="spfSeriesPI" class="spfField" />
<input title="PreviousServiceCode" type="text" id="spfSeriesID" class="spfField" />

gox777 Aug 20, 2014 at 10:12 PM 
One issue I came across - If a user types very quickly, some of the key presses are discarded. Any ideas on fixing this? How would I go about putting in a very slight delay so that no search is made until the user pauses for a moment?

These libraries have been a great help. Thanks!

shvimer Aug 3, 2014 at 10:04 AM 
hi
i did whatever you write to do
but the aoutcomplete not working
which problem it can be
I have a input:
<input id='IturMahirTxb' type='text'
and in the java script:
$document).ready(function() {
$("#'IturMahirTxb' ).SPServices.SPAutocomplete({
sourceList: "Products",
sourceColumn: "Title",
columnName: "Title",
ignoreCase: true,
numChars: 3,
slideDownSpeed: 1000,
debug: true
});
});
</script>

if you can answer me
it will be very helpful
thanks

willgart Feb 23, 2014 at 1:57 AM 
Hi,
is it possible to return another column like the ID of the row? and is there a version working with a business data services entity?
thanks.

samsuree Jul 4, 2013 at 5:43 AM 
how can i display an image along with the search text. For example if i type a persons name, his image has to be displayed on the left. Something similar to facebook search. Please let me know on how we can implement the same using SPServices Autocomplete.

iOnline247 Feb 8, 2013 at 8:05 PM 
@bronskrat
The jQuery selector for <input> elements work based off of the title attribute. You are missing that in your code. Modify your element to include the title attribute and it should just work.

<input title="Full Name" type="text" title="Display Name" name="uiEmployee" id="uiEmployee"/>

Cheers,
Matthew

bronskrat Feb 8, 2013 at 7:36 PM 
I tried this within a CEWP and created a text field (eg <input title="Full Name" type="text" name="uiEmployee" id="uiEmployee"/> ). The dropdown works correctly but when I click on a name in the dropdown, it does not populate the text field.

Any idea why? Same thing works with a SharePoint list form.

kandasamyg2012 Jan 29, 2013 at 1:13 PM 
Hi, Is there a way to control to limit the user to submit only the autocomplete suggested values. Since it is a text box the user can type his own text and save the item. I want to restrict it. Please suggest your ideas. Thanks in advance. By-Kandasamy

mdininio Dec 31, 2012 at 3:51 PM 
This works perfect in SPF 2010 ! Thanks Marc!

naijacoder Sep 12, 2012 at 2:34 AM 
Hi Marc good stuff
It seems i can't use this with a custom webpart e.g a custom textbox.I haven't tried it though but it looks like so.
Cheers
Pat

derron7 Jul 27, 2012 at 12:35 PM 
Is there the possibility to use the arrow keys (up/down)? I don not want to switch into mouse mode for selection.
and it would be great to link to the dispform.

sympmarc Aug 17, 2011 at 12:23 PM 
fmorriso: Was the part of the documentation where I say "The DisplayName of the column in the form" not good enough? How would you rewrite that? I can't change the option name at this point, and the naming is consistent with all of the other functions in the library. Finally, please post questions/suggestions in the Discussions for better interactivity (no alerting here). M.

fmorriso Aug 17, 2011 at 2:33 AM 
The one very confusing part of the API for SPAutoCcomplete is that what it calls "columnName" is really the "title" attribute. The first time I tried using it, it failed because the input field had no title attribute. Adding a title attribute fixed the issue but I would love to see the API for SPAutoComplete changed so that "columnName" becomes "destinationInputFieldTitle" or "targetInputFieldTitle" or something with "title" as part of the name to make it clear what the relationship is between the "source" column (the one in the list) and the "destination" input field.
// Suggest as you type from a special custom list
$('input[id$=mlQueryText_MXSFSearch]').attr('title', 'mlQueryText'); // add missing title attribute to my input text field that has an "id" that ends with the specified name
$().SPServices.SPAutocomplete({
sourceList: "SearchTypeAheadSuggestions", // The name of the list which contains the values
sourceColumn: "Title", // The static name of the column which contains the values
columnName: "mlQueryText", // The 'title' attribute of the column in the form <--------------- THIS IS THE UNNECESSARLY UNCLEAR, TRICKY PART OF THE API DUE TO POOR CHOICE OF NAME
numChars: 1, // Wait until this number of characters has been typed before attempting any actions
ignoreCase: true, // If set to true, the function ignores case, if false it looks for an exact match
highlightClass: "ms-bold", // If a class is supplied, highlight the matched characters in the values by aplying that class to a wrapping span
slideDownSpeed: "fast", // Speed at which the div should slide down when values match (milliseconds or ["fast" | "slow"])
debug: false // If true, show error messages; if false, run silent
});

sympmarc Feb 11, 2011 at 3:01 PM 
rajdeep1510: I'm moving your question into the Discussions here: http://spservices.codeplex.com/discussions/245641 M.

rajdeep1510 Feb 11, 2011 at 5:08 AM 
This one is just excellent. I am using it successfully. But does it work in cross site ? I want to use this from a site collection and want to access the list present in another site collection. some thing like this :

$().SPServices.SPAutocomplete({
WebURL: "/sites/AnotherSiteCollection",
sourceList: "Test",

sourceColumn: "ID",
columnName: "Enter the No",
numChars: 1,
ignoreCase: true,
slideDownSpeed: 100,
debug: true
});

//This webUrl is of AnotherSiteCollection and the code is in ASiteCollection. Presently its not populating the records. Am I missing something ?

jonasenglish Feb 1, 2011 at 4:20 PM 
he's using
var columnObj = $("input[Title='" + opt.columnName + "']");

jonasenglish Feb 1, 2011 at 4:18 PM 
Hi, I noticed dipetersen's comment from Nov 11....
in your input tag add a title attribute with your desired column name.

<input title="Full Name" type="text" name="uiEmployee" id="uiEmployee"/>
where "Full Name" is the columnName

I assumed that Marc was searching for the input with $('input[title=<columnName>]') and it works.

mpeterson79 Nov 23, 2010 at 3:37 PM 
Works on SP 2010

sympmarc Nov 13, 2010 at 12:42 PM 
di: Yes, everything in this library is built to work with SharePoint, and in most cases with the default capabilities. If there are tricks to make something work with custom forms or something, then they will be in the docs. There's just no way to generalize the script to know what *you* might do in a custom Web Part.

M.

p.s. Use the Diiscussions rather than the wiki pages to ask questions; I don't always see them here.

dipetersen Nov 11, 2010 at 8:24 PM 
Does this only work for SharePoint default forms? I tried using this on a custom web part that I wrote and it appears that it can't find the text field.