You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by ar...@apache.org on 2009/12/21 23:24:05 UTC
svn commit: r893014 -
/myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java
Author: arobinson74
Date: Mon Dec 21 22:24:05 2009
New Revision: 893014
URL: http://svn.apache.org/viewvc?rev=893014&view=rev
Log:
Document client events in the tag documentation
Modified:
myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java
Modified: myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java
URL: http://svn.apache.org/viewvc/myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java?rev=893014&r1=893013&r2=893014&view=diff
==============================================================================
--- myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java (original)
+++ myfaces/trinidad-maven/branches/2.0.0-branch/maven-tagdoc-plugin/src/main/java/org/apache/myfaces/trinidadbuild/plugin/tagdoc/TagdocReport.java Mon Dec 21 22:24:05 2009
@@ -6,9 +6,9 @@
* 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
@@ -24,10 +24,13 @@
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
+
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLClassLoader;
+
import java.util.ArrayList;
+import java.util.Arrays;
import java.util.Collections;
import java.util.Comparator;
import java.util.Enumeration;
@@ -70,11 +73,14 @@
import org.apache.myfaces.trinidadbuild.plugin.faces.util.PropertyFilter;
import org.apache.myfaces.trinidadbuild.plugin.faces.util.ValidatorFilter;
import org.apache.myfaces.trinidadbuild.plugin.faces.util.XIncludeFilter;
+
import org.codehaus.doxia.sink.Sink;
import org.codehaus.doxia.site.renderer.SiteRenderer;
+
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;
+
/**
* Report for generating JSF tagdoc based on faces-config.xml parsing.
* Note that this is not really an AbstractMavenMultiPageReport - the
@@ -94,7 +100,7 @@
factory.setSiteRenderer(getSiteRenderer());
factory.setSiteDirectory(getOutputDirectory());
setSinkFactory(factory);
-
+
processIndex(project, resourcePath);
try
{
@@ -120,15 +126,15 @@
components = new FilteredIterator(components, new SkipFilter());
components = new FilteredIterator(components, new ComponentTagFilter());
components = new FilteredIterator(components, new ComponentNamespaceFilter());
-
+
Iterator validators = facesConfig.validators();
validators = new FilteredIterator(validators, new ValidatorTagFilter());
validators = new FilteredIterator(validators, new ValidatorNamespaceFilter());
-
+
Iterator converters = facesConfig.converters();
converters = new FilteredIterator(converters, new ConverterTagFilter());
converters = new FilteredIterator(converters, new ConverterNamespaceFilter());
-
+
// =-=AEW Note that only updating out-of-date components, etc. is
// permanently tricky, even if we had proper detection in place,
// because the index always has to have all docs
@@ -143,7 +149,7 @@
Set componentPages = new TreeSet();
Set converterPages = new TreeSet();
Set validatorPages = new TreeSet();
-
+
int count = 0;
while (components.hasNext())
{
@@ -182,7 +188,7 @@
sink.head();
sink.title();
sink.text("Tag library documentation");
- sink.title_();
+ sink.title_();
sink.head_();
sink.body();
@@ -226,8 +232,8 @@
private Set _gatherOtherTags()
{
TreeSet set = new TreeSet();
- String subDir =
- _platformAgnosticPath(_platformAgnosticPath("xdoc/" +
+ String subDir =
+ _platformAgnosticPath(_platformAgnosticPath("xdoc/" +
_DOC_SUBDIRECTORY));
File siteSubDir = new File(siteDirectory, subDir);
if (siteSubDir.exists())
@@ -247,7 +253,7 @@
}
private String _formatPropList(
- String[] pList,
+ String[] pList,
String header)
{
String[] nullList = {};
@@ -255,7 +261,7 @@
}
private String _formatPropList(
- String[] pList,
+ String[] pList,
String header,
String[] ignores)
{
@@ -316,24 +322,24 @@
sink.text("Tag Name");
sink.tableHeaderCell_();
sink.tableRow_();
-
+
Iterator iter = pages.iterator();
while (iter.hasNext())
{
sink.tableRow();
sink.tableCell();
-
+
String name = (String) iter.next();
String tagName = "<" + name.replace('_', ':') + ">";
-
+
sink.link(_DOC_SUBDIRECTORY + "/" + name + ".html");
sink.text(tagName);
sink.link_();
-
+
sink.tableCell_();
sink.tableRow_();
}
-
+
sink.table_();
sink.section1_();
}
@@ -347,7 +353,7 @@
{
return _getPrefix(qName) + "_" + qName.getLocalPart();
}
-
+
private String _getQualifiedName(QName qName)
{
return _getPrefix(qName) + ":" + qName.getLocalPart();
@@ -357,7 +363,7 @@
{
if ((qName.getPrefix() != null) && !"".equals(qName.getPrefix()))
return qName.getPrefix();
-
+
String namespace = qName.getNamespaceURI();
if (namespace == null)
return null;
@@ -381,8 +387,8 @@
}
String pageName = _toPageName(component.getTagName());
- File targetDir = new File(outputDirectory.getParentFile(),
- _platformAgnosticPath("generated-site/xdoc/" +
+ File targetDir = new File(outputDirectory.getParentFile(),
+ _platformAgnosticPath("generated-site/xdoc/" +
_DOC_SUBDIRECTORY));
targetDir.mkdirs();
File targetFile = new File(targetDir, pageName + ".xml");
@@ -408,6 +414,15 @@
_writeExamples(out, component);
+ if (component.isClientBehaviorHolder())
+ {
+ out.write(" <section name=\"Client Events\">\n");
+ out.write(" <p>\n");
+ _writeComponentClientEvents(out, component);
+ out.write(" </p>\n");
+ out.write(" </section>\n");
+ }
+
if (component.hasEvents(true))
{
out.write(" <section name=\"Events\">\n");
@@ -416,7 +431,7 @@
out.write(" </p>\n");
out.write(" </section>\n");
}
-
+
if (component.hasFacets(true))
{
out.write(" <section name=\"Supported Facets\">\n");
@@ -425,7 +440,7 @@
out.write(" </p>\n");
out.write(" </section>\n");
}
-
+
out.write(" <section name=\"Attributes\">\n");
_writeComponentAttributes(out, component);
out.write(" </section>\n");
@@ -440,7 +455,7 @@
return pageName;
}
-
+
private String _generateConverterDoc(ConverterBean converter) throws IOException
{
if (converter.getTagName() == null)
@@ -450,8 +465,8 @@
String pageName = _toPageName(converter.getTagName());
- File targetDir = new File(outputDirectory.getParentFile(),
- _platformAgnosticPath("generated-site/xdoc/" +
+ File targetDir = new File(outputDirectory.getParentFile(),
+ _platformAgnosticPath("generated-site/xdoc/" +
_DOC_SUBDIRECTORY));
targetDir.mkdirs();
File targetFile = new File(targetDir, pageName + ".xml");
@@ -501,8 +516,8 @@
String pageName = _toPageName(validator.getTagName());
- File targetDir = new File(outputDirectory.getParentFile(),
- _platformAgnosticPath("generated-site/xdoc/" +
+ File targetDir = new File(outputDirectory.getParentFile(),
+ _platformAgnosticPath("generated-site/xdoc/" +
_DOC_SUBDIRECTORY));
targetDir.mkdirs();
File targetFile = new File(targetDir, pageName + ".xml");
@@ -543,13 +558,12 @@
return pageName;
}
-
private void _writeComponentSummary(Writer out, ComponentBean bean) throws IOException
{
out.write(" <b>Tag name:</b> <" +
_getQualifiedName(bean.getTagName()) + ">\n");
out.write(" <br/>\n");
-
+
out.write(" <b>UIComponent class:</b> ");
String javadocURL = _platformAgnosticPath("../apidocs/" +
@@ -569,7 +583,7 @@
"component (\"partialTriggers\", <code>findComponent()</code>, etc.), " +
"you must prefix the child's ID with this component's ID and a colon (':').</p>");
}
-
+
String fmtd = _formatPropList(bean.getUnsupportedAgents(),
"Unsupported agents",
_NON_DOCUMENTED_AGENTS);
@@ -586,7 +600,6 @@
out.write("\n");
}
-
private boolean _isNamingContainer(ComponentBean bean)
{
if (bean.isNamingContainer())
@@ -603,7 +616,7 @@
out.write(" <b>Tag name:</b> <" +
_getQualifiedName(bean.getTagName()) + ">\n");
out.write(" <br/>\n");
-
+
out.write(" <br/>\n");
out.write(" <b> type:</b> " + bean.getValidatorId() + "\n");
out.write(" <br/>\n");
@@ -616,13 +629,12 @@
out.write("\n");
}
-
private void _writeConverterSummary(Writer out, ConverterBean bean) throws IOException
{
out.write(" <b>Tag name:</b> <" +
_getQualifiedName(bean.getTagName()) + ">\n");
out.write(" <br/>\n");
-
+
out.write(" <br/>\n");
out.write(" <b> type:</b> " + bean.getConverterId() + "\n");
out.write(" <br/>\n");
@@ -711,7 +723,7 @@
String attrName = (String) iter.next();
list.add(bean.findProperty(attrName, true));
}
-
+
TreeSet groups = new TreeSet(new GroupComparator());
/* No current support for grouping
@@ -762,7 +774,7 @@
String attrName = (String) iter.next();
list.add(bean.findProperty(attrName));
}
-
+
_writeComponentAttributes(out,
list.iterator(),
bean.getConverterClass(),
@@ -791,7 +803,7 @@
String attrName = (String) iter.next();
list.add(bean.findProperty(attrName));
}
-
+
_writeComponentAttributes(out,
list.iterator(),
bean.getValidatorClass(),
@@ -810,7 +822,7 @@
while (attributes.hasNext())
{
PropertyBean attr = (PropertyBean) attributes.next();
-
+
if (attr.isHidden())
{
continue;
@@ -871,7 +883,7 @@
String elSupported;
// MethodBindings, "binding", and some other attributes
// require EL support
- if (attr.isMethodBinding() ||
+ if (attr.isMethodBinding() ||
attr.isMethodExpression() ||
"binding".equals(propertyName))
{
@@ -907,33 +919,33 @@
{
out.write("<td>\n");
}
-
+
// out.write(EscapeUtils.escapeElementValue(doc.doc));
if (valStr != null)
{
out.write(valStr);
out.write("<br/>");
}
-
- if (attr.getDeprecated() != null)
+
+ if (attr.getDeprecated() != null)
{
out.write("<b>");
out.write(attr.getDeprecated());
out.write("</b>");
}
-
- if (attr.isNoOp())
+
+ if (attr.isNoOp())
{
out.write("<b>");
out.write("This property has a no-op setter for both the client and server components effectively making it a read-only property.");
- out.write("</b>");
+ out.write("</b>");
}
-
- if (attr.isNoOp() || attr.getDeprecated() != null)
+
+ if (attr.isNoOp() || attr.getDeprecated() != null)
{
out.write("<br/><br/>");
}
-
+
out.write(attr.getDescription());
if (unsupAgentsStr != null)
{
@@ -985,6 +997,41 @@
return type;
}
+ private void _writeComponentClientEvents(
+ Writer out,
+ ComponentBean bean
+ ) throws IOException
+ {
+ String defaultEvent = bean.getDefaultEventName();
+
+ out.write("<table>\n<tbody>\n<tr>\n<td>\n<ul>\n");
+
+ String[] eventNames = bean.getEventNames();
+ int size = eventNames.length;
+ String[] dest = new String[size];
+ System.arraycopy(eventNames, 0, dest, 0, size);
+ Arrays.sort(dest);
+ // create 3 columns to better utilize the space on the page
+ int numRows = (int)Math.ceil(size / 3d);
+
+ for (int i = 0; i < size; ++i)
+ {
+ if (i > 0 && (i % numRows) == 0)
+ {
+ out.write("</ul>\n</td>\n<td>\n<ul>\n");
+ }
+ String eventName = dest[i];
+ out.write("<li>");
+ out.write(eventName);
+ if (eventName.equals(defaultEvent))
+ {
+ out.write(" <small>(default)</small>");
+ }
+ out.write("</li>\n");
+ }
+ out.write("</ul>\n</td>\n</tr>\n</tbody>\n</table>\n");
+ }
+
private void _writeComponentEvents(Writer out, ComponentBean bean) throws IOException
{
out.write("<table>\n");
@@ -1056,20 +1103,18 @@
out.write("</table>\n");
}
-
-
private void _writeExamples(Writer out, AbstractTagBean bean) throws IOException
{
if (!bean.hasExamples())
return;
-
+
ExampleBean exBean = null;
// Write header
out.write(" <section name=\"Code Example(s)\">\n");
- out.write(" <p>\n");
+ out.write(" <p>\n");
out.write(" <html>\n");
-
+
// Go through each example, write its description
// followed by the example source code.
Iterator iter = bean.examples();
@@ -1078,12 +1123,12 @@
exBean = (ExampleBean) iter.next();
String desc = exBean.getSourceDescription();
String source = exBean.getSourceCode();
-
+
if (desc != null)
{
desc = desc.replaceAll("<", "<");
desc = desc.replaceAll(">", ">");
-
+
if (!"".equals(desc))
out.write(" <p>" + desc + "</p>");
}
@@ -1102,14 +1147,14 @@
}
out.write(" </html>\n");
out.write(" </p>\n");
- out.write(" </section>\n");
+ out.write(" </section>\n");
}
private void _writeScreenshots(Writer out, AbstractTagBean bean) throws IOException
{
if (!bean.hasScreenshots())
return;
-
+
ScreenshotBean ssBean = null;
// Write header
@@ -1146,10 +1191,10 @@
out.write("<br/>");
out.write(desc + "\n");
}
- }
- out.write(" </div>\n");
+ }
+ out.write(" </div>\n");
- // create extra space between each screenshot to ensure it is clear which description
+ // create extra space between each screenshot to ensure it is clear which description
// text belongs to which image
if (iter.hasNext())
{
@@ -1165,7 +1210,7 @@
{
return project;
}
-
+
protected String getOutputDirectory()
{
return outputDirectory.getAbsolutePath();
@@ -1472,7 +1517,7 @@
* @required
*/
private File outputDirectory;
-
+
/**
* Directory where the original site is present.
@@ -1480,9 +1525,9 @@
* the string for some reason. TRIED using ${siteDirectory},
* which was undefined. TRIED ${project.directory}src/site; which also
* inserted a null. ${project.build.directory}/../src/site seems to work,
- * though it assumes that ${project.build.directory} is
+ * though it assumes that ${project.build.directory} is
* ${project.directory}/target.
- *
+ *
* @parameter default-value="${project.build.directory}/../src/site/"
* @required
*/