Hi! My name is Ricardo Loo. I am a Programming Writer for SharePoint. In today's article we'll talk about how to use the JavaScript object model (JSOM) in a simple HTML page in your app for SharePoint. By using the JSOM, you can access data and functionality in SharePoint 2013. You can also use Representational State Transfer (REST) endpoints to access data. The choice depends on various factors such as your abilities or development platform. For more information, see Choose the right API set in SharePoint 2013.

To keep things simple and short, I am using an app page hosted in SharePoint—but remember that you can also use the JSOM if your pages are not hosted in SharePoint. To access the objects using the JSOM in pages not hosted in SharePoint, you can use the cross-domain library (we'll post more information about the cross-domain library in a subsequent article.)

To use the JSOM, you must follow these steps:

1. Reference the required libraries.

2. Get a client context instance and load SharePoint objects.

3. Execute the query and provide callback functions.

Reference the required libraries

Before using the JSOM you must reference the following libraries, in this order:

1. ASP.NET Ajax library

2. sp.runtime.js file

3. sp.js file

When the app pages are hosted in SharePoint, you can use relative paths to the required files. The following script tags show you how to reference the required libraries in a page hosted in SharePoint:

<script 
 type="text/javascript" 
 src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js">
</script>
<script type="text/javascript" src="_layouts/15/sp.runtime.js"></script>
<script type="text/javascript" src="_layouts/15/sp.js"></script>
<script type="text/javascript">
 // Continue your program flow here.
</script>

Get a client context and load the objects

To access the objects in the JSOM, you first need an instance of the client context. You can get an instance of SP.ClientContext by using the get_current() method. Now, we have an access point (the client context) to the objects in SharePoint. As you probably imagine, you must issue a query to get the specific objects you need.

What's next? Let's create a list. You can use lists in the app web to provide storage for your app. For example, you can use a list to store user data or some other information. Whether you use lists or another type of storage depends on how you design your app. For more information, see Data storage options in apps for SharePoint.

The following code shows how to get an instance of the client context and load the required objects to create a list:

var clientContext; 
var listCreationInfo; 
var web; 
var list; 

clientContext = SP.ClientContext.get_current(); 
web = clientContext.get_web(); 
listCreationInfo = new SP.ListCreationInformation(); 
listCreationInfo.set_title("User data"); 
listCreationInfo.set_templateType(SP.ListTemplateType.genericList); 
list = web.get_lists().add(listCreationInfo); 

clientContext.load(list);

Execute the query and provide callback functions

Now, you are ready to send the query to SharePoint and get your list created. You can send your query by using the executeQueryAsync method in the client context object. You should provide callback functions to handle the success and failure events. The following code shows how to use the executeQueryAsync method and provide callback functions for the success and failure events:

clientContext.executeQueryAsync(
 function () { alert("Success!") },
 function () { alert("Request failed") }
);

Great! So… where is your list?

To see your list, just go to the following URL:

app_web/Lists/User%20data

clip_image002[6]

Figure 1. List created using the JSOM

Easy! Well, I think that is enough for one post. I hope you found it useful to get up and started using the JSOM in your apps for SharePoint.

Beyond this article

  • About the tools used for this article: I wrote the code for this article on my home computer. I don't have Visual Studio or SharePoint installed on that computer. I just used the "Napa" Office 365 Development Tools. You can sign up for Office 365 and install the "Napa" app in your developer website. Then you can build apps just like the one explained in this article, using only your browser. For the full instructions, see Sign up for an Office 365 Developer Site.
  • About storage in real-world apps: You can check for apps that handle data in real-world scenarios by browsing the Office Store. The Customer Orders and Products app is a good example of a real app that handles and stores data.
  • About more operations using the JSOM: The example in this article is a very simple one. I chose creating a list to demonstrate how to use the JSOM. You can find many more operations in the article How to: Complete basic operations using JavaScript in SharePoint 2013.

Let us know what other topics you would like us to talk about by using the comments section below. Thanks for your time!