Replace your Page and Partial classes with middleware

August 19, 2016 9:54 am Published by Leave your thoughts

Starting from Starcounter 2.2, it is recommended to replace the usage of Page and Partial classes with HtmlFromJsonProvider and PartialToStandaloneHtmlProvider middleware.

Since Starcounter 2.2, old APIs Handle.AddRequestFilter and Handle.AddResponseFilter are marked as obsolete in favor of the new Application.Use API. See the release notes for details.

The switch to rely more on Application.Use caused us to think what other parts of Starcounter’s API could take benefit from middleware-oriented architecture. Middleware allows you to compose the behavior of your app in an elegant manner.

The new middleware architecture allows us to replace built-in classes Page and Partial. This is a big deal, because until now, many apps contained view-models that could not extend the Json object directly. Now they can, and all the additional behavior is applied with middleware.

Replace Page with HtmlFromJsonProvider.

The Page : Json class makes JSON responses aware of HTML. When the client requests a HTML representation (Accept: text/html) and the JSON object that your respond with has a Html property, Page checks the value of this property. If the value is a path to a file, Page sends the contents of the file as the response (Content-Type: text/html).

The new solution is to use HtmlFromJsonProvider. It behaves exactly the same as the Page class, but with cleaner code. Your view-model classes can just extend the Json class now.

Replace Partial with PartialToStandaloneHtmlProvider.

The Partial : Page class makes JSON responses aware of PuppetJS. When the client requests a HTML representation (Accept: text/html), Partial sends a wrapper HTML document that loads polymer.html, puppet.js and other scripts and initiates the WebSocket connection.

This allows your app to have an implicit standalone mode with zero additional “Standalone” templates. When only your app is running, this middleware will invoke the PuppetJs connection. When another app wraps your app (e.g. Launcher), this middleware is not used, because the wrapping app invokes the connection.

The new solution is to use PartialToStandaloneHtmlProvider middleware. It behaves exactly the same as the Patial class, but with cleaner code. Your view-model classes can just extend the Json class now.

How to do the migration

The migration should be as easy as replacing any usage of Page and Partial with Json.

Change any of:


pre>[fusion_builder_container hundred_percent="yes" overflow="visible"][fusion_builder_row][fusion_builder_column type="1_1" background_position="left top" background_color="" border_size="" border_color="" border_style="solid" spacing="yes" background_image="" background_repeat="no-repeat" padding="" margin_top="0px" margin_bottom="0px" class="" id="" animation_type="" animation_speed="0.3" animation_direction="left" hide_on_mobile="no" center_content="no" min_height="none"][SomePage_json]
partial class SomePage : Page, IBound<AnyData> {


partial class SomePage : Json, IBound<AnyData> {

Then, in the file where you create the HTTP handlers, add the following lines on top to use the middleware:

Application.Current.Use(new HtmlFromJsonProvider());
Application.Current.Use(new PartialToStandaloneHtmlProvider());

We are already migrating some of our sample apps to this. Take a look at a migration commit in the People app.

Remove explicit standalone pages

When using the PartialToStandaloneHtmlProvider middleware, your view files should only containt the view <template> code. They should not contain HTML code that creates a PuppetJs session:

<!DOCTYPE html>
    <title>App Name</title>
    <meta charset="utf-8" />
    <script src="/sys/webcomponentsjs/webcomponents.js"></script>
    <link rel="import" href="/sys/polymer/polymer.html" />
    <link rel="import" href="/sys/starcounter.html" />
    <link rel="import" href="/sys/starcounter-debug-aid/src/starcounter-debug-aid.html" />
    <link rel="import" href="/sys/imported-template/imported-template.html" />
    <link rel="import" href="/sys/starcounter-include/starcounter-include.html" />
    <link rel="import" href="/sys/bootstrap.html">
/* ... */

If your app contains a HTML file that looks like above (often called StandalonePage.html or MasterPage.html), you can (and should!) safely remove that. PartialToStandaloneHtmlProvider will wrap your views in HTML code that performs PuppetJs connection.

If you would like to override the default HTML code that performs PuppetJs connection, you can provide a HTML template as a string to the PartialToStandaloneHtmlProvider constructor. See the the documentation for details.[/fusion_builder_column][/fusion_builder_row][/fusion_builder_container]

Categorised in:

This post was written by Marcin Warpechowski

Leave a Reply

Your email address will not be published. Required fields are marked *