Documentation
Publish

Anchor link Installation

Anchor link Requirements

Microservices in the DADI platform are built on Node.js, a JavaScript runtime built on Google Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient.

DADI follows the Node.js LTS (Long Term Support) release schedule, and as such the version of Node.js required to run DADI products is coupled to the version of Node.js currently in Active LTS. See the LTS schedule for further information.

Anchor link Create new Publish installation

Anchor link NPM

All DADI platform microservices are also available from NPM. To add Publish to an existing project as a dependency:

$ cd my-existing-node-app
$ npm install --save @dadi/publish

Anchor link Configuration

All the core platform services are configured using environment specific configuration.json files, the default being development. For more advanced users this can also load based on the hostname i.e., it will also look for config." + req.headers.host + ".json

The minimal config.development.json file looks like this:

{
  "server": {
    "host": "127.0.0.1",
    "port": 3001
  },
  "auth": {
    "enabled": false
  }
}

Anchor link Example Configuration File


{
  "app": {
    "name": "DADI Publish",
    "publisher": "Publisher Name"
  },
  "publicUrl": {
      "host": "publish.somedomain.tech",
      "port": 80,
      "protocol": "http"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 80
  },
  "apis": [
    {
      "name": "Publish Demo API",
      "host": "http://api.somedomain.tech",
      "port": 3000,
      "database": "publish",
      "version": "1.0",
      "credentials": {
        "clientId": "my-client-id",
        "secret": "my-client-secret"
      },
      "menu": [
        {
          "title": "Content",
          "collections": [
            "articles",
            "products"
          ]
        },
        "books"
      ]
    }
  ],
  "auth": {
    "enabled": true,
    "host": "http://api.somedomain.tech",
    "port": 3000,
    "collection": "users",
    "database": "publish",
    "version": "1.0",
    "credentials": {
      "clientId": "my-client-id",
      "secret": "my-client-secret"
    }
  }
}

You can see all the config options in config-schema.js.

Anchor link app

Property Type Default Description Example
name String DADI Publish (Repo Default) The name of your application, used for the boot message My project
publisher String DADI Publisher The name of the publisher. DADI Magazine

Anchor link publicUrl

Property Type Default Description Example
host String 0.0.0.0 The publicly available hostname or IP address of your Publish app publish.somedomain.tech
port Number 8080 The publicly available port of your Publish app 80
protocol String http The protocol the publicly available Publish application will use https

Anchor link server

Property Type Default Description Example
host String 0.0.0.0 The hostname or IP address to use when starting the Publisher server 127.0.0.1
port Number 8080 The port to bind to when starting the Publisher server 80

{to-do: Add apis and auth properties}

Anchor link Launching Publish

For your app to run, you'll need an app entry file.

Example app entry file server.js


const publish = require('@dadi/publish')

publish.run()

Once you've saved this file in the root of your Publish app directory, add a start command to you package.json

Example package.json

{
  "name": "my-publish-app",
  "version": "1.0.0",
  "description": "My Publish app",
  "main": "index.js",
  "scripts": {
    "start": "NODE_ENV=development node server.js"
  },
  "author": "Your Name <you@somewhere.com>",
  "license": "MIT",
  "dependencies": {
    "@dadi/publish": "^1.0.3-beta"
  }
}

Now run npm start to launch the app.

Anchor link First use

Before running Publish, you will need:

Anchor link Connecting to API

To connect to an API, make sure your @dadi/api install is running, then add one or more APIs to your environment config

"apis": [
  {
    "name": "My API",
    "host": "https://api.somedomain.tech",
    "port": 443,
    "database": "my-api",
    "version": "1.0",
    "credentials": {
      "clientId": "testClient",
      "secret": "secretSquirrel"
    }
  }
]

Anchor link Application Anatomy

{To-Do}

Anchor link App

{To-Do}

Anchor link Views

{To-Do}

Anchor link Containers

{To-Do}

Anchor link Components

{To-Do}

Anchor link Managing users

Users are currently managed in API. To add a user, send the user credentials to the users collection. See Creating a user how-to guide.

Note

You must have the required hooks and collection in order to insert and authorise users.

Anchor link Password recovery

{To-Do}

Anchor link Security

{To-do}

Anchor link SSL

SSL is currently disabled by default.

Publish generates certificates automatically with dadi/ssl, using LetsEncrypt, the non-profit free certificate authority. Certificates are renewed two days before expiry and do not require an app relaunch. To handle inbound challenge requests from the certificate authority, Publish opens port 80. All traffic other than requests from the CA are upgraded to 443.

When SSL is enabled, the port defined in environment config is ignored in favour of port 443. LetsEncrypt requires an email address for renewal notifications.

 "server": {
    "host": "127.0.0.1",
    "port": 80,
    "ssl": {
      "enabled": true,
      "domains": ["somedomain.tech"],
      "email": "publish@somedomain.tech"
    }
  }

Note

When SSL is enabled, all connected APIs must also run over SSL. Any insecure APIs will not be available in Publish.

Anchor link How-to guides

{To-do}

Anchor link Authentication

