Skip to main content

Library plugin

This plugin allows you to manage several types of resources, creating an abstraction layer over any entity you want to define common multimedia resource properties.

Files​

Files are the lowest level atoms in the Library.

ATTENTION

A file can NOT be managed from the Library frontend, but CAN be managed from the service Register a file.

File Schema
// LeebraryFile
{
    name: string, // Required.
    provider: string, // Stores the name of the supplier being used by Library at the time of file registration.
    type: string, // Stores the mime-type of the file.
    extension: string, // Stores the file extension. E.g. docx, xls, jpg, etc.
    metadata: MetadataObject, // Stores the metadata obtained from the file.
}

Metadata​

When registering a file, the plugin tries to extract the following information to be stored as metadata.

Metadata object
// MetadataObject
{
    format: string, // Indicates the file format. E.g. PNG, DOCX, MOV
    words: number, // For file types that support it. E.g. DOCX, TXT
    duration: number, // Retrieves the duration of the file when they are video or audio.
    revision: number, // Retrieves the revision of the file in case it supports it. E.g. Office files that support it.
    pages: number, // Retrieves the number of pages for those files that support it. E.g. DOC, ODF, etc
    slides: number, // Returns the number of slides for files that support it. E.g. PPT, etc
    spreadsheets: number, // Indicates the number of spreadsheets. E.g. XLS, etc
    books: number, //
    height: number, // Image height, for image file type
    width: number, // Image width, for image file type
    bitrate: number, // Gets the bitrate, for video and audio files
}

Assets​

When you want to have more control over a file, Library has the Asset entity.

By default, resources in Library are a type of Media Files .

The idea of the Library is that all entities that need to have similar characteristics, refer to a resource of type Media Files.

Asset Categories​

All resources stored in the Library must belong to a category.

All categories must have a unique identifier, which must be public, and which will be used for searching or browsing, called a key in the data model.

Category Schema
// LeebraryCategory
{
    key: string, // Required. Unique identifier set by the plugin that registers the category
    pluginOwner: string, // Required.  Defaults to the same Library plugin. Defaults to "plugins.leebrary".
    provider: string, // Required. Indicates the name of the logic provider for this category. Defaults to "leebrary".
    creatable: boolean, // Indicates whether the category allows "creating" resources from the frontend. Defaults to FALSE
    duplicable: boolean', // Indicates whether the category allows "mirroring" of resources from the frontend. Defaults to FALSE
    listCardComponent: string, // Optional. Indicates the path of a custom Card component to show in the list.
  detailComponent: string, // Optional. Indicates the path of a custom Card detail component.
}

In addition to the Schema, categories can appear in the Library Menu, and for this it is necessary to indicate these parameters at the time of category registration.

More info in Creating a category.

Pre-installed categories​

The default categories that comes pre-installed with the plugin are:

Media files​

KEY

Category key: media-files

This is the simplest category, and is used by default in the plugin resources.

Versioning​

Library uses the Version control plugin to manage its Assets IDs.

Asset Schema
// Asset
{
  id: CurrentVersion.id, // ID generated by the version control plugin
  name: string, // Required
  tagline: string, // Tagline or Subtitle
  description: string,
  color: string, // Hex color
  cover: LeebraryFile, // File object
  public: boolean, // Indicates whether the resource is visible to all platform users. Defaults to FALSE
  category: LeebraryCategory, // Category object. Defaults to key "media-files"
  indexable: boolean, // Indicates whether or not the resource is visible to searches, listings, etc. in the frontend. Defaults to TRUE
}

Bookmarks​

KEY

Category key: bookmarks

It is the special catagory for storing external URLs within the Library.

Assets in this category type also make use of Media Files category to store common data.

Asset Schema
{
  id: UUID, // Autogenerated
  asset: Asset.CurrentVersion.id, // Refers to the ID of the resource "media-file".
  url: string,
  icon: LeebraryFile, // File Object
}

Services​

Register an asset​

To register an Asset within Library, we must use the add method of the assets service.

const myFile = {
  readStream: fs.createReadStream('my-file.jpg'),
  contentType: 'image/png',
};

