You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by lu...@apache.org on 2009/03/26 04:42:49 UTC
svn commit: r758509 [1/2] - in
/myfaces/myfaces-build-tools/trunk/maven2-plugins:
myfaces-builder-annotations/
myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/
myfaces-builder-plugin/ myfaces-bui...
Author: lu4242
Date: Thu Mar 26 03:42:44 2009
New Revision: 758509
URL: http://svn.apache.org/viewvc?rev=758509&view=rev
Log:
MYFACES-2168 Add documentation for myfaces-builder-plugin and MYFACES-2169 force parameter does not work on make-components, make-tags, make-converter-tags and make-validator-tags goals of myfaces-builder-plugin
Added:
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/attributes.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/components.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/config-files.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/converters.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/doclets-annotations.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/properties.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/setup.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/tags.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/templates.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/validators.apt
Modified:
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/pom.xml
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspProperty.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspTag.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/pom.xml
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/BuildMetaDataMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeComponentsMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConfigMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConverterTagsMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeTagsMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorTagsMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorsMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/unpack/UnpackMojo.java
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/howto.apt
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/site.xml
myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-plugin-parent/src/site/site.xml
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/pom.xml
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/pom.xml?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/pom.xml (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/pom.xml Thu Mar 26 03:42:44 2009
@@ -27,7 +27,7 @@
<parent>
<groupId>org.apache.myfaces.buildtools</groupId>
<artifactId>myfaces-plugin-parent</artifactId>
- <version>1.0.2</version>
+ <version>1.0.3-SNAPSHOT</version>
</parent>
<groupId>org.apache.myfaces.buildtools</groupId>
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspProperty.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspProperty.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspProperty.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspProperty.java Thu Mar 26 03:42:44 2009
@@ -39,7 +39,7 @@
* has this annotation, will inherit the declared attributes.
* <p>
* This annotation should only be applied to classes that also have the JSFComponent
- * annotation.
+ * and JSFValidator annotation.
*
* @author Leonardo Uribe (latest modification by $Author$)
* @version $Revision$ $Date$
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspTag.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspTag.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspTag.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-annotations/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/annotation/JSFJspTag.java Thu Mar 26 03:42:44 2009
@@ -25,7 +25,8 @@
import java.lang.annotation.Target;
/**
- * The name of the component in a page (ex: x:mycomp).
+ * Used to define a jsf tag that does not fall in a category like converter, validator
+ * or component. Examples are f:verbatim or f:actionListener
*
* @author Leonardo Uribe (latest modification by $Author$)
* @version $Revision$ $Date$
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/pom.xml
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/pom.xml?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/pom.xml (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/pom.xml Thu Mar 26 03:42:44 2009
@@ -27,7 +27,7 @@
<parent>
<groupId>org.apache.myfaces.buildtools</groupId>
<artifactId>myfaces-plugin-parent</artifactId>
- <version>1.0.2</version>
+ <version>1.0.3-SNAPSHOT</version>
</parent>
<groupId>org.apache.myfaces.buildtools</groupId>
@@ -73,6 +73,9 @@
<artifactId>maven-plugin-plugin</artifactId>
<version>2.2</version>
</plugin>
+ <plugin>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ </plugin>
</plugins>
</reporting>
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/BuildMetaDataMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/BuildMetaDataMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/BuildMetaDataMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/BuildMetaDataMojo.java Thu Mar 26 03:42:44 2009
@@ -46,7 +46,7 @@
* that metadata file embedded in the generated jarfile is useful for two
* purposes:
* <ul>
- * <li>It is needed if other projects then use the maven-builder-plugin to
+ * <li>It is needed if other projects then use the myfaces-builder-plugin to
* create subclasses of the jsf classes in this project.</li>
* <li>It is good documentation (more precise than the tld and faces-config.xml
* files).</li>
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeComponentsMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeComponentsMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeComponentsMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeComponentsMojo.java Thu Mar 26 03:42:44 2009
@@ -56,6 +56,18 @@
/**
* Maven goal to generate java source code for Component classes.
*
+ * <p>It uses velocity to generate templates, and has the option to define custom templates.</p>
+ * <p>The executed template has the following variables available to it:</p>
+ * <ul>
+ * <li>utils : Returns an instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.utils.MyfacesUtils,
+ * it contains some useful methods.</li>
+ * <li>component : Returns the current instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.model.ComponentMeta</li>
+ * <li>innersource : code to be injected from the template class when template
+ * mode is used</li>
+ * </ul>
+ *
* @version $Id$
* @requiresDependencyResolution compile
* @goal make-components
@@ -74,6 +86,8 @@
private MavenProject project;
/**
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
*/
@@ -87,46 +101,85 @@
private String metadataFile = "META-INF/myfaces-metadata.xml";
/**
+ * The directory used to load templates into velocity environment.
+ *
* @parameter expression="src/main/resources/META-INF"
*/
private File templateSourceDirectory;
/**
+ * The directory where all generated files are created. This directory is added as a
+ * compile source root automatically like src/main/java is.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/java"
*/
private File generatedSourceDirectory;
/**
+ * Generate only component classes that starts with the specified package prefix.
+ *
* @parameter
*/
private String packageContains;
/**
+ * Generate only component classes that starts with the specified component type prefix.
+ *
* @parameter
*/
private String typePrefix;
/**
+ * Log and continue execution when generating component classes.
+ * <p>
+ * If this property is set to false (default), errors when a component class is generated stops
+ * execution immediately.
+ * </p>
+ *
* @parameter
*/
private boolean force;
/**
- * @parameter
- */
- private boolean suppressListenerMethods;
-
- /**
+ * Defines the jsf version (1.1 or 1.2), used to take the default templates for each version.
+ * <p>
+ * If version is 1.1, the default templateComponentName is 'componentClass11.vm' and if version
+ * is 1.2 the default templateComponentName is 'componentClass12.vm'.
+ * </p>
+ *
* @parameter
*/
private String jsfVersion;
/**
+ * Define the models that should be included when generate component classes. If not set, the
+ * current model identified by the artifactId is used.
+ * <p>
+ * Each model built by build-metadata goal has a modelId, that by default is the artifactId of
+ * the project. Setting this property defines which objects tied in a specified modelId should
+ * be taken into account.
+ * </p>
+ * <p>In this case, limit component generation only to the components defined in the models
+ * identified by the modelId defined. </p>
+ * <p>This is useful when you need to generate files that take information defined on other
+ * projects</p>
+ * <p>Example:</p>
+ * <pre>
+ * <modelIds>
+ * <modelId>model1</modelId>
+ * <modelId>model2</modelId>
+ * </modelIds>
+ * </pre>
+ *
* @parameter
*/
private List modelIds;
/**
+ * The name of the template used to generate component classes. According to the value on
+ * jsfVersion property the default if this property is not set could be componentClass11.vm (1.1) or
+ * componentClass12.vm (1.2)
+ *
* @parameter
*/
private String templateComponentName;
@@ -275,7 +328,23 @@
}
}
log.info("Generating component class:"+component.getClassName());
- _generateComponent(velocityEngine, builder,component,baseContext);
+
+ try
+ {
+ _generateComponent(velocityEngine, builder,component,baseContext);
+ }
+ catch(MojoExecutionException e)
+ {
+ if (force)
+ {
+ log.severe(e.getMessage());
+ }
+ else
+ {
+ //Stop execution throwing exception
+ throw e;
+ }
+ }
}
}
}
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConfigMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConfigMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConfigMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConfigMojo.java Thu Mar 26 03:42:44 2009
@@ -94,9 +94,8 @@
private MavenProject project;
/**
- * The current maven project (auto-injected by Maven).
- *
- * TODO: this default value looks wrong. What should really be here?
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded,
+ * and the generated file named by xmlFile parameter is created.
*
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConverterTagsMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConverterTagsMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConverterTagsMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeConverterTagsMojo.java Thu Mar 26 03:42:44 2009
@@ -47,6 +47,16 @@
/**
* Maven goal to generate java source code for Component tag classes.
*
+ * <p>It uses velocity to generate templates, and has the option to define custom templates.</p>
+ * <p>The executed template has the following variables available to it:</p>
+ * <ul>
+ * <li>utils : Returns an instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.utils.MyfacesUtils,
+ * it contains some useful methods.</li>
+ * <li>converter : Returns the current instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.model.ConverterMeta</li>
+ * </ul>
+ *
* @version $Id$
* @requiresDependencyResolution compile
* @goal make-converter-tags
@@ -65,6 +75,8 @@
private MavenProject project;
/**
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
*/
@@ -78,6 +90,8 @@
private String metadataFile = "META-INF/myfaces-metadata.xml";
/**
+ * The directory used to load templates into velocity environment.
+ *
* @parameter expression="src/main/resources/META-INF"
*/
private File templateSourceDirectory;
@@ -99,11 +113,18 @@
private File mainSourceDirectory2;
/**
+ * The name of the template used to generate converter tag classes. According to the value on
+ * jsfVersion property the default if this property is not set could be tagConverterClass11.vm (1.1) or
+ * tagConverterClass12.vm (1.2)
+ *
* @parameter
*/
private String templateTagName;
/**
+ * The directory where all generated files are created. This directory is added as a
+ * compile source root automatically like src/main/java is.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/java"
* @required
*/
@@ -124,21 +145,47 @@
private String typePrefix;
/**
+ * Log and continue execution when generating converter tag classes.
+ * <p>
+ * If this property is set to false (default), errors when a converter tag class is generated stops
+ * execution immediately.
+ * </p>
+ *
* @parameter
*/
private boolean force;
/**
- * @parameter
- */
- private boolean suppressListenerMethods;
-
- /**
+ * Defines the jsf version (1.1 or 1.2), used to take the default templates for each version.
+ * <p>
+ * If version is 1.1, the default templateTagName is 'tagConverterClass11.vm' and if version
+ * is 1.2 the default templateTagName is 'tagConverterClass12.vm'.
+ * </p>
+ *
* @parameter
*/
private String jsfVersion;
/**
+ * Define the models that should be included when generate converter tag classes. If not set, the
+ * current model identified by the artifactId is used.
+ * <p>
+ * Each model built by build-metadata goal has a modelId, that by default is the artifactId of
+ * the project. Setting this property defines which objects tied in a specified modelId should
+ * be taken into account.
+ * </p>
+ * <p>In this case, limit converter tag generation only to the components defined in the models
+ * identified by the modelId defined. </p>
+ * <p>This is useful when you need to generate files that take information defined on other
+ * projects.</p>
+ * <p>Example:</p>
+ * <pre>
+ * <modelIds>
+ * <modelId>model1</modelId>
+ * <modelId>model2</modelId>
+ * </modelIds>
+ * </pre>
+ *
* @parameter
*/
private List modelIds;
@@ -251,7 +298,22 @@
}
}
log.info("Generating tag class:"+converter.getTagClass());
- _generateConverter(velocityEngine, converter,baseContext);
+ try
+ {
+ _generateConverter(velocityEngine, converter,baseContext);
+ }
+ catch(MojoExecutionException e)
+ {
+ if (force)
+ {
+ log.severe(e.getMessage());
+ }
+ else
+ {
+ //Stop execution throwing exception
+ throw e;
+ }
+ }
}
}
}
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeTagsMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeTagsMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeTagsMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeTagsMojo.java Thu Mar 26 03:42:44 2009
@@ -47,6 +47,16 @@
/**
* Maven goal to generate java source code for Component tag classes.
*
+ * <p>It uses velocity to generate templates, and has the option to define custom templates.</p>
+ * <p>The executed template has the following variables available to it:</p>
+ * <ul>
+ * <li>utils : Returns an instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.utils.MyfacesUtils,
+ * it contains some useful methods.</li>
+ * <li>component : Returns the current instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.model.ComponentMeta</li>
+ * </ul>
+ *
* @version $Id$
* @requiresDependencyResolution compile
* @goal make-tags
@@ -65,6 +75,8 @@
private MavenProject project;
/**
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
*/
@@ -78,6 +90,8 @@
private String metadataFile = "META-INF/myfaces-metadata.xml";
/**
+ * The directory used to load templates into velocity environment.
+ *
* @parameter expression="src/main/resources/META-INF"
*/
private File templateSourceDirectory;
@@ -99,11 +113,18 @@
private File mainSourceDirectory2;
/**
+ * The name of the template used to generate component tag classes. According to the value on
+ * jsfVersion property the default if this property is not set could be tagClass11.vm (1.1) or
+ * tagClass12.vm (1.2)
+ *
* @parameter
*/
private String templateTagName;
/**
+ * The directory where all generated files are created. This directory is added as a
+ * compile source root automatically like src/main/java is.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/java"
* @required
*/
@@ -124,21 +145,47 @@
private String typePrefix;
/**
+ * Log and continue execution when generating component tag classes.
+ * <p>
+ * If this property is set to false (default), errors when a component tag class is generated stops
+ * execution immediately.
+ * </p>
+ *
* @parameter
*/
private boolean force;
/**
- * @parameter
- */
- private boolean suppressListenerMethods;
-
- /**
+ * Defines the jsf version (1.1 or 1.2), used to take the default templates for each version.
+ * <p>
+ * If version is 1.1, the default templateTagName is 'tagClass11.vm' and if version
+ * is 1.2 the default templateTagName is 'tagClass12.vm'.
+ * </p>
+ *
* @parameter
*/
private String jsfVersion;
/**
+ * Define the models that should be included when generate component tag classes. If not set, the
+ * current model identified by the artifactId is used.
+ * <p>
+ * Each model built by build-metadata goal has a modelId, that by default is the artifactId of
+ * the project. Setting this property defines which objects tied in a specified modelId should
+ * be taken into account.
+ * </p>
+ * <p>In this case, limit component tag generation only to the components defined in the models
+ * identified by the modelId defined. </p>
+ * <p>This is useful when you need to generate files that take information defined on other
+ * projects.</p>
+ * <p>Example:</p>
+ * <pre>
+ * <modelIds>
+ * <modelId>model1</modelId>
+ * <modelId>model2</modelId>
+ * </modelIds>
+ * </pre>
+ *
* @parameter
*/
private List modelIds;
@@ -251,7 +298,22 @@
}
}
log.info("Generating tag class:"+component.getTagClass());
- _generateComponent(velocityEngine, component,baseContext);
+ try
+ {
+ _generateComponent(velocityEngine, component,baseContext);
+ }
+ catch(MojoExecutionException e)
+ {
+ if (force)
+ {
+ log.severe(e.getMessage());
+ }
+ else
+ {
+ //Stop execution throwing exception
+ throw e;
+ }
+ }
}
}
}
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorTagsMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorTagsMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorTagsMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorTagsMojo.java Thu Mar 26 03:42:44 2009
@@ -47,6 +47,16 @@
/**
* Maven goal to generate java source code for Component tag classes.
*
+ * <p>It uses velocity to generate templates, and has the option to define custom templates.</p>
+ * <p>The executed template has the following variables available to it:</p>
+ * <ul>
+ * <li>utils : Returns an instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.utils.MyfacesUtils,
+ * it contains some useful methods.</li>
+ * <li>validator : Returns the current instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.model.ValidatorMeta</li>
+ * </ul>
+ *
* @version $Id$
* @requiresDependencyResolution compile
* @goal make-validator-tags
@@ -65,6 +75,8 @@
private MavenProject project;
/**
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
*/
@@ -78,6 +90,8 @@
private String metadataFile = "META-INF/myfaces-metadata.xml";
/**
+ * The directory used to load templates into velocity environment.
+ *
* @parameter expression="src/main/resources/META-INF"
*/
private File templateSourceDirectory;
@@ -99,11 +113,18 @@
private File mainSourceDirectory2;
/**
+ * The name of the template used to generate validator tag classes. According to the value on
+ * jsfVersion property the default if this property is not set could be tagValidatorClass11.vm (1.1) or
+ * tagValidatorClass12.vm (1.2)
+ *
* @parameter
*/
private String templateTagName;
/**
+ * The directory where all generated files are created. This directory is added as a
+ * compile source root automatically like src/main/java is.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/java"
* @required
*/
@@ -124,21 +145,47 @@
private String typePrefix;
/**
+ * Log and continue execution when generating validator tag classes.
+ * <p>
+ * If this property is set to false (default), errors when a validator tag class is generated stops
+ * execution immediately.
+ * </p>
+ *
* @parameter
*/
private boolean force;
/**
- * @parameter
- */
- private boolean suppressListenerMethods;
-
- /**
+ * Defines the jsf version (1.1 or 1.2), used to take the default templates for each version.
+ * <p>
+ * If version is 1.1, the default templateTagName is 'tagValidatorClass11.vm' and if version
+ * is 1.2 the default templateTagName is 'tagValidatorClass12.vm'.
+ * </p>
+ *
* @parameter
*/
private String jsfVersion;
/**
+ * Define the models that should be included when generate validator tag classes. If not set, the
+ * current model identified by the artifactId is used.
+ * <p>
+ * Each model built by build-metadata goal has a modelId, that by default is the artifactId of
+ * the project. Setting this property defines which objects tied in a specified modelId should
+ * be taken into account.
+ * </p>
+ * <p>In this case, limit converter tag generation only to the components defined in the models
+ * identified by the modelId defined. </p>
+ * <p>This is useful when you need to generate files that take information defined on other
+ * projects.</p>
+ * <p>Example:</p>
+ * <pre>
+ * <modelIds>
+ * <modelId>model1</modelId>
+ * <modelId>model2</modelId>
+ * </modelIds>
+ * </pre>
+ *
* @parameter
*/
private List modelIds;
@@ -251,7 +298,22 @@
}
}
log.info("Generating tag class:"+validator.getTagClass());
- _generateValidator(velocityEngine, validator,baseContext);
+ try
+ {
+ _generateValidator(velocityEngine, validator,baseContext);
+ }
+ catch(MojoExecutionException e)
+ {
+ if (force)
+ {
+ log.severe(e.getMessage());
+ }
+ else
+ {
+ //Stop execution throwing exception
+ throw e;
+ }
+ }
}
}
}
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorsMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorsMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorsMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/MakeValidatorsMojo.java Thu Mar 26 03:42:44 2009
@@ -49,6 +49,16 @@
/**
* Maven goal to generate java source code for Validator classes.
*
+ * <p>It uses velocity to generate templates, and has the option to define custom templates.</p>
+ * <p>The executed template has the following variables available to it:</p>
+ * <ul>
+ * <li>utils : Returns an instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.utils.MyfacesUtils,
+ * it contains some useful methods.</li>
+ * <li>validator : Returns the current instance of
+ * org.apache.myfaces.buildtools.maven2.plugin.builder.model.ValidatorMeta</li>
+ * </ul>
+ *
* @version $Id$
* @requiresDependencyResolution compile
* @goal make-validators
@@ -67,6 +77,8 @@
private MavenProject project;
/**
+ * Defines the directory where the metadata file (META-INF/myfaces-metadata.xml) is loaded.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/resources"
* @readonly
*/
@@ -80,41 +92,78 @@
private String metadataFile = "META-INF/myfaces-metadata.xml";
/**
+ * The directory used to load templates into velocity environment.
+ *
* @parameter expression="src/main/resources/META-INF"
*/
private File templateSourceDirectory;
/**
+ * The directory where all generated files are created. This directory is added as a
+ * compile source root automatically like src/main/java is.
+ *
* @parameter expression="${project.build.directory}/myfaces-builder-plugin/main/java"
*/
private File generatedSourceDirectory;
/**
+ * Only generate tag classes that contains that package prefix
+ *
* @parameter
*/
private String packageContains;
/**
+ * Log and continue execution when generating validator classes.
+ * <p>
+ * If this property is set to false (default), errors when a validator class is generated stops
+ * execution immediately.
+ * </p>
+ *
* @parameter
*/
private boolean force;
/**
- * @parameter
- */
- private boolean suppressListenerMethods;
-
- /**
+ * Defines the jsf version (1.1 or 1.2), used to take the default templates for each version.
+ * <p>
+ * If version is 1.1, the default templateValidatorName is 'validatorClass11.vm' and if version
+ * is 1.2 the default templateValidatorName is 'validatorClass12.vm'.
+ * </p>
+ *
* @parameter
*/
private String jsfVersion;
/**
+ * Define the models that should be included when generate validator classes. If not set, the
+ * current model identified by the artifactId is used.
+ * <p>
+ * Each model built by build-metadata goal has a modelId, that by default is the artifactId of
+ * the project. Setting this property defines which objects tied in a specified modelId should
+ * be taken into account.
+ * </p>
+ * <p>In this case, limit converter tag generation only to the components defined in the models
+ * identified by the modelId defined. </p>
+ * <p>This is useful when you need to generate files that take information defined on other
+ * projects.</p>
+ * <p>Example:</p>
+ * <pre>
+ * <modelIds>
+ * <modelId>model1</modelId>
+ * <modelId>model2</modelId>
+ * </modelIds>
+ * </pre>
+ *
* @parameter
*/
private List modelIds;
/**
+ * The name of the template used to generate validator classes. According to the value on
+ * jsfVersion property the default if this property is not set could be validatorClass11.vm (1.1) or
+ * validatorClass12.vm (1.2)
+ *
* @parameter
*/
private String templateValidatorName;
@@ -263,7 +312,22 @@
}
}
log.info("Generating validator class:"+validator.getClassName());
- _generateValidator(velocityEngine, builder,validator,baseContext);
+ try
+ {
+ _generateValidator(velocityEngine, builder,validator,baseContext);
+ }
+ catch(MojoExecutionException e)
+ {
+ if (force)
+ {
+ log.severe(e.getMessage());
+ }
+ else
+ {
+ //Stop execution throwing exception
+ throw e;
+ }
+ }
}
}
}
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/unpack/UnpackMojo.java
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/unpack/UnpackMojo.java?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/unpack/UnpackMojo.java (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/main/java/org/apache/myfaces/buildtools/maven2/plugin/builder/unpack/UnpackMojo.java Thu Mar 26 03:42:44 2009
@@ -40,47 +40,26 @@
/**
* Goal that retrieves a list of artifacts from the repository and unpacks them
* in a defined location.
- *
+ * <p>
* This mojo reutilize org.apache.maven.plugin.dependency.fromConfiguration.UnpackMojo
* from maven-dependency-plugin.
- *
+ * </p>
+ * <p>
* The idea of this plugin, instead just unpack a list of artifacts is add some new
* features necessary to make easier maintain 1.1 and 1.2 code on myfaces projects like
* tomahawk.
- *
+ * </p>
+ * <p>
* This plugin works as unpack goal of maven-dependency-plugin with 2 additional
* enhancements:
- *
- * 1. If some file exists on the base directories, it is added as excluded, so it is
- * not copied to the output directory. This makes easier to manage the code and maintain it.
- * 2. If a file is generated from the model (reading the myfaces-metadata.xml) it is not
- * copied, since this should be generated again.
- *
- *
-<execution>
-<id>unpack-tomahawk</id>
-<phase>process-resources</phase>
-<goals>
- <goal>unpack</goal>
-</goals>
-<configuration>
- <artifactItems>
- <artifactItem>
- <groupId>org.apache.myfaces.tomahawk</groupId>
- <artifactId>tomahawk</artifactId>
- <version>1.1.7-SNAPSHOT</version>
- <!--
- <groupId>org.apache.myfaces.core</groupId>
- <artifactId>myfaces-api</artifactId>
- <version>1.1.6-SNAPSHOT</version>
- -->
- <classifier>sources</classifier>
- <outputDirectory>${basedir}/target/unpackmyfaces</outputDirectory>
- </artifactItem>
- </artifactItems>
-</configuration>
-</execution>
-
+ * </p>
+ * <ol>
+ * <li>If some file exists on the base directories, it is added as excluded, so it is
+ * not copied to the output directory. This makes easier to manage the code and maintain it.</li>
+ * <li>If a file is generated from the model (reading the myfaces-metadata.xml) it is not
+ * copied, since this should be generated again.</li>
+ * </ol>
+ *
* @since 1.0
* @goal unpack
* @phase process-sources
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/attributes.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/attributes.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/attributes.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/attributes.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,124 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Attributes
+ ------
+
+Attributes
+
+ Tags has attributes. Attribute behavior is different from a property,
+ so it is necessary to use a different annotation/doclet to use it.
+ Usually tags are written by users, but has few attributes and does not
+ have a complex hierarchy, so it is not necessary make tags inherit
+ attributes from other tags.
+
+ The objective of use @JSFJspTag and @JSFJspAttribute annotation/doclet is
+ make easier keep synchronized the .tld file with the tag class.
+
+* Attribute loaded from basic type
+
+ On jsf 1.1 and in some special cases, no ValueExpressions are allowed
+ on some attribute.
+
+-------------------
+ /**
+ * On tlds this is translated to something like:
+ *
+ * <attribute>
+ * <description><![CDATA[Some description]]></description>
+ * <name>var</name>
+ * <required>false</required>
+ * <rtexprvalue>false</rtexprvalue>
+ * <type>java.lang.String</type>
+ * </attribute>
+ *
+ */
+ @JSFJspAttribute
+ public void setVar(String var)
+ {
+ // .... some code ....
+ }
+-------------------
+
+* Attribute loaded from ValueExpression
+
+ There are two cases
+
+-------------------
+
+ /**
+ * On jsf 1.1 this translates to something like:
+ *
+ * Works on version 1.0.2, but some jsf 1.2 tld templates translate it to:
+ *
+ * <attribute>
+ * <description><![CDATA[The fully qualified class name of the ActionListener class.]]></description>
+ * <name>type</name>
+ * <required>false</required>
+ * <deferred-value>
+ * <type>java.lang.String</type>
+ * </deferred-value>
+ * </attribute>
+ *
+ * On version 1.0.3 this should be translated to something like:
+ *
+ * <attribute>
+ * <description><![CDATA[The fully qualified class name of the ActionListener class.]]></description>
+ * <name>type</name>
+ * <required>false</required>
+ * <rtexprvalue>true</rtexprvalue>
+ * </attribute>
+ *
+ * But this depends on the template used to generate its tld.
+ **/
+ @JSFJspAttribute(className = "java.lang.String", rtexprvalue = true)
+ public void setType(ValueExpression type)
+ {
+ // .... some code ....
+ }
+
+ /**
+ * Works on version 1.0.3 and upper for jsf 1.2 and upper tld templates:
+ *
+ * <attribute>
+ * <description><![CDATA[The fully qualified class name of the ActionListener class.]]></description>
+ * <name>type</name>
+ * <required>false</required>
+ * <deferred-value>
+ * <type>java.lang.String</type>
+ * </deferred-value>
+ * </attribute>
+ **/
+ @JSFJspAttribute(deferredValueType = "java.lang.String")
+ public void setType(ValueExpression type)
+ {
+ // .... some code ....
+ }
+
+
+-------------------
+
+* Attribute loaded from MethodExpression
+
+-------------------
+ /** works on version 1.0.3 and upper for jsf 1.2 and upper tld templates **/
+ @JSFJspAttribute(required=true,
+ deferredMethodSignature = "void myMethod(javax.faces.context.FacesContext, java.io.OutputStream)")
+ public void setMethod(MethodExpression method)
+ {
+ _method = method;
+ }
+-------------------
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/components.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/components.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/components.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/components.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,240 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Creating Custom Components
+ ------
+
+Creating Custom Components
+
+ Any JSF Component has the following elements:
+
+ * Component class file(s).
+
+ * JSP tag class file(s).
+
+ * Entry on faces-config.xml.
+
+ * Renderer class file(s) (optional).
+
+ * TLD file (optional).
+
+ * facelet-taglib entry (optional).
+
+ * Facelets tag handler files (optional).
+
+ Keep all those files up to date is a complex task, but with
+ myfaces-builder-plugin you just need to take care about:
+
+ * Component class file(s).
+
+ * Renderer class file(s) (optional).
+
+ * Facelets tag handler files (optional).
+
+ This example shows step by step what do you need to create a custom
+ component.
+
+Setting up your project
+
+ All information related can be found {{{setup.html}here}}.
+
+Configuration files (faces-config.xml, .tld, facelets taglib)
+
+ This {{{config-files.html}page}} shows some examples.
+
+Writing your component class
+
+ There are three possibilities for create a component class:
+
+ * Write just one file and add all code manually (Example: t:aliasBean).
+
+ * Write an abstract class, and let generate all property code, including
+ saveState/restoreState methods in a concrete child class
+ (Example: almost all components in tomahawk core and sandbox).
+
+ * Write an abstract class (generally package scope) and use template
+ pattern. In other words, all property code is generated including
+ saveState/restoreState methods in a concrete child class, but other
+ code inside the abstract class is copied to the generated class.
+
+* Write a component class manually
+
+ In this mode, no code is generated, but the information is chained to
+ other files to be generated like faces-config.xml, tlds, tag classes, etc.
+
+ Below there is an example of it:
+
+-------------------
+/**
+ * The most important points are:
+ *
+ * 1. Define componentType, componentFamily and rendererType adding its
+ * constants (like below) or directly in the annotation.
+ *
+ * 2. If the component has a jsp tag, define the "name" and the "tagClass"
+ * If the tagClass does not exists a new file is generated if make-tags
+ * goal is set on pom.xml
+ *
+ */
+@JSFComponent(
+ name = "mycomponents:sayHello",
+ clazz = "org.myorganization.component.sayhello.SayHello",
+ tagClass = "org.myorganization.component.sayhello.SayHelloTag")
+public class SayHello extends UIOutput
+{
+ public static final String COMPONENT_TYPE = "org.myorganization.SayHello";
+ public static final String DEFAULT_RENDERER_TYPE = "org.myorganization.SayHelloRenderer";
+ public static final String COMPONENT_FAMILY = "javax.faces.Output";
+
+ /** ..... Some custom code goes here .... **/
+}
+-------------------
+
+* Write a component class using Abstract Pattern
+
+ The objective is create a abstract component class
+ that defines all information required to generate the concrete
+ component class. All custom code goes in the abstract class, so it
+ is inherited to the child component.
+
+ This pattern is preferred over template mode, because it is more simple
+ to understand, but there are some cases where this mode cannot be
+ applied (like in myfaces core api, where the component hierarchy cannot
+ be changed).
+
+ Below there is an example of it:
+
+-------------------
+/**
+ * To generate component classes using abstract pattern
+ *
+ * 1. Define the "clazz" file which it is generated
+ *
+ * 2. Define componentType, componentFamily and rendererType adding its
+ * constants (like below) or directly in the annotation.
+ *
+ * 3. If the component has a jsp tag, define the "name" and the "tagClass"
+ * If the tagClass does not exists a new file is generated if make-tags
+ * goal is set on pom.xml
+ *
+ */
+@JSFComponent(
+ name = "mycomponents:sayHello",
+ clazz = "org.myorganization.component.sayhello.SayHello",
+ tagClass = "org.myorganization.component.sayhello.SayHelloTag")
+public abstract class AbstractSayHello extends UIOutput
+{
+ public static final String COMPONENT_TYPE = "org.myorganization.SayHello";
+ public static final String DEFAULT_RENDERER_TYPE = "org.myorganization.SayHelloRenderer";
+ public static final String COMPONENT_FAMILY = "javax.faces.Output";
+
+ /**
+ * User's first name.
+ */
+ @JSFProperty
+ public abstract String getName();
+}
+-------------------
+
+* Write a component class using Template Pattern
+
+ The objective is create an abstract (generally package scoped) class
+ that works as a "template".
+
+-------------------
+@JSFComponent(
+ name = "mycomponents:sayHello",
+ clazz = "org.myorganization.component.sayhello.SayHello",
+ tagClass = "org.myorganization.component.sayhello.SayHelloTag")
+abstract class _SayHello extends UIOutput
+{
+ public static final String COMPONENT_TYPE = "org.myorganization.SayHello";
+ public static final String DEFAULT_RENDERER_TYPE = "org.myorganization.SayHelloRenderer";
+ public static final String COMPONENT_FAMILY = "javax.faces.Output";
+
+ /**
+ * This method is copied to generated SayHello class
+ **/
+ public void broadcast(javax.faces.event.FacesEvent event)
+ throws javax.faces.event.AbortProcessingException
+ {
+ //Some custom code goes here
+ }
+
+ /**
+ * This method is not copied, but @JSFExclude works with fields too!
+ **/
+ @JSFExclude
+ public void doSomething()
+ {
+ //Some never used custom code goes here
+ }
+
+ /**
+ * User's first name.
+ */
+ @JSFProperty
+ public abstract String getName();
+}
+-------------------
+
+Generating Component Tag Classes
+
+ The goal "make-tags" trigger component jsp tag generation. This goal
+ checks if the tag class exists and if not, it creates one.
+
+ Here there are two scenarios:
+
+ * The component class inherits from jsf core UIXXXXX, so the generated
+ class inherits from javax.faces.webapp.UIComponent(EL)Tag.
+
+ * The component class inherits from jsf core HtmlXXX. In this case,
+ the tag classes where your component inherits is on myfaces core
+ impl jar, so again there are three options:
+
+ * Add myfaces core impl jar as compile dependency and use myfaces
+ core in your web application.
+
+ * Add tomahawk core or core12 to your dependencies, where there
+ is an alternate tag hierarchy, so your components can work
+ with the reference implementation. Make sure tomahawk dependency.
+ should be before myfaces core dependency in the pom, to be sure
+ that tomahawk model is loaded first.
+
+ * Generate a jsf html tag hierarchy in your jar. See tomahawk core
+ or core12 pom for details.
+
+ If you need to write some custom code on tag class, but keep some
+ code generated, use abstract pattern on tag class. The properties that
+ needs to be defined on abstract tag class must have inheritedTag="true",
+ so there are not overriden. See t:tree component for an example.
+
+Adding a Renderer to faces-config.xml file.
+
+ The annotations/doclets @JSFRenderer and @JSFRenderKit are used include
+ renderer configuration to generated faces-config.xml files. Just add it
+ to your renderer like this:
+
+---------------------------
+@JSFRenderer(
+ renderKitId = "HTML_BASIC",
+ family = "javax.faces.Output",
+ type = "org.myorganization.SayHelloRenderer")
+public class SayHelloRenderer extends Renderer
+{
+ //Some code goes here
+}
+---------------------------
\ No newline at end of file
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/config-files.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/config-files.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/config-files.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/config-files.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,84 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Configuration files
+ ------
+
+Configuration files (faces-config.xml, .tld, facelets taglib)
+
+ All configuration files are generated by
+ {{{make-config-mojo.html}make-config}} goal.
+
+ This goal can be seen as an equation:
+
+-------------------------
+ xmlBaseFile + templateFile( model(s) to take in consideration ) = xmlFile
+-------------------------
+
+ It is enought flexible to generate any file based on the model.
+ Some examples can be seen below.
+
+-------------------------
+ ............ plugin declaration goes before ...........
+ <!-- faces-config -->
+ <execution>
+ <id>makefacesconfig</id>
+ <configuration>
+ <templateFile>faces-config12.vm</templateFile>
+ <xmlFile>META-INF/faces-config.xml</xmlFile>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+
+ <!-- tld -->
+ <execution>
+ <id>maketomahawktld</id>
+ <configuration>
+ <xmlFile>META-INF/tomahawk.tld</xmlFile>
+ <xmlBaseFile>src/main/conf/META-INF/tomahawk-base.tld</xmlBaseFile>
+ <templateFile>tomahawk12.vm</templateFile>
+ <params>
+ <shortname>t</shortname>
+ <uri>http://myfaces.apache.org/tomahawk</uri>
+ <displayname>Tomahawk tag library 1.2.</displayname>
+ </params>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+
+ <!-- facelets taglib -->
+ <execution>
+ <id>maketomahawktaglib</id>
+ <configuration>
+ <xmlFile>META-INF/tomahawk.taglib.xml</xmlFile>
+ <xmlBaseFile>src/main/conf/META-INF/facelets-taglib-base.xml</xmlBaseFile>
+ <templateFile>facelets-taglib.vm</templateFile>
+ <params>
+ <shortname>t</shortname>
+ <uri>http://myfaces.apache.org/tomahawk</uri>
+ </params>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+ .................
+-------------------------
+
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/converters.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/converters.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/converters.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/converters.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,75 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Creating Custom Converters
+ ------
+
+Creating Custom Converters
+
+ A JSF Converter needs the following elements:
+
+ * A class implementing converter interface.
+
+ * Entry on faces-config.xml.
+
+ * Tag entry on tld.
+
+ * Tag entry on facelets taglib (optional).
+
+ * JSP Tag class
+
+ Myfaces builder plugin provide annotations/doclets to help users maintain
+ configuration files, and generating converter jsp tag classes
+ automatically. In this way, all information for a converter is just in
+ one file (the class implementing Converter interface).
+
+ On jsf 1.2, it is necessary to provide a base tag class that extends
+ from javax.faces.webapp.ConverterELTag where all converters should
+ inherit. This class is on myfaces commons converters project, but
+ users can provide custom template implementations for it.
+
+Setting up your project
+
+ All information related can be found {{{setup.html}here}}.
+
+Configuration files (faces-config.xml, .tld, facelets taglib)
+
+ This {{{config-files.html}page}} shows some examples.
+
+Annotate Converter Classes
+
+ Just add the annotations/doclets as presented below:
+
+-------------------
+
+@JSFConverter(
+ name = "mcc:convertDateTime",
+ tagClass = "org.apache.myfaces.commons.converter.ConvertDateTimeTag",
+ tagSuperclass = "org.apache.myfaces.commons.converter.ConverterTag")
+public class DateTimeConverter extends javax.faces.convert.DateTimeConverter
+{
+ public static final String CONVERTER_ID = "org.apache.myfaces.custom.convertDateTime.DateTimeConverter";
+
+ /** .......... impl code goes here ......... **/
+
+ @JSFProperty
+ public String getProperty()
+ {
+ // some stuff
+ }
+}
+-------------------
+
\ No newline at end of file
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/doclets-annotations.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/doclets-annotations.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/doclets-annotations.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/doclets-annotations.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,70 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Doclets and Annotations
+ ------
+
+Doclets and Annotations
+
+ To annotate the necessary information in
+ component / converter / validator / renderkit / renderer / tag files
+ you can use doclets:
+
+-------------------
+
+ /**
+ * This is a doclet
+ *
+ * @JSFProperty
+ * required = "true"
+ * defaultValue = "AnyValue"
+ **/
+
+-------------------
+
+ or annotations
+
+-------------------
+
+ /**
+ * This is an annotation
+ *
+ **/
+ @JSFProperty(
+ required = true,
+ defaultValue = "AnyValue")
+
+-------------------
+
+ Doclets and annotations can be used on both jsf 1.1 and jsf 1.2, but
+ since jsf 1.1 is jdk 1.4 compatible, it is preferred to use doclets with
+ jsf 1.1 (note that if you use annotations, your source code should be
+ jdk 1.5 in order to compile).
+
+ The differences between doclets and annotations are listed below:
+
+ * Attribute names like "class", "implements" in annotated
+ version are "clazz" and "implementz".
+
+ * All attribute values in doclets must be between "". In annotations
+ boolean attributes must not (see "required" example below).
+
+ * Usage of annotations like @JSFJspProperties and @JSFRenderers are
+ not required on doclets.
+
+ Taking into account the previous differences, you can consult the
+ annotation javadoc for doclets.
+
Modified: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/howto.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/howto.apt?rev=758509&r1=758508&r2=758509&view=diff
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/howto.apt (original)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/howto.apt Thu Mar 26 03:42:44 2009
@@ -1,40 +1,100 @@
- ~~ Licensed to the Apache Software Foundation (ASF) under one or more
- ~~ contributor license agreements. See the NOTICE file distributed with
- ~~ this work for additional information regarding copyright ownership.
- ~~ The ASF licenses this file to You under the Apache License, Version 2.0
- ~~ (the "License"); you may not use this file except in compliance with
- ~~ the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing, software
- ~~ distributed under the License is distributed on an "AS IS" BASIS,
- ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- ~~ See the License for the specific language governing permissions and
- ~~ limitations under the License.
-
- ------
- Myfaces Builder Plugin
- ------
-
-How to Use
-
- A quick summary of how to use the plugin...
-
--------------------
-<project>
- ...
- <build>
- ...
- <plugins>
- <plugin>
- <groupId>org.apache.myfaces.buildtools</groupId>
- <artifactId>myfaces-builder-plugin</artifactId>
- </plugin>
- </plugins>
- ...
- </build>
- ...
-</project>
--------------------
-
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ How to Use
+ ------
+
+Scan annotations/doclets and generate metadata
+
+ Just add this code to your project pom.xml
+
+-------------------
+<project>
+ ...
+ <build>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.myfaces.buildtools</groupId>
+ <artifactId>myfaces-builder-plugin</artifactId>
+ <version>1.0.2<version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build-metadata</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+-------------------
+
+ This goal scans all source classes for annotations or doclets and other metadata
+ files inside the project dependences and build the metadata file
+ (META-INF/myfaces-metadata.xml), required by other goals to work.
+
+Archetype using myfaces-builder-plugin
+
+ The latest myfaces-archetype-jsfcomponents available {{{http://svn.apache.org/repos/asf/myfaces/myfaces-build-tools/trunk/maven2-archetypes/myfaces-archetype-jsfcomponents/}here}}
+ or with version 1.0.2 or upper uses myfaces-builder-plugin to generate component classes,
+ tag classes, config files, etc. Just checkout the code, compile it and look the instructions on
+ {{{http://wiki.apache.org/myfaces/MyFaces_Archetypes_for_Maven}Myfaces Archetypes for Maven}}.
+
+Generate custom components
+
+ The code below shows how to configure the plugin to generate metadata
+ and then use it to generate component classes.
+
+-------------------
+<project>
+ ...
+ <build>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.myfaces.buildtools</groupId>
+ <artifactId>myfaces-builder-plugin</artifactId>
+ <version>1.0.2<version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build-metadata</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>makecomp</id>
+ <goals>
+ <goal>make-components</goal>
+ </goals>
+ <configuration>
+ <jsfVersion>12</jsfVersion>
+ <templateComponentName>myComponentTemplateClass.vm</templateComponentName>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+-------------------
+
+ Take a look at user guide section to see more detailed information.
\ No newline at end of file
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/properties.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/properties.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/properties.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/properties.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,146 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Properties
+ ------
+
+Properties
+
+ Components, converters and validators have properties. Usually,
+ properties must be defined on .tld files. Also, property getter/setter
+ and saveState/restoreState methods can be generated automatically,
+ reducing the amount of code that should be maintained.
+
+ Properties are inherited, so if a component/converter/validator extends
+ from a parent component/converter/validator that has some property
+ defined, the child must have it on its .tld.
+
+ But sometimes we have the following scenarios:
+
+ * Components, converters and validators also have properties with
+ no getter and setters (like "binding" property), which are implemented
+ in their tag classes or facelets tag handler.
+
+ * Also, some properties implemented on a parent class are not
+ implemented on some children, so we need to exclude it from its
+ tld definition.
+
+ * Users can implement its own setter and getter methods for properties.
+
+ * Some properties are related only to component but should not be on
+ tld.
+
+ * Some properties have some specific behavior (for example they could
+ contains objects implementing StateHolder interface).
+
+ All these cases could be handled using @JSFProperty and @JSFJspProperty
+ annotations. Below there are some examples describing how to use it.
+
+* General case
+
+ The most common case is let the property body be generated.
+
+-------------------
+
+ @JSFProperty
+ public abstract String getAutocomplete();
+
+-------------------
+
+* Custom Implementation of getter/setters
+
+ One example is UIViewRoot "renderKitId" property:
+
+-------------------
+ @JSFProperty
+ public String getRenderKitId()
+ {
+ //... custom implementation ...
+ }
+
+ public void setRenderKitId(String renderKitId)
+ {
+ //... custom implementation ...
+ }
+-------------------
+
+* Properties without getter/setters
+
+ This syntax should be used only in very special cases and users should
+ use @JSFProperty annotation/doclet instead.
+
+-------------------
+@JSFComponent(type = "javax.faces.ComponentBase", family = "javax.faces.ComponentBase", desc = "base component when all components must inherit", tagClass = "javax.faces.webapp.UIComponentELTag", configExcluded = true)
+@JSFJspProperty(name = "binding",
+ returnType = "javax.faces.component.UIComponent",
+ longDesc = "Identifies a backing bean property (of type UIComponent or appropriate subclass) to bind to this component instance. This value must be an EL expression.", desc = "backing bean property to bind to this component instance")
+public abstract class UIComponentBase extends UIComponent
+{
+ // .... some code ...
+}
+-------------------
+
+* Excluding properties from tld
+
+ One example is UIParameter "rendered" property:
+
+-------------------
+
+ /**
+ * Disable this property; although this class extends a base-class that defines a read/write rendered property, this
+ * particular subclass does not support setting it. Yes, this is broken OO design: direct all complaints to the JSF
+ * spec group.
+ */
+ @Override
+ @JSFProperty(tagExcluded = true)
+ public void setRendered(boolean state)
+ {
+ super.setRendered(state);
+ // call parent method due TCK problems
+ // throw new UnsupportedOperationException();
+ }
+-------------------
+
+* Properties with different name in component and tag class
+
+ One example is UICommand "action" property. To change it on tld,
+ use "jspName".
+
+-------------------
+ @JSFProperty(stateHolder = true, returnSignature = "java.lang.Object", jspName = "action")
+ public MethodExpression getActionExpression()
+ {
+ // .... some code ...
+ }
+-------------------
+
+* MethodExpression/MethodBinding properties
+
+-------------------
+
+ @JSFProperty(stateHolder = true, returnSignature = "void", methodSignature = "javax.faces.event.ActionEvent")
+ public MethodBinding getActionListener()
+ {
+ // .... some code ...
+ }
+
+ @JSFProperty(stateHolder = true, returnSignature = "java.lang.Object", jspName = "action")
+ public MethodExpression getActionExpression()
+ {
+ // .... some code ...
+ }
+-------------------
+
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/setup.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/setup.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/setup.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/setup.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,168 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Setting up your project
+ ------
+
+Setting up your project
+
+* Configuring your pom.xml
+
+ According to your jsf version you will need to set the required
+ dependencies.
+
+ In jsf 1.1 (use doclets).
+
+------------------------------------------------------
+ <dependency>
+ <groupId>org.apache.myfaces.core</groupId>
+ <artifactId>myfaces-api</artifactId>
+ <version>1.1.6</version>
+ <scope>provided</scope>
+ </dependency>
+------------------------------------------------------
+
+ In jsf 1.2 (use annotations).
+
+------------------------------------------------------
+ <dependency>
+ <groupId>org.apache.myfaces.core</groupId>
+ <artifactId>myfaces-api</artifactId>
+ <version>1.2.6</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.myfaces.buildtools</groupId>
+ <artifactId>myfaces-builder-annotations</artifactId>
+ <version>1.0.2</version>
+ <scope>provided</scope>
+ </dependency>
+------------------------------------------------------
+
+ If you are working with converters and validators, you should use
+ myfaces commons dependencies as base for it:
+
+-----------------------------------------------------------
+ <dependency>
+ <groupId>org.apache.myfaces.commons</groupId>
+ <artifactId>myfaces-validators12</artifactId>
+ <version>1.0.0</version>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.myfaces.commons</groupId>
+ <artifactId>myfaces-converters12</artifactId>
+ <version>1.0.0</version>
+ <scope>compile</scope>
+ </dependency>
+-----------------------------------------------------------
+
+ Then you need to define the plugin configuration in your projects
+ pom.xml like this:
+
+-------------------
+ <build>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <excludes>
+ <exclude>**/*.vm</exclude>
+ </excludes>
+ </resource>
+ </resources>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.myfaces.buildtools</groupId>
+ <artifactId>myfaces-builder-plugin</artifactId>
+ <version>1.0.2</version>
+ <executions>
+ <execution>
+ <id>buildmetadata</id>
+ <goals>
+ <goal>build-metadata</goal>
+ <!-- when use components -->
+ <goal>make-components</goal>
+ <goal>make-tags</goal>
+
+ <!-- when use validators -->
+ <goal>make-validators</goal>
+ <goal>make-validator-tags</goal>
+
+ <!-- when use converters -->
+ <goal>make-converter-tags</goal>
+ </goals>
+ <configuration>
+ <!-- Use 1.1 or 1.2 according to your jsf version -->
+ <jsfVersion>1.2</jsfVersion>
+ </configuration>
+ </execution>
+ <execution>
+ <id>makefacesconfig</id>
+ <configuration>
+ <xmlFile>META-INF/faces-config.xml</xmlFile>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>maketld</id>
+ <configuration>
+ <xmlFile>META-INF/mycomponents.tld</xmlFile>
+ <!-- as templateFile you can use tomahawk.vm or tomahawk12.vm -->
+ <templateFile>mycomponents.tld.vm</templateFile>
+ <params>
+ <shortname>mycomponents</shortname>
+ <uri>http://www.myorganitzation.org/mycomponents</uri>
+ <displayname>Custom tag library.</displayname>
+ <description>Enhanced standard JSP actions and custom MyFaces actions.</description>
+ </params>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>makefaceletstaglib</id>
+ <configuration>
+ <xmlFile>META-INF/mycomponents.taglib.xml</xmlFile>
+ <xmlBaseFile>src/main/conf/META-INF/facelets-taglib-base.xml</xmlBaseFile>
+ <templateFile>facelets-taglib.vm</templateFile>
+ <params>
+ <shortname>mycomponents</shortname>
+ <uri>http://www.myorganitzation.org/mycomponents</uri>
+ </params>
+ </configuration>
+ <goals>
+ <goal>make-config</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+-------------------
+
+* Customizing your templates
+
+ The plugin uses velocity templates to generate files, and on its jar
+ there are some already defined. If you need some file (like a template
+ for tld) you can find the most up to date template on tomahawk core
+ or core12.
+
+ More detailed information can be found {{{templates.html}here}}.
\ No newline at end of file
Added: myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/tags.apt
URL: http://svn.apache.org/viewvc/myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/tags.apt?rev=758509&view=auto
==============================================================================
--- myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/tags.apt (added)
+++ myfaces/myfaces-build-tools/trunk/maven2-plugins/myfaces-builder-plugin/src/site/apt/tags.apt Thu Mar 26 03:42:44 2009
@@ -0,0 +1,82 @@
+ ~~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~~ contributor license agreements. See the NOTICE file distributed with
+ ~~ this work for additional information regarding copyright ownership.
+ ~~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~~ (the "License"); you may not use this file except in compliance with
+ ~~ the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing, software
+ ~~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~~ See the License for the specific language governing permissions and
+ ~~ limitations under the License.
+
+ ------
+ Creating Custom JSF Tags
+ ------
+
+Creating Custom JSF Tags
+
+ A JSF Tag needs the following elements:
+
+ * JSP Tag class.
+
+ * Tag entry on tld.
+
+ * Facelets Tag Handler class (optional).
+
+ * Tag entry on facelets taglib (optional).
+
+ Myfaces builder plugin provide annotations/doclets to help users maintain
+ configuration files. In this way, all information for a tag is just in
+ one file.
+
+ Any tag is registered on facelets taglib if it has a related tag handler.
+ Usually, custom tag classes should have facelets tag handlers with
+ similar functions, but on facelets world there is no need to define
+ properties on a xml file.
+
+Setting up your project
+
+ All information related can be found {{{setup.html}here}}.
+
+Configuration files (faces-config.xml, .tld, facelets taglib)
+
+ This {{{config-files.html}page}} shows some examples.
+
+Annotate JSF Tag Classes
+
+ Just add the annotations/doclets as presented below:
+
+-------------------
+
+@JSFJspTag(
+ name = "f:valueChangeListener",
+ bodyContent = "empty")
+public class ValueChangeListenerTag extends
+ GenericListenerTag<EditableValueHolder, ValueChangeListener>
+{
+
+ /** ............. some code goes here ................. **/
+
+ @Override
+ @JSFJspAttribute(
+ className = "java.lang.String",
+ rtexprvalue = true)
+ public void setType(ValueExpression type)
+ {
+ super.setType(type);
+ }
+
+ @Override
+ @JSFJspAttribute(
+ className = "javax.faces.event.ValueChangeListener",
+ rtexprvalue = true)
+ public void setBinding(ValueExpression binding)
+ {
+ super.setBinding(binding);
+ }
+}
+-------------------
\ No newline at end of file