So to create a new SharePoint 2013 Hosted App you need to ensure that when you create the project in Visual Studio you select the correct option.
Once the project is created you should get a structure similar to this:
The basic construct is the following:
- Feature Folder – Normal SharePoint Feature dialog you have used in the previous tooling
- Content Folder – Any specific content that will reside in the App Web, by default the App.CSS file
- Images Folder – Images that will reside in the App Web
- Pages Folder – The core pages that will reside in the App Web (Core User Experience)
- AppManifest File – Base configuration and permission sets for the App
If we deploy this solution as is, it will render values that are called from the App.js file. This will display your current display name.
This page is loaded from the App Web, this is the separate web site that gets stood up as part of the new App Model. A SharePoint 2013 Hosted App when deployed does this automatically and crea6es a URL similar to this:
So let’s think about an example app we could build. For this demonstration I would like an end user to access a list, see the list items, press a ribbon button, and then popup a dialog over the top listing out the selected items only and then allow the end user to perform some action. I can hear you thinking this is going to be easy. Write a full trust solution that does the following:
- Adds a Ribbon Button, maybe as a custom “Additional Page Head” control so it shows up on all Ribbon Bars
- Uses C# to get the currently viewed list
- Opens the Dialog
- Loads a custom page, maybe “_layouts” page
- Custom Page uses C# to get the currently selected list, renders only the selected items based on what is passed to it
Of course there are many ways of doing this same thing whether using Full Trust C# or Sandboxed Client Object Model code. So how do we do this for a SharePoint 2013 Hosted App. First off let’s look at adding a ribbon button. In the Visual Studio right click he project and select “Add New Item“. From the list select the “Ribbon Custom Action“.
Once selected you are asked to define the type of Ribbon Action. The first thing is where you wish this custom action to reside. The Host Web is SharePoint, the App Web is the funny website that got created in my Office 365 Tenant when I deployed it. As we need this ribbon button to be in the current SharePoint, we will select the “Host Web” option. We also have the ability to scope the action to one of the following:
The interface does not allow for scoping actions to anything other than List Templates and List Instances. Selecting List Template will populate the second dropdown with the available list templates in the SharePoint site that is connected to Visual Studio. If you select List Instance it will populate the dropdown with available lists that are deployed and active in the SharePoint site. For this example we are going to choose “None” as I would like to associate this action to more than one list or template.
The tooling then let’s you select the control location from a predefined list:
This list is great but once again does not list every location you would want to use. You can overtype this with your own values if needed. For this demonstration we will use “Ribbon.List.Actions“, with the control navigation set to the default page.
Visual Studio will then create the custom action object in the project and the “elements.xml” file is loaded and will look similar to this:
The code looks fairly straight forward and what you would be used to seeing, however notice that the “CommandUIHandler” is a redirect to the following URL:
You will notice it is using a token for the URL, the “~appWebUrl” is a unique one that SharePoint 2013 understands and will replace at the build and deployment time into the full URL of the App Web, so it will end up being something like this:
You will also see an appended query string of “StandardTokens“, this is one of the replacement tokens that are available. This specific one combines five other tokens. “SPHostUrl“, “SPAppWebUrl“, “SPLanguage“, “SPClientTag” and “SPProductNumber“. Sahil Malik has a list of all the tokens that are available in SharePoint 2013 Apps and when they can be used.
Now if we build the application is Visual Studio all is well. Now if we try to deploy it something strange happens.
So back to performing a redirect, this means we need to write the code in the App Web for getting list items etc. as per our design for this demonstration app. If we change the code back and build and deploy we should be back to the site now. To test the ribbon we can access a list and see in the “Actions” section our new button.
If you click this button it will redirect you to the App Web and show the default page. If we look at the URL we can see the token values:
This is great as it already passes a lot of information that we would need to us in the App Web, such as the actual site we are in. We can change our Visual Studio solution to also send us further details, such as the ID’s of the selected items, the list ID and name. To do this we need to make changes to the “CommandAction” link. Modify the link to be the following:
Now build and deploy the solution and test the link this time. This time access the list and select a few items as shown below and click the ribbon link and the URL should now be similar to this:
This time you will notice that we get the list ID and the selected ID’s of the values we selected in the list, so now we just have to wire up the new page in the App Web to display these items in a list view type grid.
This design now means that we need to allow the end user to perform the required tasks such as selecting items in SharePoint, send that to the App Web and then re-connect to the SharePoint site and list or library using the client object model or the REST API features. This logic will be added to the “App.js” file which is referenced in the “default.aspx” page.