Mantra official documentation

33-mantra-API-reference.md

❮ Previous
Index
Next ❯
A  A  A 

Mantra API Reference

Considrerations about Mantra API object

In a Mantra project, any interaction between the framework and within the components, is performed using an single instance object of the class MantraAPI, usually named as Mantra in handlers. One interaction = one instace of that object.

This API object is created by Mantra by each interaction with your project, like:

  • In any request for a view, get or post routes.
  • In an event handler.
  • In middlewares handlers.
  • In rendering blocks.
  • When running access conditions and prerequests.
  • etc.

This is, when any component handler of any kind is called by Mantra Framework, a Mantra API object is created by the framework so that the handler doesn't need to create it.

This is extremely important in Mantra Framework because, mainly, of performance: Mantra API object is heavy to create and load with initial values, and that's the reason why Mantra uses only one instance the this object in any interaction, and that's why API calls or DAL calls between components, should send this instance as well.

This is how prerequests, for instance, can add data for the view handlers calling AddRequestData() method and share common data for the next handler call.

Anyway, and despite it is not recommended (depending on the case), you can get a new instance of Mantra API object with:

const Mantra = global.Mantra.MantraAPIFactory();

Mantra is a high performance framework because in any request or interaction between components, a Mantra API object is shared.

Mantra API methods reference

Mantra API object is the heart of the framework, all it's represented by its methods. To develop Mantra applications, you need to master this object.

MantraAPI methods definitions

Mantra.AddCss

AddCss( resource )

Adds to the current request a css file placed at "css" folder. Like AddJs, the "resource" parameter indicates which css file to include following one of these two formats options:

  • "componentname.filename": Mantra will look for a css file inside "/componentname/ui/js", in the folder of the component indicated in the first part of the parameter.
  • "frontend.pathtofile": in this case, "frontend" is a special key string indicating to Mantra that the file should be found in the UI assets of the current application.

All css files added with AddCss() in the same request, will be rendered at "mantra-css-files" Mustache tag indicated in html root document.

See Adapting Root Html Document to Mantra for more infor about Mantra Mustache tags.

Also, the parameter can be an array with a number of js resources to include.

You can also define the css files to include in on specific view indicating "<viewname>_css": property in its definition.

Some examples:

Mantra.AddCss( "cookieswarning.alertckstyle" ); // Will include /cookieswarning/ui/css/alertckstyle.css file.

