Super User

Super User

Thursday, 16 October 2014 00:00

Logs

To access to end-points access logs go to menu Components > jBackend > Logs. A list of traced requests will be shown:

jBackend Logs

Each logged request has the following information:

Field:Description:
Endpoint The ID of the end-point that has received the request
Access type The type of access used on the end-point (free, user, API key)
Request time The date and time of the request
Duration Time required to serve the request (in seconds)
Error code The error code in case of request error
User ID The ID of the user when available
Key The API key used when available
Action The action of the request
Module The module of the request
Resource The resource of the request

It is possible to enable log trace for each end-point from the menu item options:

jBackend - Enable Trace

Thursday, 16 October 2014 00:00

Keys

To manage API Keys used to grant access to end-points go to menu Components > jBackend > Keys. A list of jBackend Keys will be shown:

jBackend Keys

Each key has the following properties:

Field: Description:
Key The enabling key
User The user associated to this key (to restrict access with key and to a single user)
Enabled endpoints If this key is enable on ALL endpoints or ONLY on selected endpoints
Selected endpoints The endpoints for which the key is enabled, when not enabled for ALL
Enabled on default If the key should also work on the default requests (i.e. /index.php?option=com_jbackend&view=request&...)
Daily requests Maximum number of daily requests allowed for the key (0 means unlimited)
Expiration date Key expiration date (0000-00-00 00:00:00 means never expires)
Comment Just a reminder for the key

For each key the following statistics fields are available:

Field: Description:
Hits Number of times the key was used
Last visit Last time the key was used
Current day Current day for daily requests limit
Current hits Hits of current day for daily requests limit

The API key, when required by the endpoint, must be included in any request using one of the following methods:

  • Adding api_key=<KEY> to the query params (for GET requests);
  • Adding api_key=<KEY> to the payload (for POST requests);
  • Adding api_key: <KEY> to the JSON payload (for JSON POST requests);
  • Adding Authorization: api_key <KEY> to the headers (in any case).
Friday, 26 September 2014 00:00

SobiPro Module API

The SobiPro Module is implemented with the plg_jbackend_sobipro plugin. It provides functions related to SobiPro directory extension (sections, categories and entries). Here is the list of supported methods.

Get the list of sections

Request parameters

action=get
module=sobipro
resource=sections

Example

<end-point>?action=get&module=sobipro&resource=sections

Example (REST format)

<end-point>/get/sobipro/sections

Response

{
    "status": "ok",
    "total": <T>,
    "sections": [
        {
            "id": "<section id>",
            "nid": "<section nid>",
            "name": "<section name>"
        },
        ...
        {
            "id": "<section id>",
            "nid": "<section nid>",
            "name": "<section name>"
        }
]}

 

Get a section

Request parameters

action=get
module=sobipro
resource=sections
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=sections&id=<N>

Example (REST format)

<end-point>/get/sobipro/sections/<N>

Response

{
    "status": "ok",
    "id": "<section id>",
    "nid": "<section nid>",
    "name": "<section name>",
    "description": "<section description>",
    "owner": "<section owner id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>"
}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

 

Get the list of categories

Request parameters

action=get
module=sobipro
resource=categories
parent=<N>

Example

<end-point>?action=get&module=sobipro&resource=categories&parent=<N>

Example (REST format)

<end-point>/get/sobipro/categories?parent=<N>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "nid": "<category nid>",
            "name": "<category name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        },
        ...
        {
            "id": "<category id>",
            "nid": "<category nid>",
            "name": "<category name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

 

Get a category

Request parameters

action=get
module=sobipro
resource=categories
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=categories&id=<N>

Example (REST format)

<end-point>/get/sobipro/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "nid": "<category nid>",
    "name": "<category name>",
    "description": "<category description>",
    "owner": "<category owner id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>",
    "parent": "<parent id>"
}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

 

Get the list of entries

Request parameters

action=get
module=sobipro
resource=entries
category=<C>

Example

<end-point>?action=get&module=sobipro&resource=entries&category=<C>

Example (REST format)

<end-point>/get/sobipro/entries?category=<C>

Response

