Friday, 18 March 2016

OfficeDev: Convert Comment App to a nuget Package



In my previous post  I provided a full walkthrough to create a Comment SharePoint Addin, In this post I will convert the existing Addin to a nuget package so we can add it to any newly create SharePoint addin via visual studio template and at the end we will try to create a minimal Angular seed for SharePoint Add-in by removing all non-generic components.
  1. First let's  create the folder strucure for the nuget package
    1. Content Folder
    2. Tools Folder
    3. Nuget Spec file (generate it using nuget spec)
    4. gulp definition file for packaging the nuget package
  2. Open the folder using VSCode Let's update the nuget spec file , I'm going to skip the usual package metadata stuff and I will jump to the files, as you can see there is two different types of files , some PS scripts under tools folder and some assets we need to add to the SharePoint Add-in.
Adding the files using nuget spec file tags won't do the trick as it need to be copied to SharePoint Add-in web site as the addin is being installed. The only way of doing this is to create a new Module element and add files to it.  Most of the code written to automate these steps is added to the init.ps1 file. 
as you can see in the nuget spec file snapshot below, all the files has been copied not to the content folder but to the package folder as a staging location. Afterwards, the PowerShell script under the tools folder will read these files from the package folder and copy it to the appropriate container(s).


The only files copied directly to the destination content folder is the files under pages folder because there is a module element defined already for the SharePoint Add-in pages.

Init.ps1

As mentioned earlier, this file is responsible of creating the necessary containers for the files to be copied to (SharePoint Module elements). The script kicks off by trying to get the project item template which represents a Module element. afterwards, it adds two different containers:
  1. Apps : container for all angular goodness  
  2. Assets: another container for all the needed CS
Note: always reference the Item template by the item template name not the folder name, if you struggle to find it open the .vstemplate file and use the exact name.

The second trick is to create the SharePoint artifacts (Lists and App Part) needed by the app, from the previous post I've exported the Comment List as a Project Item Template and using the same technique I've added it to the new SharePoint Add-in project. Similar thing is done with the App Part artifact.



Note: One Important thing to notice is , If I created the module elements and try to copy the files via nuget spec file <files> section it won't work , I will have some files under the module element folder structure but they aren't included in the module elements definitions (element.xml) so it won't be copied to the SharePoint Add-in app web site.

In a nutshell the main steps are:
  1. Create Containers using Module Project Item Template
  2. Copy the files to the template root
  3. Copy the files via PowerShell script from the template root to the appropriate location.
Building the nuget package using gulp

Create a new gulpfile  and define a task that runs the command line nuget pack.


now if you run gulp build the nuget package will be created as below:

To test this nuget package , simply get the source code from here, and build the sample then add the build destination folder to your nuget packages source(s) then create new SharePoint Add-in and add the package to it.


a minimal version with a simple Angular goodness will be published to nuget.org soon.


Tuesday, 1 March 2016

OfficeDev: Comment Add-in Walkthrough


In this post will try to walk you through build of a SharePoint Add-In , The addin will have the following building blocks:

  1. Comment List to store the comments.
  2. App Part which can be added to any page and will have a parameter called PageID used to identify particular page comments, the app part will be Angular App consist of
    1. Comment Service : Load the comments from the comment list 
    2. Comment directive:render the comments using a template (comments.html)
    3. Main controller and a main view.
  3. We will update the app manifest file to allow read user profile properties to show the user image and display name.
now let's dive into more details about the above building blocks:

Comment List

The comment list will be used to store the comments and it will have the following fields:

App Part

Represented by  the page commentapp.aspx with a single parameter (PageID) , commentapp.aspx will be the entry point for an angular app, in the angular app we had the $locationProvider Html5Mode enabled , we add the base href to be the commentapp.aspx page itself.

  1. Main controller:  will have the addcomment, load comment functions which utilizes the comment service. note: when executing POST request to add comment we need to get the current SharePoint context FormDigest value
  2. Then you need to pass the value to you addComment function in comment service.
  3. Comment Directive , which basically render the comments and replies and as you can see in the structure below , I'm using a recursive directive , which is having a comment directive within the comment directive template.
  4. Getting user properties is just another function in the comment service , we retrieve the Email and Display name properties and construct the avatar url from o365 outlook( you might want to discard this approach if you are building this app for on-Premises version of SharePoint)
to make the last bit of code works without getting 403 forbidden error we need to update the app manifest file and add an app permission to read user properties

Let's see the addin in action

In my developer site I'll install the SharePoint AddIn, the addin will prompt me to trust it , once we gone pass the installation bit, we can Add the app part to our test page and that's how the app part is rendered, 
Sadly I have only one user in my O365 tenant, In Part II of this walk-though we will see how can we convert this example into a nuget package we can add to an Out of the box SharePoint Add-In Project.
Hint:: Don't forget to add the PageID parameter to filter out different comments.

The code for this app can be found @https://github.com/ministainer/CommentApp