Add SpaServices with ASP.NET Core doc by scottaddie · Pull Request #3563 · dotnet/AspNetCore.Docs

scottaddie · 2017-06-23T19:50:27Z

Review URL
This is the new SpaServices doc which is intended to serve as a reference rather than an end-to-end tutorial. The goal is to focus on what SpaServices offers to developers creating SPAs with ASP.NET Core. Please review.

Rick-Anderson

@scottaddie @tdykstra it wouldn't let me make a new PR of this PR, I'd like to figure that out. So I had to commit into Scott's branch. See 573272c and let me know where I was too aggressive.
@tdykstra point out any changes that should be backed out

Rick-Anderson · 2017-06-23T19:59:04Z

+---
+# Using SpaServices for Creating Single Page Applications with ASP.NET Core
+
+By [Scott Addie](https://github.com/scottaddie)


can you add the other guy - if you got anything from his work.

Rick-Anderson · 2017-06-23T20:11:41Z

+
+[!code-javascript[Main](../client-side/spa-services/sample/SpaServicesSampleApp/webpack.config.js?range=53)]
+
+In the following Angular example, the *ClientApp/boot-server.ts* file utilizes the `createServerRenderer` function and `RenderResult` type of the `aspnet-prerendering` npm package to configure server rendering via Node.js. The HTML markup destined for server-side rendering is passed to a `resolve` function call, which is wrapped in a JavaScript `Promise` object of type `RenderResult`. The `Promise` object's significance is that it asynchronously supplies the HTML markup to the page for injection in the DOM's placeholder element.


We really like to avoid english versions of code. Would the following work? Do you really need all that type info:

The HTML markup destined for server-side rendering is passed to a resolve function call, which is wrapped in a JavaScript Promise object ~~of type RenderResult.~~

or even better
The HTML markup destined for server-side rendering is passed to a resolve function call, ~~which is wrapped in a JavaScript Promise object of type RenderResult.~~

I prefer the first of your alternatives; the second omits the mention of Promise which is used in the following sentence.

Rick-Anderson · 2017-06-23T20:19:34Z

+
+## Webpack Dev Middleware
+
+[Webpack Dev Middleware](https://webpack.github.io/docs/webpack-dev-middleware.html) introduces a streamlined development workflow whereby Webpack builds resources on demand. The middleware automatically compiles and serves client-side resources when a page is reloaded in the browser. The alternate, less efficient approach is to manually invoke Webpack via the project's npm build script when a third-party dependency or the custom code changes. An example of said build script in the `package.json` file is:


Files are italic, never code fenced

Rick-Anderson · 2017-06-23T20:34:44Z

+    * doesn't optimize the client-side code for performance
+1. **Production**:
+    * excludes source maps
+    * optimizes the client-side code via bundling & minification


Should you link to our B&M article?

Rick-Anderson · 2017-06-23T20:41:23Z

@scottaddie much better.. Do you have a sample app to point to?

scottaddie · 2017-06-23T20:58:36Z

@Rick-Anderson Thank you. There's a link to the sample app in the beginning of the doc.

Rick-Anderson · 2017-06-23T22:49:07Z

@scottaddie I think it's ready to ask one of the SPA folks to review it.

tdykstra

This looks much better! My comments are mostly style nits.

tdykstra · 2017-06-23T20:11:18Z

+ms.technology: aspnet
+ms.prod: asp.net-core
+uid: client-side/spa-services
+ms.custom: H1Hack27Feb2017


Does this belong here?

tdykstra · 2017-06-23T20:13:04Z

+
+By [Scott Addie](https://github.com/scottaddie)
+
+This article describes the value proposition of [SpaServices](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices) in building a Single Page Application (SPA) with ASP.NET Core.


Could link just to the repo, i.e. https://github.com/aspnet/JavaScriptServices

tdykstra · 2017-06-23T20:14:27Z

+
+<a name="using-spa-services"></a>
+
+## Using SpaServices with ASP.NET Core


This h2 is practically identical to the h1, and the text under it seems like it's actually the doc intro; it could replace the "this doc covers" text currently located under the h1.

tdykstra · 2017-06-23T20:18:46Z

+<a name="what-is-spa-services"></a>
+
+## What is SpaServices?
+


Why do we introduce JSServices and then ignore it. I think if it's relevant here some more explanation of the relationship between the two and why JSServices is called a "project" would be helpful.

Will readers understand what nonopinionated means? Or something like:

~~Because~~ SpaServices ~~is a nonopinionated, client framework-agnostic library, it~~ doesn't lock you into a particular client framework, library, or coding style.

This almost sounds like a separate paragraph, as it seems off the topic of whether SS can be used to develop SPAs.

tdykstra · 2017-06-23T22:29:16Z

+
+SpaServices provides useful infrastructure such as:
+* [Server-side prerendering](#server-prerendering)
+* [Webpack Dev Middleware](#webpack-dev-middleware)


When used in text (as opposed to code or a package name) it might be better to spell out development

tdykstra · 2017-06-23T23:06:43Z

+
+## Creating a new project
+
+JavaScriptServices provides pre-configured application templates. SpaServices is used in these templates, in conjunction with different frameworks and libraries such as Angular, Aurelia, Knockout, React, and Vue.


We should have a "what is" paragraph for JavaScriptServices somewhere

tdykstra · 2017-06-23T23:07:46Z

+| MVC ASP.NET Core with React.js and Redux  | reactredux | [C#]     | Web/MVC/SPA |
+| MVC ASP.NET Core with Vue.js              | vue        | [C#]     | Web/MVC/SPA | 
+
+To create a new project using one of the SPA templates, include the **Short Name** of the template in the `dotnet new` command. The following command creates an Angular application with ASP.NET Core MVC configured for the server-side:


no hyphen in server side

tdykstra · 2017-06-23T23:08:57Z

+### Set the runtime configuration mode
+
+Two primary runtime configuration modes exist:
+1. **Development**:


Does this need to be an ordered list?

tdykstra · 2017-06-23T23:10:36Z

+
+### Running with Visual Studio 2017
+
+Open the *.csproj* file generated by the `dotnet new` command. The required NuGet and npm packages are restored automatically upon project open. This restoration process may take up to a few minutes; and, the application is ready to run when it completes. Click the green run button or press `Ctrl` + `F5`, and the browser opens to the application's landing page. The application runs on localhost according to the [runtime configuration mode](#runtime-config-mode). 


; and, --> , and

Ctrl + F5 --> Ctrl+F5 or just Ctrl+F5 (so long as style is consistent throughout the doc; we haven't established a preference for one or the other yet)

tdykstra · 2017-06-23T23:13:35Z

+npm test
+```
+
+The script launches the Karma test runner, which reads the settings defined in the *karma.conf.js* file. Amongst other settings, the *karma.conf.js* identifies the test files to be executed via its `files` array:


scottaddie · 2017-06-27T20:05:43Z

@Rick-Anderson and @tdykstra I've implemented many of your suggestions. Please take another look.

Rick-Anderson · 2017-06-27T21:53:50Z

Fixes #2461 @scottaddie looks great
@jawache @FabianGosebrink @fiyazbinhasan please review.

damienbod · 2017-06-28T05:49:25Z

Maybe you could update the packages to the latest versions typescript, angular, types/node, how can you view the finish doc, I need to login when I click the review URL

scottaddie · 2017-06-28T13:53:55Z

@damienbod Unfortunately, the review URL is only available internally. The npm package versions used by the latest stable release of dotnet new angular are what the sample app uses. We'd like to keep those versions aligned to avoid confusion.

@Rick-Anderson What's the best way for Damien to review this doc without access to the internal review page?

Rick-Anderson · 2017-06-28T15:03:14Z

@dend Do we have a timeline on when external customers will be able to display builds? [@]damienbod is asking:

how can you view the finish doc, I need to login when I click the review URL

Rick-Anderson · 2017-06-28T15:46:34Z

@bradygaster customer would like to review doc.

FabianGosebrink · 2017-06-28T15:51:26Z

I also only reviewed the last commit and approved this one. Would like to take a peek at the document as well if possible :)

Rick-Anderson · 2017-06-28T16:21:44Z

@damienbod @FabianGosebrink use https://www.dropbox.com/sh/qgdar994qilhoi4/AADcNg553QGc_d271D5bLa4ia?dl=0 to download 3.zip

FabianGosebrink · 2017-06-28T16:22:47Z

Did so, thanks.

damienbod · 2017-06-28T17:50:20Z

ASP.NET Core Tag Helpers provided by SpaServices simplify the implementation of server-side prerendering by invoking the JavaScript functions on the server for you.

=>

ASP.NET Core Tag Helpers provided by SpaServices, simplify the implementation of server-side prerendering by invoking the JavaScript functions on the server.

damienbod · 2017-06-28T17:56:33Z

Some code blocks are JavaScript, but the code is Typescript code. Would it be possible to use Typescript code blocks for the Typescript code?

Rick-Anderson · 2017-06-28T17:59:55Z

Some code blocks are JavaScript, but the code is Typescript code. Would it be possible to use Typescript code blocks for the Typescript code?

Looks like that's a know tag.

TypeScript typescript, ts

damienbod · 2017-06-28T18:09:10Z

Additional resources

Only Angular is listed. Maybe the other SPA frameworks, libraries could be also listed

scottaddie · 2017-06-28T18:10:34Z

@damienbod Nice catches! I've implemented the wording and TypeScript changes.

@Rick-Anderson Thoughts on listing other supported SPA frameworks in Additional resources?

damienbod · 2017-06-28T18:14:02Z

nice docs :), looks good.

fiyazbinhasan

Looks great!

scottaddie · 2017-06-30T16:16:29Z

@Rick-Anderson Is this ready to merge?

spboyer · 2017-06-30T17:00:49Z

👏 @scottaddie

irontoby · 2017-10-10T15:23:46Z

@scottaddie is "changes are simply another banned word pushed to the browser" what you meant to commit? Looks like possible Scunthorpe issue...

https://github.com/aspnet/Docs/blame/4f67e612670e29d08c73864c6829b66f8f4de4ff/aspnetcore/client-side/spa-services.md#L168

(Sorry if you got 2 notices for this, wasn't sure whether GitHub notifies for comments on merged commits)

scottaddie · 2017-10-10T15:34:40Z

@irontoby Thank you for pointing this out! I'll fix it right now.

scottaddie added 20 commits June 20, 2017 12:46

Initial commit for revised SpaServices doc

c46eee1

Add Tag Helpers text and code

f5c1ff8

Add screenshot of global postList variable

d14aa67

Restore Tag Helpers code sample to original state

04d665c

Adjust Tag Helpers heading styles

04df38b

Add Webpack Dev Middleware code and text

4fcb40f

Reorganize headings and start to HMR content

b54230f

HMR changes

0585a5a

Additional tweaks to content

a7cb255

Add HMR screenshot and finish SpaServices prereqs section

0fe0da0

Start to project creation content for .NET Core CLI

671530c

Add Karma / Jasmine testing content

35fc763

More minor tweaks

b351dc8

Refine existing content

82aab44

Remove unused Tag Helper from Index view

37f1da2

Update TOC

dbfd8c5

Start publishing section of content

8cb4185

Finish writing publishing section of content

f8770d1

Remove original, unused images

e3746b0

Replace future tense usage

f93b7f1

scottaddie requested review from Rick-Anderson and tdykstra June 23, 2017 19:50

dnfclas added the cla-already-signed label Jun 23, 2017

Update spa-services.md

573272c

Rick-Anderson suggested changes Jun 23, 2017

View reviewed changes

Rick-Anderson approved these changes Jun 23, 2017

View reviewed changes

tdykstra reviewed Jun 23, 2017

View reviewed changes

Implement suggestions from Tom and Rick

bc665a3

FabianGosebrink approved these changes Jun 28, 2017

View reviewed changes

Implement suggestions from Damien

170da91

fiyazbinhasan approved these changes Jun 30, 2017

View reviewed changes

Rick-Anderson merged commit 4f67e61 into dotnet:master Jun 30, 2017

scottaddie deleted the scottaddie/spa-services-doc branch June 30, 2017 19:30

fiyazbinhasan mentioned this pull request Jul 19, 2017

2.0 Create an angular app using the templates #3769

Closed


		[!code-javascript[Main](../client-side/spa-services/sample/SpaServicesSampleApp/webpack.config.js?range=53)]

		In the following Angular example, the ClientApp/boot-server.ts file utilizes the `createServerRenderer` function and `RenderResult` type of the `aspnet-prerendering` npm package to configure server rendering via Node.js. The HTML markup destined for server-side rendering is passed to a `resolve` function call, which is wrapped in a JavaScript `Promise` object of type `RenderResult`. The `Promise` object's significance is that it asynchronously supplies the HTML markup to the page for injection in the DOM's placeholder element.


		## Webpack Dev Middleware

		[Webpack Dev Middleware](https://webpack.github.io/docs/webpack-dev-middleware.html) introduces a streamlined development workflow whereby Webpack builds resources on demand. The middleware automatically compiles and serves client-side resources when a page is reloaded in the browser. The alternate, less efficient approach is to manually invoke Webpack via the project's npm build script when a third-party dependency or the custom code changes. An example of said build script in the `package.json` file is:


		By [Scott Addie](https://github.com/scottaddie)

		This article describes the value proposition of [SpaServices](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices) in building a Single Page Application (SPA) with ASP.NET Core.


		<a name="using-spa-services"></a>

		## Using SpaServices with ASP.NET Core


		## Creating a new project

		JavaScriptServices provides pre-configured application templates. SpaServices is used in these templates, in conjunction with different frameworks and libraries such as Angular, Aurelia, Knockout, React, and Vue.


		### Running with Visual Studio 2017

		Open the .csproj file generated by the `dotnet new` command. The required NuGet and npm packages are restored automatically upon project open. This restoration process may take up to a few minutes; and, the application is ready to run when it completes. Click the green run button or press `Ctrl` + `F5`, and the browser opens to the application's landing page. The application runs on localhost according to the [runtime configuration mode](#runtime-config-mode).

Conversation

scottaddie commented Jun 23, 2017 • edited by Rick-Anderson Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rick-Anderson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rick-Anderson commented Jun 23, 2017

Uh oh!

scottaddie commented Jun 23, 2017

Uh oh!

Rick-Anderson commented Jun 23, 2017

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scottaddie commented Jun 27, 2017

Uh oh!

Rick-Anderson commented Jun 27, 2017

Uh oh!

damienbod commented Jun 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scottaddie commented Jun 28, 2017

Uh oh!

Rick-Anderson commented Jun 28, 2017

Uh oh!

Rick-Anderson commented Jun 28, 2017

Uh oh!

FabianGosebrink commented Jun 28, 2017

Uh oh!

Rick-Anderson commented Jun 28, 2017

Uh oh!

FabianGosebrink commented Jun 28, 2017

Uh oh!

damienbod commented Jun 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

damienbod commented Jun 28, 2017

Uh oh!

Rick-Anderson commented Jun 28, 2017

Uh oh!

damienbod commented Jun 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scottaddie commented Jun 28, 2017

scottaddie commented Jun 23, 2017 •

edited by Rick-Anderson

Loading

damienbod commented Jun 28, 2017 •

edited

Loading

damienbod commented Jun 28, 2017 •

edited

Loading

damienbod commented Jun 28, 2017 •

edited

Loading