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
- 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.
- 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.
- 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
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>
Contributing Using Nuxeo CLI
Contributing to an extension using Nuxeo CLI requires more steps than using Nuxeo Studio.
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.xmlinto 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.
- In Nuxeo, we follow this naming convention
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
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
Nuxeo-Componententry already exists with another component declaration, separate them by commas.
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>