{
    "status": "ok",
    "total": <T>,
    "entries": [
        {
            "id": "<entry id>",
            "nid": "<entry nid>",
            "name": "<entry name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        },
        ...
        {
            "id": "<entry id>",
            "nid": "<entry nid>",
            "name": "<entry name>",
            "owner": "<owner id>",
            "counter": "<counter>",
            "createdTime": "<created time>",
            "updatedTime": "<updated time>",
            "metaDesc": "<meta description>",
            "metaKeys": "<meta keywords>",
            "metaAuthor": "<meta author>",
            "metaRobots": "<meta robots>",
            "version": "<version number>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

 

Get an entry

Request parameters

action=get
module=sobipro
resource=entries
id=<N>

Example

<end-point>?action=get&module=sobipro&resource=entries&id=<N>

Example (REST format)

<end-point>/get/sobipro/entries/<N>

Response

{
    "status": "ok",
    "id": "<entry id>",
    "nid": "<entry nid>",
    "name": "<entry name>",
    "owner": "<entry owner id>",
    "section": "<entry section id>",
    "counter": "<counter>",
    "createdTime": "<created time>",
    "updatedTime": "<updated time>",
    "metaDesc": "<meta description>",
    "metaKeys": "<meta keywords>",
    "metaAuthor": "<meta author>",
    "metaRobots": "<meta robots>",
    "version": "<version number>",
    "fields": [
        {
            "name": "<field name>",
            "fid": "<field id>",
            "nid": "<field nid>",
            "sid": "<field sid>",
            "section": "<section id>",
            "lang": "<language code>",
            "_data": "<field data>",
            "_rawData": "<field raw data>",
            "fieldType": "<field type>",
            "isFree": "<is free>",
            "position": "<position>"
        },
        ...
        {
            "name": "<field name>",
            "fid": "<field id>",
            "nid": "<field nid>",
            "sid": "<field sid>",
            "section": "<section id>",
            "lang": "<language code>",
            "_data": "<field data>",
            "_rawData": "<field raw data>",
            "fieldType": "<field type>",
            "isFree": "<is free>",
            "position": "<position>"
        }
]}

Notes

Created and updated date format is YYYY-MM-DD HH:MM:SS

 

Plugin Settings

jBackend SobiPro Plugin Settings

The following options are available for user plugin:

Option Description
JSON Entries Enable JSON payload on entries action.
Monday, 21 July 2014 00:00

K2 Module API

The K2 Module is implemented with the plg_jbackend_k2 plugin. It provides functions related to K2 content construction kit for Joomla (items and categories). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=k2
resource=categories
rootid=<R> (optional)
endlevel=<E> (optional)

Example

<end-point>?action=get&module=k2&resource=categories&rootid=<R>&endlevel=<E>

Example (REST format)

<end-point>/get/k2/categories?rootid=<R>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<category description>",
            "parent": "<parent category id>"
        },
        ...
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<category description>",
            "parent": "<parent category id>"
        }
    ]
}

Notes

If rootid is specified, starts to get subcategories from the specified category id instead of the root category. If endlevel is specified, get categories and all subcategories up to the specified number of level, otherwise get all levels (default).

 

Get a category

Request parameters

action=get
module=k2
resource=categories
id=<N>

Example

<end-point>?action=get&module=k2&resource=categories&id=<N>

Example (REST format)

<end-point>/get/k2/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "name": "<category name>",
    "alias": "<category alias>",
    "description": "<category description>",
    "robots": "<meta robots>",
    "author": "<meta author>",
    "language": "<language code>",
    "parent": "<category id>"
}

Notes

Language can be "*" if any.

 

Get the list of items

Request parameters

action=get
module=k2
resource=items
cats=<C1,C2,...,CN> (optional)
subs=<0|1> (optional)
featured=<0|1|2> (optional)
limit=<L> (optional)
page=<P> (optional)
ordering=<field> (optional)

Example

<end-point>?action=get&module=k2&resource=items&cats=<C>&subs=1

Example (REST format)

<end-point>/get/k2/items?cats=<C>&limit=<L>&page=<P>

Response

{
    "status": "ok",
    "total": "<total items>",
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    items: [
        {
            "id": "<item id>",
            "title": "<item title>",
            "alias": "<item alias>",
            "content": "<item content>",
            "featured": "<featured>",
            "images": {
                "image": "<image URL>",
                "imageWidth": "<image width>",
                "image_caption": "<image caption>",
                "image_credits": "<image credits>",
                "imageXSmall": "<image extra small URL>",
                "imageSmall": "<image small URL>",
                "imageMedium": "<image medium URL>",
                "imageLarge": "<image large URL>",
                "imageXLarge": "<image extra large URL>"
            },
            "video": {
                "video": "<video URL>",
                "video_caption": "<video caption>",
                "video_credits": "<video credits>"
            },
        "language": "<item language>",
        "category_id": "<category id>",
        "category_name": "<category name>",
        "author": "<item author>",
        "created": "<item creation date>",
        "modified": "<item modification date>"
        },
        ...
        {
            ...
        }
    ]
}

Notes

Cats:
List of categories id to include

Subs:
0=Do not include sub categories (default), 1=Include sub categories

Featured:
0=Hide, 1=Show (default), 2=Show only featured items

Ordering:
date, rdate, alpha, ralpha, order, rorder, featured, hits, rand, best, modified, publishUp, id (default)

Created and modified date format is YYYY-MM-DD HH:MM:SS

 

Get an item

Request parameters

action=get
module=k2
resource=items
id=<N>

Example

<end-point>?action=get&module=k2&resource=items&id=<N>

Example (REST format)

<end-point>/get/k2/items/<N>

Response

{
    "status": "ok",
    "id": "<item id>",
    "title": "<item title>",
    "alias": "<item alias>",
    "content": "<item content>",
    "featured": "<featured>",
    "images": {
        "image": "<image URL>",
        "imageWidth": "<image width>",
        "image_caption": "<image caption>",
        "image_credits": "<image credits>",
        "imageXSmall": "<image extra small URL>",
        "imageSmall": "<image small URL>",
        "imageMedium": "<image medium URL>",
        "imageLarge": "<image large URL>",
        "imageXLarge": "<image extra large URL>"
    },
    "video": {
        "video": "<video URL>",
        "video_caption": "<video caption>",
        "video_credits": "<video credits>"
    },
    "metadesc": "<meta description>",
    "metakey": "<meta keywords>",
    "metadata": {
        "robots": "<meta robots>",
        "author": "<meta author>",
        "rights": "<meta content rights>",
        "xreference": "<meta external reference>"
    },
    "language": "<language code>",
    "category_id": "<category id>",
    "category_name": "<category name>",
    "author": "<item author>",
    "created": "<item creation date>",
    "modified": "<item modification date>"
}

