HOWTO: Contribute to an Extension

Watch the related courses on Hyland University: Course on Handling Service Extension Points

Finding the Extension Point Where to Contribute

Whatever the tools you're using (Nuxeo Studio or Nuxeo CLI), your first step is to find the open door configuration where you want to contribute. We call these open doors Extension points. Nuxeo lists all extension points for a given version in the Nuxeo Explorer.

Click on Extension points.
Filter what you want using the combobox.
Click on the extension point you're interested in. The documentation of this extension point is displayed.
Then, if you click on any link in the Contributions section, you will see all the default contributions implemented into your Nuxeo instance. There are hundreds of configuration possibilities.

Contributing Using Nuxeo Studio

In the Advanced Settings > XML extensions, click on the New button.
Give the extension a name and click on the Next button.
Type the content of your extension directly in the area. The editor helps you: start typing < and it will suggest possible values. While you are typing, some suggestion happens sometimes when typing on space, and you can always call the suggester using the key CTRL+space.
Click on Save.

Notes

Pay attention to always start with an <extension> element, or a <require> element followed by an <extension> element. There is a minimal check done so as to avoid you contribute non correct XML. The <require> mechanism can be used to make sure you deploy after another contribution that is deployed by some built-in plugins for instance. You need to reference the component name in the require content.

You can contribute several extension points in the same XML Extensions feature. This is useful to group extensions that are contributed for the same high level functional goal. Thus, you can have:

<extension point ="" target =""> ...</extension>

<require> component name</require>
<extension point ="" target =""> ...</extension>

<extension point ="" target =""> ...</extension>
<extension  point ="..." target="...">...</extension>

<require> component name</require>
<require> component name bis</require>
<extension  point ="..." target="...">...</extension>

etc.

Contributing Using Nuxeo CLI

Contributing to an extension using Nuxeo CLI requires more steps than using Nuxeo Studio.

Here we assume that you have installed Nuxeo CLI and follow the page Develop with Nuxeo Platform to understand the basics.

Creating Your XML Extension in Nuxeo CLI

Once you have found the extension point you want to contribute to:

Create a file myproject-servicewhereIcontribute-contribution.xml into the directory src/main/resources/OSGI-INF/ of your project.
Declare an empty component into this file, like that:
```
 <?xml version="1.0"?>
 <component name="org.mycompany.myproject.extension.point.where.we.contribute.contribution" version="1.0">

 </component>
```
Naming your component
In Nuxeo, we follow this naming convention org.mycompany.myproject.extension.point.where.we.contribute.contribution.
You can follow your way but be careful to avoid conflicts.
You must give a unique name for your component. If the name of your package is not unique it will not be deployed.

Add your contribution that express the configuration you want in the component XML fragment. You get something like:

 <?xml version="1.0"?>
 <component name="org.mycompany.myproject.extension.point.where.we.contribute.contribution" version="1.0">

   <!-- target and point value is given by the extension point definition -->
   <extension target="name.of.the.component.where.the.service.isdeclared" point="pointNameIntoThisComponent">
     <!-- here you put your configuration XML fragment
       ...
     <-->
     </extension>
 </component>

Declaring Your Contribution into Your Bundle

In the previous section you have created your configuration. You must now declare your component in your bundle so it's deployed in your Nuxeo Server. This declaration is made through the src/main/resources/META-INF/MANIFEST.MF file.

Create a new parameter, if it does not exist.

 Manifest-Version: 1.0
 Bundle-Vendor: Nuxeo
 Bundle-ActivationPolicy: lazy
 Bundle-ClassPath: .
 Bundle-Version: 5.5
 Bundle-Name: jalon-dm-bundle
 Nuxeo-Component: OSGI-INF/extensions/me.jalon.dm.bundle.importer.FileSystemFetcher.xml,
  OSGI-INF/extensions/com.mycomapny.test.FillIDDocument.xml,
  OSGI-INF/extensions/com.mycomapny.test.asda.xml
 Bundle-ManifestVersion: 2
 Bundle-SymbolicName: jalon-dm-bundle
 Bundle-RequiredExecutionEnvironment: JavaSE-1.6

 Manifest-Version: 1.0
 ... all the existing element already set ...
 Nuxeo-Component: OSGI-INF/myproject-servicewhereIcontribute-contribution.xml

If the Nuxeo-Component entry already exists with another component declaration, separate them by commas.

Formatting

The trickiest and most important part of a MANIFEST.MF file is its formatting. One mistake and the OSGi context can't be correctly started, leading to unexpected issues and an unreachable bundle. Here are the three formatting rules to respect:

Each property name:
- begins at the first character of the line;
- ends with a colon without space between the name of the property and the colon itself.
Each value:
- must be preceded by a space;
- ends with a "end of line" with eventually a comma before it.
There MUST be an EMPTY LINE at the END OF THE FILE.

Overriding the Nuxeo Default Configuration

Most of the time you will want to override an existing Nuxeo Component. Each extension point has its own logic (even if most of the time you will just have to contribute the same item with the same name). So look into the extension point definition to see how to override an existing configuration.

Components deployment is linear, so if you want to override an existing configuration, it must be deployed AFTER the existing component.

Follow the steps for your preferred tool (see above) combined the specific steps below.

Identify this component: using Nuxeo Explorer, go to the extension point definition (see the first section ).
Click on the contribution you want to override.
Copy the name of the component (value after In component).

Paste it in your component into a <require> item. You will have something like that:

 <?xml version="1.0"?>
 <component name="org.mycompany.myproject.extension.point.where.we.contribute.contribution" version="1.0">
   <require>name.of.the.component.you.want.to.override</require>

   <!-- target and point value is given by the extension point definition -->
   <extension target="name.of.the.component.where.the.service.isdeclared" point="pointNameIntoThisComponent">
     <!-- here you put your configuration XML fragment
       ...
     <-->
   </extension>
 </component>