FrançaisEnglish

Declaration of a new service (Notes)

Introduction

Create a new plugin.

Add an extension to the org.ametys.web.service.ServiceExtensionPoint

Use a class that implements Service such as the org.ametys.web.service.StaticService class

Definition

A service is defined by :

  • an unique id
  • a URL
  • a title, description and icons
  • somes parameters

StaticService

As named, this implementation is static : based on its configuration (in plugin.xml file)

<extension point="org.ametys.web.service.ServiceExtensionPoint"
	   class="org.ametys.web.service.StaticService"
	   id="myservice">

	<url>relative/path/to/myplugin.html</url>

	<label i18n="true">CATALOGUE:KEY</label>
	<description i18n="true">KEY</description>

	<thumbnail>
	    <small plugin="web">img/service/servicepage_16.png</small>
	    <medium>img/myimg.png</medium>
	    <large>img/mylargeimg.png</large>
	</thumbnail>

	<parameters>
	    <parameter>...</parameter>
	</parameters>
</extension>

url is an url in the plugin sitemap
label and description are mandatory

thumbnails are optionnal

parameters use shared configuration for parameters (e.g. config)

Service parameters

Each parameter has :

  • a name
  • a label
  • a description
  • a type (string, long, double, date, ..)
  • a default-value (optional)
  • enumerated values (optional)
  • a validator (optional)

This is a sample of the declaration of an enumerated parameter :

<parameter name="content-type" type="string">
        <label i18n="true">PLUGINS_WEB_SERVICE_FILTERED_CONTENTS_CONTENT_TYPE</label>
	<description i18n="true">PLUGINS_WEB_SERVICE_FILTERED_CONTENTS_CONTENT_TYPE_DESC</description>
	<enumeration>
	      <custom-enumerator class="org.ametys.cms.contenttype.ContentTypeEnumerator"/>
	</enumeration>
	<validation>
	      <mandatory/>
	</validation>
</parameter>

Parameters types

The supported types for parameters are :

  • string
  • long
  • double
  • date
  • boolean

Parameters widget

The service parameters can use a specific widget among :

  • tags : this widget allows to select tags of type CONTENT or PAGE
  • content-tags : this widget allows to select tags of type CONTENT
  • page-tags : this widget allows to select tags of type PAGE
  • sitemap : this widget allow to select a page in a sitemap (Not yet implemented)
  • resources : this widget allow to select a page a resource (Not yet implemented)

To use a widget, simply do as below :

<parameter name="tags" type="string">
        <label i18n="true">PLUGINS_WEB_SERVICE_FILTERED_CONTENTS_TAGS</label>
	<description i18n="true">PLUGINS_WEB_SERVICE_FILTERED_CONTENTS_TAGS_DESC</description>
	<widget>content-tags</widget>
</parameter>

Service URL

The URL of the service is the relative url of a Coccon pipeline defined by sitemap.xmap file of the service plugin.

For example:

<map:match pattern="service/sitemap.html">
	<map:generate type="service-sitemap">
		<map:parametername="depth" value="{parent-context-attr:depth}"/>
		<map:parametername="all" value="{parent-context-attr:all}"/>
	</map:generate>
	<map:transformtype="xslt"src="service://@xslt"/>
	<map:transformtype="i18n">
		<map:parametername="locale"value="{request-attr:sitemapLanguage}"/>
		<map:parametername="plugin"value="{request-attr:pluginName}"/>
	</map:transform>
	<map:serializetype="xml"/>
</map:match>

Override the default behavior

By default, the service parameters are automatically displayed in a dialog box when selecting the service. The input field or the widged used will be chose according to the parameter type.

This a sample of dialog box automatically drawing:

 

The default behavior can be override to do by your own way. In order to do this this, add the <action> balise in the declaration of service like this:

<extension point="org.ametys.web.service.ServiceExtensionPoint"
	   class="org.ametys.web.service.StaticService"
	   id="myservice">

	<url>relative/path/to/myplugin.html</url>

	<label i18n="true">CATALOGUE:KEY</label>
	<description i18n="true">KEY</description>
        <parameters>
	      <action class="org.ametys.MyOwnJSAction">
                    <param name="myparam">valueoftheparam</param>
	      </action>
	      <scripts>
		    <file>js/path/to/my/own/JsClass.js</file>
	      </scripts>
              <css>
                    <file>css/path/to/my/own/css.js</file>
              </css>
              <parameter>
              ....
              </parameter>
        </parameters>
</extension>
Complete override

Your JS class receives 2 parameters :

  • params : the service parameters service-org.ametys.web.service$id, service-org.ametys.web.service$pageId, service-org.ametys.web.service$zoneName. Those parameters are needed to create the service
  • callback : the callback function to call after the service creation. This function is in charge to send the message of creation on the bus event. It is waiting for a XML server response in first argument and the concerned page id in second arguments. The page id must be in an object with the key service-org.ametys.web.service$pageId
Partial override

You may want to override the parameters dialog box only to do some logic between the parameters. In order to do this, you can used the default function which is in charge to draw the parameters  :

org.ametys.web.content.ServiceParameters.drawServiceParameters

The draw fields or widget are stored in org.ametys.web.content.ServiceParameters._widgets. DO NOT FORGET to show the dialog box.

org.ametys.MyOwnJSAction = function (params, callback)
{
   org.ametys.web.content.ServiceParameters.drawServiceParameters (org.ametys.web.content.ServiceParameters._form, org.ametys.MyOwnJSAction.doSpecific);
}

org.ametys.MyOwnJSAction.doSpecific = function ()
{
    var widgets = org.ametys.web.content.ServiceParameters._widgets;

    // Do specific actions here

    org.ametys.web.content.ServiceParameters.box.show();
}
Back to top

Development