Getting Started - JS API

This section describes the basic usage and functionality of the Mooltipage JavaScript API. The JS API is an advanced interface, and the information on this page assumes a background knowledge of JavaScript and Node.JS. Additionally, this guide does not explain the basic concepts and features of Mooltipage. It is recommended to review the CLI documentation even if you intend to use only the API. You will also need an editor capable of working with JavaScript. A basic text editor like Notepad will work, but a full editor such as VS Code is recommended.

If you followed the recommended setup in the installation section, then you have a basic npm project with Mooltipage installed. The next step is to create a "build" script that will be called by Node.JS to compile your project. This script will be responsible for loading, configuring, and invoking Mooltipage. For a basic general-purpose build script, follow these steps:

1. First, we need to create the build script file. Create a file call "build.js" in the root of your project. It can be moved later if you prefer to structure your project differently.
2. Next, open the new file in an editor. Add this line to the top of the file: const { Mooltipage } from 'mooltipage'; This will instruct Node.JS to load the main Mooltipage API constructor, and save it to the local constant Mooltipage.
3. Mooltipage is loaded, but we need an instance before we can use it. To create an instance, we call the Mooltipage() construct and pass it a configuration object. Create a configuration object like this: const mooltipageConfig = { inPath: './src/', outPath: './dist/', formatter: 'pretty' }; With this config object, Mooltipage will be configured to load inputs from "./src" and save them to "./dist". Additionally, HTML outputs will be formatted with the "pretty" HTML formatter. For more details on these properties and their effects, see the CLI usage section.
4. Now that we have loaded Mooltipage and have prepared a config object, we can create a Mooltipage instance. We create an instance by invoking the Mooltipage constructor. Add this code to your build script: const mp = new Mooltipage(mooltipageConfig); This instance is immediately ready to use and can be reused for as many pages as desired.

At this point, the build script should look like this (comments added for clarity): // import and load mooltipage const { Mooltipage } from 'mooltipage'; // prepare mooltipage config object const mooltipageConfig = { // load inputs from "./src" folder inPath: './src/', // save outputs to "./dist" folder outPath: './dist/ // format output HTML for human readability formatter: 'pretty' }; // create mooltipage instance const mp = new Mooltipage(mooltipageConfig); This script is almost done. Mooltipage is loaded, configured, and ready to start compiling pages. All that is left is to tell Mooltipage which files to process.

Building a single page is very easy. You simply invoke the processPage function with the path to file. The default compilation pipeline will load, compile, and save the file automatically. Simple usage looks like this: mp.processPage('./index.html'); All compilation settings, like the input / output paths and selected formatter, are taken from the configuration values provided earlier. If you need to compile a page with different settings, then you can create another Mooltipage instance with new configuration data. The instances are completely isolated and will not conflict.

Compiling a single page is useful, but most projects will include more than one page. The obvious way to compile multiple pages is to call processPage multiple times, like this: mp.processPage('./index.html'); mp.processPage('./pages/page1.html'); mp.processPage('./pages/page2.html'); This will work, but there is a better way. In addition to processPage, the Mooltipage API also exposes the processPages function which compiles multiple pages at once. Simply pass in an array containing paths to all of the pages that you want to compile, and they will all be compiled sequentially. The above example can be simplified to: const pagePaths = [ './index.html', './pages/page1.html', './pages/page2.html' ]; mp.processPages(pagePaths);

All of the examples so far have only emulated functionality that is already available through the CLI. The API, however, is capable of more. This and the following sections will demo functionality that is only available through the API. If you have followed all the previous sections, then your build script should look something like this (comments added for clarity): // import and load mooltipage const { Mooltipage } from 'mooltipage'; // prepare mooltipage config object const mooltipageConfig = { // load inputs from "./src" folder inPath: './src/', // save outputs to "./dist" folder outPath: './dist/ // format output HTML for human readability formatter: 'pretty' }; // create mooltipage instance const mp = new Mooltipage(mooltipageConfig); // list pages to compiled const pagePaths = [ './index.html', './pages/page1.html', './pages/page2.html' ]; // compile all pages mp.processPages(pagePaths); This build script is perfectly usable, but it does nothing that the CLI can't already do. To make it actually useful, lets add support for a special page where HTML formatting must be disabled. To do this with the CLI, multiple commands are required. With the API, however, there is no such limitation. Add the following to the script: const mooltipageConfigNoFormat = { inPath: './src/', outPath: './dist/ formatter: 'none' }; const mpNoFormat = new Mooltipage(mooltipageConfigNoFormat); mpNoFormat.processPage('./pages/special.html'); This code will instruct Mooltipage to compile special.html without an HTML formatter, while the other pages still compile in pretty mode. Unfortunately, this is not very compact. An additional seven lines of code for one just one page is somewhat excessive. To mitigate that, we can rework the script a bit. Change the script to look like this: const { Mooltipage } from 'mooltipage'; // create base config object const baseConfig = { inPath: './src/', outPath: './dist/',. formatter: 'pretty' }; // create mooltipage instances const mp = new Mooltipage(baseConfig); const mpSpecial = new Mooltipage(Object.assign(Object.create(baseConfig), { formatter: 'none' }); // compile pages mp.processPages([ './index.html', './pages/page1.html', './pages/page2.html' ]); mpSpecial.processPage('./pages/special.html'); This version is smaller and more extensible. This works by creating a single "base" configuration object that holds settings common to all configurations used. The main "mp" instance uses this directly, while the mpSpecial instance extends baseConfig and overrides the "formatter" property to none. If additional special compilation modes are needed, then adding them is as simple as duplicating the "new Mooltipage" block and modifying the configuration overrides.

