This package provides a JavaScript bootstrap for your client-side code which can be embedded in your HTML pages. The bootstrap implements feature detection (cuts the mustard) to determine if the browser should receive a core or enhanced experience, and the capability to load script files as appropriate.
This package is compatible with Node 12+ and is distributed on npm.
npm install --save @financial-times/dotcom-ui-bootstrapAfter installing the package you can use it to embed the bootstrap data into your pages.
After installing the package you should add no-js and core class names to your document element (<html>). These can be used as hooks for styling elements when providing a non-enhanced, core experience. They will be swapped with js and enhanced class names if the bootstrap runs successfully.
<!DOCTYPE html>
- <html>
+ <html class="no-js core">Because the bootstrap is intended to load scripts asynchronously and as early as possible you should always check that the DOM is ready before initialising your client-side code. We recommend using the ready-state library which provides a promise-based interface for this:
import readyState from 'ready-state'
readyState.domready.then(() => {
console.log('Ready!')
})Please note that the bootstrap code should be embedded in the <head> section of your pages to ensure scripts begin downloading as soon as possible.
If you are using React to render your app you can use the Bootstrap component:
import { Bootstrap } from '@financial-times/dotcom-ui-bootstrap'
export default (props) => (
<html class="no-js core">
<head>
<meta charSet="utf-8" />
<title>My Amazing Website</title>
<Bootstrap coreScripts={props.coreScripts} enhancedScripts={props.enhancedScripts} />
</head>
<body>
...
</body>
</html>
)Otherwise this package provides two methods to manually integrate the bootstrap code into your templates. First you must insert a JSON formatted string of configuration into a <script> element with an ID of page-kit-bootstrap-config and then you must embed the bootstrap script itself:
const bootstrap = require('@financial-times/dotcom-ui-bootstrap/server')
function page() {
return `<!DOCTYPE html>
<html class="no-js core">
<head>
<meta charset="utf-8">
<title>My Amazing Website</title>
<script type="application/json" id="page-kit-bootstrap-config">
${bootstrap.formatConfigJSON(coreScripts, enhancedScripts)}
</script>
<script>
${bootstrap.getBootstrapJS()}
</script>
</head>
<body>
...
</body>
</html>`
}There is no client-side integration required. The bootstrap component can only be used on the server-side.
Returns a JSON formatted string representing the configuration for the bootstrap snippet. This must be inserted into a <script> element with an ID of page-kit-bootstrap-config. This method requires two arguments and has one optional argument:
-
coreScriptsAn array of JavaScript file URLs which are required by the page if the browser fails to cut the mustard and should deliver a core experience.
-
enhancedScriptsAn array of JavaScript file URLs which are required by the page if the browser successfully cuts the mustard and should deliver an enhanced experience.
-
trackErrorsIf enabled this will drop a tracking pixel on the page to send a JavaScript loading failure event to Spoor.
Returns the bootstrap code as a string. This should be inserted into a <script> element.
This package is used to generate a piece of JavaScript code to be embedded into your pages. This code should be executed as soon as possible by the browser. The code implements 4 features:
If JavaScript is available the no-js class on the document element will be replaced with js.
If the browser passes the cuts the mustard test then the core class name on the document element will be replaced with enhanced.
If any scripts fail to load a tracking pixel will be loaded to send a JavaScript loading failure event to Spoor.
Cutting the mustard is a function which uses feature detection to determine if a browser is capable of supporting the JavaScript-enhanced experience. Currently the enhanced experience is intended to target all modern browsers and IE11.
The configured script files will be asynchronously loaded and executed when ready. There is no guarantee that they will be downloaded and executed in the order specified.