Notes

Created and modified date format is YYYY-MM-DD HH:MM:SS

Language can be "*" if any.

 

Plugin Settings

jBackend K2 Plugin Settings

The following options are available for user plugin:

Option Description
Full image URL Generate absolute URL (i.e. with domain) for images fields.
Full video URL Generate absolute URL (i.e. with domain) for video fields.
Full img tag URL Force absolute URL (i.e. with domain) in any HTML img tag.
Content in items Include or exclude full content in the items response.

This post will show how it can be simple to create an hybrid mobile app using HTML, CCS and Javascript (i.e. a Phonegap app), and jBackend to access to Joomla content in JSON format and so to use Joomla as data source to feed the app. It's easy as 1,2,3.

jBackend Demo App

Friday, 27 June 2014 00:00

Changelog

Version 3.8.0:

  • Fixed an issue with create notifications for devices;
  • [plg_jbackend_content] added function to get an article by alias;
  • [plg_jbackend_content] dropped unpublished articles in get articles by tag;
  • [plg_jbackend_user] fixed an issue with FieldsHelper;
  • [plg_jbackend_push] replaced GCM with FCM.

Version 3.7.0:

  • Added license integration with jBackend Release System.

Version 3.6.0:

  • Fixed an issue with API key usage;
  • Fixed an issue with session_id;
  • Now all dates in DATETIME format are UTC-based;
  • [plg_jbackend_content] output date format changed to ISO 8601;
  • [plg_jbackend_content] added max limit option;
  • [plg_jbackend_user] fixed profile extra fields.

Version 3.5.0:

  • [plg_jbackend_content] extended support for joomla custom fields to the article list.

Version 3.4.0:

  • Added the list of endpoints on the dashboard;
  • [plg_jbackend_content] added support for joomla custom fields.

Version 3.3.0:

  • Added a log of all notifications sent;
  • Added target devices to push notifications;
  • [plg_jbackend_push] fixed an issue with NOW;
  • [plg_jbackend_content] fixed an issue with function to get articles by tags.

Version 3.2.0:

  • Improved CORS support;
  • Added delete all logs button;
  • Added endpoint filtering to logs;
  • Added target endpoints feature for API keys;
  • Added the user information to a registered device;
  • Added support for api_key passed as Authorization header (Authorization: api_key );
  • Added support for api_key passed as JSON parameter;
  • Added target users and groups to push notifications;
  • [plg_jbackend_user] fixed an issue with registration, remind and reset when captcha is enabled;
  • [plg_jbackend_user] added an option to process register, remind and reset as an authentication request;
  • [plg_jbackend_content] added an option to return also raw content (no content plugin);
  • [plg_jbackend_push] added an API function to create a push notification.

Version 3.1.0:

  • Added support for session_id passed as GET/POST/JSON parameter;
  • Added support for custom payload in push notifications;
  • Fixed an issue with log search.

Version 3.0.0:

  • Added support for push notifications for iOS and Android;
  • Added user information to logs;
  • Improved logs filtering;
  • Added CSV export to logs;
  • [plg_jbackend_content] added hits to single article response;
  • [plg_jbackend_content] added an option to exclude content from article list;
  • [plg_jbackend_content] added an option to include support for SEBLOD CCK custom fields;
  • [plg_jbackend_user] added profile request;
  • [plg_jbackend_user] added profile update request;
  • [plg_jbackend_user] added status request.

Version 2.1.3:

  • [plg_jbackend_user] fixed a PHP 5.3 compatibility issue (array initialization).

Version 2.1.2:

  • Added basic CORS feature;
  • [plg_jbackend_user] added username remind request;
  • [plg_jbackend_user] added password reset request.

Version 2.1.1 (only for J3):

  • Added the force SSL option.

Version 2.1.0:

  • Fixed an issue with delete log entry;
  • Fixed an issue with installer script;
  • Added the ability to select which modules to enable for each endpoint.

Version 2.0.2:

  • Fixed an issue with API key expiration check related to never expiring keys;
  • [plg_jbackend_content] added filter by featured in the list of articles;
  • [plg_jbackend_content] added featured field in the response for the list of articles;
  • [plg_jbackend_content] added tags to response for articles (only for J3);
  • [plg_jbackend_content] added tagarticles resource to get articles by tag (only for J3).

Version 2.0.1:

  • Added onBeforeCheckModule event.

Version 2.0.0:

  • Added a trace function for logs and statistics;
  • Added a new dashboard as a better landing page;
  • [plg_jbackend_content] fixed an issue with generateImagesFields() function;
  • [plg_jbackend_content] added a plugin option to force full image URLs in content.

Version 1.0.3:

  • [plg_jbackend_user] fixed an issue with com_users language costants.