One of the most useful benefits of the API interface is that it enables dynamic calls into Mooltipage. Both processPage and processPages can be called multiple times - even from within loops or other functions. This makes it possible to selectively include or exclude a page based on some factor external to Mooltipage. For an example, lets assume that we have a "debug.html" that should only be included in non-production builds. We can use the NODE_ENV environment variable to check if this is a production build. To support this, add the following to the build script: const isProduction = process.env.NODE_ENV === 'production'; if (!isProduction) { mp.processPage('./pages/debug.html'); } With this code, debug.html will only be included if Node.JS is NOT running in production mode.

The API's dynamic functionality is not limited to just pages that are known about in advance. It is possible to build an arbitrary number of pages with any filenames and content. As an example, lets extend the build script to accept a list of pages from the command line. In a real-world application, these could be the paths to semi-compiled HTML artifacts produced by an earlier build process. This feature could be implemented like this: const pages = process.argv.slice(2); for (const page of pages) { mp.processPage(page); } This will compile any number - including zero - of extra pages passed in via the command line.

If you've been following all previous sections, then your build script should look like this (with tweaks to minimize boilerplate): const { Mooltipage } from 'mooltipage'; // create base config object const baseConfig = { inPath: './src/', outPath: './dist/', formatter: 'pretty' }; // create mooltipage instances const mp = new Mooltipage(baseConfig); const mpSpecial = new Mooltipage(Object.assign(Object.create(baseConfig), { formatter: 'none' }); // compile pages mp.processPages([ './index.html', './pages/page1.html', './pages/page2.html' ]); mpSpecial.processPage('./pages/special.html'); // compile debug page if not in production if (process.env.NODE_ENV !== 'production') { mp.processPage('./pages/debug.html'); } // compile extra pages from CLI mp.processPages(process.argv.slice(2)); This is a pretty powerful build script. It supports compiling pages with differing settings, optionally including pages based on environment, and dynamic pages from external sources. But if were to run it, you would notice right away that something is missing. This script includes no feedback, progress, or any output at all! For hardcoded page paths, it is simple to add console.log statements to print progress. But that wont work for processPages, where multiple pages are passed at once. Fortunately, the API accepts a callback that will be invoked whenever a page is compiled. You can attach a callback to the config object using one of these syntaxes: // Option 1 const config = { onPageCompiled: (page) => console.log(`Compiled \${ page.path }`); } // Option 2 function pageCompiledCallback(page) { console.log(`Compiled \${ page.path }`) } const config = { onPageCompiled: pageCompiledCallback } For this sample build script, we will use Option 1 due to its smaller size. Add the onPageCompiled callback to the baseConfig object, and the build script should look like this: const { Mooltipage } from 'mooltipage'; // create base config object const baseConfig = { inPath: './src/', outPath: './dist/', formatter: 'pretty', onPageCompiled: (page) => console.log(`Compiled \${ page.path }`); }; // create mooltipage instances const mp = new Mooltipage(baseConfig); const mpSpecial = new Mooltipage(Object.assign(Object.create(baseConfig), { formatter: 'none' }); // compile pages mp.processPages([ './index.html', './pages/page1.html', './pages/page2.html' ]); mpSpecial.processPage('./pages/special.html'); // compile debug page if not in production if (process.env.NODE_ENV !== 'production') { mp.processPage('./pages/debug.html'); } // compile extra pages from CLI mp.processPages(process.argv.slice(2)); With this change, the build script will now print out a status line each time a page is compiled. We won't be using them in this example script, but the page object provided to the callback has more properties than just "path". The definition for that object (in TypeScript) is: interface Page { // Path to the file (relative to inPath) readonly path: string; // Root of the Document Object Model (DOM) tree representing the page, can be used to examine the output readonly dom: DocumentNode; // Formatted HTML output of the compiled page readonly html: string; } For some advanced situations, it can be useful to be able to programmatically example the compiled output. The "dom" and "html" properties are exposed for that purpose. Be aware, however, that the onPageCompiled callback is called *after* the page is saved. Changes here will have no effect on the compiled output.

TODO: example of adding a loosely-integrated <if-debug> custom element