await leemons.getPlugin('leebrary').services.assets.add({ file: myFile, name: 'my-new-file' });
Examples

Suppose we want to upload and register a resource from a form:

// This data comes directly from the file upload in the form.
const fileFromTempPath = {
  path: 'my-file.docx',
  type: 'application/msword',
};

// The cover comes from a Library image
const coverFromFile = 'other-file-id';

Then we simply call the service method with the option we need:

const myAsset = await leemons.getPlugin('leebrary').services.assets.add(
  {
    file: fileFromTempPath,
    cover: coverFromFile,
    color: '#FABADA',
    name: 'This is the title card', // Required
    description: 'This is my awesome file',
    tags: ['awesome', 'leemons'],
    category: 'my-category-key',
    tagline: 'This is the subtitle',
    // Optional fields
    indexable: true, // To make the resource visible in Library. Defaults to TRUE
    public: false, // If we want to restrict access through permissions. Defaults to FALSE
  },
  {
    userSession,
    transacting,
  }
);

Allowing access​

By default, an Asset is created as private and the userAgent that creates it is the owner, so only the owner can see it.

To change this, we can use the canAccess property and use the default roles that Library provides:

  • editor
  • viewer
  • owner
const myAsset = await leemons.getPlugin('leebrary').services.assets.add({
  ...otherAssetFields,
  canAccess: [
    { userAgent: 'some-id-01', role: 'editor' },
    { userAgent: 'some-id-02', role: 'viewer' },
    { userAgent: 'some-id-03', role: 'owner' },
  ],
});

Register a file​

To register a file in Library, we must register it as an Asset in the simplest way.

Examples

We want to upload and register a file. There are 4 options to prepare a file:

const fs = require('fs');

// Option 1
const fileFromStream = {
    readStream: fs.createReadStream('my-file.jpg'),
    contentType: 'image/png'
};

// Option 2
const fileFromPath = {
    path: 'my-file.jpg',
    type: 'image/png'
};

// Option 3
const fileFromUrl = 'https://my-domain.com/my-file.jpg';

// Option 4
const fileFromOtherFile = 'other-file-id':

Then we simply call the service method with the option we need:

const assetService = leemons.getPlugin('leebrary').services.assets;
const myAsset = await assetService.add(
  {
    file: fileFromStream || fileFromPath || fileFromUrl || fileFromOtherFile,
    name: 'my-new-file',
    // Optional as appropriate
    indexable: false, // In case we do not want it to be listed in Library.
    public: true, // If we want all users to have access to it
  },
  {
    userSession,
    transacting,
  }
);

Create a category​

If a plugin wants to register a category within Library to manage its resources, it can be done with the add method of the categories service.

await leemons.getPlugin('leebrary').services.categories.add(myCategoryData);
MENU

If we want the category we are creating to appear in the Library menu, we must indicate the menu properties, as well as the permissions related to the menu-item.

Examples

Let's create a category with the following data:

const myCategoryData = {
  // Category properties
  key: 'my-awesome-category',
  creatable: true,
  createUrl: '/private/my-plugin/create',

  // Used to perform searchs. Set as 'leebrary' to search only in assets fields
  provider: 'leebrary',

  // Menu properties
  menu: {
    item: {
      iconSvg: '/public/my-plugin/category-icon.svg',
      activeIconSvg: '/public/my-plugin/category-icon_active.svg',
      label: {
        en: 'My awesome category',
        es: 'Mi increíble categoría',
      },
    },
    permissions: [
      {
        permissionName: 'plugin.my-plugin.my-permission',
        actionNames: ['view', 'update', 'create', 'delete', 'admin'],
      },
    ],
  },

  // Frontend config
  // Paths must be realtive to plugin's frontend "src/widgets/leebrary"
    listCardComponent: 'path/to/my/card-component',
    detailComponent: 'path/to/my/detail-component',
    
    // Used to compose the path on dynamicImport of Card components. Eg:
    // import(`@leemons/plugins/${componentOwner.split('.')[1]}/src/widgets/leebrary/${listCardComponent}.js`)
  componentOwner: 'plugins.my-plugin', // should begin with "plugins" or "providers" as appropriate.
};