Please read the documentation (starting with the
General Instructions at the bottom of this page) before asking questions. I'm happy to help out, but it's so much nicer when folks read the documentation.
Core
| Function Name |
Short Description |
Introduced |
Certification |
| $().SPServices |
This is the core function of the library, which you can use to make Ajax calls to the SharePoint Web Services. |
0.2.3 |
See individual Web Services |
| $().SPServices.defaults |
With this defaults function, you can set the defaults for the remainder of the page life. This can be useful if you'd like to make many calls into the library for a single list or site. |
0.2.4 |
NA |
| $().SPServices.Version |
Returns the current version of SPServices as aa string, e.g., "0.7.2" |
0.7.2 |
NA |
Form Enhancements/Assistance
Utilities
General Instructions
First, please read
this blog post, which can help you to be sure that your script file references are correct.
The library can be implemented by adding a reference to it into a single page, a page layout, or a master page, depending upon your desired scope of use. The SPServices library requires the
jQuery library. See the System Requirements section for required versions.
Most releases of the library include both a
minified and a normal version of the release. If you would like to understand the workings of the library, look at the normal version, but use the minified version for any production use.
I recommend storing the jQuery library and SPServices in a Document Library in your Site Collection and referencing it as needed, like this:
<script language="javascript" type="text/javascript" src="/jQueryLibraries/jquery-1.8.3.min.js"></script>
<script language="javascript" type="text/javascript" src="/jQueryLibraries/jquery.SPServices-0.7.2.min.js"></script>
You can also reference the js files from a CDN, like so:
<!-- Reference jQuery on the Google CDN -->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
<!-- Reference SPServices on cdnjs (Cloudflare) -->
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/jquery.SPServices/0.7.2/jquery.SPServices-0.7.2.min.js"></script>
See
this post for more info on using CDNs.
Debug Mode, first implemented in
v0.4.5, also can be helpful in implementing solutions with the library.
Here's a small example. If you want to add functionalty to NewForm.aspx, then take a copy of the form, call it something like NewFormCustom.aspx, and add your script into it. I like to put my scripts below this line:
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
Other places may work, but this location has proven foolproof for me, regardless of what others may recommend.
...
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
<script type="text/javascript" language="javascript" src="/jQuery%20Libraries/jquery-1.6.1.min.js"></script>
<script type="text/javascript" language="javascript" src="/jQuery%20Libraries/jquery.SPServices-0.6.2.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
$().SPServices.SPCascadeDropdowns({
relationshipList: "Regions",
relationshipListParentColumn: "Country",
relationshipListChildColumn: "Title",
parentColumn: "Country",
childColumn: "Region"
});
});
</script>
...
Obviously, the src attributes should point to wherever you've put the .js files.
Alternatively, you can place the code in a Content Editor Web Part (CEWP). I prefer the approach above (see the
FAQs), but the CEWP approach works as well.
Once you've got the page set up the way you want it, right click on the list in the Folder List pane, select Properties, and then the Supporting Files tab. Choose the Content Type in the dropdown (NOT Folder) and then browse to your NewFormCustom.aspx to
set it as the New Item Form. Click OK and you should be good to go.
Debugging Hints and Tips
- If you are working in SharePoint Designer, Ctrl-click the addresses of each of the two .js references. If you get a "file not found" message, you have a bad src URL. Most often, it's an incomplete path or occasionally a very innocuous misspelling.
- Set the debug parameter to "true" (if available for the function you are using), and make one purposeful mistake, e.g., misspelling a column name. Then save and preview in a browser. You should get a popup error message. If not, your script is
not running, most likely because it is in the wrong place. Reposition the script elsewhere in the code until you get an error message.
- Wrapping your script in
$(document).ready(function()
means that the calls will be made once the page is fully loaded, i.e., the page is "ready". If you aren't getting the results you want and you aren't using $(document).ready(), then wrap your code in it and try again.
(Depending on what you are trying to do, wrapping your script in $(document).ready() may *not* be what you want, but if you are just using the "value-added functions", you almost always will use it.)