SharePoint JavaScript Helpers (SJH) makes it easier to work with SharePoint lists through JavaScript.
SJH's simple features can be combined to produce complex SharePoint-based applications.
- Get list items
- Add list item
- Update list item
- Get the current user's e-mail address
- SharePoint 2010, 2013, and Office 365
- Today's web browsers including IE 8 and above
-
If you're using SharePoint 2013 or Office 365, disable the Minimal Download Strategy site feature on any sites using this script. The option to disable MDS is under Site Settings > Site Features. Alternatively, you can optimize your JavaScript to be compatible with MDS, but that is outside the scope of this library.
-
Copy sjh.js (in the
dist
folder above) to SiteAssets. -
Create an HTML file in SiteAssets, and link it to a content editor web part on a page. In that HTML file, place the following code:
<script src="../SiteAssets/sjh.js"></script>
<script>
SP.SOD.executeFunc("sp.js");
ExecuteOrDelayUntilScriptLoaded(YOUR_FUNCTION_NAME_HERE, "sp.js");
</script>
Replace YOUR_FUNCTION_NAME_HERE
with any SJH code you'd like to run on load. If no SJH code needs to run on load, remove that line.
You may need to adjust the path to sjh.js. The path above assumes the content editor web part is in SitePages or Pages.
SJH focuses on certain use cases. To request another, file an Issue on this GitHub repo.
All example code below can be placed after the Easy Setup code above, within the same content editor web part.
SJH.getListItems({
list: "Test", /* The name of the list on SharePoint, as it appears in the list URL. */
fields: ["Title"], /* An array of fields to retrieve from the list. */
query: "<View><Query><Where><Eq><FieldRef Name='Active'/><Value Type='Boolean'>1</Value></Eq></Where></Query></View>", /* OPTIONAL: A query to filter, sort, or limit the list items returned. It is written in CAML, Microsoft's preferred method for querying SharePoint lists. Leave this out to return all. */
site: "/SomeSite" /* The relative URL of the SharePoint site containing the list. Leave this out to use the current site. */
}).then(function(items) {
/* Do something with the array 'items' */
});
Before running the code below, create a custom list called Test. It will start with just one column, Title. Add a couple of items to the list.
SJH.getListItems({
list: "Test",
fields: ["Title"]
}).then(function(items) {
var itemsAsList = $.map(items, function(item) {
return item["Title"];
}).join(", ");
alert("Read list item test succeed. Here are the items from Test: " +
itemsAsList);
});
Here are some quirky SharePoint fields that come with most lists. Include these in the fields, and SJH will include them in the results:
- Id
- DisplayName: In a document library, this is the file name without the extension. For a list, it's the item's title.
- EncodedAbsUrl: In a document library, this is the URL to open the document. For a list, it's generally not useful.
SJH.addListItem({
list: "Test", /* The name of the list on SharePoint, as it appears in the list URL. */
data: { /* The data you'd like to add, as a JavaScript object. Field names must match the system names of the fields (see section below called List and Field Names. */
Title: "my new item",
Description: "This item rocks"
},
site: "/SomeSite" /* The relative URL of the SharePoint site containing the list. Leave this out to use the current site. */
}).then(function(id) {
/* Do something once this succeeds */
});
Create a custom list called Test. It will start with just one column, Title.
SJH.addListItem({
list: "Test",
data: {
Title: "my new item"
}
}).then(function(id) {
alert("Item added. Its ID is " + id.toString());
});
SJH.updateListItem({
list: "Test", /* The name of the list on SharePoint, as it appears in the list URL. */
id: 1, /* The ID of the list item to update */
data: { /* The data you'd like to update, as a JavaScript object. Field names must match the system names of the fields (see section below called List and Field Names. */
Title: "my updated item"
},
site: "/SomeSite" /* The relative URL of the SharePoint site containing the list. Leave this out to use the current site. */
}).then(function() {
/* Do something once this succeeds */
});
Create a custom list called Test.
SJH.addListItem({
list: "Test",
data: {
Title: "test item"
}
}).then(function(id) {
/* AddListItem returns the ID of the item added, which we'll use to update that item */
SJH.updateListItem({
list: "Test",
id: id,
data: {
Title: "updated test item"
}
}).then(function() {
alert("Item added and updated");
});
});
SJH.deleteListItem({
list: "Test", /* The name of the list on SharePoint, as it appears in the list URL. */
id: 1, / * The ID of the list item to delete */
site: "/SomeSite" /* The relative URL of the SharePoint site containing the list. Leave this out to use the current site. */
}).then(function() {
/* Do something once this succeeds */
});
SJH.getCurrentUserEmail({
site: "/SomeSite" /* OPTIONAL: The current site is used if this is not specified. */
}).then(function(email) {
/* Do something with the email address in email */
});
SJH.getCurrentUserEmail().then(function(email) {
alert("Hi! Your e-mail address is " + email + ".");
});
With this method, your code under then
is executed after all of the specified actions are completed.
var getSomeItems = function() {
return SJH.getListItems({
list: "Some list",
fields: ["Title"]
});
};
var getMoreItems = function() {
return SJH.getListItems({
list: "Another list",
fields: ["Title"]
});
};
SJH.all([getSomeItems(), getMoreItems()])
.then(SJH.spread(function(someItems, moreItems) {
alert("I got " + someItems.length + " items from some list and "
+ moreItems.length + " items from another list!");
}));
See the example above of updating an item in a list.
SJH's simplicity makes it compatible with modern JavaScript libraries like React.
Here's is SJH and React combined, ready to run in a content editor web part:
<script src="https://fb.me/react-0.13.3.js"></script>
<script src="https://fb.me/JSXTransformer-0.13.3.js"></script>
<script src="../SiteAssets/sjh.js"></script>
<div id="sjh-test-react"></div>
<script type="text/jsx">
var Test = React.createClass({
getInitialState: function() {
return {items: []};
},
componentWillMount: function() {
SJH.getListItems({list: "Test", fields: ["Title"]}).then(function(items) {
this.setState({items: items});
}.bind(this));
},
render: function() {
var items = this.state.items.map(function(item) {
return <li>{item.Title}</li>;
});
return (
<div>
<p>Here are the items in the list, rendered with React:</p>
<ul>
{items}
</ul>
</div>
);
}
});
var renderTest = function() {
React.render(<Test/>, document.getElementById("sjh-test-react"));
}
SP.SOD.executeFunc("sp.js");
ExecuteOrDelayUntilScriptLoaded(renderTest, "sp.js");
</script>
There are more steps before the React app is production ready. See this guide.
Always use a list's current title, as specified in List Settings.
Always use a field's system name, which is often different from its displayed name. To find a field's system name, go to List Settings and click on that field. The field's system name will be in the URL.
SharePoint-specific errors will result in a popup alert, helpful for debugging. Any other errors that SJH encounters will be thrown to the console. You're best off using Google Chrome and its console to debug your JavaScript.
To disable error alerts, add this right after the <script>
tag for sjh.js:
SJH.Config.errorAlerts = false;
You can catch errors in your own code and do with them what you wish by using catch
. The syntax below is a bit odd, but makes this code IE 8 compatible.
SJH.getListItems({list: "Test", fields: ["Title"]}).then(
function(items) {
/* do something on success */
})
["catch"](
function(err) {
/* Do something with the error in err */
});
For upcoming features, see the Issues tab. Feel free to submit your own!
- Microsoft's quick reference to SharePoint's JavaScript Client Side Object Model, which powers SJH.
- SPServices, for pioneering and continuing to provide excellent JavaScript helpers for SJH.