Introduction

A consequent part of the development of openveo-core (and plugins) is made in conf.json file at project root. conf.json is used to :

Map routes on actions

Routes are separated into three categories : public, private and Web Service routes.

{
  "routes" : {
    "public" : {
      ...
    },
    "private" : {
      ...
    },
    "ws" : {
      ...
    }
  }
}

Route descriptor

A route map an HTTP method and a path to an action (JavaScript function).

The route :

"get /logout" : "app/server/controllers/authenticationController.logoutAction"

Can be interpreted as :

A GET request on /logout will call the function logoutAction exposed by module app/server/controllers/authenticationController.js

The route :

"post /authenticate" : "app/server/controllers/authenticationController.authenticateAction"

Can be interpreted as :

A POST request on /authenticate will call the function authenticateAction exposed by module app/server/controllers/authenticationController.js

The route :

"/login" : "app/server/controllers/defaultController.defaultAction"

Can be interpreted as :

All requests on /login (GET, POST, DELETE, PUT) will call the function defaultAction exposed by module app/server/controllers/defaultController.js

Example of valid routes :

{
  "routes" : {
    "public" : {
      "get /test" : "adminExampleController.getTestAction",
      "post /test" : "adminExampleController.postTestAction",
      "put /test" : "adminExampleController.putTestAction",
      "/" : "exampleController.invalidAction",
      "/test" : "invalid action"
    }
  }
}

Group routes

You can group actions by routes :

{
  "routes" : {
    "public" : {
      "*" : [
        "adminExampleController.allFirstAction",
        "adminExampleController.allSecondAction"
      ]
    }
  }
}

Route parameters

You can add parameters using colon character :

{
  "routes" : {
    "public" : {
      "DELETE /test/:id" : "adminExampleController.deleteTestAction"
    }
  }
}

Create entities

Entities are elements subject to CRUD (Create Read Update Delete). OpenVeo core defines 4 entities :

  • application - Web Service client applications
  • taxonomy - Taxonomies (not directly used by the core)
  • user - Back end users
  • role - Back end roles

Each entity will automatically have 3 associated back end permissions : create, update and delete.

To create a new entity you need to create a new EntityModel and a new EntityProvider. Let's say we want to create a new entity called book.

Create entity provider

'use strict';

var util = require('util');
var openVeoAPI = require('@openveo/api');

/**
 * Creates a BookProvider.
 */
function BookProvider(database) {

  // In BookProvider collection "books"
  openVeoAPI.EntityProvider.prototype.init.call(this, database, 'books');
}

// BookProvider must extend EntityProvider
module.exports = BookProvider;
util.inherits(BookProvider, openVeoAPI.EntityProvider);

Create entity model

'use strict';

// Module dependencies
var util = require('util');
var openVeoAPI = require('@openveo/api');

var BookProvider = process.require('BookProvider.js');

/**
 * Creates a BookModel.
 */
function BookModel() {
  openVeoAPI.EntityModel.prototype.init.call(this, new BookProvider(openVeoAPI.applicationStorage.getDatabase()));
}

module.exports = BookModel;
util.inherits(BookModel, openVeoAPI.EntityModel);

Declare entity

You can now declare your entity in conf.json :

{
  "entities" : {
    "book" : "BookModel"
  }
}

Use the entity

Now that you entity book is created you can see the 3 new permissions in the back end (create, update and delete). You can also perform CRUD operations on your entity using the following routes :

  • get /crud/book/:id - Get a particular book
  • get /crud/book - Get all books
  • post /crud/book/:id - Update a particular book
  • put /crud/book - Add a new book
  • delete /crud/book/:id - Delete a book

Define back end permissions

Each role can have n associated permissions. Permissions are described in conf.json :

{
  "permissions" : [
    ...
  ]
}

Create a permission

Let's create new permissions "sell" and "buy" to sell / buy books.

{
  "permissions" : [
    {
      "id" : "sell-book", // Permission id
      "name" : "Sell", // Permission name
      "description" : "Sell books", // Permission description
      "paths" : [ // List of paths associated to the permission
        "get /sell*"
      ]
    },
    {
      "id" : "buy-book", // Permission id
      "name" : "Buy", // Permission name
      "description" : "Buy books", // Permission description
      "paths" : [ // List of paths associated to the permission
        "get /buy*"
      ]
    }
  ]
}

Group permissions

You can group permissions to organize the list of permissions in the back end.

Nb : Actually OpenVeo only supports one sub level

