Building Client Side Web Parts
with the SharePoint Framework
About Me
Professional
Presented by
Travis Lingenfelder
Founder & Principal Consultant
http://www.constellationsolutions.com
Twitter: @tlingenf
LinkedIn: https://www.linkedin.com/in/travislingenfelder/
Email: [email protected]
• Building web parts since 2005 and WSS v2
• SharePoint roles:
• Solution Architect
• Consultant
• Administrator
• Developer
• Done everything from records management
to dot-com sites
• SharePoint development team configuration
manager – automated build and deploy
• Migrations
• SharePoint On-prem, SharePoint Online
• Azure development
• Office 365
Personal
•
•
•
•
Married with 2 awesome kids
Amateur astronomer
Guitar player
Enjoy the outdoors: hiking & camping
Then and Now…
Evolution of JavaScript
Old-school JavaScript
Object-Oriented Modules
JSON Syntax
<script type="text/javascript">
function foo(bar) {
alert(bar);
}
var MODULE = (function () {
var my = {},
privateVariable = 1;
var JSONModule = {
foo("hello world");
</script>
"myProperty": 1,
"myMethod" : function() {
function privateMethod() {
// ...
}
my.moduleProperty = 1;
my.moduleMethod = function () {
// ...
};
return my;
}());
MODULE.moduleMethod();
// ...
}
};
JSONModule.myMethod("hello world");
Use TypeScript with The
SharePoint Framework
Enter TypeScript
TypeScript
transpiles to ⇒
class Greeter {
constructor(public greeting: string) { }
JavaScript
var Greeter = (function () {
function Greeter(greeting) {
this.greeting = greeting;
public greet(): string {
return "<h1>" + this.greeting + "</h1>";
}
Greeter.prototype.greet = function () {
}
};
return "<h1>" + this.greeting + "</h1>";
};
return Greeter;
var greeter = new Greeter("Hello, world!");
}());
document.body.innerHTML = greeter.greet();
var greeter = new Greeter("Hello, world!");
document.body.innerHTML = greeter.greet();
The Rest of the Tool Chain
≅
≅
Visual Studio Code
≅
≅
≅
File → New Project
Connect
≅
http server
IIS
Building a Promoted Links ClientSide Web Part
Promoted Links Demo
Demo 1
Promoted Links in SharePoint
Setup Your Dev Environment
Downloads
• Visual Studio Code - https://code.visualstudio.com
• Node JS LTS version (4.x.x) - https://nodejs.org/en/
NPM Commands (Node.js Command Prompt)
• npm -g install npm@3
• npm install --global --production windows-build-tools
• npm i -g yo gulp
• npm i -g @microsoft/generator-sharepoint@latest
Create a Web Part Project
Your Project Is Ready
Run ≅ gulp serve
To avoid this warning in the future, run:
gulp trust-dev-cert
Source Control ≅ Git
Building a Promoted Links ClientSide Web Part
What is React?
• JavaScript UI library from Facebook
• Instagram.com written entirely in React
Virtual DOM
• Renders subtrees of nodes based upon state changes
• When changes are applied
• 1) performs a “diff” to identify what has changed
• 2) reconciliation to update the DOM based on the diff
Don’t manipulate React elements with jQuery!
Component rendering using JSX (JavaScript XML syntax transform)
Anatomy of a React Component
• props – properties passed to a React component
• state – component status used when rendering this display
Lifecycle Methods
•
•
•
•
•
•
•
•
render() – process the virtual DOM and update the display
getInitialState() – initial state value
getDefaultProps() – fallback for when props are not supplied
setState(state) – triggers UI updates
componentWillMount() – Invoked once, on both client & server before rendering occurs.
componentDidMount() – Invoked once, only on the client, after rendering occurs. LOAD DATA HERE
shouldComponentUpdate() – Return value determines whether component should update.
componentWillUnmount() – Invoked prior to unmounting component.
Thinking in React
• Split UI into multiple
components – a component
should do only one thing
• Build in phases – start with a
static version and add
functionality
• Do not set state directly – use
setState()
SharePoint Framework Client Side Web Part
Import other JavaScript modules
import
import
import
Import
default from ‘path’;
{ nonDefault } from ‘path’;
default, { nonDefault } from ‘path’;
* as moduleName from ‘path’;
Pay attention to this import
Creates an instance of a React
component in render()
Define a class and mark it as
the default export. Extends
BaseClientSideWebPart.
Define the web part property
pane: pages, groups, controls
React Component
The exports for the previously
mentioned import statement.
JSX. Not your standard HTML
element. i.e. use of
className, not class
(TypeScript reserved word).
Creates a new class based
from a React.Component.
Define props and state types.
Use { } to access JavaScript
object values
Create a new file/React component to be used for each Promoted Link Item
We will use an Office UI
Fabric React component for
displaying the images.
Create a new file in the
components folder.
Define the props that will be
used for this component.
Define a class for the new component
and mark it as the default export. Extends
React.Component<propsType, stateType>
Office UI Fabric
http://dev.office.com/fabric
Microsoft library of UI
styles & components
• Similar to Bootstrap and
FontAwesome
•
•
•
•
•
•
Styles
Icons
Colors
Typography
Responsive grid
Large array of UI components for
use across Office, SharePoint, and
Other applications
Multiple versions
•
•
•
•
•
Fabric Core
Fabric React
Fabric JS
Fabric AngularJS
Fabric iOS
Establish basic rendering for the PromotedLinkItem component
Don’t forget to export objects
you will use in other
components.
Office UI Fabric Image component.
Supply IImageProps values.
Use props when rendering
the component
Use JSX to define the
rendering for the component
Add instances of the PromotedLinkItem to the parent PromotedLinks component
Import the PromotedLinkItem
component and property types
Create static items while
performing initial testing and
applying styles
SharePoint Workbench
running on localhost
≅ F5 (Run)
Demo 3
Basic Rendering
Non-Conflicting Styles
Let’s Add Some Style
Now it is starting to look
like a Promoted Links web
part
Sass (Syntactically Awesome StyleSheets)
• CSS extension
• Allows for the use of:
•
•
•
•
•
Variables
Calculations
Imports
Mixins
etc.
• Nested rules for organization
• Transpiles to normal CSS
SASS Style Sheet
Variable for use in other styles
Using the variable in multiple styles
Use the variable in calculations
Demo 4
Sass Styles With Real-Time Compile and Refresh
Git – now is a good time to save changes to
source control
commit
sync
Add Hover State
• Show a description panel when the mouse hovers over an item.
• Remember to use setState()  calls render().
• Tip: .bind(this) provides context of the React component, not the
HTML element in events.
Define the component
state type
Event handlers to
manipulate the state. Use
setState to trigger
render(). Can use JSON for
setting simple values.
Change rendering
according to current state.
In this case swap CSS class
names.
Register the state type for
use with the component
Set the initial state. Ok to
directly set state here.
Register the events on an element. Use
.bind(this) to ensure the component
context from within event handler, not
the hovered HTML element.
Demo 5
Hover Interaction
Working With SharePoint Data
Promoted Links list in classic SharePoint
Promoted Links Client Side Web Part
Use componentDidMount()
lifecycle method to get data
Initialize the state with
an empty array
If working in a local workbench
set the state with mock data.
Note: collapsed for brevity.
If NOT in a local workbench
query SharePoint for items in
the list configured in the listId
property.
Easy request method from
Waldek Mastykarz. See
resources slide for link.
Tip: Use ` for strings with
embedded variables.
For each query result, add a
new item to the array
Make sure to setState
For each item in the state
array, create a new
PromotedLinkItem
Brackets indicate a
JavaScript block
Demo 6
Complete Solution
References
Get the code, slide deck, or watch the presentation video
http://www.constellationsolutions.com/how-to/client-side-web-parts-with-the-sharepoint-framework-usingreact-and-the-office-ui-fabric
https://github.com/Constellation-Solutions/spfx-promoted-links
Other Tutorials and References
Learning React - https://scotch.io/tutorials/learning-react-getting-started-and-concepts
Basics of Git - http://rogerdudler.github.io/git-guide/
Easy-to-use Request method for SharePoint (Waldek Mastykarz) - https://blog.mastykarz.nl/buildingsharepoint-framework-client-side-web-parts-react/
Dynamic drop-downs in web part properties - http://www.sharepointnutsandbolts.com/2016/09/sharepointframework-spfx-web-part-properties-dynamic-dropdown.html