Pipevine Deployment and Integration Instructions

PLEASE read the Angular deployment guide and familiarize yourself with how Angular works before attempting to deploy Pipevine.

But also keep in mind this is not a typical angular project (it’s a webcomponent, not an SPA), so don’t just blindly copy-paste commands from the angular guide without understanding what they do.

Here’s a table of build options which you may find useful:

Option Description
–prod Enables a production build, which improves performance
–outputHashing Enables or disables adding the hash of a script’s contents to its filename
–outputPath Path to place build files

0. Compilation

If you’re not the one compiling Pipevine you can ignore this

To build the client application you probably want to use something like:

npm run build:client:prod -- --outputHashing=false

1. Include the scripts

You need to embed the scripts on your page like the following:

<body>
  <pipevine-root deploy-url="..." api-host="..." chili-host="..." close="someCallback()"></pipevine-root>
  <!-- more on this later -->
  <script src="https://example-static-bucket.s3.amazonaws.com/runtime-es2015.js" type="module"></script>
  <script src="https://example-static-bucket.s3.amazonaws.com/runtime-es5.js" nomodule></script>
  <script src="https://example-static-bucket.s3.amazonaws.com/polyfills-es5.js" nomodule></script>
  <script src="https://example-static-bucket.s3.amazonaws.com/polyfills-es2015.js" type="module"></script>
  <script src="https://example-static-bucket.s3.amazonaws.com/main-es2015.js" type="module"></script>
  <script src="https://example-static-bucket.s3.amazonaws.com/main-es5.js" nomodule></script>
</body>

The src attributes will need to be changed depending on whether you enabled output hashing, and you will definitely need to add the full path to the files if they’re coming from a different domain. Generally speaking you need to include runtime, polyfills, and main, and for each of them you also need to include the -es2015 version as type="module" and the -es5 version as nomodule.

If you’re wondering what the module/nomodule is about, the angular documentation includes the following:

Each script tag has a type=“module” or nomodule attribute. Browsers with native support for ES modules only load the scripts with the module type attribute and ignore scripts with the nomodule attribute. Legacy browsers only load the scripts with the nomodule attribute, and ignore the script tags with the module type that load ES modules.

2. Insert the element and configure attributes

You need to add a pipevine-root element to your page. Where you add it doesn’t really matter because the application will always open fullscreen anyway.

You also may need to add some configuration options depending on your setup:

Attribute Description
deploy-url Base url to where the pipevine static assets are deployed.
api-host Base url to the Pipevine api server.
uppy-companion-host Base url to the uppy companion api.

You can either add the element in HTML:

<pipevine-root
  deploy-url="https://example-static-bucket.s3.amazonaws.com"
  api-host="https://example-server-host.net/api"
  chili-host="https://example-server-host.net/CHILI/"
  uppy-companion-host="https://example-server-host.net/uppy-companion"
></pipevine-root>

Or dynamically in javascript:

const pv = document.createElement('pipevine-root');
pv.setAttribute('deploy-url', 'https://example-static-bucket.s3.amazonaws.com');
pv.setAttribute('api-host', 'https://example-server-host.net/api');
pv.setAttribute('chili-host', 'https://example-server-host.net/CHILI/');
pv.setAttribute('uppy-companion-host', 'https://example-server-host.net/uppy-companion');
document.body.append(pv);

3. Add styles

Include styles.css in your page as well:

Most of the styles are designed to not interfere with the rest of your page, but we’re currently working on removing the bootstrap styles from the root scope.

<head>
  <link href="https://example-static-bucket.s3.amazonaws.com/styles.css" rel="stylesheet" type="text/css" />
</head>

4. Call methods and attach event handlers

Next you need to attach event handlers and call the preloadEditor and openDocument methods.

document.querySelector('pipevine-root'); // if you don't already have a reference from inserting the element in javascript

// this event is firef when the angular framework finishes initialization. the preloadEditor and openDocument methods will not be available until after this event is fired!
pv.addEventListener('loaded', () => {
  // then you can preload the editor. this preloads Chili in the background so it loads quicker when the user selects a document.
  pv.preloadEditor();
});

// fired when the user saves a document
pv.addEventListener('onsave', e => {
  console.log('Save event!', e.detail);
});

// fired when the user clicks the exit button
pv.addEventListener('onexit', e => {
  console.log('Exit Event!', e.detail);

  //closes the editor
  pv.close();
});

// this method takes an id to an existing document and opens the Pipevine editor in fullscreen.
pv.openDocument('123');