Runtime and Component Model

How to Contribute to an Extension

Updated: October 16, 2020

 

Finding the Extension Point Where to Contribute

Whatever the tools you're using (Nuxeo Studio or Nuxeo IDE), 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.

  1. Click on the Explore button of the given version you work with.
  2. In the Browse by category panel, click on Bundle groups > Components > Extension points.
  3. In the Extension Point column, click on the extension point you're interested in. The documentation of this extension point is displayed.
  4. 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

  1. In the Advanced Settings > XML extensions, click on the New button.
  2. Give the extension a name and click on the Next button.
  3. 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.
  4. 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 plug-ins 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>
    

    or

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

    or

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

    or

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

    etc.

Contributing Using Nuxeo IDE

Contributing to an extension using Nuxeo requires more steps that using Nuxeo Studio.

Here we assume you that you have installed Nuxeo IDE and follow the Getting started with Nuxeo IDE.

Creating Your XML Extension in Nuxeo IDE

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

  1. Create a file myproject-servicewhereIcontribute-contribution.xml into the directory src/main/resources/OSGI-INF/ of your project.
  2. Declare an empty component into this file, like that:

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

    Naming your component

    • In Nuxeo, we follow this naming way org.mycompany.myproject.extention.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.
  3. 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.extention.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.

  1. 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.FileS
    &nbsp;ystemFetcher.xml,OSGI-INF/extensions/com.mycomapny.test.FillIDDocumen
    &nbsp;t.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
    
    
  2. If the Nuxeo-Component already exists with another component declaration, separate them by commas.

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.

  1. Identify this component: using Nuxeo Explorer, go to the extension point definition (see the first section).
  2. Click on the contribution you want to override.
  3. Copy the name of the component (value after In component).
  4. Paste it in your component into a <require> item. You will have something like that:

    <?xml version="1.0"?>
    <component name="org.mycompany.myproject.extention.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>