Building your first Project Server app : Part 3 – Taking the app to the next level

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 (this is currently Preview 2).

To export the project, in Napa click on the ‘Open in Visual Studio’ icon

Napa : Open in Visual Studio

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 : Export Project to Visual Studio

Napa will prompt you to download a small .exe file that will open Visual Studio and the exported project.

Napa : Run the exported solution

As you can see, our app has been opened in Visual Studio 2012 with all the components you would expect to see

Our project in Visual Studio

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

Visual Studio : Add > New Item

From the menu, select Ribbon Custom Action, name it and click Add.

Add Ribbon Custom Action

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.

Create Custom Action for Ribbon

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.

More Create Custom Action

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.

Visual Studio Generated Element.xml

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…

Publish all projects on Ribbon

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:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="">
  <CustomAction Id="cb1834f2-06ed-4b4e-9531-71bdc4539fcb.HostWebCustomAction"
      <CommandUIDefinition Location="Ribbon.ContextualTabs.ProjectCenter.Home.Groups._children">
        <Group Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish"
        Description="Publish Custom Group"
        Title="Publish App"
          <Controls Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish.Controls">
            <Button Id="Ribbon.ContextualTabs.ProjectCenter.Home.Publish.PublishAllProjects"
            LabelText="Publish all projects"
      <CommandUIDefinition Location="Ribbon.ContextualTabs.ProjectCenter.Home.Scaling._children">

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.

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
   = spHostUrl;

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.

// Function from MS examples to read the query strings
function getQueryStringParameter(urlParameterKey) {
    var params = document.URL.split('?')[1].split('&amp;');
    for (var i = 0; i < params.length; i = i + 1) {
        var singleParam = params[i].split('=');
        if (singleParam[0] == urlParameterKey)
            return decodeURIComponent(singleParam[1]);

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.

Configure AppIcon in 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.

Projects Published

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 Smile

4 thoughts on “Building your first Project Server app : Part 3 – Taking the app to the next level

  1. Pingback: Building your first Project Server app : Part Zero–The introduction « EPMSource

  2. Pingback: Building a Project Server app « Buzz Blog

  3. Pingback: Building a Project Server app « SharePoint (and Project Server) Shenanigans

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s