SharePoint Clientside Project Generator
===================


This tool will automatically scaffold out your clientside sharepoint projects.  It's powered by Node.js and Yeoman.

----------


##Install

Install <a href="https://nodejs.org/en/">Node.js</a>, go for highest version. 
Install 'yo' and then the 'spclientside' generator

``` bash
#Install yeoman if you have never done so before
npm install --global yo

#install spclientside generator
npm install --global generator-spclientside
```

##Create Project

With Powershell, go to where you keep all your projects and run:
```bash
yo spclientside
```
The generator will ask you some questions like:
```bash
yo spclientside
----------------
? Your project name: mycompany-intranet
? Your SharePoint site url:  https://andrewpetersen.sharepoint.com
? Your namespace (this will prefix all your deployed files):  droopy
----------------
```
You should now have a new folder named after your project (mycompany-intranet).  Change directory into the project folder and install all of your dependencies.  This will probably take a few minutes.

```bash
cd mycompany-intranet
npm install
```
##Provision a List
When you provision a list, you specify a SharePoint url and a list name.  The generator will then connect to the site and extract the list's Schema XML and put in the the `/ProvisioningSchemas`.
Any XML files inside of `/ProvisioningSchemas` will be provisioned on your project's SharePoint site when your run `npm run spinstall`.
```bash
# From inside your project folder, run the 'list' generator
yo spclientside:list 
------------------------------
? What's url of the SharePoint site?:  https://andrewpetersen.sharepoint.com
? What's the name of the list?:  Comments
------------------------------
```
##Create a component (webpart)
The generator supports 2 types of web parts:

 - '**js**' - Similar to jquery plugins.  You just pass in a selector to the element that should contain your component
 - '**html**' - this type of component will upload an html file that can be referenced by a Content Editor Web Part

```bash
# From inside your project folder, create a new component
yo spclientside:component
---------------------------
? Your component name:  footer
? Your parent file type ('html' or 'js') :  js
---------------------------
# hit 'enter' to allow overwrite of components/index.js
```


##Tutorial: Custom Footer Control
Lets say we want to render a custom list driven footer.  First we will create a 'js' component.  Then we will update our site.js to create an instance of the footer component on all our pages.

Use powershell to navigate to the root of your project folder.

```bash
# From inside your project folder, create a new component
yo spclientside:component
---------------------------
? Your component name:  footer
? Your parent file type ('html' or 'js') :  js
---------------------------
# hit 'enter' to allow overwrite of components/index.js

   create src\scripts\components\footer\footer.css
   create src\scripts\components\footer\index.js
   create src\scripts\components\footer\templates\container.html
   create src\scripts\components\footer\templates\item.html

```
Next, we would go into `components/footer/index.js` and code it to query our "Footer" list and render the links.   

Then, we want to update our site-wide javascript to create an instance of the footer on every page.  Go to `entries/entry.site.js` and add the following to the end of the file.

```javascript
//prefix with the namespace (droopy) you specified when creating your project
droopy.components.footer.create("#DeltaHelpPanel");
```

We are all done coding so we want to build our code into the `/dist` folder, then copy the contents of `/dist` to the SharePoint site's Style Library.  Hint: If you want to build and not deploy, use `npm run build`
```bash
# Copy everything from /dist into /Style Libary/_${namespace}
npm run deploy
# You may get a popup asking you to log into SharePoint
```
Our javascript file now lives on SharePoint Style Library, now lets get it to fire on all of our pages by adding a Script Link custom action. 
```bash
# To see what is happening when you run spinstall, checkout install.ps1 at the root of your project
npm run spinstall
```

Go to your SharePoint site and gaze with wonder and amazement at your custom footer component.