Documenting components (or compositions)
Am am rewriting a big site and have divided my xhtml-pages into different compositions and components to make them general and usable by all sorts of pages. I have added theese component xhtml-files in a taglib to easily use them where I want. The components themselves often uses some kind of backing bean or object to do it's job correctly.
For example I have created a tooltipImage-component that displays a image and when you put your mouse over it, a larger copy of the image is displayed in a tooltip floating above it. I easily use the component I have created by entering the following in a xhtml-page:
<mylib:tooltipImage image="#{myAction.currentImage}" />The mylib.taglib.xml looks something like this:
... <tag> <tag-name>tooltipImage</tag-name> <source>/components/tooltipImage.xhtml</source> </tag> ...
In my tooltipImage.xhtml-file I use something like the following (not exactly like this, but you get the point):
<img src="#{image.imageUrl}" />My tooltipImage.xhtml works like a metod that takes one parameter (in this case as the image-attribute on the tooltipImage-tag). In other components I have created, I can pass variables (and even methods) that are either required or optional.
Because of my growing number of components with different variables needed to be set, it is getting difficult to keep track and remember what kind of parameters required to be passed on to a component.
Now to my question. Is there a standard way of documenting facelet components/compositions? As I said before, many of my xhtml-component files works like methods, so is there possibly some kind of JavaDoc (or similar)-standard on how to specify what variables a component need to have set to work properly?
I have started to create a comment-block at the beginning of each component (before the <ui:composition> or <ui:component>-tags) where I use a kind of JavaDoc-ish style of documenting what the component does and what input it needs. Something like this that is:
<html xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:rich="http://richfaces.org/rich"> <!-- Displays a image with a larger copy of it as a tooltip Input parameters are: image (required) - The image to fetch the URL from width (optional) - The width of the image to display height (optional) - The height of the image to display --> <ui:composition> ...
Is there anyone out there that has had the same problem? Is there any standard way of documenting facelet components/compositions?