PlatformOS and Scrivito

PlatformOS is a world class marketplace engine created by the original Adobe Business Catalyst developers. It is a platform for developers and agencies to easily manage and scale multiple marketplace projects. When integrated with Scrivito, one has a full marketplace solution combined with unmatched WYSIWYG editing and content management. Once set up, you will find that platformOS provides many backend features to the typical Scrivito setup. This allows for forms, users, products etc. to be added with one solution rather than several serverless solutions as typically exampled in our documentation. Setup and usage is a bit out of the typical Scrivito pattern, and we will detail how to get started, show some examples and detail exactly how to integrate with platformOS.

The setup

platformOS uses Liquid templates as their standard templating engine. And while Liquid templates are good, adding Scrivito makes it even better, by allowing editors to create pages and add content without having to “code”. We will continue to use the Liquid templates, in part, as platformOS relies on their file structure to define the website. To get started, you will need a Scrivito tenant and a platformOS instance.

The basic integration

There a several steps to follow to convert the Example App provided with your Scrivito tenant. In the future, we will work with platformOS to provide an integrated Example App when you sign up. For now, follow along.

To begin, create a directory for your project on your computer and cd into it.

Copy
~ mkdir scrivito_market
~ cd scrivito_market

Then follow the instructions from the Marketplace-kit commands cheat sheet in the instance created at https://portal.apps.near-me.com/instances/number_of_your_instance. It looks like this:

Copy
marketplace-kit env add staging --email EMAIL_USED_FOR_pOS_LOGIN --url URL_OF_pOS_INSTANCE
marketplace-kit init
marketplace-kit deploy staging

Next, download the files from your Scrivito instance. You can get a zip file of your Scrivito Website code in the “Deployment” tab of your account at https://my.scrivito.com/tenants. Unzip the files and then move them into the same directory and at the same level you have the marketplace_builder files.

Copy
~ scrivito_market unzip ~home_folder/Downloads/example_app/* .

To get things wired up we will be updating the typical settings of the Example App. First, update webpack to work with platformOS's deployments by updating the build path. In "webpack.config.js" change the line const buildPath = 'build’; to const buildPath = 'marketplace_builder/assets’;.

Next, we need an empty publicPath for the static assets included in the project. To do this, update as follows:

webpack.config.js
Copy
...
{
  test: /\.(jpg|png|eot|svg|ttf|woff|woff2|gif|html)$/,
    use: [
      {
        loader: "file-loader",
        options: {
          name: "[name].[hash].[ext]",
          publicPath: "",
        },
      },
    ],
 },
...
 output: {
      publicPath: "",
...

To make the above work, we need to add a file to marketplace_builder/views/layouts:

marketplace_builder/views/layouts/javascript-variables.html.liquid
Copy
<script type="text/javascript">
  window.__cdnUrl = function() { return "{{ '' | asset_url }}" };
</script>

This file will look for the CDN URL platformOS assigns to our instance and where platformOS hosts all the asset files like static images, JavaScript, HTML and CSS. It then uses a special Liquid helper they have implemented and takes assets with an empty URL and assigns them the the asset_url, which is the cdnUrl. Sounds confusing, but this is how it works, and once setup, it just works.

Next, since platformOS uses Liquid templates for routing, we are going to use the pages and layouts to display the Scrivito Example App at the root page /. To do this, we need to add and update some files. The contents of these files can be found in the “public” folder of the Example App. After moving or copying the contents into the new files, you can delete the “public” folder as it is no longer needed. Click on each button to reveal the files and code:

MARKETPLACE_BUILDER/VIEWS/PAGES/
marketplace_builder/views/pages/home.html.liquid
Copy
---
slug: /
layout_name: application
---

This is the file platformOS will use to determine the content of the root page; here we just tell it to use the application layout.

marketplace_builder/views/pages/scrivito_extensions.html.liquid
Copy
---
slug: _scrivito_extensions
layout_name: scrivito_extensions
---

Scrivito Extensions are customized editing interfaces designed into the Scrivito editing UI. One example is the columns editor.

marketplace_builder/views/pages/scrivito.html.liquid
Copy
---
slug: scrivito
layout_name: scrivito
---

This page indicates which layout to use for the “/scrivito” path, otherwise known as the editing UI.

MARKETPLACE_BUILDER/VIEWS/LAYOUTS/
markteplace_builder/veiws/layouts/application.html.liquid
Copy
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="generator" content="Scrivito by Infopark AG (scrivito.com)">

  <title>Scrivito Example App JS</title>
  <link rel="preconnect" href="https://api.scrivito.com" crossorigin>
  <link rel="preconnect" href="https://api.scrivito.com">
  <link rel="stylesheet" href="{{ 'index.css' | asset_url }}">
</head>
<body>
  <div id="application">
    <span class="loader">Loading...</span>
  </div>

  <script src="{{ 'index.js' | asset_url }}"></script>
  {%- include 'layouts/javascript-variables' -%}
</body>
</html>

As you may note, this is the same code as previously seen in “public/index.html” in the Scrivito Example App codebase. We have updated it to be compatible with and use platformOS's asset_url helper.

marketplace_builder/views/layouts/scrivito_extensions.html.liquid
Copy
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="generator" content="Scrivito by Infopark AG (scrivito.com)">

  <title>Scrivito Example App JS - Extensions</title>
  <link rel="preconnect" href="https://api.scrivito.com" crossorigin>
  <link rel="preconnect" href="https://api.scrivito.com">
  <link rel="stylesheet" href="{{ 'index.css' | asset_url }}">
</head>
<body>
  <script src="{{ 'scrivito_extensions.js' | asset_url }}"></script>
</body>
</html>

Here we provide the HTML markup for displaying the scrivito extension editing interfaces.

marketplace_builder/views/layouts/scrivito.html.liquid
Copy
<!DOCTYPE html>
<html>
<head>
  <title>Scrivito</title>
  <link rel="preconnect" href="https://api.scrivito.com" crossorigin>
  <link rel="preconnect" href="https://api.scrivito.com">
  <link rel="stylesheet" media="screen" href="https://assets.scrivito.com/sjs/1.2.0/scrivito_ui.css" />
  <script src="https://assets.scrivito.com/sjs/1.2.0/scrivito_ui.js"></script>
  <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
  <meta name="robots" content="noindex" />
</head>
<body>
  {%- include 'layouts/javascript-variables' -%}
</body>
</html>

Again, the HTML markup to display the website in the Scrivito editing UI.

Test it out

After you have made the appropriate modifications and added the necessary files, you can deploy your site to your platformOS instance. To do this, run the following commands:

Copy
npm install
npm run build
marketpalce-kit-deploy staging -f

Once all the commands have run, you can visit your new website at the indicated URL. You now have a Scrivito Example App website deployed to a platformOS instance and can edit content as you would on any Scrivito website. If you make any code changes, just use the three commands above to update the deployment.

What is next?

There is a ton you can do with platformOS, and we have not even scratched the surface. We will be following this article up, in the near future, with articles detailing how to continue developing your website with the tools offered by platformOS.