Fix for bug #193167.
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/design-time_tag_metadata_operations.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/design-time_tag_metadata_operations.html new file mode 100644 index 0000000..6c8e8ba --- /dev/null +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/design-time_tag_metadata_operations.html
@@ -0,0 +1,254 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> + +<head> + <title>Design-Time Tag Metadata Operations</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> + <meta http-equiv="Content-Style-Type" content="text/css"/> + <meta http-equiv="Content-Script-Type" content="text/javascript"/> + <link rel="stylesheet" href="../../book.css" type="text/css"/> +</head> + +<body> + +<h1>Design-Time Tag Metadata Operations</h1> + +<h2>Overview</h2> +This document provides a reference of the operations that are available to +"design-time" ("DT") metadata for JSP tags. DT metadata is consumed by the DT +tag conversion / decoration framework to produce close-to-runtime visuals in +the Web Page Editor.<br/> +<br/> +Please see <a href="../tutorials/Providing_Design-Time_Tag_Metadata.html">Providing Design-Time Tag Metadata</a> +for a tutorial on how to provide DT tag metadata. + +<h2>Operations</h2> +<table border="2" cellspacing="1" cellpadding="2"> + <tr> + <th>Operation</th> + <th>Parameters</th> + <th>Purpose</th> + </tr> + <tr valign="top"> + <td>AppendChildElementOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Element name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1 (optional):</b></td> + <td nowrap="nowrap">Make child Element current</td> + </tr> + </table> + </td> + <td>Appends a new child Element to the current Element, and optionally makes the new child Element current.</td> + </tr> + <tr valign="top"> + <td>AppendChildTextFromXPathOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">XPath expression</td> + </tr> + </table> + </td> + <td>Appends child Text node containing the value of the evaluated XPath expression.</td> + </tr> + <tr valign="top"> + <td>AppendChildTextOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Text node content</td> + </tr> + </table> + </td> + <td>Appends child Text node containing the content specified by the parameter.</td> + </tr> + <tr valign="top"> + <td>ConvertAttributeToTextOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Attribute name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1 (optional):</b></td> + <td nowrap="nowrap">Remove attribute</td> + </tr> + </table> + </td> + <td>Creates a new child Text node where the content is the specified attribute's value, and optionally removes the specified attribute.</td> + </tr> + <tr valign="top"> + <td>CopyAllAttributesOperation</td> + <td>(None)</td> + <td>Copies all source Element's attributes to the current Element.</td> + </tr> + <tr valign="top"> + <td>CopyAttributeOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Attribute name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1 (optional):</b></td> + <td nowrap="nowrap">Create if not present</td> + </tr> + <tr> + <td nowrap="nowrap"><b>2 (optional):</b></td> + <td nowrap="nowrap">New value if not present</td> + </tr> + </table> + </td> + <td>Copies a single source Element's attribute to the current Element, optionally creating a new attribute with the specified new value if not present on the source Element.</td> + </tr> + <tr valign="top"> + <td>CopyChildrenOperation</td> + <td>(None)</td> + <td>Copies all child Elements to be further processed by the framework.</td> + </tr> + <tr valign="top"> + <td>CreateAttributeFromXPathOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Attribute name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1:</b></td> + <td nowrap="nowrap">XPath expression</td> + </tr> + </table> + </td> + <td>Creates an attribute on the current Element where the value is the value of the evaluated XPath expression.</td> + </tr> + <tr valign="top"> + <td>CreateAttributeOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Attribute name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1:</b></td> + <td nowrap="nowrap">Attribute value</td> + </tr> + </table> + </td> + <td>Creates an attribute with the specified value on the current Element.</td> + </tr> + <tr valign="top"> + <td>CreateElementOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Element name</td> + </tr> + </table> + </td> + <td>Creates a new Element in the Document and makes it the current Element.</td> + </tr> + <tr valign="top"> + <td>CustomTransformOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Fully-qualified classname</td> + </tr> + </table> + </td> + <td>Instantiates custom class (assumed to be in same plug-in as the metadata file in which it is referenced) that must implement ITransformOperation. This allows custom code to handle transformation operations for which there is currently no adequate pre-defined operation.</td> + </tr> + <tr valign="top"> + <td>IfNotOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">XPath expression</td> + </tr> + </table> + </td> + <td>Processes child operations only if the XPath expression does not evaluate to "true". IfNotOperation and IfOperation can be nested arbitrarily deep.</td> + </tr> + <tr valign="top"> + <td>IfOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">XPath expression</td> + </tr> + </table> + </td> + <td>Processes child operations only if the XPath expression evaluates to "true". IfNotOperation and IfOperation can be nested arbitrarily deep.</td> + </tr> + <tr valign="top"> + <td>IterateOverElementsOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">XPath expression</td> + </tr> + </table> + </td> + <td>Processes child operations for each Element in the set returned by the evaluated XPath expression.</td> + </tr> + <tr valign="top"> + <td>MakeParentElementCurrentOperation</td> + <td>(None)</td> + <td>Makes the current Element's parent Element current.</td> + </tr> + <tr valign="top"> + <td>RemoveAttributeOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Attribute name</td> + </tr> + </table> + </td> + <td>Removes the specified attribute from the current Element.</td> + </tr> + <tr valign="top"> + <td>RenameAttributeOperation</td> + <td> + <table border="0" cellspacing="0" cellpadding="2"> + <tr> + <td nowrap="nowrap"><b>0:</b></td> + <td nowrap="nowrap">Old attribute name</td> + </tr> + <tr> + <td nowrap="nowrap"><b>1:</b></td> + <td nowrap="nowrap">New attribute name</td> + </tr> + </table> + </td> + <td>Renames the specified attribute of the current Element.</td> + </tr> +</table> + +<h2>References</h2> +<ul> + <li><a href="../tutorials/Providing_Design-Time_Tag_Metadata.html">Providing Design-Time Tag Metadata</a></li> +</ul> + +</body> + +</html> \ No newline at end of file
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/Providing_Design-Time_Tag_Metadata.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/Providing_Design-Time_Tag_Metadata.html new file mode 100644 index 0000000..1cc16c0 --- /dev/null +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/Providing_Design-Time_Tag_Metadata.html
@@ -0,0 +1,158 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> + +<head> + <title>Providing Design-Time Tag Metadata</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> + <meta http-equiv="Content-Style-Type" content="text/css"/> + <meta http-equiv="Content-Script-Type" content="text/javascript"/> + <link rel="stylesheet" href="../../book.css" type="text/css"/> +</head> + +<body> + +<h1>Providing Design-Time Tag Metadata</h1> + +<h2>Overview</h2> +This document provides an overview of what is required to provide "design-time" +("DT") metadata for JSP tags. DT metadata is consumed by the DT tag conversion / decoration +framework to produce close-to-runtime visuals in the Web Page Editor.<br/> +<br/> +This note assumes the following user knowledge: +<ul> + <li>How to create plugin projects</li> + <li>How to declare dependencies in plugin projects</li> + <li>How to use extension points</li> + <li>How to package and deploy plugins</li> +</ul> + +<h2>Setup Steps</h2> +The following setup steps are described in more details in the sections that follow: +<ol> + <li>Create a Plug-in Project</li> + <li>Specify plug-in's dependencies</li> + <li>Configure "standardMetaDataFiles" extension point</li> + <li>Create DT metadata XML file</li> +</ol> + +<h3>Create a Plug-in Project</h3> +A plug-in project is required to use the "standardMetaDataFiles" extension point and to contain the DT metadata file. +<ol> + <li>Select menu items, "File" > "New" > "Project..."</li> + <li>Select "Plug-in Project" and click "Next >"</li> + <li>Provide a reasonable value for "Project name" and click "Next >"</li> + <li>Provide reasonable values for "Plug-in Properties"</li> + <li>Uncheck "This plug-in will make contributions to the UI"</li> + <li>Click "Finish"</li> +</ol> + +<h3>Specify Plug-in's Dependencies</h3> +<ol> + <li>Open the new project's "META-INF/MANIFEST.MF" file in the "Plug-in Manifest Editor"</li> + <li>Select the "Dependencies" tab</li> + <li>Add "org.eclipse.jst.jsf.common" under "Required Plug-ins"</li> +</ol> + +<h3>Configure "standardMetaDataFiles" Extension Point</h3> +<ol> + <li>Open the new project's "META-INF/MANIFEST.MF" file in the "Plug-in Manifest Editor"</li> + <li>Select the "Extensions" tab</li> + <li>Add "org.eclipse.jst.jsf.common.standardMetaDataFiles" under "All Extensions"</li> + <li>Right-click the new extension and select "New" > "standardMetaDataFile"</li> + <li>Select "(standardMetaDataFile)"</li> + <li>Under "Extension Element Details", set appropriate values:</li> + <ol> + <li>For "uri", value should match the URI value as set in the tag library</li> + <li>The "location" value is a plugin-relative path and filename (file has not been created yet - value entered will be required in subsequent steps)</li> + <li>No value is required for "locator" (leave blank)</li> + </ol> +</ol> +<img src="images/DTTagMD_1.png" border="0" alt="Extension Details"/> + +<h3>Create DT Metadata XML File</h3> +<ol> + <li>Create necessary folder(s) and file, to match value specified for "location" of the "standardMetaDataFile" (e.g. "metadata/jsf_tomahawk_dti.xml")</li> +</ol> + +<h2>Writing the DT Metadata</h2> +<h3>Document Node</h3> +Copy the following XML into the DT metadata file as a starting point:<br/> +<br/> +<pre> +<?xml version="1.0" encoding="UTF-8"?> +<md:metadatamodel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" + xmlns:md="http://org.eclipse.jst.jsf.common.metadata/metadata.ecore" + xmlns:dti="http://org.eclipse.jsf.pagedesigner/dtinfo.ecore" + id="http://myfaces.apache.org/tomahawk" + type="tagFile"> + + + +</md:metadatamodel> +</pre> +Note that the "id" attribute of the document node matches the "uri" as specified previously in the plug-in manifest. + +<h3>Entity (Tag) Node</h3> +Insert the following XML inside the previously created document node:<br/> +<br/> +<pre> + <entity id="inputText" type="tag"> + <trait id="dt-info"> + <value xsi:type="dti:DTInfo"> + <tag-convert-info> + <operation id="CreateElementOperation"> + <parameter value="input"/> + </operation> + <operation id="CopyAllAttributesOperation"/> + <operation id="RenameAttributeOperation"> + <parameter value="styleClass"/> + <parameter value="class"/> + </operation> + <operation id="CreateAttributeOperation"> + <parameter value="type"/> + <parameter value="text"/> + </operation> + </tag-convert-info> + <tag-decorate-info id="vpd-decorate-design" + multiLevel="true" + widget="true" + setNonVisualChildElements="true" + /> + <tag-decorate-info id="vpd-decorate-preview"> + <resolve-attribute-value attributeName="value"/> + </tag-decorate-info> + </value> + </trait> + </entity> +</pre> +Note the following: +<ul> + <li>The "entity" node's "id" attribute specifies the name of the tag for which metadata is being provided (in this example, "inputText")</li> + <li>The "entity" node must have a "type" attribute with the value "tag"</li> + <li>The "trait" node must have an "id" attribute with the value "dt-info"</li> + <li>The "value" node must have an "xsi:type" attribute with the value "dti:DTInfo"</li> + <li>A single DT metadata file will typically contain one "entity" node per tag for which metadata is being provided - generally there will be one such file per tag library</li> +</ul> + +<h3>Child Nodes</h3> +The child nodes specify the tag conversion and decoration operations that will +be performed to translate the source JSP node into HTML that is rendered in the +Web Page Editor. Full discussion of the operations available is outside the +scope of this document. The listings above serve to demonstrate the form of the +metadata.<br/> +<br/> +(Suggested study materials for interested readers are the metadata files +located in the "org.eclipse.jst.pagedesigner.jsf.ui" plug-in, which provide the +metadata for JSF core and JSF HTML tag libraries.) + +<h2>References</h2> +<ul> + <li><a href="../programmersguide/design-time_tag_metadata_operations.html">Design-Time Tag Metadata Operations</a></li> +</ul> + +</body> + +</html> \ No newline at end of file
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/DTTagMD_1.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/DTTagMD_1.png new file mode 100644 index 0000000..af7aa75 --- /dev/null +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/DTTagMD_1.png Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml b/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml index ec175c7..fad450c 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml +++ b/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml
@@ -12,4 +12,5 @@ <topic label="Contributing EL Variables" href="html/programmersguide/contributing_el_variables.html"/> <topic label="The Design Time Application Manager" href="html/programmersguide/the_design_time_application_manager.html"/> </topic> + <topic label="Design-Time Tag Metadata Operations" href="html/programmersguide/design-time_tag_metadata_operations.html"/> </toc>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/toctutorials.xml b/plugins/org.eclipse.jst.jsf.doc.dev/toctutorials.xml index 47a0f1b..0c54dd2 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/toctutorials.xml +++ b/plugins/org.eclipse.jst.jsf.doc.dev/toctutorials.xml
@@ -4,4 +4,5 @@ <toc label="Tutorials" link_to="toc.xml#jsf_dev_tutorials"> <topic label="Supplying Tag Library Metadata for Apache MyFaces Tomahawk" href="html/tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html"/> <topic label="Implementing a New Tag-Based EL Variable Contributor for JSP" href="html/tutorials/implementing_a_new_tag_based_el_variable_contributor_for_jsp.html"/> + <topic label="Providing Design-Time Tag Metadata" href="html/tutorials/Providing_Design-Time_Tag_Metadata.html"/> </toc>