Authentication is currently handled with a hook and collection in the current connected api. To install these required files, run the following from your publish directory

NODE_ENV=development npm explore @dadi/publish -- npm run api-install --configDir=/path/to/config/directory

Note

If the api does not contain these required files it will not be able to handle authentication.

Anchor link Creating a user

The eaisest way to create your first user is by sending a POST request to the API connected to your Publish installation.

POST /1.0/publish/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer 1aaf758d-0e3d-4d16-b7ae-b75977dc5223
Host: api.somedomain.tech

{
  "first_name": "First",
  "last_name": "User",
  "email": "you@domain.co",
  "password": "something-tricky"
}

Anchor link Creating a document

Publish interacts directly with any number of instances of dadi/api.

To create a document:

  1. Select a collection from the collection menu and on the list view. {Image of menu}
  2. On the document list view, click the Create New button to the top right of the document list table.

Anchor link Validation

Validation rules are taken directly from the validation block in the collection config schema.

An example field in API

"fieldName": {
  "type": "String",
  "required": true,
  "label": "Title",
  "validation": {
    "minLength": 4,
    "maxLength": 20,
    "regex": {
      "pattern": "/[A-Za-z0-9]*/"
    }
  }
}

As you edit each field, Publish will identify any validation errors and display them clearly next to the field input.

Validation is also checked once more as a document is saved.

If an invalid field is not part of the current selected tab (see tabs below), a warning icon will appear on each tab containing one or more validation errors.

Anchor link Filtering documents

{To-do}

Anchor link Document selection

For individual document selection a checkbox to the left of the document can be toggled. To toggle select on an entire page, click the checkbox in the table header, to the far left.

Document selection is retained even during Pagination. This means that Batch actions will be applied to documents that aren't currently in view.

Anchor link Batch Document actions

Some basic document tasks can be performed on the list view. By default, Delete is the only option.

Note

Other batch actions will be made available soon. These will include actions for Boolean fields, and other types that can be updated without input.

Anchor link Document Pagination

If a collection contains more than the pagination limit (20 by default), page buttons will appear under the document list.

Anchor link Collaborative editing

The first component of collaborative editing is already availble. This will show you other editors that are currently viewing the same document.

Note

Future collaborative features include multi-user editing, in-document messaging and revision history.

Anchor link Performance

Publish is a web-app. This means that after the first page load, all subsequent pages are rendered in the browser, and the only requests to the server are for data and images.

Anchor link Customisation

The Publish app can be customised to optomize user experience, and add a personal touch to your organisation.

Anchor link Document sections

When there are a lot of fields in the collection schema, splitting the fields into sections makes the interface less cluttered. Each section will appear as a tab at the top of the document edit view.

Example section

"fieldName": {
  "type": "String",
  "required": true,
  "label": "Title",
  "publish": {
    "section": "Article",
    "placement": "main",
    "display": {
      "list": true,
      "edit": true
    }
  }
}

Anchor link Document layout

Not all fields require a lot of room. You can decide to place fields in either the main view, or the sidebar depending on the size.

Example placement setting

"fieldName": {
  "type": "String",
  "required": true,
  "label": "Title",
  "publish": {
    "section": "Article",
    "placement": "main"
  }
}

Anchor link Collection navigation groups

By default, the navigation menu will display collections in the order they are returned from the connected APIs.

If a large number of menu entries becomes difficult to read, or two connected APIs contain a collection with matching names, you may want to group or order collections into sub-menus.

Example menu layout

"apis": [
  {
    "name": "API 1",
    "host": "https://api.somedomain.tech",
    "port": 443,
    "database": "my-api",
    "version": "1.0",
    "credentials": {
      "clientId": "testClient",
      "secret": "superSecret"
    },
    "menu": [
      {
        "title": "Blog",
        "collections": [
          "articles"
        ]
      },
      "galleries"
    ]
  },
  {
    "name": "API 2",
    "host": "https://api.anotherdomain.tech",
    "port": 443,
    "database": "my-second-api",
    "version": "1.0",
    "credentials": {
      "clientId": "testClient",
      "secret": "superSecret"
    },
    "menu": [
      {
        "title": "Reviews",
        "collections": [
          "articles"
        ]
      },
      "books"
    ]
  }
]

Anchor link Hidden fields

To hide a field from either list or edit view, add each property to a publish.display block in the field schema.

Example hidden field settings

"fieldName": {
  "type": "String",
  "required": true,
  "label": "Title",
  "publish": {
    "display": {
      "edit": true,
      "list": false
    }
  }
}

Anchor link Hidden collections

If an enire collection needs to be hidden, add hidden to the collections settings.publish block.

Example hidden collection settings

{
  "fields": {
    "fieldName": {
      "type": "String",
      "required": true,
      "label": "Title",
      "publish": {
        "display": {
          "edit": true,
          "list": false
        }
      }
    }
  },
  "settings": {
    "publish": {
      "hidden": true
    }
  }
}

Anchor link Build process

When you install the Publish app directly from npm, a post-install script runs automatically, and builds the bundle.js, and main.css required to run the app. This process only needs to happen when the app installs or is updated.