Version 1.0.2:

  • [plg_jbackend_content] fixed an issue with orderby and orderdir parameters;
  • [plg_jbackend_content] added images fields for a single article and the list of articles;
  • [plg_jbackend_content] added a plugin option to return relative or full URLs for images fields;
  • [plg_jbackend_content] changed the date format of published date to YYYY-MM-DD HH:MM:SS.

Version 1.0.1:

  • Completed porting to J2
  • Some minor fixes and little improvements

Version 1.0.0:

  • Initial J3 version

Menu module

Version 1.0.1:

  • Fixed an issue with get menu items due to a new ACL check.

Version 1.0.0:

  • Initial version.

K2 module

Version 1.3.1:

  • Fixed an issue with ordering parameter in items.

Version 1.3.0:

  • Added support for language filter on categories and items;
  • Added an option to force full url for all img tags;
  • Improved support for K2 plugins in the list of items.

Version 1.2.0:

  • Added an option to include or exclude full content from items response;
  • Added introtext to item and items response;
  • Added extra_fields and extra_fields_search to item and items response;
  • Added image field to category and categories response;
  • Fixed an issue with items ordering.

Version 1.1.1:

  • Fixed an issue with path of images.

Version 1.1.0 (only for J3):

  • Fixed an issue with list of items.

Version 1.0.4 (only for J2):

  • Fixed an issue with path of images.

Version 1.0.3:

  • Some code optimization.

Version 1.0.2:

  • Fixed name of plugin options constants;
  • Changed error code K2_KGE to K2_CGE.

Version 1.0.1:

  • Completed porting to J2;
  • Some minor fixes and little improvements.

Version 1.0.0:

  • Initial J3 version.

SobiPro module

Version 1.2.0:

  • Added category_name filter field for entries;
  • Added an option to enable JSON payload on entries action.

Version 1.1.0:

  • Changed entries function to support multiple categories.

Version 1.0.1:

  • Some code optimization.

Version 1.0.0:

  • Initial version.

ZOO module

Version 1.1.1:

  • Extended named elements also for a single item (thanks to Ray Lawlor).

Version 1.1.0:

  • Added an option to include elements in the list of items (thanks to Ray Lawlor);
  • Added an option to use slug (friendly) names for elements (thanks to Ray Lawlor).

Version 1.0.0:

  • Initial version.

Kunena module

Version 1.0.0:

  • Initial version.

Community Builder module

Version 1.0.1:

  • Added full URL for avatar field in the get user profile.

Version 1.0.0:

  • Initial version.
Tuesday, 10 June 2014 00:00

Developer's guide

jBackend provides a robust and extensible solution to expose content and services through a Joomla website. The component provides the basic structure that has in charge of managing requests, controlling accesses, and dispatching incoming requests to the corresponding module. The jBackend architecture is extensible because its service modules are implemented as Joomla plugins, so adding new plugins allows to add new services and expose the contents of new extensions.

In this section we will describe how to create custom modules, and what is the structure of a jBackend plugin. For this purpose it was created an "Hello World" plugin available for download here:

http://www.selfget.com/downloads/file/31-plg-jbackend-helloworld-j30.html

Structure of supported requests

Each HTTP request to an jBackend endpoint MUST include at least three parameters:

action=<action_type>
module=<module_name>
resource=<service_request>

The action would specify one of the HTTP methods used in a RESTful service (e.g. GET, PUT, POST, or DELETE). This is because all Joomla requests are made using GET, so this FIRST parameter introduces the missing information.

The module parameter indicates the name of the module that has in charge of managing this request (e.g. content). This can be implemented as a single jBackend plugin, or even a pool of plugins where each one implements a subset of module services. As example, for com_content core extension a content plugin already exists, which provides read-only access to content and categories. It could be possible to create a new plugin (e.g. plg_jbackend_content_admin) registered also as content module, which takes in charge editor functions like create content and categories.

The resource parameter specifies the service we are requesting to the module (e.g. articles of the content module, login service of the user module, etc.). This parameter must be validated and managed by the plugin itself, no checks will be made on this by jBackend (it cannot know about services provided by each plugin).

Considering all the required parameters (action, module, and resource), each request has this structure:

<end-point>?action=<action_type>&module=<module_name>&resource=<service_request>

If Joomla SEF is enabled, the request can assume this REST-like structure:

<end-point>/<action_type>/<module_name>/<service_request>

A request can also take additional parameters needed by the resource itself for the required service (e.g. the id of the article). This parameters can be added as a standard URL query string, so the request structure assumes this aspect:

<end-point>?action=<action_type>&module=<module_name>&resource=<service_request>&var1=<value1>&...&varN=<valueN>

Or can be (when SEF is enabled):

<end-point>/<action_type>/<module_name>/<service_request>?var1=<value1>&...&varN=<valueN>

An event onBeforeCheckModule is triggered just before to check the module name to dispatch. This permits to override the module variable (as well as action and resource variables) before the request dispatching process and can be useful, as example, when a plugin must deal with existing client requests that cannot be customized as required by jBackend.

Using onBeforeCheckModule it is possible, as example, to match a request like the following:

<endpoint>?var=catchme

