Thursday, July 21, 2016

Reflections on Learning React....

What's quiet amusing (and frustrating….) is that the simplest user interactions with page elements have to be relearnt in a way fitting the paradigms of the React model. As an example, imagine a search form. Just a text box and a button, simple right? In "classic" JS, adding an onclick event handler to read and search on the value in the textbox takes no thought at all (ignoring here the "production -quality" trimmings that are necessary in a real world form, such as validation).

Reproducing this interaction in React requires knowledge of a few principles:
  • Event handlers are attached to an element as a property. If using JSX, be careful not to enclose the handler in quotes!
     < input onclick={this.submitSearch} type="button" value="Search" />
  • The "this" context pointing to the React component is not available in the event handler. That means that if the value in the text box is bound to a member of the component state, this value would not be accessible in the handler. There are two approaches to correcting this - either add the "bind(this)" call to the end of the handler invocation
     < input onclick={this.submitSearch.bind(this)} type="button" value="Search" /> 
    or define the handler as an arrow function
    submitSearch = ( e ) => { … }
  • Bind the text box default value to an initial value. Do not bind the value property, as doing so causes the box to behave as read only in the form. Also need to add an onchange handler for the text box, bound to a function that updates the appropriate member of the state object with the value from the control (
  • Add the shouldComponentUpdate() lifecycle function to the component, ensuring that the change of text value in the state member does not trigger the update (unless you want the search to occur on every key stroke)
  • Setting the state in React (using Typescript in VS Code) requires all members of the state object to be set each time

Tuesday, July 19, 2016

Browserify is Sensitive in its Entry Files Parameter - "Cannot Find Module" Error

Faced an issue today whilst using Browserify to bundle some JavaScript files. The JS files had been compiled in Visual Studio Code from Typescript TSX files via gulp, and were all stored together in a single intermediate folder.

The single JS output bundle file was created just fine by Browserify. But when used in an HTML page, that file would result in a "cannot fund module" error. This error is created in the _prelude.js module, part of the output from Browserify.

So, it was time to explore the contents of the bundled JavaScript file. That file contains sections for each of the bundled modules. The last of those modules is generally the one that executes after loading. If that module needs to reference methods or properties exported by other modules, then there should be a mapping between the exported module name and that module key in the bundled modules array. Looking at the end of my output file, that mapping was as follows:


This means that the "AppHeader" module was not reachable, leading to that "cannot find module" error. After plenty of research into the bundling tool (during which I came across this useful article by Ben Clinkinbeard that describes the Browserify actions), I went back to look at the calling task in gulp. There I found that the Entry Files parameter was using a glob to point at all the JS files in the intermediate folder - the result of some previous testing in a project on which this set of files was based.

I changed this parameter to point just at the single root JS file, reran the bundling task in gulp, and now the output file ended with this:

This new bundled file worked just fine in the browser. So beware the Entry Files parameter!

PS For lots more details on this tool, consult the Browserify handbook!

Modern JS in SharePoint (3) - NPM and Gulp

Here's a quick analogy to help visualize the difference between using Visual Studio and Visual Studio Code. Imagine you need to build a bookshelf. You can pop into Ikea, select a few shelf unit to suit your needs, add a few accessories, and then spend an hour or two at home assembling the units. All the instructions and the fittings are in the kit.

Alternatively you can build from scratch, selecting the wood, learning to use the right tools for each task, choosing the hardware from the huge available range of screws & bolts & brackets. Along the way you gain skills with the tools, and create something totally customized for your needs.

No doubt you see where this is leading.... Starting our with VS Code feels a little like an apprenticeship, with so many new techniques and concepts to master. The familiar development workflow in Visual Studio of "New Project..." is replaced when using VS Code by decisions of what tools and facilities I need in this project, and what build steps will be appropriate.

I think this is a good learning process to face. Disrupting our normal routines can be painful at first, but helps make us aware of new and better ways to do things. Core to the new development workflow is npm, the Node Package Manager. This is usually compared to Nuget, but npm is a more vital element in the process than Nuget is in VS.

There is plenty of guidance on the web of how to install Node and npm, so I won't repeat it here (in case you were wondering, Node runs JavaScript code in a background process, and is required if using npm & gulp).  I will, however, mention the usefulness of the integrated terminal window in VS Code (CTRL+`) - that has been the place in which I have carried out all the command-line work necessary in my projects.

Starting a New Development Project

Visual Studio Code focusses on files within a folder structure. The tools used within the editor expect files with particular names to be in certain locations in that folder structure - convention over configuration. The general principle when starting from scratch is to create a top level folder for you new development files, open that folder in VS Code, and then run the following:
npm init -y
This creates the package.json file, similar in some ways to the project file in VS - it stores high-level settings for your development project, including the node modules that are used during the development operations.

Tailoring the Development Workflow

Node modules are plugins that can add content to your development project (such as libraries needed in your code). And node modules can also add task handlers to help with the development workflow. We are working here in the open source world, so there are a variety of "competing" options when choosing how to automate and orchestrate tasks in your development process. By this, I mean the ability for the development environment to do such things as check the quality of our source code("linting"), running tests, translate coding languages into runnable formats (compiling or "transpiling"), and packaging the source code for deployment.

The main players at the time of writing for creating workflows from these tasks (otherwise known as task runners) are gulp and grunt. An alternative is to use webpack which is a bundling tool that is able to run tasks other than just bundling files. Each takes a different approach to automating tasks. Each can suit different projects, or can seem a better fit for our own way of working. Gulp defines the operations to perform in JavaScript, whereas grunt (and webpack) use configuration files to define the operations.

Using gulp

After some experimentation with webpack and gulp, personally I prefer gulp. It gives me huge flexibility in how I organise the development tasks, is easier to debug through the use of logging statements to explore status of the tasks, and I find it easier to visualize thanks to the low-level step-by-step control. But you may prefer one of the other approaches - as I say, its down to personal preference, as you can probably achieve the same outcomes with any of the approaches. James Nelson provides some useful ideas on this subject.

If you choose to use gulp, it is worthy to know that the gulpfile can be written in ES6/ES2015 - this article by Mark Goodyear explains how to achieve this (using babel, and renaming the gulpfile). Why do this? Its another opportunity to become familiar with the new coding styles in ES6/ES2015

In the next installment, I will explain the gulp configuration I have found useful.

Monday, July 18, 2016

Modern JS in SharePoint (2) - Visual Studio Code

How to compare the Visual Studio full IDE with Visual Studio Code? If the VS IDE were a high spec campervan, replete with every mod con and comfort to offer good living anywhere, VS Code is the nippy little two door sports car. Pared-down for speed and performance, but with enough optional extras to allow for comfort as well as fun (so, more Porsche than Mazda!).

SharePoint development used to need access to the server-side objects, allowing the compiled code to interact directly with the farm. In the newer world of building at the front end, that tight coupling is replaced by remote hosted compiled apps or by client-side code. So Visual Studio no longer needs to run on a SharePoint server.

The lightness of Visual Studio Code is refreshing. It loads quickly on my laptop, and it views my work as files in a series of folders rather than as solutions or projects. Extensions are available in a Marketplace, but for now I am keeping my install lean - after spending time recently investigating a problem in Visual Studio Professional related to a troublesome extension, I am keen to reduce the potential for add-ins to cause me difficulties. The marketplace includes extensions to aid the development workflow, such as tools to check the quality of your code (linters and validators) - but I suggest ignoring these for now. Instead, have a go with the task runners and associated tools from the world of Node. One of the huge benefits is that you'll gain web dev experience applicable beyond the SharePoint "walled garden".

I challenge you to look through the list of extensions you have installed in Visual Studio, and think about which of those you actually use? I know the feeling... "that looks useful, I'll install it and might use it later..."!

Learn the VS Code shortcut keys, and you can quickly be cruising along concentrating on writing good code rather than on nurturing the development environment. The integrated terminal window will soon become very useful in this new world of npm and task runners, so CTRL+` is a good combination to learn straight away.

You can grab VS Code from here - last time I downloaded the setup package, it was about 60MB in size.

Sunday, July 17, 2016

Modern JS in SharePoint - the Motivation

When building customisations and enhancements for SharePoint, JavaScript has been my technology of choice for the last few years. It simplifies the life cycle management, works across SharePoint Online or on-premises, and offers a huge foundation of libraries upon which to build. It also is being acknowledged as the way forwards within the SharePoint product itself - the "Modern Document Library" released in Office 365 uses the React JS framework.

I have to admit, though, that my JavaScript was being created in the "old fashioned" way. No ES6, no build process, just the "quick" approach of a simple file in the style library within SharePoint. That approach brings the benefits of simplicity in structure, of being quickly updateable where needed, and of requiring just a text editor plus the dev tools in the browser. It is a very effective technique for small enhancements such as modifying the display of a column in a list view.

But those benefits are eclipsed by the downsides when building bigger applications in JavaScript. Very quickly a single JS file becomes too long. Encapsulating methods and properties in IIFEs helps to some extent, but refactoring and testing becomes hard. The code becomes sensitive to change. A better way is needed.

One such "better way" is to adopt the tools and practices that are commonplace in the open-source web dev world. Amongst these are the use of:
  • Coding in modern JavaScript - ES6 and/or Typescript
  • "Transpiling" that code into JavaScript that is compatible with current browsers (as the browsers are not keeping up with all features in the standards) - Babel
  • Packaging the code to improve download times and browser processing
  • Configuring flexible build processes through the creation of task runners - Gulp
  • Manipulating code in nimble code editors rather than heavy-weight development environments - Visual Studio Code
It's a lot of change! I dived into that world last week, and getting to the first speck of working code in a SharePoint page has been a challenge, for sure. Here I would like to document some of the things I have tried, and the lessons I have learnt. The combination of tools in my new working set are not necessarily the right fit for your circumstances. I am not suggesting that this combination of tools and techniques are recommended as being best of breed - they are the ones that are working for me at present. My aim in this small set of articles is to give a little help if you are interested in the evolution to "enterprise-scale" front-end development for SharePoint.

Tuesday, May 27, 2014

A hidden benefit of presenting...

A big benefit of presenting technical subjects is the surprising new tangents that open to widen your existing knowledge of a subject. When preparing demos for SharePoint or JavaScript sessions, I often find that an investigation into data or techniques to enliven an example will uncover lots of new ideas and approaches that can benefit my every day work.

As an example, recently I was preparing a session on Visualising data in SharePoint through the use of OData and client-side code, and came across the wonders of Crossfilter for analysing/processing large data sets on the client. That (and the similar library "PourOver") look to make this type of data presentation very efficient. Looking forward to doing more with them.

Have you used these libraries yourself? Any good or bad experiences to share?

Wednesday, March 26, 2014

More "Small Steps in SharePoint" guides

Today I have published two more Small Steps in SharePoint (and Office 365) guides to achieving everyday tasks in the system:
If you have any suggestions or requests on other tasks I could cover in these guides, please let me know and I will add new ones to the set.