Skip to content

nonblocking/mashroom-content

Repository files navigation

Mashroom Content

Content (CMS) plugins for Mashroom Server.

It provides an API abstraction for plugins on the server-side and Microfrontends (SPAs) on the client-side to easily retrieve and update content from a Headless CMS. The actual Headless CMS backend can transparently be exchanged.

It also comes with some neat features like versioning, internationalization, automatic asset proxying, image optimizations (format conversion, resizing) and CDN support.

At the moment it consists of:

  • A Content API that allows you to retrieve and manage content from a Headless CMS in Mashroom plugins (e.g. Portal Apps). The Headless CMS/Content Provider can transparently be switched.
  • A Media Library App which allows it to browse and manage your assets such as images and videos. It can also be used by custom Apps to lookup assets.
  • A Markdown Display App which renders Markdown content and also provides the possibility to update/create content directly as Administrator. This is more like a demo how the Content API can be used.
  • A provider that uses the internal Mashroom storage as backend
  • A provider for the strapi Headless CMS.

Architecture

Mashroom Content Architecture

Requirements

  • Node >= 16
  • Mashroom 2.x

Basic Usage

Add the following packages to dependencies to your Mashroom Server project:

  • @mashroom-content/mashroom-content-api
  • @mashroom-content/mashroom-content-asset-processing
  • @mashroom-content/mashroom-content-provider-internal-storage
  • @mashroom-content/mashroom-content-media-library-app
  • @mashroom-content/mashroom-content-markdown-renderer-app

And add the following to the plugin lookup path in the server config:

{
    "pluginPackageFolders": [
        {
            "path": "./node_modules/@mashroom-content"
        }
    ]
}

Configure the plugins like this to use the internal storage:

{
    "plugins": {
        "Mashroom Content Services": {
            "provider": "Mashroom Content Internal Storage Provider",
            "cacheEnable": false
        },
        "Mashroom Content Asset Processing Services": {
            "scaleUp": false,
            "defaultQuality": 75,
            "cacheEnable": true,
            "cacheDefaultTTLSec": 31536000,
            "cacheFolder": "./data/asset-proc-cache"
        },
        "Mashroom Content Internal Storage Provider": {
            "assetsFolder": "./data/assets"
        }
    }
}

Now you can use the service on the server-side (e.g. in a SSR bootstrap) like this:

    const contentService: MashroomContentService | undefined = req.pluginContext.services.content?.service;
    if (contentService) {
        // Search
        const result = await contentService.searchContent<WebContent>(req, 'web-content', {tags: {$in: ['foo']}}, 'de', 'published', { foo: 'desc' }, 100);
        // Fetch
        const {data} = await contentService.getContent<WebContent>(req, 'web-content', '1234567');
        //...
    }

And on the client-side like this:

const bootstrap: MashroomPortalAppPluginBootstrapFunction = async (portalAppHostElement, portalAppSetup, clientServices) => {
    const contentService: MashroomContentClientService | undefined = clientServices.contentService;

    if (contentService) {
        // Search
        const result = await contentService.searchContent<WebContent>('web-content', {tags: {$in: ['foo']}}, 'de', 'published', { foo: 'desc' }, 100);
        // Fetch
        const {data} = await contentService.getContent<WebContent>('web-content', '1234567');
        // ...
    }
}

And you can add the Markdown Display App to any page to display some content there:

Markdown Display

Media Library

Other Content Providers

To switch the provider just change the provider property of the Mashroom Content Services plugin.

For example for the Strapi Provider just add the plugin:

  • @mashroom-content/mashroom-content-provider-strapi

and update the config like this:

{
    "plugins": {
        "Mashroom Content Services": {
            "provider": "Mashroom Content Strapi Provider",
            "cacheEnable": true,
            "cacheTTLSec": 1800
        },
        "Mashroom Content Strapi Provider": {
            "strapiUrl": "http://localhost:1337",
            "apiToken": "xxxxxxx"
        }
    }
}

Development

For development Node.js >= 16 is required.

After cloning the repository just run

npm run setup

to install all dependencies.

To start the test server:

cd packages/test/test-server1
npm start

The test server will be available at http://localhost:5050

To load some test data call: http://localhost:5050/initContent To login, enter: http://localhost:5050/login - the Administrator credentials are admin/admin