This request doesn't include any of the required variables (action, module, resource), but we can "catch" the var and set the required variables:

  public function onBeforeCheckModule()
  {
    $app = JFactory::getApplication();
    $var = $app->input->getString('var');
    if ($var === 'catchme') {
      $app->input->set('action', 'get');
      $app->input->set('module', 'content');
      $app->input->set('resource', 'articles');
      $app->input->set('catid', '64');
      $app->input->set('id', '71');
    }
  }

Basic elements of a jBackend plugin

As a standard Joomla plugin, any jBackend plugin needs an XML installation file with the following structure:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="jbackend" method="upgrade">
    <name>plg_jbackend_helloworld</name>
...
</extension>

The plugin group must be "jbackend". All other XML elements are the same of a standard Joomla plugin. The PHP plugin code should have a generateError() function which builds and return all plugin specific errors:

  /**
   * This is the function to generate plugin specific errors
   * The error response is an array with the following structure:
   *    array(
   *     'status' => 'ko',
   *     'error_code' => $errorCode,
   *     'error_description' => <short error description>
   *    )
   *
   * @param  string  $errorCode  The error code to generate
   *
   * @return  array  The response of type error to return
   */
  public static function generateError($errorCode)
  {
    $error = array();
    $error['status'] = 'ko';
    switch($errorCode) {
      case 'REQ_ANS':
        $error['error_code'] = 'REQ_ANS';
        $error['error_description'] = 'Action not specified';
        break;
      case 'HWD_GEN':
        $error['error_code'] = 'HWD_GEN';
        $error['error_description'] = 'Generic hello world error';
        break;
    }
    return $error;
  }

It is not mandatory, but a good practice for the format of the error code is to use a pattern like XXX_YYY, where XXX is a code associated to the plugin (e.g. HWD for the helloworld plugin), and YYY for the specific error (e.g. GEN for generic error).

The other function that any jBackend plugin should have is the onRequest<Module>() function. This is called by jBackend during requests dispatching process. It has three parameters, an input parameter $module that is the module name and is used by the plugin to understand if it should handle the request, an output parameter $response that is the response object, and a $status parameter that can return additional information. The function returns true if there are no problems (status = ok), false in case of errors (status = ko):

public function onRequestHelloWorld($module, &$response, &$status = null)

The first thing the onRequest function should do is to check if it must handle the request or not. If not, it should return to improve the performance of the dispatching process:

if ($module !== 'helloworld') return true; // Check if this is the triggered module or exit

The second thing is to add the plugin to the module call stack:

// Add to module call stack
jBackendHelper::moduleStack($status, 'helloworld'); // Add this request to the module stack register

After these tasks, it is possible to get request vars and process the response:

$app = JFactory::getApplication();
$action = $app->input->getString('action');
$resource = $app->input->getString('resource');

// Check if the action is specified
if (is_null($action)) {
  $response = plgJBackendHelloWorld::generateError('REQ_ANS'); // Action not specified
  return false;
}

switch ($resource)
{
  case 'greeting':
    if ($action == 'get')
    {
      return $this->actionGreeting($response, $status);
    }
    break;
  case 'about':
    if ($action == 'get')
    {
      return $this->actionAbout($response, $status);
    }
    break;
}

return true;

Each function like actionGreeting() and actionAbout() is specific to manage the resource requested by the action. To maintain the code clean it is a good practice to create a different function for each action.

The following is an example of an action() function that shows the code structure and how to manage the errors:

  public function actionGreeting(&$response, &$status = null)
  {
    $app = JFactory::getApplication();

    // Get additional request parameters
    $id = $app->input->getInt('id');
    if (!is_null($id))
    {
      // Example of how to generate and return an error inside an action function
      if ($id == '101')
      {
        $response = plgJBackendHelloWorld::generateError('HWD_GEN'); // Generic hello world error
        return false;
      }
    }

    // Get plugin params
    $option_name = $this->params->get('option_name', 0);

    $response['status'] = 'ok';
    $response['message'] = $this->_greeting_msg;
    if ($option_name)
    {
      $response['option'] = 'true';
    }
    return true;
  }
Monday, 21 April 2014 00:00

Initial configuration

The first thing to do is to enable Tag Meta plugin. To enable the plugin go to menu "Extensions" -> "Plug-in Manager", find a system type plugin named "System - Tag Meta Community" or "System - Tag Meta Enterprise" in the plugin list, and click on it to access to plugin settings. Set "Status" to “Enabled”, and set other parameters on the right side according to your needs. Look at "Plugin settings" paragraph for detailed information about each parameter. Click on "Save & Close" button and check that the plugin is now enabled.

Tag Meta Enable Plugin

Remember that is the plugin that "does the work". The Tag Meta component is just the administrative interface for managing meta rules an other features, but is the plugin that checks site requests and performs meta enhancement when needed. So, the very first thing to do is to enable the plugin. Note that if you need to disable Tag Meta, just disable the plugin.

Another thing to check is the plugins order that can be very important, especially if there are some other plugins that mess with page's meta information. In most cases it is better to set Tag Meta as the last system plugin, so it will be the last to be executed and to madofy page content. Now Tag Meta is ready to work! You can now create your first meta rule, and test the result through the web browser. Be careful that you could get a cached page. To avoid this just clear server-side cache from backend (menu "Maintenance" -> "Clean Cache"), and client-side cache from your web browser.

