web-commons-export

Library for exporting presentations for Nielsen Marketing Cloud

Description

This library contains helpers for generating presentations with minimal effort using server-side rendering techniques. Using this Library, any App in Nielsen Marketing Cloud can create an export server which exposes an endpoint for generating presentations with nielsen theme (logo, background, copyright, etc) and automatic title injection, as well as automatic page counts and more.

Creating presentations

• Easily create pages with rich UI elements
• Built-in page counts, title, copyright, background, etc …
• Custom components version
• Supports pptx + pdf
• Decoupled themes repository

Creating export server

• Initializes backend with minimal effort
• Automatic Webpack configuration

Flow

Requirements

• To support pre-defined themes: https://github.com/xl8/web-commons-export-themes
• To support pdf:
  • install LibreOffice 3.6.5
  • install unoconv

Usage

Creating documents

1. Create a directory under documents to hold your document. e.g: /src/documents/SegmentDocument/SegmentDocument.js.

the file exports your document creator function and unique document identifier. e.g:

export default {
  documentName: 'segment',
  documentCreator: async function (authorizationHeader) {
    let data = await getDataAsync(authorizationHeader)
    let pages = [Page1, Page2]
    return {
      pages,
      data,
    }
  }
}

add the document into your array of all defined documents in /documents/index.js:

import segmentDocument from './SegmentDocument/SegmentDocument'
export default [
  segmentDocument
]

2. if required, you can create a dedicated export styles file SegmentDocument.less and import it in SegmentDocument.js.

3. implement the getDataAsync function to return the data required for the document

async function getDataAsync (authorizationHeader, queryParams) {
  const headers = {
    'authorization': authorizationHeader
  }
  return fetch('http://localhost:6200/dmp/entities', {headers})
    .then(res => res.json())
}

• authorizationHeader contains the authorization field as passed to the request's header
• queryParams contains all the query params as passed to the request in the querystring

4. define the Page classes. each class represents a Page in the presentation you export. use the page decorator for built-in capabilities by the library. e.g:

import { page } from 'web-export/documents'
@page({
    title: 'SEGMENT REPORT', 
    bodyText:'make love not segments', 
    theme: 'NIELSEN_SIDEBAR_AND_N', 
    skipPageNumber: true
})
class Page1 {
  constructor (data) {
    this.data = data
  }

  getMainContent () {
    const data = this.data
    return (
        <SegmentViewer data={data} isExportMode />
    )
  }
}

if you would like to build the presentation via custom code, you can expose getCustomContent method. e.g:

@page({bodyText: 'page 2 text body'})
class Page2 {
  getCustomContent (slide) {
    slide.addText('Title with manual location and design',
     {x: '50%', y: 0.25, font_size: 18, font_face: 'Arial', color: 'FF0000'})
  }

  getMainContent () {
    return (
      <div>
        Did you know? method `getMainContent` is optionally. if you use getCustomContent you may not even need it.
      </div>
    )
  }
}

read here for more details on how to write custom code.

page decorator options

| Option | Type | Default | Description | Possible Values | | :---------------- | :------ | :------------------------ | :-----------------------------------------| :---------------------------- | | title | string | | title in page header | | | bodyText | string | | paragraph below the title | | | skipPageNumber | bool | false | skip the page count | true, false | | theme | string | NIELSEN_SIDEBAR_AND_N | theme (background, logo, copyright, etc) | null, NIELSEN_SIDEBAR_AND_N |

Settings the server

The library exports setServer function which gets an express app and initializes the endpoint /export. the function also receives array of documents and optional array of themes, and registers them.

usage example:

const express = require('express')
const {setServer} = require('web-commons-export/server')
const themes = require('web-commons-export-themes')

let documents = require('./dist/documents')
const app = express()
setServer(app, '/agen/export', documents, themes)
app.listen(9003, () => {
  console.log('Export Server is listening on port 9003 ...')
})

the exporting endpoint is: /export/:documentName with optionally format querystring param. e.g: https://localhost/file/agen/download/export/segment?format=pptx

the library supports the following formats: pptx (default), pdf

Setting authentication for api requests

the export server should implement server-side jwt authentication in order to be able to perform api requests for getting data required for the export. read here for instructions.

Themes

Themes repository

There is an additional library web-commons-export-themes which acts as a decoupled repository of the common themes. when calling setServer initialization function, you pass it the themes from this library as follows:

const themes = require('web-commons-export-themes')
setServer(app, '/agen/export', documentsRegisters, themes)

Creating custom themes

If you would like to use a custom theme unique to your app across documents, you can register a new theme manually. to do so, add it to the themes argument of the setServer function. e.g:

let copyrightTheme = {
  themeId: 'NIELSEN_SIDEBAR_AND_N',
  apply: function (slide) {
      const copyright = `Copyright © ${new Date().getFullYear()} The Nielsen Company (US), LLC. Confidential and proprietary. Do not distribute.`
      slide.addText(copyright, {
        x: -2.73,
        y: 4.4,
        w: 5,
        align: 'r',
        rotate: 270,
        font_size: 6,
        font_face: 'Arial',
        color: 'FFFFFF'
      })
  }
}
setServer(app, '/agen/export', documentsRegisters, [...themes, copyrightTheme])

now you can pass it to any page in the theme property of the page decorator.

note: If you created a theme that can be useful for other NMC apps, please make a PR to the web-commons-export-themes library.

Configuring the server

Webpack

The library exports a common webpack configuration with relevant settings. among other thing it does, is compiling all the styles into a single bundled css file, extracting fonts and images of the app, setting global variable for hinting server mode, setting globals, and more.

the configuration contains common loaders. however, you may extend the configuration or override it for your app's needs. for example, in case you need to transpile sass or TypeScript.

usage:

const exportLibWebpackConfig = require('web-commons-export/server').webpackConfig(__dirname)

module.exports = exportLibWebpackConfig.merge({
  entry: {
    documents: ['babel-polyfill', './src/documents/index.js']
  }
})

Using Infra goodness

When NMC app is loaded, the Infra injects all kind of libraries for it to use before it loads the app, such as: Underscore, React, Moment, WebInfra-Components and more.

since there is no such Infra injection for us in the export server, its our responsibility to simulate that injection for any library required by the document.

The trick is a predefined global variable __IS_SERVER_SIDE__ loaded by webpack that would hint us that we are on server-side, and if that the case, then we inject what required.

in a InfraFacade.js file:

/**
 * Facade for connecting with Infra
 */

let facade
// we run in Server Side
if (__IS_SERVER_SIDE__) {
  // Mock window
  global.window = {}

  // expose underscore from the actual package, because there is no Infra to inject it globally for us
  let underscore = require('underscore')
  global.window._ = underscore
  global._ = underscore

  // import Infra components from the actual package, because there is no Infra to inject it globally for us
  let InfraComponents = require('@master/webinfra-frontend-components')
  facade = {InfraComponents}
}
// we run in browser
else {
  // use facade which exposes the global Infra components injected for us by the Infra globally
  facade = require('webapps-frontend-components/src/main/Infra/InfraFacadeShared')
}

export default facade

now in the app, we can import what required from the facade. e.g:

import { InfraComponents } from 'InfraFacade'
const { CancelButton, DetailsActionButton } = InfraComponents

NMC webapp usage example

https://github.com/xl8/web-agen-frontend/tree/master/agen-app/export-server