= jsf-extension-points Wiki =
This project provides a simple way to add a plugin system to your Java Web Application. With it, you can define an Extension Point anywhere in a XHTML file and users can add regular XHTML files as extensions. It's especially handy for existing projects. There's no configuration required, it's not limited to a specific server (unlike OSGi/Spring based solutions), and you'll be ready to go in less than 5 minutes, including the time to understand how to use it.
== Getting started
Just add the jar to your project as a library, or declare a Maven dependency. There is no further configuration required. It's available from the maven repository:
you can add it to your dependencies, e.g. the 1.0-SNAPSHOT, which is the only version at the time of writing:
You can download the jar there as well, e.g. the 1.0-SNAPSHOT:
== Adding Extension Points
Add this namespace definition xmlns:ep="http://www.eppleton.de/ns/facelettags" to your XHTML files, and define an extensionpoint by adding a tag anywhere you like:
<pre name="xml"><ep:extensionpoint src="path/for/extensions" class="optional.class.for.Validation"></pre>
The "class" Attribute is optional. The plugin uses it to validate the extensions. As an example, if your Extension Point is inside a [http://www.primefaces.org/showcase/ui/menubar.jsf Primefaces Menubar], you only want users to add Submenus. So you would add class="org.primefaces.component.submenu.Submenu" as an Attribute, and the fragment will only be added to the page, if it defines a Submenu.
== Creating Extensions
Plugins can then be created as simple JAR files. No additional dependencies required. Not on the project you're extending, not even on jsf-extension-points. The simplest way is to use the Maven archetype provided as a subproject of this. If you want to do it manually, so you understand every tiny detail, here you go:
You just need to add a META-INF/faces-config.xml to make sure your Facelets and Managed Beans can be found. Registration of plugins is done via a configuration file.
The config file itself is registered in the JAR Manifest file. In a Maven project you can do it by adding this to your pom:
In case you are not using maven, you need to tell your build system to add the key to the manifest (OpenIDE-Module-Layer=path/to/ep-config.xml...). The config file is very simple. It consists of folder and file elements and each of them can have attributes. Here's an example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.2//EN" "http://www.netbeans.org/dtds/filesystem-1_2.dtd">
<folder name="CMS" >
<attr name="src" stringvalue="/fragment3.xhtml"/>
The example above registers a XHTML page for an ExtensionPoint <pre name="xml"><ep:extensionpoint src="MenuBar/CMS"/></pre>As a result /fragment3.xhtml will be inserted at the location of the extensionpoint tag. fragment3.html should sit in the META-INF/resources of your JAR, so it can be found by the RescourceResolver.
One important thing to note is, that if you want to add a configuration file to your Webapplication which is deployed as a WAR, the config file must be in META-INF and must be called layer.xml. This is due to the fact that loading the manifest is a bit different. That's also why for the WAR, there's no need to add anything to the manifest. If you want it more consistent in the next version, file an Issue.
== How you can Help
Use it, [http://java.net/jira/browse/JSF_EXTENSION_POINTS report bugs, and ask for features], and send me ideas for a nice name and icon for the project!