Developer Guide; supplying tag lib metadata tutorial.
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/default_style.css b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/default_style.css
new file mode 100644
index 0000000..d93789f
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/default_style.css
@@ -0,0 +1,12 @@
+p, table, td, th { font-family: arial, helvetica, geneva; font-size: 10pt}
+pre { font-family: "Courier New", Courier, mono; font-size: 10pt}
+h2 { font-family: arial, helvetica, geneva; font-size: 18pt; font-weight: bold ; line-height: 14px}
+code { font-family: "Courier New", Courier, mono; font-size: 10pt}
+sup { font-family: arial,helvetica,geneva; font-size: 10px}
+h3 { font-family: arial, helvetica, geneva; font-size: 14pt; font-weight: bold}
+li { font-family: arial, helvetica, geneva; font-size: 10pt}
+h1 { font-family: arial, helvetica, geneva; font-size: 28px; font-weight: bold}
+body { font-family: arial, helvetica, geneva; font-size: 10pt; clip: rect( ); margin-top: 5mm; margin-left: 3mm}
+.indextop { font-size: x-large;; font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: bold}
+.indexsub { font-size: xx-small;; font-family: Arial, Helvetica, sans-serif; color: #8080FF}
+div.code {margin:5px; padding:5px; background:#EFEFEF; border:1px solid black;}
\ No newline at end of file
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml1.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml1.png
new file mode 100644
index 0000000..cd6b78e
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml1.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml2.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml2.png
new file mode 100644
index 0000000..a8add6a
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml2.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml3.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml3.png
new file mode 100644
index 0000000..27c98ed
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml3.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml4.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml4.png
new file mode 100644
index 0000000..dcb678d
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/edit_xml4.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog1.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog1.png
new file mode 100644
index 0000000..e3caa84
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog1.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog2.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog2.png
new file mode 100644
index 0000000..960daf6
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog2.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog3.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog3.png
new file mode 100644
index 0000000..d1806ca
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_plugin_project_dialog3.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_project_dialog.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_project_dialog.png
new file mode 100644
index 0000000..8d12887
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/new_project_dialog.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_manifest.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_manifest.png
new file mode 100644
index 0000000..25d6aeb
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_manifest.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_metadata_xml.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_metadata_xml.png
new file mode 100644
index 0000000..bee738d
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/open_metadata_xml.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_dependencies.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_dependencies.png
new file mode 100644
index 0000000..9d935f2
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_dependencies.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions1.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions1.png
new file mode 100644
index 0000000..db15a70
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions1.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions2.png b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions2.png
new file mode 100644
index 0000000..a6fc7a4
--- /dev/null
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/images/plugin_extensions2.png
Binary files differ
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html
index 538d08a..4c081ba 100644
--- a/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html
@@ -7,6 +7,7 @@
<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"/>
+<link rel="stylesheet" href="default_style.css"/>
</head>
<body>
<table summary="" cellspacing="0" cellpadding="0" width="100%">
@@ -17,11 +18,222 @@
</tr>
</table>
<hr/>
+<h3>Summary</h3>
<p>
- CONTENT
+ In this tutorial we will write a plugin that supplies metadata that will be
+ used when editing a JSF JSP page that uses the tag library for the Apache
+ MyFaces Tomahawk JSF component library.
+</p>
+<h3>Introduction</h3>
+<p>
+ This tutorial will walk through the process of writing a plugin that
+ provides additional functionality while editing JSF JSP pages that use the
+ tag library for the Apache MyFaces Tomahawk component library. By supplying
+ metadata for this tag library, code-completion and validation functionality
+ becomes available for attributes of the Tomahawk tags. This plugin will not
+ aim to provide a complete set of metadata for the library, it will simply
+ lay the groundwork and explain the general concepts.
</p>
<p>
- <span style="font-style:italic">Complete information will be available in a future build.</span>
+ It is assumed that the user is already familiar with the use of JSP tags
+ and basic editing of JSP pages. It is further assumed that the user is
+ familiar with adding tag libraries to web projects and correctly specifying
+ their use in JSP pages.
</p>
+<h3>Create New Plug-in Project</h3>
+<p>
+ First we will need to create a new Plug-in Project in order to extend the
+ necessary extension point to supply your metadata. Select <b>File</b> >
+ <b>New</b> > <b>Project...</b> to open the New Project dialog, select
+ <b>Plug-in Project</b> and click <b>Next ></b>.
+</p>
+<img src="images/new_project_dialog.png" border="0" alt="New Project dialog"/>
+<p>
+ Provide an appropiate value for <b>Project name</b>, uncheck <b>Create a
+ Java project</b> (in this example we do not require this to be a Java
+ project, although a Java project is perfectly valid and in some cases may
+ be desirable) and click <b>Next ></b>.
+</p>
+<img src="images/new_plugin_project_dialog1.png" border="0" alt="New Plug-in Project dialog"/>
+<p>
+ Provide appropriate values for <b>Plug-in Properties</b> and click <b>Next
+ ></b>.
+</p>
+<img src="images/new_plugin_project_dialog2.png" border="0" alt="New Plug-in Project dialog"/>
+<p>
+ Uncheck <b>Create a plug-in using one of the templates</b> and click
+ <b>Finish</b> to complete creation of the plug-in project.
+</p>
+<img src="images/new_plugin_project_dialog3.png" border="0" alt="New Plug-in Project dialog"/>
+<h3>Configure Plug-in Project</h3>
+<p>
+ In the <b>Package Explorer</b>, double-click <b>MANIFEST.MF</b> to open it
+ in the Plug-in Manifest Editor (if it is not already open as a result of
+ creating the project in the previous step).
+</p>
+<img src="images/open_manifest.png" border="0" alt="Open MANIFEST.MF"/>
+<p>
+ In the Plug-in Manifest Editor, select the <b>Dependencies</b> tab and
+ click the <b>Add...</b> button to add
+ <b>org.eclipse.jst.jsf.contentmodel.annotations</b> as a required plug-in.
+</p>
+<img src="images/plugin_dependencies.png" border="0" alt="Plug-in Dependencies"/>
+<p>
+ In the Plug-in Manifest Editor, select the <b>Extensions</b> tab and click
+ the <b>Add...</b> button to add
+ <b>org.eclipse.jst.jsf.contentmodel.annotations.annotationFiles</b> as an
+ extension.
+</p>
+<img src="images/plugin_extensions1.png" border="0" alt="Plug-in Extensions"/>
+<p>
+ Still in the Plug-in Manifest Editor and on the Extensions tab, right-click
+ <b>org.eclipse.jst.jsf.contentmodel.annotations.annotationFiles</b> and
+ select <b>New</b> > <b>annotationFile</b>. Set the <b>uri</b> to
+ <b>http://myfaces.apache.org/tomahawk</b> and the <b>location</b> to
+ <b>metadata/apache_tomahawk.xml</b> (the value of location is the
+ plugin-relative location of the metadata file that we will create in a
+ later step and so is arbitrary, while the value of uri <i>must</i>
+ correspond with the tag library's specified URI). For this example, we
+ will not be specifying values for the optional properties <b>locator</b>
+ and <b>parser</b>. Save your work and close the Plug-in Manifest Editor if
+ you desire.
+</p>
+<img src="images/plugin_extensions2.png" border="0" alt="Plug-in Extensions"/>
+<h3>Create Metadata File</h3>
+<p>
+ Create a new folder and XML file, such that from the plug-in project root
+ you now have the file <b>metadata/apache_tomahawk.xml</b> (which matches
+ the value of <b>location</b> as set in the previous step). Double-click
+ this file to open in the XML editor.
+</p>
+<img src="images/open_metadata_xml.png" border="0" alt="Open metadata/apache_tomahawk.xml"/>
+<p>
+ Working in the XML editor, paste the following XML into the
+ <b>metadata/apache_tomahawk.xml</b> file. We now have a minimal, legal
+ (although not yet incredibly useful) metadata file.
+</p>
+<div class="code"><pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<p:grammar-annotations
+ xmlns:p="http://org.eclipse.jst.jsf.contentmodel.annotations/grammarAnnotationSchema"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://org.eclipse.jst.jsf.contentmodel.annotations/grammarAnnotationSchema ../../org.eclipse.jst.jsf.contentmodel.annotations/schema/grammar-annotations.xsd">
+ <cm-element name="">
+ </cm-element>
+</p:grammar-annotations>
+</pre></div>
+<p>
+ In this example, we will be providing metadata for Tomahawk's <b>popup</b>
+ tag. To begin, we need to specify in our metadata file the name of the
+ element (tag) that we are annotating. We do this by simply setting the
+ <b>name</b> attribute of the <b>cm-element</b> element to <b>popup</b>,
+ as seen below.
+</p>
+<img src="images/edit_xml1.png" border="0" alt="Edit Metadata"/>
+<p>
+ We continue by specifying properties for the <b>popup</b> tag's attributes.
+ We do this by adding <b>cm-attribute</b> elements to our XML file. We will
+ start with the <b>displayAtDistanceX</b> and <b>displayAtDistanceY</b>
+ attributes, the values of which must be an integer. We specify this by
+ adding the appropriate <b>cm-attribute</b> and <b>property</b> elements to
+ our XML file, as seen below. (The
+ "org.eclipse.jst.jsf.taglibprocessing.attributevalues.IntegerType" runtime
+ type is one of the types pre-defined in the
+ org.eclipse.jst.jsf.taglibprocessing plug-in.)
+</p>
+<img src="images/edit_xml2.png" border="0" alt="Edit Metadata"/>
+<p>
+ We continue by specifying appropriate <b>cm-attribute</b> and
+ <b>property</b> elements for the <b>closePopupOnExitingElement</b> and
+ <b>closePopupOnExitingPopup</b> attributes, the values of which must be
+ boolean, and the default value of each is "true". As seen below, we use
+ the "org.eclipse.jst.jsf.taglibprocessing.attributevalues.BooleanType"
+ runtime type to specify this.
+</p>
+<img src="images/edit_xml3.png" border="0" alt="Edit Metadata"/>
+<p>
+ To complete the metadata for this example, we will address those attributes
+ which have the same meaning no matter which element upon which they are
+ defined. Examples are <b>id</b> and <b>binding</b>. In these cases, rather
+ than specify the metadata for every element, we can specify the metadata
+ once for any element by using "*" as the value of the <b>cm-element</b>'s
+ <b>name</b> attribute. As seen below, we now do this for the <b>id</b> and
+ <b>binding</b> attributes using pre-defined runtime types and properties.
+</p>
+<img src="images/edit_xml4.png" border="0" alt="Edit Metadata"/>
+<p>
+ This plugin can now be packaged and deployed to Eclipse in order to get
+ advanced editing capabilities (e.g. content-assist and validation) for the
+ attributes of the elements of the Tomahawk tag library that we have defined
+ here. Obviously, this example only covers part of the tag library, but
+ hopefully serves as a starting point for interested developers.
+</p>
+<p>
+ For reference, the contents of the completed example
+ <b>metadata/apache_tomahawk.xml</b> file follows.
+</p>
+<div class="code"><pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<p:grammar-annotations
+ xmlns:p="http://org.eclipse.jst.jsf.contentmodel.annotations/grammarAnnotationSchema"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://org.eclipse.jst.jsf.contentmodel.annotations/grammarAnnotationSchema ../../org.eclipse.jst.jsf.contentmodel.annotations/schema/grammar-annotations.xsd">
+ <cm-element name="popup">
+ <cm-attribute name="displayAtDistanceX">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.IntegerType
+ </value>
+ </property>
+ </cm-attribute>
+ <cm-attribute name="displayAtDistanceY">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.IntegerType
+ </value>
+ </property>
+ </cm-attribute>
+ <cm-attribute name="closePopupOnExitingElement">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.BooleanType
+ </value>
+ </property>
+ <property name="default-value">
+ <value>true</value>
+ </property>
+ </cm-attribute>
+ <cm-attribute name="closePopupOnExitingPopup">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.BooleanType
+ </value>
+ </property>
+ <property name="default-value">
+ <value>true</value>
+ </property>
+ </cm-attribute>
+ </cm-element>
+ <cm-element name="*">
+ <cm-attribute name="id">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.ComponentIDType
+ </value>
+ </property>
+ </cm-attribute>
+ <cm-attribute name="binding">
+ <property name="attribute-value-runtime-type">
+ <value>
+ org.eclipse.jst.jsf.taglibprocessing.attributevalues.ComponentBindingType
+ </value>
+ </property>
+ <property name="runtime-return-type">
+ <value>javax.faces.component.UIComponent</value>
+ </property>
+ </cm-attribute>
+ </cm-element>
+</p:grammar-annotations>
+</pre></div>
</body>
</html>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml b/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml
index 9f5153a..5e264ab 100644
--- a/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml
+++ b/plugins/org.eclipse.jst.jsf.doc.dev/tocprogrammersguide.xml
@@ -2,7 +2,7 @@
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Programmer's Guide" link_to="toc.xml#jsf_dev_programmersguide">
- <topic label="Creating Plugin-Provided JSF Libaries" href="html/programmersguide/creating_plugin_provided_jsf_libraries.html"/>
+ <topic label="Creating Plugin-Provided JSF Libraries" href="html/programmersguide/creating_plugin_provided_jsf_libraries.html"/>
<topic label="Contributing JSP Source Page Editing Services for a Tag Library" href="html/programmersguide/contributing_jsp_source_page_editing_services_for_a_tag_library.html"/>
<topic label="JSF Expression Language Tooling" href="html/programmersguide/jsf_expression_language_tooling.html">
<topic label="Using Context Resolvers" href="html/programmersguide/using_context_resolvers.html"/>
