Creation of Custom Widget (Service?)

mcdons · 01/11/2013 00:22:02

I have been tasked with the creation of a custom widget for our Ametys CMS instance. The desired use-case for this custom widget is as follows:

The content editor logs into the CMS.
He/She starts editing a web page.
He/She selects to add this widget to a content box on the page.
He/She is prompted with a configuration popup where a form of config settings is filled out (in this pop-up communication with internal and external servers may need to occur so some custom JS handlers will likely be necessary).
He/She saves the configuration and the content area is now populated with custom HTML and JS, which has been affected by the entered config settings.

The behavior of this widget is going to change based on the credentials of the person logged in at the time it is included in a page, in the Back End, and at the time it is viewed in the Front End.

From what I can tell this behavior looks like what is happening with a service. And I found some info about services in the Wiki, but the pages are very incomplete and don't have very useful explanation of what a service is and how to incorporate it into the CMS.

Can you give me a better explanation of what a service is and how to create a custom service to be incorporated into the CMS?

Also if there is a better option for getting the desired use-case behavior please let me know. I want to do this is proper Amertys' way.

Thanks.

Last edited by mcdons (01/11/2013 17:03:15)

Cédric Damioli · 04/11/2013 12:28:50

Hi,

Indeed, what you call a "widget" is actually a "service" in the Ametys world.
A service is made of:
- A definition (in the plugin.xml), containing service parameters, a Java class, and a service URL
- A configuration panel for the contributor to define settings, which is by default automatically generated from the service parameters
- the Java class is responsible for parsing the XML definition and managing the service instance. You may use "org.ametys.web.service.StaticService"
- the URL is internally called when the Page is rendered. It should be matched by a Cocoon pipeline in the sitemap of the plugin containing the service.

The documentation is actually very poor about that. We're currently doing a major rewriting of the documentation, including service development, but it's a loooong task
In the meantime, please ask any question here or look at existing services in the web plugin.

mcdons · 08/11/2013 22:44:38

I noticed that the existing services distributed with Ametys are all located in the $CATALINA_HOME/webapps/cms/WEB-INF/lib folder as a pair of jar files, one with the service java classes, cocoon pipeline xmap file, plugin.xml file, etc.; the other with various resources, images, css files, js files, etc.

I have tried to create a proof of concept service following this template with no success. I followed the layout of the google maps plugin.

I created a plugin.xml file that I believe has the minimum requirements filled out:

<?xml version="1.0" encoding="UTF-8" ?>

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">
    
    <extension point="org.ametys.web.service.ServiceExtensionPoint"
        class="org.ametys.web.service.StaticService"
        id="org.ametys.plugins.spreadsheet.Spreadsheet">
 
        <url>service/spreadsheet/spreadsheet.xhtml</url>
 
        <label>PLUGINS_SPREADSHEET_SERVICE_LABEL</label>
        <description>PLUGINS_SPREADSHEET_SERVICE_DESCRIPTION</description>
 
    </extension>
    
</plugin>

I am unsure what to put into the id attribute of the extension tag and I am unsure what to put into the label and description tags. It looks like the existing services use place holders that get replaced somehow but I am not sure.

I also created a cocoon pipeline with a <map:match> who's pattern matches the url from the plugin.xml file. The pipeline is very simple for proof of concept purposes. It is the default file generator with src pointing to a xhtml file with some static html on it, and the cocoon xhtml serializer, I got the declaration from the Apache Cocoon website.

I packed up these files into a jar file and put them into the $CATALINA_HOME/webapps/cms/WEB-INF/lib folder. Then I restarted Ametys and, not too surprisingly the service didn't show up. I then restarted Tomcat and the service didn't show up. What am I missing?

Cédric Damioli · 09/11/2013 19:54:02

Hi,

The first thing is to ensure that your plugin is actually recognized and parsed. Ametys handle two packagings for plugins : bundled in jar files and located on the file system in the "plugins" directory.
For jar-bundled plugins, the system looks for special files located under the META-INF/folder in the jar itself.
If these files are not present, the plugin is not loaded.
To begin the development of a new plugin, I strongly suggest to begin to test it directly in the application, by putting it in the "plugins" directory of your web application. You should have examples in the downloaded package.

The structure should look like :