Sunday, 20 April 2014 00:00

Changelog

Version 1.9.3:

  • Fixed REGEP BINARY query error with MySQL 8.

Version 1.9.2:

  • Fixed URLs and links for Joomla! 3.9.x.

Version 1.9.1:

  • Fixed an issue with seterror function;
  • Added support for https to custom error page of type link.

Version 1.9.0:

  • Added macros {camelcase} and {ucwords};
  • Added support for Joomla! Update System.

Version 1.8.3:

  • Fixed an issue with empty function (return value in write context);
  • Added an option to apply a rule only in case of error (sponsored by damago gmbH).

Version 1.8.2:

  • Fixed an issue with shortcut extensions.

Version 1.8.1:

  • Fixed an issue with exception handler for Joomla 3.6.0;
  • Improved error management.

Version 1.8.0:

  • Fixed an issue with exception handler;
  • Changed some code for PHP 7 compatibility.

Version 1.7.10:

  • Fixed and issue with exception handler.

Version 1.7.9 (only for J3):

  • Fixed an issue with pagination;
  • Fixed an issue with {requestvar};
  • Added macro {placeholder_insert} (only for Enterprise);
  • Added macro {placeholder_update} (only for Enterprise).

Version 1.7.8:

  • Fixed an issue with filter in search tools on errors and redirects;
  • Improved route_url() function;
  • Fixed an issue with drop_query_vars() function.

Version 1.7.7:

  • Fixed code for PHP 5.5 deprecated preg_replace /e modifier;
  • Fixed issue with {queryvar} macro;
  • Fixed issue with {substr} macro;
  • Added macro {pathfolder} (only for Enterprise).

Version 1.7.6:

  • Fixed an issue with exceptions management (call_user_func and variable passed by reference).

Version 1.7.5:

  • Added macros {urlencode} and {urldecode};
  • Improved function sanitizeURL for UTF-8 support when multibyte library is missing;
  • Added a redirect URL for each error URL;
  • Added a clean function for errors which saves errors with a redirect attached (unlike the purge function);
  • Fixed an issue with {username} and {userid} macros;
  • Added macros {rawurldecode} and {rawurlencode};
  • Added macro {str_replace};
  • Removed a wrong check on document type inside onAfterInitialise;
  • Added skip_usergroups feature to skip rules for specified groups of users (only for Enterprise);
  • Added macro {placeholder_select} (only for Enterprise).

Version 1.7.4:

  • Changed the interface to support new filters and ordering (only for J3);
  • Fixed an issue related to changes of JUri behavior (only for J3);
  • Fixed an issue of compatibility of plugin with PHP 5.2.

Version 1.7.3:

  • Fixed an issue with rule search filter;
  • Fixed an issue with errors search filter, pages 404 and referers (only for J3);
  • Fixed an issue on the custom error page (when the option is enabled but page is not selected);
  • Improved macro {routeurl} for the unwanted variables removal;
  • Improved function to manage redirect of all errors;
  • Improved interface to manage errors and referers;
  • Added new URL macros {queryappend}, {querybuildappend}, and {querydropappend};
  • Added new site macros {username}, {userid};
  • Added new string macros {lowercase}, {uppercase};
  • Added rule condition to skip redirect;
  • Added button to reset statistics (hits and last visit);
  • Fixed an issue in the package related to plugin uninstall.

Version 1.7.2:

  • Improved trim text function;
  • Improved queryfull macro;
  • Added "shortcut extensions" option to plugin;
  • Created installation package;
  • First release for Joomla 3.0.

Version 1.7.1:

  • Fixed issue with custom error page;
  • Added combobox selection for the custom error page.

Version 1.7.0:

  • Added support for placeholders and comments for redirection rules;
  • Added support for new macros for redirection rules.

Version 1.6.2:

  • Replaced TYPE=MyISAM with ENGINE=MyISAM;
  • Fixed issue with $basepath related to "/" encoded with %2F;
  • Fixed issue with creation of exclude referers list;
  • Hidden warning messages on preg_match macro (@preg_match) (only for Enterprise);
  • Hidden notice message "Notice: Undefined offset: 0:" on array_key_exists (only for Enterprise);
  • Replaced urlencode(<string>) with urlencode(utf8_encode(<string>)) (only for Enterprise);
  • Replaced urldecode(<string>) with utf8_decode(urldecode(<string>)) (only for Enterprise).

Version 1.6.0:

  • Completely rewritten for the new version of Joomla! 1.6 and 1.7;
  • The redirection rules can work on the entire URL, including protocol and domain;
  • It can be specified for each redirect rule whether or not to first decode the URL.
Saturday, 19 April 2014 00:00

Content Module API

The Content Module is implemented with the plg_jbackend_content plugin. It provides functions related to Joomla content (articles and categories). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=content
resource=categories
rootid=<R> (optional)
recursive=<true or 1> (optional)
countitems=<true or 1> (optional)

Example

<end-point>?action=get&module=content&resource=categories&rootid=<R>&recursive=<false>&countitems=<0>