{
  "permissions" : [
    {
      "label": "Books", // Group label
      "permissions": [ // List of permission in the group
        {
          "id" : "sell-book",
          "name" : "Sell",
          "description" : "Sell books",
          "paths" : [
            "get /sell*"
          ]
        },
        {
          "id" : "buy-book",
          "name" : "Buy",
          "description" : "Buy books",
          "paths" : [
            "get /buy*"
          ]
        }
      ]
    }
  ]
}

Use permissions

You can assign your permission to a role through the back end or manipulate the permission using back end client (AngularJS application).

Define back end menu items

Back end menu items are described in conf.json :

{
  "backOffice": {
    "menu" : [
      ...
    ]
  }
}

Add a menu item

Let's create two new back end menu items.

{
  "backOffice": {
    "menu" : [
      {
        "label" : "Sell books", // Menu item name
        "path" : "sell-books", // Menu item path
        "permission" : "sell-book" // Menu item associated permission
      },
      {
        "label" : "Buy books", // Menu item name
        "path" : "buy-books", // Menu item path
        "permission" : "buy-book" // Menu item associated permission
      }
    ]
  }
}

weight property helps order menu items, the larger the weight is, the better will be the item position.
path defines the AngularJS root path (see back end client)
permission associates a permission to the menu item, if the connected user doesn't have that permission the item won't be displayed

Group menu items

You can group menu items as sub menu items.

Nb : Actually OpenVeo only supports one sub level of menu items

{
  "backOffice": {
    "menu" : [
      {
        "weight" : 100, // Position of the item in the menu
        "label" : "Books", // Name of the menu item
        "subMenu" : [ // List of sub menu items
          {
            "label" : "Sell books", // Menu item name
            "path" : "sell-books", // Menu item path
            "permission" : "sell-book" // Menu item associated permission
          },
          {
            "label" : "Buy books", // Menu item name
            "path" : "buy-books", // Menu item path
            "permission" : "buy-book" // Menu item associated permission
          }
        ]
      }
    ]
  }
}

Back end scripts

The list of JavaScript files to load for the AngularJS back end application are defined in conf.json :

{
  "backOffice": {
    "scriptLibFiles" : { // List of back end JavaScript files to load first
      "base" : [ // List of scripts to load on both development and production environments
        ...
      ],
      "dev" : [ // List of scripts to load on development environment
        ...
      ],
      "prod" : [ // List of script to load on production environment
        ...
      ]
    },
    "scriptFiles" : { // List of back end JavaScript files to load next
      "dev" : [ // List of scripts to load on development environment
        ...
      ],
      "prod" : [ // List of script to load on production environment
        ...
      ]
    }
  }
}

Back end CSS

The list of CSS files to load for the AngularJS back end application are defined in conf.json :

{
  "backOffice": {
    "cssFiles" : [ // List of CSS to load
      ...
    ]
  }
}

List of directories containing templates

OpenVeo uses Mustache as the template engine. Mustache requires directories were to look for potential templates. The list of directories is defined in conf.json :

{
  "viewsFolders" : [ // List of directories holding mustache templates
    ...
  ]
}

Define image styles

You can define image styles in conf.json :

{
  "imageProcessing": {
    "imagesFolders": ["example/images"], // List of folders concerned by this style
    "cacheDir": "example/.thumbs", // Path of the directory containing generated images
    "quality": 50, // Compression level (from 0 to 100)
    "imagesStyle": { // Style to apply
      "small": 200 // Width (in px) of the image to generate for small style
    }
  }
}

Default width is 10px if no image style is specified for the directory.
Default cacheDir is .thumbs directory at the root of the application.
Default quality is 90.

Then you can call the image with your custom style small

<img src="example/images/image1.jpg?thumb=small"/>

Define custom configuration

You can define a custom configuration object in conf.json :

{
  "custom": {
    "customProperty1" : "customValue1",
    "customProperty2" : 2
  }
}

Nb : Custom configuration won't be interpreted but can be retrieved later using OpenVeo API. You can use it to configure your plugin.

Define Web Service scopes

You can define Web Service scopes in conf.json :

{
  "webServiceScopes" : [
    {
      "id": "scopeId",
      "name" : "Scope name",
      "description" : "Scope description",
      "paths" : [
        "get /book/sell/*",
        "get /book/books*"
      ]
    }
  ]
}

A scope is defined by an id, a name, a description and a list of authorized paths for a Web Service application who has access to this scope.
Routes like /book/sell/25 or /book/books will be available for a Web Service application with the scope scopeId in the above example.