webapp-root
  |-- plugins
         |-- your-plugin
                |-- plugin.xml
                |-- sitemap.xmap

Once done, there's several ways to ensure a plugin is actually loaded by the system, either by looking at log files (loaded plugins are logged as INFO at starting-time), or by looking at the "plugins and workspaces" part in the administration application.
Once the plugin is actually loaded, your service should show up.

Label and description actually refer to i18n keys, replaced at runtime by their translated counterparts. For testing purposes, you could also put non-i18n messages with the following format :

        <label i18n="false">My label</label>
        <description i18n="false">My description</description>

mcdons · 11/11/2013 21:02:02

As per your suggestion I tried to load the service by putting it un-packed and flattened in the 'webapp-root/plugins' directory and it tried to load the service but I am getting an error that I can't parse through myself. It is finding my service, trying to load it but something is wrong with my plugin.xml file, specifically with my <extension> tag.

java.lang.RuntimeException: Unable to access to plugin at /var/lib/tomcat7/webapps/cms/plugins/spreadsheet-1.0/plugin.xml
... ... ...
Caused by: org.xml.sax.SAXParseException; systemId: file:///var/lib/tomcat7/webapps/cms/plugins/spreadsheet-1.0/plugin.xml; lineNumber: 10; columnNumber: 51; cvc-complex-type.2.4.a: Invalid content was found starting with element 'extension'. One of '{"http://www.ametys.org/schema/plugin":config, "http://www.ametys.org/schema/plugin":extension-points,
"http://www.ametys.org/schema/plugin":feature}' is expected.
... ... ...

This is my plugin.xml file:

<?xml version="1.0" encoding="UTF-8" ?>

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">
    
    <extensions>
        <extension point="org.ametys.web.service.ServiceExtensionPoint"
            class="org.ametys.web.service.StaticService"
            id="org.ametys.plugins.spreadsheet.Spreadsheet">
 
            <url>service/spreadsheet/spreadsheet.xhtml</url>
 
            <label i18n="false">Spreadsheet</label>
            <description i18n="false">Create Custom Spreadsheet</description>
 
        </extension>
    </extensions>
    
</plugin>

I didn't know what to put for the "id", "point", or "class" in the <extension> tag. I copied the "point" and "class" from the aforementioned google maps plugin, and for the "id" I copied the pattern used by the google maps plugin but replaced where applicable. I don't know what these attributes mean or what they point to.

Cédric Damioli · 12/11/2013 11:23:22

Indeed, your plugin.xml is syntactically wrong.

A plugin is made of "features", each feature may contains "extensions".

Your plugin should then look like :

<?xml version="1.0" encoding="UTF-8" ?>

<plugin xmlns="http://www.ametys.org/schema/plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.ametys.org/schema/plugin http://www.ametys.org/schema/plugin-2.0.xsd"
        runtimeVersion="2.0" version="2.0">

  <feature name="spreadsheet">
    <extensions>
        <extension point="org.ametys.web.service.ServiceExtensionPoint"
            class="org.ametys.web.service.StaticService"
            id="org.ametys.plugins.spreadsheet.Spreadsheet">
 
            <url>service/spreadsheet/spreadsheet.xhtml</url>
 
            <label i18n="false">Spreadsheet</label>
            <description i18n="false">Create Custom Spreadsheet</description>
 
        </extension>
    </extensions>
  </feature>
</plugin>

Concerning the attributes :

- an extension is always an extension to an "extension-point". There's several extension points in Ametys to help plugin writers to customize many parts of Ametys. The "point "attribute" refers to one of these points.
A plugin itself may create new extension points if needed.
The list of existing extension points and all available extensions to them is found in the Administration application, under the "Plugins & workspaces" section.

- the id is the identifier of your extension. it should be unique among other extensions to the same "extension-point". We use to have globally unique identifiers.

- the "class" attribute points to the actual Java class implementing the extension. In your case, "StaticService" is the most simple implementation of a Service, taking all its parameters in the XML conf of the plugin.

mcdons · 14/11/2013 00:19:56

I got the plugin.xml file up and running and the service showed up and is rendering the html file that I declared in my file generator in the xmap file. But I am having some issues with the routing of resource requests (js, css, img files) via my xmap file.