Example (REST format)

<end-point>/get/content/categories?rootid=<R>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "title": "<category title>",
            "description": "<category description>",
            "parent_id": "<parent category id>",
            "numitems": <items count>
        },
        ...
        {
            "id": "<category id>",
            "title": "<category title>",
            "description": "<category description>",
            "parent_id": "<parent category id>",
            "numitems": <items count>
        }
    ]
}

Notes

If rootid is specified, starts to get subcategories from the specified category id instead of the root category. If recursive is true or 1, get categories and all subcategories, otherwise get only one level (default). If countitems is true or 1, return the number of articles of each category, otherwise do not return this information (default). Category id can be "root" for root node.

 

Get a category

Request parameters

action=get
module=content
resource=categories
id=<N>

Example

<end-point>?action=get&module=content&resource=categories&id=<N>

Example (REST format)

<end-point>/get/content/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "title": "<category title>",
    "alias": "<category alias>",
    "description": "<category description>",
    "metadesc": "<meta description>",
    "metakey": "<meta keywords>",
    "metadata": {
        "page_title": "<meta title>",
        "author": "<meta author>",
        "robots": "<meta robots>"
    },
    "language": "<language code>",
    "parent_id": "<category id>",
    "level": "<category level>",
    "numitems": "<N>"
}

Notes

Language can be "*" if any. Category id can be "root" for root node.

 

Get the list of articles

Request parameters

action=get
module=content
resource=articles
catid=<C> (optional)
maxsubs=<S> (optional)
featured=<F> (optional)
limit=<L> (optional)
offset=<O> (optional)
orderby=<field> (optional)
orderdir=<dir> (optional)

Example

<end-point>?action=get&module=content&resource=articles&catid=<C>&maxsubs=<S>&featured=<F>&orderby=<id>

Example (REST format)

<end-point>/get/content/articles?catid=<C>&limit=<L>&offset=<O>

Response

{
    "status": "ok",
    "total": <total articles>,
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    "pages_current": <current page>,
    "pages_total": <total pages>,
    "articles": [
        {
            "id": "<article id>",
            "title": "<article title>",
            "alias": "<article alias>",
            "featured": "<featured>",
            "content": "<article content>",
            "catid": "<article category id>",
            "images": {
                "image_intro": "<image_url_for_intro>",
                "float_intro": "<float_side_for_intro>",
                "image_intro_alt": "<alt_text_for_intro>",
                "image_intro_caption": "<caption_for_intro>",
                "image_fulltext": "<image_url_for_fulltext>",
                "float_fulltext": "<float_side_for_fulltext>",
                "image_fulltext_alt": "<alt_text_for_fulltext>",
                "image_fulltext_caption": "<caption_for_fulltext>"
            },
            "tags": [
                {
                    "id": "<tag id>",
                    "title": "<tag title>",
                    "alias": "<tag alias>",
                    "language": "<tag language>"
                },
                ...
            ],
            "fields": [
                {
                    "id": "<field id>",
                    "title": "<field title>",
                    "name": "<field name>",
                    "type": "<field type>",
                    "default_value": "<default value>",
                    "group_id": "<field group id>",
                    "label": "<field label>",
                    "description": "<field description>",
                    "required": "<field required>",
                    "value": "<field value>",
                    "rawvalue": "<field raw value>"
                },
                ...
            ],
            "metakey": "<meta keywords>",
            "metadesc": "<meta description>",
            "metadata": {
                "robots": "<meta robots>",
                "author": "<meta author>",
                "rights": "<meta content rights>",
                "xreference": "<meta external reference>"
            },
            "language": "<language code>",
            "category_title": "<category title>",
            "category_alias": "<category alias>",
            "author": "<article author>",
            "created_date": "<created date>",
            "modified_date": "<modified date>",
            "published_date": "<publish up date>",
            "unpublished_date": "<publish down date>",
            "state": "<article state>"
            },
            ...
            {
                ...
            }
    ]
}

Notes

State:

  • Published = 1,
  • Unpublished = 0,
  • Archived = 2,
  • Trashed = -2

Max subs:
Number of subcategories to include (default 0=none)

Featured:
hide,only,show (default)

Order by:
id, title, alias, catid, state, created, created_by, ordering (default), hits

Order dir:
asc (default), desc

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

Property content is present only if plugin's option Content in article list is set.

Property tags is present only if plugin's option Add tags in article list is set.

Property fields is present only if plugin's option Prepare content in article list is set.

 

Get an article

Request parameters

action=get
module=content
resource=articles
id=<N>

Example

<end-point>?action=get&module=content&resource=articles&id=<N>

Example (REST format)

<end-point>/get/content/articles/<N>

Response

