Class: ContentController

controllers/ContentController~ContentController()

ContentController

Constructor

new ContentController()

Defines base controller for all controllers which need to provide HTTP route actions for all requests relative to content entities.

A content entity is an entity owned by a user, consequently user must be authenticated to use ContentController actions. Content entities which belong to the anonymous user can be manipulated by all. Content entities which belong to a particular user can be manipulated by this particular user, the super administrator, the entity manager, and, if entity is inside a group, by all users which have enough privileges on this group.

The authenticated user must have the following properties:

  • String id The user id
  • Array permissions An array of permissions in the following format: OPERATION-group-GROUP_ID, where OPERATION is one of ContentController.OPERATIONS and GROUP_ID the id of a group (e.g. ['get-group-Jekrn20Rl', 'update-group-Jekrn20Rl', 'delete-group-YldO3Jie3'])

A content entity has a "metadata" property with:

  • String user The id of the content entity owner
  • Array groups The list of groups associated to the content entity
Source:

Extends

Members

(static, constant) OPERATIONS :Object

The list of operations used to manage privileges of a user.

Type:
  • Object
Default Value:
  • {"READ":"get","UPDATE":"update","DELETE":"delete"}
Source:

Methods

(private, static) getUserAuthorizedGroups(user, operation) → {Array}

Gets the list of groups of a user, with authorization on a certain operation.

All user groups with authorization on the operation are returned.

Parameters:
Name Type Description
user Object

The user
operation String

The operation (get, update or delete)
Source:
Returns:

The list of user groups which have authorization on the given operation

Type
Array

(private, static) getUserGroups(user) → {Object}

Gets user permissions by groups.

Parameters:
Name Type Description
user Object

The user to extract groups from
Source:
Returns:

Groups organized by ids

Type
Object
Example
// Example of user permissions
['get-group-Jekrn20Rl', 'update-group-Jekrn20Rl', 'delete-group-YldO3Jie3']

// Example of returned groups
{
  'Jekrn20Rl': ['get', 'update'], // User only has get / update permissions on group 'Jekrn20Rl'
  'YldO3Jie3': ['delete'], // User only has delete permission on group 'YldO3Jie3'
  ...
}

addAccessFilter(filteropt, user) → {ResourceFilter}

Adds access rules to the given filter reference.

Access rules make sure that content entities belong to the user (owner or in the same group). If no filter is specified, a new filter is created.

Parameters:
Name Type Attributes Description
filter ResourceFilter <optional>

The filter to add the access rules to
user Object

The user information

Properties
Name Type Description
id String

The user id
permissions Array

The user permissions
Source:
Returns:

The modified filter or a new one if no filter specified

Type
ResourceFilter

addEntitiesAction(request, response, next)

Adds entities.

Information about the user (which becomes the owner) is automatically added to the entities.

Parameters:
Name Type Description
request Object

ExpressJS HTTP Request

Properties
Name Type Description
body Array

The list of entities to add with for each entity the fields with their values

Properties
Name Type Attributes Description
groups Array <optional>

The list of groups the content entities belong to
response Object

ExpressJS HTTP Response
next function

Function to defer execution to the next registered middleware
Overrides:
Source:
Example
// Response example
{
  "entities": [ ... ],
  "total": 42
}

getAnonymousId() → {String}

Gets the id of the anonymous user.

It must be overriden by the sub class.

Source:
Throws:

getAnonymousId is not implemented

Type
Error
Returns:

The id of the anonymous user

Type
String

getEntitiesAction(request, response, next)

Gets entities.

If user does not have enough privilege to read a particular entity, the entity is not listed in the response.

Parameters:
Name Type Description
request Object

ExpressJS HTTP Request

Properties
Name Type Description
query Object

Request query

Properties
Name Type Attributes Description
include String | Array <optional>

The list of fields to include from returned entities
exclude String | Array <optional>

The list of fields to exclude from returned entities. Ignored if include is also specified.
limit Number <optional>

A limit number of entities to retrieve per page (default to 10)
page Number <optional>

The page number started at 0 for the first page (default to 0)
sortBy String <optional>

The entity field to sort by
sortOrder String <optional>

Either "asc" for ascendant or "desc" for descendant
response Object

ExpressJS HTTP Response
next function

