Building your first Project Server app : Part 3 – Taking the app to the next level
By blurg64
In this post, we will take our app that we built in Napa and successfully tested and export it out to Visual Studio to enhance the app, specifically we are going to add a ribbon button so our app can be invoked directly from the PWA ribbon.
Exporting the Napa solution out to Visual Studio
Whilst Napa is a great tool, at the moment it is not possible to add a CustomUI Action at present, so we need to use Visual Studio. Luckily Napa has a handy export to Visual Studio capability. Before we export, make sure you have Visual Studio 2012 installed and have downloaded and installed the Visual Studio Tools for Office 2013 from http://t.co/lrkaq4au (this is currently Preview 2).
To export the project, in Napa click on the ‘Open in Visual Studio’ icon
You will be prompted for which language you wish to export using, our app is all JavaScript so it doesn’t really matter, but I usually pick C#
Napa will prompt you to download a small .exe file that will open Visual Studio and the exported project.
As you can see, our app has been opened in Visual Studio 2012 with all the components you would expect to see
To add our ribbon button, we need to add a new item to our app project. To do so, right click on the project name and choose Add > New Item
From the menu, select Ribbon Custom Action, name it and click Add.
A dialog will pop up asking to configure the custom action. Make sure you choose to expose the custom action in the host web (in our case the PWA instance) and that it is scoped to None (we don’t want it on a list, but rather the ribbon). Click on Next.
Another dialog will pop up asking us to provide a target location, label text etc. Unfortunately the options it provides are a little limited for Project Server, so we will accept the defaults (by clicking Finish) and edit them later.
Visual Studio will generate the Ribbon XML automatically, including placeholder graphics which is pretty cool. But unfortunately the generated XML won’t meet our needs.
For our app, we want to add a new group to the Project ribbon in Project Center, and pop our button in there, like so…
To do this we need to define a new group, the button and a graphic in the XML, which follow the usual format for a SharePoint / Project Server ribbon customisation. However there are a couple of changes in 2013 with regards to ribbons:
- We can’t have JavaScript in the ribbon – which means instead of calling our App.js from the ribbon like we would have in 2010, now we have to call the default.aspx page and get that to do the work
- We need to use a special token ~appWebUrl to tell SharePoint to navigate to the app web which resides under the host web (PWA)
- We will also pass through the {StandardTokens} query string that contains information about the site calling the app, including language and most importantly it’s location.
In Visual Studio, replace the contents of the Elements.xml file for the custom action with the following:
[sourcecode language=”xml”]
<CustomAction Id="cb1834f2-06ed-4b4e-9531-71bdc4539fcb.HostWebCustomAction”
Location="CommandUI.Ribbon">
<Group Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish”
Sequence="110”
Description="Publish Custom Group”
Title="Publish App”
Template="Ribbon.Templates.Flexible2">
<Button Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish.PublishAllProjects”
Sequence="10”
Command="Invoke_CustomAction”
Alt="Publish”
LabelText="Publish all projects”
TemplateAlias="o1”
Image16by16=”_layouts/15/1033/images/ps16x16.png?rev=23”
Image16by16Left="0”
Image16by16Top=”-112”
Image32by32=”_layouts/15/1033/images/ps32x32.png?rev=23”
Image32by32Left="0”
Image32by32Top=”-224”/>
<MaxSize
Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish”
Sequence="140”
GroupId="Ribbon.ContextualTabs.ProjectCenter.Home.Publish”
Size="LargeLarge”/>
<CommandUIHandler
Command="Invoke_CustomAction”
CommandAction="~appWebUrl/Pages/Default.aspx?{StandardTokens}"/>
[/sourcecode]
In the XML above, I have cheated and used one of the out of the box buttons for Project Server, but you could add your own in the Images folder of the solution and reference it.
Next, we need to make some minor changes to the to the App.js file to ensure return the page back out of the app when it’s completed. To do this replace the QueueJobSent() function as per below.
[sourcecode language=”javascript”]
function QueueJobSent(response) {
// Whilst the call is status = 0, i.e happening, then show the publishing message
if (response == 0) {
$(‘#spanMessage’).text(‘Publishing projects…’);
} else
// When the call has come back successfully, show the published message and then navigate back
if (response == 4) {
// Navigate back to the calling page
var spHostUrl = decodeURIComponent(getQueryStringParameter(‘SPHostUrl’));
// We’re in an iFrame, so make sure you use the top
window.top.location.href = spHostUrl;
}
}
[/sourcecode]
We also need to add another function called getQueryStringParameter which reads the query string from the SPHostURL (part of the {StandardTokens}.In this case here I am borrowed some code to read the query string used in a couple of Microsoft app examples.
[sourcecode language=”javascript”]
// Function from MS examples to read the query strings
function getQueryStringParameter(urlParameterKey) {
var params = document.URL.split(‘?’)1.split(‘&’);
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split(‘=’);
if (singleParam[0] == urlParameterKey)
return decodeURIComponent(singleParam1);
}
}
[/sourcecode]
With that all the development is complete, all we need to do is come up with a graphic that will be seen in SharePoint, the app should have a transparent background if you want it to fit in with Project Server 2013’s new look and feel themes. Once you have built an icon, add it into the Images folder of the solution and configure the Icon in the App Manifest.
Now all we need to do is build the app, deploy it to the corporate catalog and add it back to our PWA instance.
Installing our new improved app will now show a button on the ribbon in the Project Center that when clicked will navigate out to our Publish Projects page and then once complete, navigate back to the calling site.
So you can see how simple and easy it was include a new button on the ribbon that calls our app directly, publishes the projects and then returns the user to the source site.
In the final post in this series, I will take you through the submission process to make your app available in the SharePoint app store to start making millions 