{
    "status": "ok",
    "id": "<article id>",
    "title": "<article title>",
    "alias": "<article alias>",
    "featured": "<featured>",
    "introtext": "<article intro text>",
    "content": "<article content>",
    "content_raw": "<article content raw>",
    "catid": "<article category id>",
    "images": {
        "image_intro": "<image_url_for_intro>",
        "float_intro": "<float_side_for_intro>",
        "image_intro_alt": "<alt_text_for_intro>",
        "image_intro_caption": "<caption_for_intro>",
        "image_fulltext": "<image_url_for_fulltext>",
        "float_fulltext": "<float_side_for_fulltext>",
        "image_fulltext_alt": "<alt_text_for_fulltext>",
        "image_fulltext_caption": "<caption_for_fulltext>"
    },
    "tags": [
        {
            "id": "<tag id>",
            "title": "<tag title>",
            "alias": "<tag alias>",
            "language": "<tag language>"
        },
        ...
    ],
    "associations": [
    ],
    "event": {
        "afterDisplayTitle": "<after display title>",
        "beforeDisplayContent": "<before display content>",
        "afterDisplayContent": "<after display content>"
    },
    "fields": [
        {
            "id": "<field id>",
            "title": "<field title>",
            "name": "<field name>",
            "type": "<field type>",
            "default_value": "<default value>",
            "group_id": "<field group id>",
            "label": "<field label>",
            "description": "<field description>",
            "required": "<field required>",
            "value": "<field value>",
            "rawvalue": "<field raw value>"
        },
        ...
    ],
    "cck_fields": [
    ],
    "metakey": "<meta keywords>",
    "metadesc": "<meta description>",
    "metadata": {
        "robots": "<meta robots>",
        "author": "<meta author>",
        "rights": "<meta content rights>",
        "xreference": "<meta external reference>"
    },
    "language": "<language code>",
    "category_title": "<category title>",
    "category_alias": "<category alias>",
    "author": "<article author>",
    "parent_id": "<parent id>",
    "parent_title": "<parent title>",
    "parent_alias": "<parent alias>",
    "parent_route": "<parent route>",
    "created_date": "<created date>",
    "modified_date": "<modified date>",
    "published_date": "<publish up date>",
    "unpublished_date": "<publish down date>",
    "version": "<article version>",
    "hits": "<article hits>",
    "rating": "<article rating>",
    "rating_count": "<article rating count>",
    "state": "<article state>"
}

Notes

State:

  • Published = 1,
  • Unpublished = 0,
  • Archived = 2,
  • Trashed = -2

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

Language can be "*" if any.

Property content_raw is present only if plugin's option Include content raw is set.

Property event is present only if plugin's option Show article event is set.

Property cck_fields is present only if plugin's option Include CCK is set.

 

Get the list of articles by tag id

Request parameters

action=get
module=content
resource=tagarticles
tagid=<T1,T2,...,Tn>
limit=<L> (optional)
offset=<O> (optional)

Example

<end-point>?action=get&module=content&resource=tagarticles&tagid=<T>&limit=<L>&offset=<O>

Example (REST format)

<end-point>/get/content/tagarticles?tagid=<T>&limit=<L>&offset=<O>

Response

{
    "status": "ok",
    "total": <total articles>,
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    "pages_current": <current page>,
    "pages_total": <total pages>,
    articles: [
        {
            "id": "<article id>",
            "title": "<article title>",
            "alias": "<article alias>",
            "featured": "<featured>",
            "content": "<article content>",
            "images": {
                "image_intro": "<image_url_for_intro>",
                "float_intro": "<float_side_for_intro>",
                "image_intro_alt": "<alt_text_for_intro>",
                "image_intro_caption": "<caption_for_intro>",
                "image_fulltext": "<image_url_for_fulltext>",
                "float_fulltext": "<float_side_for_fulltext>",
                "image_fulltext_alt": "<alt_text_for_fulltext>",
                "image_fulltext_caption": "<caption_for_fulltext>"
            },
            "tags": [
                {
                    "id": "<tag id>",
                    "title": "<tag title>",
                    "alias": "<tag alias>",
                    "language": "<tag language>"
                },
                ...
            ],
            "metadesc": "<meta description>",
            "metakey": "<meta keywords>",
            "metadata": {
                "robots": "<meta robots>",
                "author": "<meta author>",
                "rights": "<meta content rights>",
                "xreference": "<meta external reference>"
            },
        "category_title": "<category title>",
        "author": "<article author>",
        "published_date": "<article date>"
        },
        ...
        {
            ...
        }
    ]
}

Notes

Dates are in ISO 8601 format (e.g 2017-05-11T10:16:32+00:00)

 

Get an article by alias

Request parameters

action=get
module=content
resource=articlebyalias
id=<alias>

Example

<end-point>?action=get&module=content&resource=articlebyalias&id=<alias>

Example (REST format)

<end-point>/get/content/articlebyalias/<alias>

Response

Same response as "Get an article"

Notes

Same notes as "Get an article".

 

Plugin Settings

jBackend Content Plugin Settings

The following options are available for user plugin:

Option Description
Filter language Filter content by language.
Status Filter content by state.
Access archived articles Allow get article on archived items.
Grant access Skip access permissions check and allow access to articles.
Full image URL Generate absolute URL (i.e. with domain) for images fields.
Force full image URL in content Try to replace relative image URL in content with absolute URL.
Add tags in article list Include article tags in the list of articles.
Prepare content in article list Call onContent events on each article in the list of articles.
Content in article list Include full content in the list of articles.
Show article event Include results of events in the article response.
Include content raw Include raw content (no content plugin) in the article response.
Include CCK Include SEBLOD CCK custom fields in the article response.