fittings

Fittings allows you to easily fit different client-side frameworks in to BigPipe. It allows you to control:

• Which frameworks/libraries should be loaded in on every page.
• How the client/server-side shared templates should be exported and exposed on the client.
• Initialize the client-side plugins.
• Bootstrap the loading of the page.
• Control the structure of the HTML fragments that are written.

Table of Contents

• Install
• Usage
  • Processing
    • fittings.tag
    • fittings.template
    • fittings.plugins
    • fittings.bootstrap
    • fittings.fragment
    • fittings.library
    • fittings.middleware
    • fittings.use
    • fittings.on
  • API
    • fittings.get
• License

Install

This module is intended for server-side usage and is released in the public npm registry. It can be installed by running the following command on the CLI:

npm install --save fittings

Usage

This part of the documentation focuses on implementing, adding a new Framework for the BigPipe framework. To create your own framework you need to extend the returned Fittings class as seen in the following example:

var Fittings = require('fittings');

Fittings.extend({
  template: 'foo.bar[{fittings:hash}] = {fittings:client};',
}).on(module);

The .on(module) automatically registers framework for you on the module so you don't need add module.exports = .. anymore. We also use it to extract the current directory of your file so we can do relative file lookups etc.

To understand how you can specify the framework you need to know how we process your instructions and which properties are used by BigPipe and what each property does.

Processing

The processing engine understands the set properties in two different ways:

1. When the property is a function it will call the function with an object and assumes that it returns a string that can be used.
2. If it's a string it will our sophisticated template engine over it which replaces all {fittings:<key>} with the value of <key> and returns the newly generated string.

This applies to all properties except the library property as is processed in an completely different way:

• If it's an Array, assumes that it should be left alone as is.
• If it's a function it will execute it and assumes it returns an Array.
• An object, which should have a path and expose property.
• When it's a string that starts with require('path').sep, it assumes it's the absolute path to a library that needs to be included and automatically wraps it in an array.
• Last case, it will attempt to the module systems module resolving method (require.resolve) on the string to get the absolute path for the given module.

Please do note that when you are using the function syntax that these functions will be called for every single page/pagelet that is processed by BigPipe. So try to keep these methods as light and fast as possible.

The template tags that we're using should be prefixed with {fittings: then the name of the property you want to add here and finally closing with the } again.

{fittings:name}

Will output:

john

If the supplied data object contains { name: 'john' }. We also support extracting deeply nested properties using a dot notation. For example:

{fittings:data.array.2.thing}

This will says we should get the data property, which is an object and we want it's array property. This property contains an array and we want the second item. The second item is also an object so we want the property thing as content.

The : char is a special data modifier instruction the modifier is the first non word character that follows the fittings prefix. All our template tags are processed by the replaces module which supports a variety of data output modifiers:

• {fittings<>key} Make sure that the data we're trying to add to the template is save to use inside of HTML tags.
• {fittings~key} Transform the receiving data in to a JSON.stringify structure.
• {fittings@key} Transform the receiving data in to a JSON.stringify structure without crashing on circular references like a normal stringify operation would.
• {fittings$key} Transform the data using the circular JSON parser and ensure that every value inside the JSON is encoded using the <> modifier.
• {fittings%key} Escape the data using the escape function.
• Any other non \W is just ignored and will indicated that the data should just be pasted in as normal (like {fittings:key} is).

You can actually change the name and syntax of these placeholders as they are processed using a regular expression.

fittings.tag

This is the regular expression that is used to find the special {fittings:what} keywords in your templates. If want to use a custom syntax you can change this regular expression to anything you want as long as it follows the following restrictions:

• The first capturing group should be a modifier that is supported by the replaces module.
• The second capturing group is the name of the key or pattern that is used to extract the data.

fittings.template

The template should contain a small template which introduces the templates that is shared between client and server. This template receives 2 properties:

• name Which is the name or md5 hash of library.
• client which contains the template function that needs to be added (already a string).

An example implementation could be:

mylibrary.register({fittings~name}, {fittings:client});

Which would result in to something like:

mylibrary.register("0f8bf99b55994d676634fae81fff2405", function (data) {
  with (data) return '<div>your '+ name +'</div>';
});

fittings.plugins

Kinda the same as the fittings.template, but instead of introducing templates you're adding new plugins. Just like the template, it has a name and client template key.

fittings.bootstrap

The bootstrap property allows you to provide a small bootstrap template which will be included by the bootstrap-pagelet as bootstrap property. This template receives all the information of the bootstrap pagelet so you can pass the amount pagelets the page expects to flush out etc.

<script>
var BigPipe = require('bigpipe')
  , pipe;

pipe = new BigPipe(undefined, { pagelets: {fittings:length}, id: {fittings~id} });
</script>

Please see fittings.library on how to use require to access your supplied libraries.

fittings.fragment

This is the actual fragment that is written to the page when a pagelet is rendered.

This is the actual HTML fragment that is written to the page once a pagelet is rendering. It has the following template tags available:

• template The HTML string that the pagelet generated. It has all it's HTML comments removed so it should be save be added within a HTML comment if needed.
• name The name of pagelet that is flushing it's output.
• id The unique id of this pagelet.
• data Additional data object that the pagelet has generated which should be synced to the client. See the Pagelet's internal render method for all various of properties that this object contains.
• state The state data that needs to be synced from server to client.

An example template could be:

<script type="pagelet/html" name={fittings~name} id={fittings~id}>
  {fittings:template}
</script>
<script>render({fittings$data}, {fittings$state});</script>

fittings.library

The location of the client side libraries that should be included. As you might have read in the processing section, there are many ways of specifying the location of the libraries. The specified libraries will be passed in to Browserify by default. If you've set an object it will use the expose property to "register" it in the require method. If you passed it a full string it will use the file name as module name. This allows you to require the library on the client side and initialize it anyway you want it.

Fittings.extend({
  library: require('path').join(__dirname, 'file.extension'),
  library: [require.resolve('module-name')],
  library: {
    path: require('path').join(__dirname, 'lib', 'whatever.extension'),
    expose: 'woop'
  }
}).on(module);

fittings.middleware

Additional middleware layers that need to be added to the BigPipe server. This should be an object where the key is the name of the middleware layer and the value is a pre-configured middleware layer.

Fittings.extend({
  middleware: {
    static: require('serve-static')(__dirname)
  }
}).on(module);

fittings.use

Additional plugins that need to be added to the BigPipe server. This should be an object where the key is the name of the plugin and the value is the required plugin:

Fittings.extend({
  use: {
    progress: require('bigpipe-progress')
  }
}).on(module);

fittings.on

Additional event that we listen on. We assume that this is an object where the key is name of the event you want listen on and the value is the function that should be executed for it. This uses the EventEmitter#on method internally so your function will be called for each and every event.

Fittings.extend({
  on: {
    log: function (line) {
      console.log(line);
    }
  }
}).on(module);

Please see the BigPipe framework documentation for the events that you can listen for.

fittings.initialize

When you add an initialize function to fittings it will be called once a new instance of the framework is created. It will receive the supplied BigPipe instance as argument so you unlimited control.

Fittings.extend({
  initialize: function initialize(bigpipe) {
  }
}).on(module);

API

The library provides a small API for processing all the specified processing instructions.

fittings.get

This method processes the set instructions for the given property name. If it's a function it will execute it, if it's a string it will replace all the things etc. The method accepts 2 arguments:

1. property The name of the property you want to have processed.
2. data Optional data object which will be passed in the processing function or used as replacement content for the {fitting:*} tags.

var Framework = Fittings.extend({
  template: ..
});

var f = new Framework(bigpipe);

License

MIT