Mantra.AddCss( "frontend.assets/css/alertckstyle.css"; // Will include the file /assets/css/alertckstyle.css that should be at the UI folder of the current application

Mantra.AddCss( ["alerts.showalertstyle", "seo.settitlestyle"] ); // Will include those two css files.

Mantra.AddDataValue

AddDataValue( key, value )

Adds data to be used by javascript browser client with Mantra.data property

Params:

  • key: <key for the property>
  • value: <value for the property>

All keys indicated with AddDataValue(), will be inserted in Mantra.data object.

Given AddDataValue( 'title', 'Lord of the Rings' ), then, javascript browser client, will have Mantra.data.title property with value 'Lord of the Rings'.

Mantra.AddJs

AddJs( resource )

Adds to the current request a javascript file placed at "js" folder. The "resource" parameter indicates which js file to include following one of these two formats options:

  • "componentname.filename": Mantra will look for a js file inside "/componentname/ui/js", in the folder of the component indicated in the first part of the parameter.
  • "frontend.pathtofile": in this case, "frontend" is a special key string indicating to Mantra that the file should be found in the UI assets of the current application.

All js files added with AddJs() in the same request, will be rendered at "mantra-js-files" Mustache tag indicated in html root document.

See Adapting Root Html Document to Mantra for more infor about Mantra Mustache tags.

Also, the parameter can be an array with a number of js resources to include.

You can also define the js files to include in on specific view indicating "<viewname>_js": property in its definition.

Some examples:

Mantra.AddJs( "cookieswarning.alertck" ); // Will include /cookieswarning/ui/js/alertck.js file.

Mantra.AddJs( "frontend.assets/js/popupmessages.js"; // Will include the file /assets/js/popupmessages.js that should be at the UI folder of the current application

Mantra.AddJs( ["alerts.showalert", "seo.settitle"] ); // Will include those two js files.

Remember: files to add in the next rendering process (js and css) are not ordered in anyway.

Mantra.AddRenderValue

AddRenderValue( key, value )

Adds data to be used in rendering using render engine template in views, blocks, etc.

Params:

  • key: <key name of the variable to render>
  • value: <value for the key>

For example, by running Mantra.AddRenderValue( "name", "Mantra Microkernel Framework" ), when rendering any html piece of code with Mustache syntax like:

<p></p>

, will be rendered as:

<p>Mantra Microkernel Framework</p>

Mantra.AddRenderValues

AddRenderValues( values )

Adds data to be used in rendering using render engine template in views, blocks, etc.

Params:

  • values: <json object with keys the their values to render>

Mantra.AddRequestData

AddRequestData( key, value )

Adds data to be used in same request.

Params:

  • key: <key for the property to be used during the request management>
  • value: <value for that key>

When Mantra manages a request (http get, post, etc.), multiple calls are performed (core middlewares, component middlewares, prerequests hooks if present, etc.). Any of those calls can enrich the request data adding info to it.

An example of this, is performed when a prequest hook checks the id of the entity included in the url, then that prerequest adds the entity with AddRequestData() so that the view handler can have it.

This decouples the code so that the view handler can be minimal.

Usually, request data is added in prerequest hooks.

Mantra.ComponentEntities

ComponentEntities( componentName )

Returns a RedEntities instance configured with the schema of the component. The instance is returned initialized with the model schema of the component.

Refer to RedEntities with the API of this library.

Mantra.ComponentEntitiesFromSchema

ComponentEntitiesFromSchema( componentName, schema )

Creates a new RedEntities instance intialized with a specific schema for the given component.

Refer to RedEntities with the API of this library.

Params:

  • componentName: <name of the component>
  • schema: <json schema object with the model>

Remember: component name is needed to load the database configuration for the component in "Entities" property of mantraconfig.json file.

Mantra.Config

Config( componentProperty )

Returns a component property componentProperty is in the format "component name"."component property".

This method is equivalent to use "config" property shortcut:

Mantra.config.componentname.property

Se Components Configuration for more details about component configurations.

Mantra.DynamicComponentEntities

DynamicComponentEntities( componentName, schema )

Returns a RedEntities instance initialized with a specific schema for the given component.

Because the creation of RedEntities object is quite heavy, this object is cached internally, unlike ComponentEntitiesFromSchema() method.

Refer to RedEntities with the API of this library.

Params:

  • componentName: <name of the component>
  • schema: <json schema object with the model>

Remember: component name is needed to load the database configuration for the component in "Entities" property of mantraconfig.json file.

Mantra.EmitEvent

async EmitEvent( eventName, eventData )

Emits an event to be managed by components events subscribers.

Params:

  • eventName: <name of the event>
  • eventData: <data for the event, optional>

See Component Events for more information about Mantra events.

Mantra.EndGetRequest

async EndGetRequest( data )

Ends current request sending back the data indicated as parameter.

This is equivalent to call Response.end(data) method of Express object.

Mantra.ExistsBlock

ExistsBlock( componentName, blockName)

Returns true if a block exists.

Params:

  • componentName: <component name>
  • blockName: <name of the block to check if exists>

Mantra.ExistsComponentApi

ExistsComponentApi( api )

Returns true if there is registered an api path, given in the format of "component name.api name".

Remember: files to add in the next rendering process (js and css) are not ordered in anyway.

Mantra.ExistsComponentByName

ExistsComponentByName( componentName )

Returns true if a component with the name indicated as parameter exists.

Mantra.ExistsView

async ExistsView( view )

Returns true if a view exists.

Param:

  • view: <view in the form of "[component name].[view name]", like "users.showuser">

Mantra.ExtractResource

async ExtractResource( resource )

Given a resource path, returns a json object indicating information about if it is a frontend or a component resource.

The json returned is like this:

{
    exists: <true if the resource exists>,
    isFrontendResource: <true if it is a front end resource>,
    isComponentResource: <true if it is a component resource>,
    fileType: <extension of the resource>,
    isMimeType: <true if it is a MIME type>
}

Mantra.GetAppName

GetAppName()

Returns a string with the name of the current running application.

Mantra.GetAssetsLocations

GetAssetsLocations()

Returns the Assets Locations instance with methods to locate assets within the project.

Mantra.GetComponentConfig

GetComponentConfig( componentName )

Returns the full config json object for a component given its name.

See Component Config for more info about components configuration.

Mantra.GetComponentDbConfig

GetComponentDbConfig( componentName )

Returns the json object with the database access properties indicated for the component, according to property "Entities" in mantraconfig.json file.

Remember this is one of the principles in a Mantra application: a component can use its own database instance.

If no specific configuration is provided, "default" will be returned.

Mantra.GetComponentDependencies

GetComponentDependencies( componentName )

Returns in an array the name of the components that a component depends on.

Mantra.GetComponentLocation

GetComponentLocation(componentName)

Returns de full path to the location of a component given its name.

Exception launched if component doesn't exist.

Mantra.GetComponentVersion

GetComponentVersion(componentName)

Returns the version of a component. This version is de "version" property of mantra.json file for the component.

Mantra.GetExtendsByType

GetExtendsByType( type )

Returns an array with all extends for the given type.

With Extends, any component can define its own types of hooks for multiple purposes.

  • Mantra.GetProjectDirectory
GetProjectDirectory()

Returns the absolute root directory of the current project.

Mantra.GetDataValues

GetDataValues()

Returns a hash table with all data values indicated previously with call to AddDataValue(). The keys of the hash table are the keys indicated when calling AddDataValue().

Mantra.GetGlobalVar

GetGlobalVar( globalVarKey )

Get the value of a global variable, included in section "GlobalTemplateVars" of mantraconfig.json file.

Returns '(unknown)' if the key entry doesn't exist.

As an example:

let globalSiteName = Mantra.GetGlobalVar( "global-sitename" )

Mantra.GetHooksByName

GetHooksByName( hookName )

Returns an array of json objects with all hooks (like "view", "post", etc.) registered by all components in the system.

Each json object of the hook have the properties indicated when they were registered in the onStart() method of the component.

Available hooks are:

  • "accesscondition"
  • "api"
  • "block"
  • "command"
  • "componentextend"
  • "cron"
  • "event"
  • "get"
  • "middleware"
  • "post"
  • "prerequest"
  • "view"

Mantra.GetInjection

GetInjection( inyectionKey )

Returns the value of an injection as indicated in Injections section of mantraconfig.json file.

Mantra.GetInstanceId

GetInstanceId()

Returns the current instance id of the application running.

For more details about instance id, see Instance Id document.

Mantra.GetRenderValues

GetRenderValues()

Gets the hash table with all data values added previusly with AddRenderValue() or AddRenderValues() used to render with then rendering template engine (Mustache by default in current version).

Mantra.GetRequestData

GetRequestData( key )

Gets especific data added previously with AddRequestData() to be used in the same request.

Mantra.GetRequestPath

GetRequestPath()

Returns a string with the current requested path.

Sends the "path" property of Request Express object.

Mantra.GetResponse

GetResponse()

Returns the Response Express object of the current request.

Mantra.GetRequest

GetRequest()

Returns the Request Express object of the current request.

Mantra.GetSchemaByVersion

async GetSchemaByVersion( componentName, version )

Loads a component schema.

Params:

  • componentName: <name of the component>
  • version: <optional, indicates the version of the schema>

Given the sample "GetSchemaByVersion( "users" ), then will return "/users/model/users.schema.json" json object file.

Given the sample "GetSchemaByVersion( "users", "1.2.0" ), then will return "/users/model/users.1.2.0.schema.json" json object file.

Mantra.GetView

async GetView( view )

Returns the html content of a view.

Param:

  • view: <view in the form of "[component name].[view name]", like "users.showuser">

Mantra.GetViewHtml

async GetViewHtml( pathToView )

Returns the html content for a view. Return the view html content "as it is", without the rendering process.

Param:

  • pathToView: <relative path to the file containing the view: /component/views/<viewname>.html>

Mantra.GlobalConfig

GlobalConfig( "propertyname" )

Returns the value of property indicated in GlobalConfig section of mantraconfig.json file.

Mantra.InstallDynamicSchema

async InstallDynamicSchema( componentName, jsonSchema, removesIfExists = true )

Install a new schema given its json definition. This is one of the advanced features of Mantra.

Params:

  • componentName: <name of the component which install the schema. According to this name, gets the right db configuration>
  • jsonSchema: <json of the schema to install>
  • removesIfExists: <if true, and if entities already exists, then they are removed and resintalled. If false, if an entity exists, then it is not removed. Default true>

Mantra.InstallSchema

async InstallSchema( componentName )

This method installs the schema of a component.

This schema (or database model), should be placed at /<compoponent name>/model/<component name>.schema.json.

The method loads that file and uses RedEntities to create the database.

The database type for the component should be indicated in "Entities" propery of mantraconfig.json.

See more información about Mantra entities management.

Usually, this method is called at onInstall() method in the component definition.

InstallSchema() looks for the schema that match de component version. If no exists, then the default one will be used.

For instance:

await Mantra.InstallSchema( "users" );

If users has "1.0.3" version (indicated at "version" property at its mantra.json file), then InstallSchema() will try to locate first the model "/users/model/users.1.0.3.schema.json". If it doesn't exist, then "/users/model/users.schema.json" will be used.

Mantra.IsServiceActive

IsServiceActive(service)

Returns true if the service indicated as parameter is active in current running application.

Available Mantra services are 'view','post','get','middleware' and 'cron'.

See Mantra Services for more information.

Mantra.IsGet

IsGet()

Returns a boolean indicating if current request is a HTTP GET request.

Mantra.IsIndex

IsIndex()

Returns a boolean indicating if current request path is the root ("/").

Mantra.Invoke

async Invoke( apiToCall, data = {} )

Invokes an API method defined by a component.

Params:

  • apiToCall: <method of the api to call: component.apiname>
  • data: <data to pass to the api method, optional>

Returns the value returned by the API method.

This method is equivalent to use "api" property shorcut:

Mantra.api.componentname.apiname

See Component APIs for more info about API registration.

Mantra.IsPost

IsPost()

Returns a boolean indicating if current request is a HTTP POST request.

Mantra.LoadSchema

async LoadSchema( schema )

Load the json for a schema according to the

Param:

  • schema: <path to the schema in typical definition of component assets: <component name>.<schema name> >. Mantra expects to locate the schema at "/<component name>/model/<component name>.schema.json" file.

Returns the json object with the schema loaded.

Mantra.LogError

async LogError( description, data = "", key = "", counter = 0 )

Adds an error message to log.

Params:

  • description: <description of the log>
  • data: <string data to add to the log trace, optional>
  • key: <string key associated with the log trace, optional>
  • counter: <counter for the log trace in the case multiple logs at the same time, optional>

Mantra.LogInfo

async LogInfo( description, data = "", key = "", counter = 0 )

Adds an info message to log.

Params:

  • description: <description of the log>
  • data: <string data to add to the log trace, optional>
  • key: <string key associated with the log trace, optional>
  • counter: <counter for the log trace in the case multiple logs at the same time, optional>

Mantra.LogWarning

async LogWarning( description, data = "", key = "", counter = 0 )

Adds a warning message to log.

Params:

  • description: <description of the log>
  • data: <string data to add to the log trace, optional>
  • key: <string key associated with the log trace, optional>
  • counter: <counter for the log trace in the case multiple logs at the same time, optional>

Mantra.PostRaw

PostRaw( data )

Ends the current post request sending the json object indicated as parameter.

Mantra.PostUnauthorizedCode

PostUnauthorizedCode()

Ends the current post request with HTTP status code 401 (Unauthorized).

More about HTTP status code here.

Mantra.Redirect

async Redirect( path )

Redirects current request to the path indicated as parameter.

Equivalent to use Response.redirect() method of Express.

Mantra.RedirectToRoot

async RedirectToRoot()

Redirects current request to the root ("/").

Equivalent to use Response.redirect("/") method of Express.

Mantra.RenameSchemaEntities

async RenameSchemaEntities( componentName, schema, sufix )

Renames the entities of the schema adding to the a sufix.

Params:

  • componentName: <name of the component>
  • schema: <json object with the schema>
  • sufix: <string with the sufix to rename the entities (table names>

Mantra.Render

async Render( html )

Renders the html document indicated as parameter.

Al data to render within the document, should be indicated previously with Mantra.AddRenderValue o Mantra.AddRenderValues.

If the document contains blocks, then they are rendered as well.

Retursn the document fully rendered.

Mantra.RenderContent

async RenderContent( htmlViewContent, htmlContainerFile )

This is the main method to render contents in mantra UI. Returns the rendering html document for the html view indicated in htmlViewConent.

Params:

  • htmlViewContent: <html to render with blocks, data values, etc>
  • htmlContainerFile: <optional, file of the container, like "index.html">

Mantra.RenderFullViewHtml

async RenderFullViewHtml( componentName, viewName, htmlContainerFile )

Render a view of a component and returns its full html content (container included).

Params:

  • componentName: <name of the component which defines the view>
  • viewName: <name of the view>.
  • htmlContainerFile: <html content of the container where render the view>

Mantra.RenderHtml

RenderHtml( templateHtml, data )

Renders the text html document with data.

Params:

  • templateHtml: <html text document to render>
  • data: <json object with data to render>

Returns the html document rendered.

Mantra.RenderLandingPage

async RenderLandingPage()

Renders default "index.html" document.

Mantra.RenderRawView

async RenderRawView( viewHtml, htmlContainer )

Renders the html content of a view in the root container html document.

Params:

  • viewHtml: <html content of the view>
  • htmlContainer: <root document container, optional, default "index.html">

Mantra.RenderRawViewContentHtml

async RenderRawViewContentHtml( viewHtml, htmlContainerFile = 'index.html' ) {

Render the content of the html view indicated in viewHtml in the container indicated in htmlContainerFile and returns the resulting html content.

Params:

  • viewHtml: <html content to render in the container file>
  • htmlContainerFile: <container file name, default "index.html">

Mantra.RenderRoot

async RenderRoot( htmlRootDocument )

Send as response the rendering of the full html document indicated as parameter.

The file to render should be placed under the frontend application folder.

As an example:

await Mantra.RenderRoot("/404.html");

Mantra.RenderTemplate

async RenderTemplate( templatefile, data )

Renders a template file with data. The template file is indicated as "<component name>/<template file name>" (with no ".html" extension).

firstly looks for the template file at /<site location>/ui/templates/<component name>/<template file>.

If it doesn't exist in that location, then looks for the template file at /<component>/ui/templates/<template file>.

If data is an array, then template file is rendered by each element.

Params:

  • templateFile: <local path to template inside site templates location (set in config) or component templates folder, like "pager/basepager" (no need to add .html extension)>
  • data: <json object with data to render | array object with json data to render, in this case, the template is rendered by each array item>

Mantra.RenderTemplateFromFile

async RenderTemplateFromFile( pathToTemplateFile, data )

Renders a template from its full location and data

Params:

  • pathToTemplate: <full path to template>
  • data: <json object with data to render within the template>

Returns the html document template rendered.

Mantra.RenderView

RenderView( view, htmlContainerFile )

This is the main method to be used in views function handlers to render component views. Renders a view and ends the get requests by sending its content.

Params:

  • view: <view to render in the format component.viewname>
  • htmlContainerFile: <optional, main container for the view, by default index.html>

As an example:

await RenderView( "books.showfullbookinfo" )

This sample sends back as response of a request the rendering of the view "showfullbookinfo" (expected to be located at /books/views/showfullbookinfo.html) within the default document root of "index.html".

Mantra.RenderViewHtml

async RenderViewHtml( componentName, viewName )

Renders a view and returns its full html content (container not included).

Params:

  • componentName: <name of the component>
  • viewName: <name of the view to render (no extension file needed)

As an example:

let viewHtml = await Mantra.RenderViewHtml( "books", "showfullbook" );

Mantra.SendError

SendError( message )

Ends the current request with HTTP status code status 500 (Internal Server Error)

More about HTTP status code here.

Mantra.SendFailure

SendFailure( message, dataPayload = {} )

Ends a request with a response indicating failure and an optional payload.

Params:

  • dataPayload: <optional, data to be sent with the post response, optional>

The method will response a json object with the property "success" to false:

{ success: false, payload: dataPayload }

Mantra.SendFile

async SendFile( fullPathToFile )

Send a file to the current request. The file should be located with its full path indicated in the parameter.

Equivalent to user Response.sendfile() method of Express.

Mantra.SendHtml

async SendHtml( htmlContent )

Sends html content over response object of the current request.

Param:

  • htmlContent: <raw html content to send>

Mantra.SendStatus

SendStatus(statusCode)

Ends the current request with the http status indicated as parameter.

More about HTTP status code here.

Mantra.SendSuccess

SendSuccess( dataPayload = {} )

Ends a request with a response indicating success and an optional payload.

Params:

  • dataPayload: <optional, data to be sent with the post response, optional>

The method will response a json object with the property "success" to true:

{ success: true, payload: dataPayload }

Mantra.UninstallSchema

async UninstallSchema( componentName, schema )

Removes current schema for the componente indicated as parameter.

Param:

  • componentName: <name of the component which schema will be removed>
  • schema: <optional, json object with the schema. If not included, Mantra will use the default component schema mode located at "/component/model" folder>

As with InstallSchema() method, the schema (or database model), should be placed at /<compoponent name>/model/<component name>.schema.json.

The method loads that file and uses RedEntities to uninstall (remove) the database.

The database type for the component should be indicated in "Entities" propery of mantraconfig.json.

See more información about Mantra entities management.

Usually, this method is called at onUninstall() method in the component definition.

UninstallSchema() looks for the schema that match de component version. If no exists, then the default one will be used.

Mantra.UpdateSchema

async UpdateSchema( componentName, currentVersion, versionToUpdate, updateEntityFnc )

Updates a new schema for a component. This method is complex and involves changes in DB.

It should be called from an onUpdate() method of the component definition.

onUpdate() is called by Mantra when running update command and if it detects changes in "version" property of mantra.json file of the component:

$ mantrad update

As with any other important update in any software system, it is recommended to make database backups before calling this method, and, of course, test the update in development or pre-production environments first.

Params:

  • componentName: <name of the component to update>
  • currentVersion: <current version of the component installed in system, as indicated in previous mantra.json>
  • versionToUpdate: <new version to update of the component, as indicated in current mantra.json>
  • updateEntityFnc: <optional callback function: async (entityName, entity, db) {}, to be called for each current entity instance for each entity in current db>

Basically, the updating to a new schema version process performs this steps:

  1. Renames current entities with the sufix "_temporal".
  2. Creates the new version of the schema.
  3. To load old data to be stored at new schema (and maybe with changes or conversion in the data entities), then calls to updateEntityFnc() calback by each entity in the old schema.
  4. Removes temporal entities renamed at step 1.

The callback function, if it is given, is called by each entity (row) in the database tables of the schema of the component, and has this prototype:

async function(entityName, entity, newdb)

Where:

  • entityName: <name of the entity (table), as defined in the schema>
  • entity: <json object with the data of the entity (row)>
  • newdb: <RedEntities instance with the new db created and where the data of the old one should be saved>

Remember: one of the Mantra main concepts to scacle applications is that entities should be small (one, two of three tables by each component as much), the entities should be defined with simple types and entities for each components should not store "very long" data sets.

If long data sets are needed, then third options should be used.

Refer to Updating Components Data Models of the documentation to read same examples.

Mantra.UpdateSchemaWithCurrentEntities

async UpdateSchemaWithCurrentEntities(componentName, currentVersion, versionToUpdate)

Same than UpdateSchema but with the difference that Mantra is in charge of move current data entities to new data model. Use this method to easily update the model when its changes only consists of minimal changes in the new version of the schema, like:

  • New properties with default values.
  • Property removed.
  • Adition of new indexes.

Refer to Updating Components Data Models of the documentation to read same examples.

To learn by example, go to Mantra demos and components sections of Mantra site.

❮ Previous
Index
Next ❯