Webstrates Package Manager (WPM) #

Webstrates Package Manager (WPM) makes it possible to easily import and use code from one webstrate to another. In this guide is a short description of the most used functionality. See the WPM API documentation for more.

Packages and the WPM Object #

Defining a Package #

The following HTML defines a simple WPM package.

<wpm-package id="myPackage">
  <wpm-descriptor>
  {
      "description": "My package",
      "dependencies": [
          "#myOtherPackage",
      ],
      "assets": ["myImage.png"],
      "version": "1"
  }
  </wpm-descriptor>
  <script>
    console.log("Hello from myPackage");
  </script>
</wpm-package>

The root element must be of the type wpm-package and must have and id attribute. The package must also have a wpm-descriptor containing a serialized JSON object with the following properties:

• description: A human-readable description of the package
• dependencies: Selectors for other packages that this package depends on.
• assets: Assets that the package uses. These will be copied over with the package when it is installed in another webstrate.
• version: The current version of the package.

All children of <wpm-package> are considered the content of the package (scripts, styles, code fragments, other DOM elements, etc.).

Requiring a Package #

The following code installs a package from another webstrate:

WPM.require([
     {package: "somePackageName", repository: "/somewebstrate"},
     {package: "someOtherPackageName", repository: "/somewebstrate"}
]).then(()=>{
    //Packages are now installed
});

require is async but await can be used:

await WPM.require([
     {package: "somePackageName", repository: "/somewebstrate"},
     {package: "someOtherPackageName", repository: "/somewebstrate"}
]);
// Packages are now installed

By default, packages will be installed transiently inside document HEAD. To install it permanently a permanent appendTarget must be provided:

let targetNode = document.querySelector("#packageContainer");
await WPM.require([
     {package: "somePackageName", repository: "/somewebstraterepo", appendTarget: targetNode},
]);

Requiring External Libraries #

In the context of a package (all Codestrates code is run in the context of a package) you can require an external library through:

await WPM.requireExternal("https://d3js.org/d3.v5.min.js");

If its uploaded as an asset:

await WPM.requireExternal("d3.v5.min.js");

CSS files can be required in the same way.

Package Manager UI #

The package manager of Codestrates v2 comes with a UI in the Cauldron editor. It allows to get an overview of installed and available packages and repositories, and makes it possible to add, remove, and add packages locally.

Opening the Package Manager #

The UI of the package manager can be opened using the the following menu entry in Cauldron: “File” → “Packages…”:

Repositories #

Packages are structured inside repositories in the package manager UI. Repositories can be either other webstrates, from which packages are installed from, or repositories that reside on another website. For instance, the packages which implement the Execution Engine, Cauldron, and WPM are stored on GitHub. The repository indicates from which source a package is installed from on page load.

Packages #

For each repository, the package manager UI lists all available packages of the respective repository. Besides the title, version, license, and description of each package, the list also indicates which packages are installed and how.

The first column (“play” icon) indicates whether the package is automatically required on boot and the second column (“download-box” icon) indicates, whether the package is embedded locally or loaded transiently from the repository on each load. Embedding it locally makes it possible to modify the package, e.g., to try out changes. Loading packages transiently ensures that the codestrate always uses the most recent version of them. By default, packages are loaded transiently.

If a box has a checkmark and is colored in dark blue, the package is selected explicitly to be required or embedded in a codestrate. If the box has merely a light blue color, the package is loaded as a dependency of another package.

Managing Packages #

To add new packages to a codestrate, one merely has to check the checkbox in the list. The package is required instantly from the repository and installed. For example, after adding the “fragment_markdown” package in the screenshot above makes the Markdown fragment type immediately usable in Cauldron.