Function to defer execution to the next registered middleware
Overrides:
Source:
Example
// Response example
{
  "entities" : [ ... ],
  "pagination" : {
    "limit": ..., // The limit number of entities by page
    "page": ..., // The actual page
    "pages": ..., // The total number of pages
    "size": ... // The total number of entities
}

getEntityAction(request, response, next)

Gets a specific entity.

User must have permission to read the entity.

Parameters:
Name Type Description
request Object

ExpressJS HTTP Request

Properties
Name Type Description
params Object

Request parameters

Properties
Name Type Description
id String

The entity id to retrieve
query Object

Request query

Properties
Name Type Attributes Description
include String | Array <optional>

The list of fields to include from returned entity
exclude String | Array <optional>

The list of fields to exclude from returned entity. Ignored if include is also specified.
response Object

ExpressJS HTTP Response
next function

Function to defer execution to the next registered middleware
Overrides:
Source:
Example
// Response example
{
  "entity" : { ... }
}

getProvider() → {EntityProvider}

Gets an instance of the entity provider associated to the controller.

Inherited From:
Source:
Throws:

getProvider not implemented for this EntityController

Type
Error
Returns:

The entity provider

Type
EntityProvider

getSuperAdminId() → {String}

Gets the id of the super administrator.

It must be overriden by the sub class.

Source:
Throws:

getSuperAdminId is not implemented

Type
Error
Returns:

The id of the super admin

Type
String

isUserAdmin(user) → {Boolean}

Tests if user is the administrator.

Parameters:
Name Type Description
user Object

The user to test

Properties
Name Type Description
id String

The user's id
Source:
Returns:

true if the user is the administrator, false otherwise

Type
Boolean

isUserAnonymous(user) → {Boolean}

Tests if user is the anonymous user.

Parameters:
Name Type Description
user Object

The user to test

Properties
Name Type Description
id String

The user's id
Source:
Returns:

true if the user is the anonymous, false otherwise

Type
Boolean

isUserAuthorized(user, entity, operation) → {Boolean}

Validates that a user is authorized to manipulate a content entity.

User is authorized to manipulate the entity if one of the following conditions is met:

  • The entity belongs to the anonymous user
  • User is the super administrator
  • User is the owner of the entity
  • User has permission to manage contents
  • Entity has associated groups and user has permission to perform the operation on one of these groups
Parameters:
Name Type Description
user Object

The user

Properties
Name Type Description
id String

The user's id
permissions Array

The user's permissions
entity Object

The entity to manipulate

Properties
Name Type Description
metadata Object

Entity information about associated user and groups

Properties
Name Type Description
user String

The id of the user the entity belongs to
groups Array

The list of group ids the entity is part of
operation String

The operation to perform on the entity
Source:
Returns:

true if the user can manipulate the entity, false otherwise

Type
Boolean

isUserManager(user) → {Boolean}

Tests if user is a contents manager.

A contents manager can perform CRUD operations on content entities. It must be overriden by the sub class.

Parameters:
Name Type Description
user Object

The user to test

Properties
Name Type Description
permissions Array

The user's permissions
Source:
Throws:

isUserManager is not implemented

Type
Error
Returns:

true if the user has permission to manage contents, false otherwise

Type
Boolean

isUserOwner(entity, user) → {Boolean}

Tests if user is the owner of a content entity.

Parameters:
Name Type Description
entity Object

The entity to test

Properties
Name Type Description
metadata Object

Entity information about associated user and groups

Properties
Name Type Description
user String

The id of the user the entity belongs to
user Object

The user to test

Properties
Name Type Description
id String

The user's id
Source:
Returns:

true if the user is the owner, false otherwise

Type
Boolean

removeEntitiesAction(request, response, next)

Removes entities.

User must have permission to remove the entities. If user doesn't have permission to remove a particular entity an HTTP forbidden error will be sent as response and there won't be any guarantee on the number of removed entities.

Parameters:
Name Type Description
request Object

ExpressJS HTTP Request

Properties
Name Type Description
params Object

Request parameters

Properties
Name Type Description
id String

A comma separated list of entity ids to remove
response Object

ExpressJS HTTP Response
next function

Function to defer execution to the next registered middleware
Overrides:
Source:
Example
// Response example
{
  "total": 42
}

removeMetatadaFromFields(fields) → {Object}

Removes "metadata" field from query fields.

The "metadata" property of a content entity is used by ContentControllers to validate that a user has enough privileges to perform an action. "metadata" property contains the id of the user the content property belongs to and the list of groups the entity is part of. Consequently "metadata" property has to be fetched by the provider when getting an entity, however we authorize the user the exclude / include fields from provider response. removeMetadataFromFields makes sure "metadata" property is not excluded from returned fields.

Parameters:
Name Type Description
fields Object

The include and exclude fields

Properties
Name Type Attributes Description
include Array <optional>

The list of fields to include which may contain a "metadata" property
exclude Array <optional>

The list of fields to exclude may contain a "metadata" property
Source:
Returns:

The same fields object with new include and exclude arrays

Type
Object

updateEntityAction(request, response, next)

Updates an entity.

User must have permission to update the entity. If user doesn't have permission to update the entity an HTTP forbidden error will be sent as response.

Parameters:
Name Type Description
request Object

ExpressJS HTTP Request

Properties
Name Type Description
params Object

Request parameters

Properties
Name Type Description
id String

The id of the entity to update
body Object

The fields to update with their values

Properties
Name Type Attributes Description
groups Array <optional>

The list of groups the content entity belongs to
user String <optional>

The id of the entity owner. Only the owner can modify the entity owner.
response Object

ExpressJS HTTP Response
next function

Function to defer execution to the next registered middleware
Overrides:
Source:
Example
// Response example
{
  "total": 1
}