I have a reader defined and I am matching appropriate url's, as defined in the html file I am reading through, but I am getting a "No pipeline matched request: ..." error for my JS and CSS files.

If I am reading the error correctly, it is not looking in my defined sitemap.xmap file, but instead it is reading "resource://org/ametys/runtime/kernel/sitemap.xmap" this it would not finding the <map:match> with a matching pattern I defined in my xmap file.

Is there something I am missing here? It seems like the request isn't being completely handled by the cocoon pipeline I defined for my service.

Raphaël Franchet · 14/11/2013 11:16:37

Hi,

There are a succession of sitemap in Ametys.
First, the kernel sitemap your are pointing.
It handles, internal plugins url, kernel resources and PLUGIN RESOURCES.
Second, the workspace sitemap (such as _admin)
It handles what it wants, but generally handles plugins url
Third, the plugin sitemap
That handles what it wants.

So, plugins resources are handled by the kernel with the following urls:
/cms/plugins/MYPLUGIN/resources/**
which will look into the folder /webapps/cms/plugins/MYPLUGIN/resources

For your problem, I think there is no match between the url and the local files.
Can you give a url of a JS that does not works (404) and the path you put it on your hard drive.

(also note, that it has to be a correctly loaded plugin for all this work - with a correct plugin.xml : set the logs in "warning" to see if your plugin is NOT loaded)

mcdons · 14/11/2013 20:59:34

The layout of my widget is as follows:

$CATALINA_HOME
    |-- webapps
        |-- cms
            |-- spreadsheet-1.0
                |-- plugin.xml
                |-- sitemap.xmap
                |-- spreadsheet.html (html file who's resources are not loading)
                |-- resources
                    |-- scripts
                        |-- testJavaScript.js
                    |-- images
                        |-- testImage.jpg
                    |-- styles
                        |-- testCSS.css

The attempted JS scripts that have all failed are:

<script type="text/javascript" src="testJavaScript.js"></script>

<script type="text/javascript" src="scripts/testJavaScript.js"></script>

<script type="text/javascript" src="resources/scripts/testJavaScript.js"></script>

The image and css scripts follow the same pattern of failure. According to your last post I would think that the second one would work, "scripts/testJavaScript.js", but alas it does not.

As far as if it is a correctly loaded plugin or not, you can see my plugin.xml file above as corrected by Cédric Damioli. And the service is loaded, put in a page, and functioning. And I have found it in the cms/_admin app under the correct plugin extension-point. I don't know what you mean by "set the logs in "warning" to see if your plugin is NOT loaded" but I can't fine an error pointing to the loading of THIS plugin in the Ametys logs under the $CATALINA_HOME/webapps/cms/WEB-INF/logs/ directory.

There are a couple of errors for a failed plugin load but none of the url's mentioned or files pointed to are my plugin's files. And in fact when I remove my plugin and restart Ametys, the same errors are reported, thus none of them are pointing to my plugin.

Raphaël Franchet · 15/11/2013 10:32:56

In your path structure, I think you forgot the "plugins" directory, isn't it?

The loading should be like this

<script type="text/javascript" src="/cms/plugins/spreadsheet-1.0/resources/scripts/testJavaScript.js"></script>

You may use some xslt helpers to build this url.
See
(note, that you have to declared a namespace to do so, the instructions are here

Forum Ametys

#1 01/11/2013 00:22:02

Creation of Custom Widget (Service?)

#2 04/11/2013 12:28:50

Re: Creation of Custom Widget (Service?)

#3 08/11/2013 22:44:38

Re: Creation of Custom Widget (Service?)

#4 09/11/2013 19:54:02

Re: Creation of Custom Widget (Service?)

#5 11/11/2013 21:02:02

Re: Creation of Custom Widget (Service?)

#6 12/11/2013 11:23:22

Re: Creation of Custom Widget (Service?)

#7 14/11/2013 00:19:56

Re: Creation of Custom Widget (Service?)

#8 14/11/2013 11:16:37

Re: Creation of Custom Widget (Service?)

#9 14/11/2013 20:59:34

Re: Creation of Custom Widget (Service?)

#10 15/11/2013 10:32:56

Re: Creation of Custom Widget (Service?)

Board footer