Enonic plugin archetype

Posted by

IntelliJ Enonic plugin archetype example
Generate new Enonic plugin project from maven archetype

Many participants of developer 3 courses have said that the most difficult part of creating Enonic plugins is the configuration of beans and the project itself. This is no longer true. UPDATED: 4. september.2014

To make it easier to get started with building a new Enonic plugin, I have created what is called a maven archetype. This is a template containing project configuration and example implementations of all extension types *1. After installing this archetype, you will be able to create a new maven Enonic Plugin project in your IDE from scratch in 5 seconds, by using the 'Create from archetype' option.

You may find the project at GitHub here: https://github.com/enonic/maven-cms-archetype. You may install this archetype by checking out this project and run mvn install, but also you may install the archetype directly from http://repo.enonic.com/public/com/enonic/cms/tools/maven-cms-archetype/4.7.6

One way to do this is to add the following dependency to any maven project to force it to be downloaded in your local .m2/repository.

<dependency>
   <groupId>com.enonic.cms.tools</groupId>
   <artifactId>maven-cms-archetype</artifactId>
   <version>4.7.6</version>
</dependency>

Afterwards you will probably need to update/refresh your local maven repository inside your IDE preferences/settings for the maven-cms-archetype to be visible. 

Then it is ready for you to create a new plugin in your IDE. In IntelliJ select 'new module' and create from archetype com.enonic.cms.tools:maven-cms-archetype->maven-cms-archetype:4.7.6. Click next and fill inn groupId (NOTE! Use com.enonic.plugin as package for now, a fix will be released soon which allow any groupId), artifactId and version of your new plugin. Next, next, finish - and you are ready to start implementing your plugin. Simply work from the example implementation that you want, and delete the other ones. 
 
Your plugin config

As you may see inside the generated project (image below), this example project uses a standard maven structure, and with the necessary plugin configuration files in resources/META-INF in place. The context.xml is set up to use <context:annotation-config/> and <context:component-scan base-package="com.enonic.plugin"/>. This will pick up any extensions in the project groupId package structure (f.x. com.enonic.plugin) that are annotated with @Component annotation. All this annotation magic is <provided> by the spring-context 3.1.3.RELEASE dependency in pom.xml. The scope of spring-context and slf4j dependencies are provided because they are already included in Enonic CMS, and you may see which version is used in cms-ce's pom.xml for any version of the CMS, her for example is pom.xml for cms-ce version 4.7.6.

Enonic plugin project structure

If you prefer, you may instead configure extensions by using xml bean definitions and bean references with spring injection in context.xml, but these extensions should then NOT use @Component annotation as in the examples, or else they will be registered twice and most probably the plugin will not be picked up by Enonic CMS. See more details about spring injection in Enonic documentation.

There are examples with @Autowired PluginConfig, PluginEnvironment and Client in most implementations. Most implementations also have examples using the provided logging framework slf4j and also one example outputting pretty formatted xml with XmlOutputter with prettyFormat in FunctionLibraryImpl. Very handy when developing and debugging plugins with org.jdom.Document and org.jdom.Element.

To work more efficiently, change the <cms.home>${project.build.directory}</cms.home> in pom.xml properties to your web-servers ${cms.home} folder, and when running mvn clean install your plugin will be automatically deployed and reloaded within 2 seconds - with default value of cms.plugin.scanPeriod in your cms.properties. In IntelliJ, use View->Tool windows->Maven projects to build your project quick and simple, just press the green play button to deploy.

maven projects window

 

The tagging of the maven project will follow Enonic CMS versions, and will be updated when plugin related changes occur. The first version is created for version 4.7.6 of Enonic, but there are usually not many changes between minor versions of the CMS.

I hope this will make it easier to get started with your new Enonic plugin. 

*1 All available Enonic plugin extensions:

 

 

Comments