<commit_before><chapter id="taglib">
    <title>Tag Libraries</title>
    
    <sect1 id="taglib-use">
        <title>Using Tags</title>
        <sect2 id="taglib-use-normal">
			<title>Tag Namespaces</title>
			<para>
				Facelets uses valid XML with namespace support for compilation.  If you are new to XML, there are great resources online, such as http://www.w3schools.com.  To use a library of tags, you would 'include' the library by declaring a namespace.  Declaring a namespace involves using the library's URI (or URL) and mapping it to a prefix.
			</para>
			<programlisting><![CDATA[<!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"
      xmlns:h="http://java.sun.com/jsf/html">
      
<body>
  <h:inputText value="#{hello.world}"/>
</body>

</html>]]></programlisting>
		<para>
			In the example above, we've declared 2 namespaces:
		</para>
		<itemizedlist>
			<listitem>
				<para><literal>xmlns="http://www.w3.org/1999/xhtml"</literal> Says every tag without a prefix, such as <literal><![CDATA[<body>]]></literal>, are part of XHTML.</para>
			</listitem>
			<listitem>
				<para><literal>xmlns:h="http://java.sun.com/jsf/html"</literal> Maps the prefix <literal>h:</literal> to the JSF HTML library.</para>
			</listitem>
		</itemizedlist>
        </sect2>
        <sect2 id="taglib-use-jsfc">
			<title>Using 'jsfc'</title>
			<para>
				Facelets provides you the ability to have one XML element in the page be converted to another at compile time by specifying the <literal>jsfc</literal> attribute.
			</para>
			<programlisting><![CDATA[<!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"
      xmlns:h="http://java.sun.com/jsf/html">
      
<body>
  <input type="text" jsfc="h:inputText" value="#{hello.world}" />
</body>

</html>]]></programlisting>
			<para>
				The <literal><![CDATA[<input>]]></literal> tag above is readable/displayable in browsers and visual tools as a normal text field.  It would be nice to use that same text field in JavaServer Faces, so we provide the <literal>jsfc="h:inputText"</literal>.  This declaration tells the compiler to resolve the <literal><![CDATA[<input>]]></literal> tag as an <literal><![CDATA[<h:inputText>]]></literal> (the same as above).  Note, the same rules for namespaces and naming apply to the value of the <literal>jsfc</literal> attribute.
			</para>
        </sect2>
        <sect2 id="taglib-use-unresolved">
			<title>Unresolved Namespaces</title>

			<para>
				If there is a namespace that is
				unresolved and/or the tag's name is not
				found in any library, then it is treated
				as regular text.  If your tag or
				component isn't showing up in your
				rendered page, check the source of page
				and see if the tag was simply ignored.
				This usually means you either misspelled
				the tag's name or you are using the
				wrong namespace for your library.
			</para>

        </sect2>
	</sect1>
    
    <sect1 id="taglib-available">
        <title>Available Tag Libraries</title>
        
        <sect2 id="taglib-available-spec">
			<title>JavaServer Faces Specification</title>
			<para>
				Facelets comes with support for all tags (components) included in the JavaServer Faces Specification.  Great care was taken to mimic the specification's JSP tag counterparts to leverage existing knowledge and available documentation.  For development, you may reference the 'Tag Library Documentation' at:
			</para>
			<itemizedlist>
				<listitem>http://java.sun.com/j2ee/javaserverfaces/reference/api/index.html</listitem>
			</itemizedlist>
			<table>
				<title>Specification Tag Libraries</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Namespace</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>http://java.sun.com/jsf/core</entry>
							<entry>The core JavaServer Faces custom actions that are independent of any RenderKit used.</entry>
						</row>
						<row>
							<entry>http://java.sun.com/jsf/html</entry>
							<entry>This tag library contains JavaServer Faces component tags for all UIComponent + HTML RenderKit Renderer combinations defined in the JavaServer Faces Specification.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		  </sect2>
		  
		  <sect2 id="taglib-available-ui">
			<title>Templating Library</title>
			<para>
				You can read all about the cool templating features in Facelets in <xref linkend="template"/>.
			</para>
		  </sect2>
		  
		  <sect2 id="taglib-available-jstl">
			<title>JSTL Support</title>
			<para>
				TODO (partial)
			</para>
		  </sect2>
		  
		  <sect2 id="taglib-available-adf">
			<title>Oracle ADF Faces</title>
			<para>
				Oracle ADF Faces will be unofficially supported by Facelets.  This work is not being done by Oracle but by independent contributions.
			</para>
			<para>
				
			</para>
		  </sect2>
		  
	</sect1>
	
	<sect1 id="taglib-function">
		<title>Functions</title>
		<para>
			As part of the EL Specification, you can incorporate <literal>static</literal> Java methods into your documents.  The JSTL library already has some of these functions available, see <xref linkend="taglib-available-jstl"/>.
		</para>
		<para>
			Functions are declared within EL in the following format: <literal>#{fn:sizeOf(myCollection)}</literal>.  What that line says is to reference the tag library using the prefix <literal>fn</literal> for a function named <literal>sizeOf</literal>.  This syntax should feel similar to what's required for using tags from imported libraries.
		</para>
		<para>
			Any tag library can offer any amount of functions.  Please reference the particular library's documentation for function names and parameters information.
		</para>
	</sect1>
    
    <sect1 id="taglib-web">
		<title>Loading Libraries</title>
		<para>
			Tag libraries can be loaded multiple ways.  First Facelets will load all libraries from your classpath (including packaged Jars) and then any libraries you have specified in your <literal>web.xml</literal>.
		</para>
		<itemizedlist>
			<listitem>
				<para>
					When Facelets searches the classpath, it will attempt to load any file with the extension <literal>*.taglib.xml</literal> from the <literal>/meta-inf</literal> folder of your Jars.  For example, <literal>/meta-inf/mycompany.taglib.xml</literal> would be found by Facelets while <literal>/mycompany.taglib.xml</literal> and <literal>/meta-inf/mycompany.xml</literal> would not.  See <xref linkend="config-logging"/> for information on recieving debug information on the libraries loaded.
				</para>
			</listitem>
			<listitem>
				<para>
					Facelets will check for an initialization parameter from your <literal>web.xml</literal> and load all libraries specified there relative to your application's root. See <xref linkend="config-webapp-init"/> for details on the parameter.  This is an ideal way to declare specialized tags for a particular application; tags that aren't necessarily distributed with code in Jars.
				</para>
			</listitem>
		</itemizedlist>
	</sect1>
	
	<sect1 id="taglib-create">
        <title>Creating Tag Libraries</title>
        
        <preface id="taglib-create-overview">
			<title>Overview</title>
			<para>
				Facelets allows you to configure custom tag libraries in a short amount of time.  This section will focus on defining tag libraries in XML which can be automatically loaded by Facelets compiler as described in <xref linkend="taglib-web"/>.
			</para>
        </preface>
        
        <sect2 id="taglib-create-schema">
			<title>Tag Library Schema</title>
			<para>
				The schema (or DTD) for Facelets is extremely simple.  Future releases of Facelets will actually just use your <literal>faces-config.xml</literal> files the same way a visual tool would for determining required attributes and namespaces.
			</para>
			<para>
				Facelets currently uses the following doc type:
			</para>
			<programlisting><![CDATA[<!DOCTYPE facelet-taglib PUBLIC
  "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN"
  "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">]]></programlisting>
			<para>
				This is the (simple) DTD that Facelets uses:
			</para>
			<programlisting><![CDATA[<!ELEMENT facelet-taglib (library-class|(namespace,(tag|function)+))>
<!ATTLIST facelet-taglib xmlns CDATA #FIXED "http://java.sun.com/JSF/Facelet">
<!ELEMENT namespace (#PCDATA)>
<!ELEMENT library-class (#PCDATA)>
<!ELEMENT tag (tag-name,(handler-class|component|converter|validator|source))>
<!ELEMENT tag-name (#PCDATA)>
<!ELEMENT handler-class (#PCDATA)>
<!ELEMENT component (component-type,renderer-type?)>
<!ELEMENT component-type (#PCDATA)>
<!ELEMENT renderer-type (#PCDATA)>
<!ELEMENT converter (converter-id)>
<!ELEMENT converter-id (#PCDATA)>
<!ELEMENT validator (validator-id)>
<!ELEMENT validator-id (#PCDATA)>
<!ELEMENT source (#PCDATA)>
<!ELEMENT function (function-name,function-class,function-signature)>
<!ELEMENT function-name (#PCDATA)>
<!ELEMENT function-class (#PCDATA)>
<!ELEMENT function-signature (#PCDATA)>]]></programlisting>
			<para>
				As you can see, JSF entities are treated as first class citizens in Facelets' tag libraries.  A couple things to observe from the schema above:
			</para>
			<itemizedlist>
			<listitem>
				<para>
					The definition of a tag library (including namespace) can be delegated to the class specified in the <literal>library-class</literal> element.  The class specified must implement <literal>com.sun.facelets.tag.TagLibrary</literal>.  This is useful if you would like to maintain your tag library in Java, but would like to have it automatically picked up by the compiler by placing an XML file in your Jar's <literal>meta-inf</literal> folder.
				</para>
			</listitem>
			<listitem>
				<para>
					Each document (not specified by <literal>library-class</literal>) requires a <literal>namespace</literal> element which will match the namespace used in your document, see <xref linkend="taglib-use-normal"/>.
				</para>
			</listitem>
			<listitem>
				<para>
					The rest of the document is made up of <literal>tag</literal> and <literal>function</literal> elements.  Tag elements require a <literal>tag-name</literal> and can take on different behavior depending on what you would like Facelets to handle for you.  Functions can also be specified under the library's namespaces and follow the same signature as in JSP TLD files.
				</para>
			</listitem>
			</itemizedlist>
			<para>
				The following sections describe how to integrate your objects within the XML tag library.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-component">
			<title>UIComponents</title>
			<para>
				<literal>UIComponents</literal> can be auto-wired by using the <literal>component</literal> element in your tag library.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>bar</tag-name>
  <component>
    <component-type>com.mycompany.Data</component-type>
    <renderer-type>com.mycompany.Bar</renderer-type>
  </component>
</tag>]]></programlisting>
			<para>
				In the above example, we are binding a component of type (not Class) <literal>com.mycompany.Data</literal> to the tag name <literal>bar</literal>.  A <literal>renderer-type</literal> is also provided, but not required since <literal>UIComponents</literal> can easily render themselves.
			</para>

			<para>
				Based on if your component implements
				<literal>ActionSource[2]</literal>,
				<literal>ValueHolder</literal>, or
				<literal>EditableValueHolder</literal>,
				Facelets will take care of auto-wiring
				those standard attributes according to
				the specification.  Facelets differs
				greatly from JSP in this important
				regard, and this difference is a feature
				of Facelets that takes advantage of the
				dynamism in JavaServer Faces that is
				wasted on JSP.  Specifically, any tag
				attribute in a Facelets page is
				tolerated.  If the value of the
				attribute is a ValueExpression, and tag
				is associated with a UIComponent, the
				expression is stored in the components's
				ValueExpression Map.  Otherwise,
				Facelets looks for a JavaBeans property
				on the component whose name is equal to
				the tag attribute name.  If it exists,
				its setter is called with the value of
				the tag attribute.  If it doesn't exist,
				an entry is created in the generic
				attribute set for the component, the
				value of which is the value of the tag
				attribute.  The upshot of all this is
				that turnaround time is greatly reduced
				because you can modify the component
				and/or renderer without having to change
				a TLD.  Of course, the downside is that
				any attribute is legal, but errors in
				that regard are logged in the logging
				system.</para>

                                <para>This approach exemplifies a
                                general philosophy of Facelets, sensible
                                default behavior from the perspective of
                                the page developer.</para>

                                <para>The attribute wiring behavior also
                                applies to validators, EL expressions,
                                converters, etc.  Any additional
                                properties on your component will also
                                be wired for you too, just as JSP sets
                                the properties on a
                                <literal>JspTag</literal>.  If you think
                                that Facelets can't handle the special
                                wiring your component needs, then skip
                                to <xref linkend="dev-meta-component"/>.
			</para>

			<para>
				If you've just created a <literal>UIComponent</literal> from scratch and you are not sure how to integrate it into JavaServer Faces, here's all the code you need:
			</para>
			<programlisting><![CDATA[<faces-config>
  <component>
    <component-type>com.mycompany.Data</component-type>
    <component-class>com.mycompany.jsf.components.UIDataComponent</component-class>
  </component>
</faces-config>]]></programlisting>
			<para>
				Notice that the <literal>component-type</literal> matches the one used in the Facelets tag library XML.  This degree of indirection by referencing components by type increases the maintainability and portability of JavaServer Faces components.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-validator">
			<title>Validators</title>
			<para>
				<literal>Validators</literal> can also be added to Facelets with the <literal>validator</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>validateEmail</tag-name>
  <validator>
    <validator-id>faces.validator.Email</validator-id>
  </validator>
</tag>]]></programlisting>
			<para>
				Again, we reference JSF entities by type or id.  Facelets will also take care of wiring attributes directly to your <literal>Validator</literal> by matching attribute name to property name.  If you would like to provide special behavior or wire odd properties, you can jump ahead to <xref linkend="dev-meta-validator"/>.
			</para>
			<para>
				If you've just written your own <literal>Validator</literal>, you can add it to your JSF Application with the following snippet in your <literal>faces-config.xml</literal>:
			</para>
			<programlisting><![CDATA[<faces-config>
  <validator>
    <validator-id>faces.validator.Email</validator-id>
    <validator-class>com.mycompany.jsf.validate.EmailValidator</validator-class>
  </validator>
</faces-config>]]></programlisting>
        </sect2>
        
        <sect2 id="taglib-create-converter">
			<title>Converters</title>
			<para>
				<literal>Converters</literal> can be registered with Facelets by adding a <literal>converter</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>convertMoney</tag-name>
  <converter>
    <converter-id>faces.convert.Money</converter-id>
  </converter>
</tag>]]></programlisting>
			<para>
				Converters are referenced by id.  Facelets will take care of wiring attributes directly to your <literal>Converter</literal> by matching attribute name to property name.  If you would like to provide special behavior or wire odd properties, you can jump ahead to <xref linkend="dev-meta-converter"/>.
			</para>
			<para>
				If you've just written your own <literal>Converter</literal>, you can add it to your JSF Application with the following snippet in your <literal>faces-config.xml</literal>:
			</para>
			<programlisting><![CDATA[<faces-config>
  <converter>
    <converter-id>faces.convert.Money</converter-id>
    <converter-class>com.mycompany.jsf.convert.ConvertMoney</converter-class>
  </converter>
</faces-config>]]></programlisting>
        </sect2>
        
        <sect2 id="taglib-create-source">
			<title>Tag (Source) Files</title>
			<para>
				Facelets has a feature similar to JSP's Tag Files.  Within your tag library definition, you can provide a <literal>source</literal> element that points to a another file, that will be compiled into another Facelet.  Since this file can be referenced by <literal>tag-name</literal>, you can easily include that Facelets into another and pass variable data to it.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>echo</tag-name>
  <source>tags/echo.xhtml</source>
</tag>]]></programlisting>
			<para>
				The <literal>echo.xhtml</literal> will be included anytime a developer uses the <literal>echo</literal> tag.  The following is an example tag file:
			</para>
			<programlisting><![CDATA[<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets">
  <span class="message">#{msg}</span>
</ui:composition>]]></programlisting>
			<para>
				This tag file can be included and any variable used within the tag file can be passed as an attribute:
			</para>
			<programlisting><![CDATA[<my:echo msg="#{bean.warningMessage}"/>]]></programlisting>
			<para>
				In this example, the <literal>msg</literal> attribute is assigned to <literal>#{bean.warningMessage}</literal> and then referenceable within <literal>echo.xhtml</literal> under the variable <literal>msg</literal>.
			</para>
			<para>
				This was a simple example, but you can do some fairly cool things with building reusable components in your pages.  Going one step further, you may provide a body to your custom tag, by placing a <literal><![CDATA[<ui:insert/>]]></literal> as a place for body inclusion.  See <xref linkend="template"/> for more information.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-custom">
			<title>Custom Tags</title>
			<para>
				Facelets allows you to write stateless tags that can be used in dictating component tree creation.  This includes JSTL-like functionality that may be tied to business logic.  Including your custom tag into your library requires using the <literal>handler-class</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>if</tag-name>
  <handler-class>com.mycompany.IfHandler</handler-class>
</tag>]]></programlisting>
			<para>
				All tags in a Facelets extend <literal>com.sun.facelets.tag.TagHandler</literal> which provides some base functionality for tying XML data to your Java code.  To read more about creating custom tags, jump to <xref linkend="dev-taghandler"/>.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-function">
			<title>Function Specification</title>
			<para>
				You may reference functions within your tag library.  Functions are represented by static methods in Java.
			</para>
			<programlisting><![CDATA[<function>
  <function-name>reverse</function-name>
  <function-class>com.mycompany.Functions</function-class>
  <function-signature>java.lang.String reverse(java.lang.String)</function-signature>
</function>]]></programlisting>
			<para>
				The <literal>function</literal> element is a top level entity like the <literal>tag</literal> element.  You need to specify both the class type and the method signature that Facelets should use.  All class names in the signature must be fully qualified, with the exception of primitives such as <literal>int</literal> or <literal>boolean</literal>.
			</para>
			<para>
				In this example, you would be able to reference this function with a namespace prefix in your document, such as <literal>#{my:reverse(employee.name}}</literal>.  See <xref linkend="taglib-function"/> for more information on function use in your pages.
			</para>
        </sect2>
        
	</sect1>
	
</chapter>


<commit_msg>clarified ADF mention<commit_after><chapter id="taglib">
    <title>Tag Libraries</title>
    
    <sect1 id="taglib-use">
        <title>Using Tags</title>
        <sect2 id="taglib-use-normal">
			<title>Tag Namespaces</title>
			<para>
				Facelets uses valid XML with namespace support for compilation.  If you are new to XML, there are great resources online, such as http://www.w3schools.com.  To use a library of tags, you would 'include' the library by declaring a namespace.  Declaring a namespace involves using the library's URI (or URL) and mapping it to a prefix.
			</para>
			<programlisting><![CDATA[<!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"
      xmlns:h="http://java.sun.com/jsf/html">
      
<body>
  <h:inputText value="#{hello.world}"/>
</body>

</html>]]></programlisting>
		<para>
			In the example above, we've declared 2 namespaces:
		</para>
		<itemizedlist>
			<listitem>
				<para><literal>xmlns="http://www.w3.org/1999/xhtml"</literal> Says every tag without a prefix, such as <literal><![CDATA[<body>]]></literal>, are part of XHTML.</para>
			</listitem>
			<listitem>
				<para><literal>xmlns:h="http://java.sun.com/jsf/html"</literal> Maps the prefix <literal>h:</literal> to the JSF HTML library.</para>
			</listitem>
		</itemizedlist>
        </sect2>
        <sect2 id="taglib-use-jsfc">
			<title>Using 'jsfc'</title>
			<para>
				Facelets provides you the ability to have one XML element in the page be converted to another at compile time by specifying the <literal>jsfc</literal> attribute.
			</para>
			<programlisting><![CDATA[<!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"
      xmlns:h="http://java.sun.com/jsf/html">
      
<body>
  <input type="text" jsfc="h:inputText" value="#{hello.world}" />
</body>

</html>]]></programlisting>
			<para>
				The <literal><![CDATA[<input>]]></literal> tag above is readable/displayable in browsers and visual tools as a normal text field.  It would be nice to use that same text field in JavaServer Faces, so we provide the <literal>jsfc="h:inputText"</literal>.  This declaration tells the compiler to resolve the <literal><![CDATA[<input>]]></literal> tag as an <literal><![CDATA[<h:inputText>]]></literal> (the same as above).  Note, the same rules for namespaces and naming apply to the value of the <literal>jsfc</literal> attribute.
			</para>
        </sect2>
        <sect2 id="taglib-use-unresolved">
			<title>Unresolved Namespaces</title>

			<para>
				If there is a namespace that is
				unresolved and/or the tag's name is not
				found in any library, then it is treated
				as regular text.  If your tag or
				component isn't showing up in your
				rendered page, check the source of page
				and see if the tag was simply ignored.
				This usually means you either misspelled
				the tag's name or you are using the
				wrong namespace for your library.
			</para>

        </sect2>
	</sect1>
    
    <sect1 id="taglib-available">
        <title>Available Tag Libraries</title>
        
        <sect2 id="taglib-available-spec">
			<title>JavaServer Faces Specification</title>
			<para>
				Facelets comes with support for all tags (components) included in the JavaServer Faces Specification.  Great care was taken to mimic the specification's JSP tag counterparts to leverage existing knowledge and available documentation.  For development, you may reference the 'Tag Library Documentation' at:
			</para>
			<itemizedlist>
				<listitem>http://java.sun.com/j2ee/javaserverfaces/reference/api/index.html</listitem>
			</itemizedlist>
			<table>
				<title>Specification Tag Libraries</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Namespace</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>http://java.sun.com/jsf/core</entry>
							<entry>The core JavaServer Faces custom actions that are independent of any RenderKit used.</entry>
						</row>
						<row>
							<entry>http://java.sun.com/jsf/html</entry>
							<entry>This tag library contains JavaServer Faces component tags for all UIComponent + HTML RenderKit Renderer combinations defined in the JavaServer Faces Specification.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		  </sect2>
		  
		  <sect2 id="taglib-available-ui">
			<title>Templating Library</title>
			<para>
				You can read all about the cool templating features in Facelets in <xref linkend="template"/>.
			</para>
		  </sect2>
		  
		  <sect2 id="taglib-available-jstl">
			<title>JSTL Support</title>
			<para>
				TODO (partial)
			</para>
		  </sect2>
		  
		  <sect2 id="taglib-available-adf">
			<title>Oracle ADF Faces</title>
			<para>
				Oracle ADF Faces will be unofficially supported by Facelets.  This work is being done by independent contributions after the EA19 release of ADF Faces.
			</para>
		  </sect2>
		  
	</sect1>
	
	<sect1 id="taglib-function">
		<title>Functions</title>
		<para>
			As part of the EL Specification, you can incorporate <literal>static</literal> Java methods into your documents.  The JSTL library already has some of these functions available, see <xref linkend="taglib-available-jstl"/>.
		</para>
		<para>
			Functions are declared within EL in the following format: <literal>#{fn:sizeOf(myCollection)}</literal>.  What that line says is to reference the tag library using the prefix <literal>fn</literal> for a function named <literal>sizeOf</literal>.  This syntax should feel similar to what's required for using tags from imported libraries.
		</para>
		<para>
			Any tag library can offer any amount of functions.  Please reference the particular library's documentation for function names and parameters information.
		</para>
	</sect1>
    
    <sect1 id="taglib-web">
		<title>Loading Libraries</title>
		<para>
			Tag libraries can be loaded multiple ways.  First Facelets will load all libraries from your classpath (including packaged Jars) and then any libraries you have specified in your <literal>web.xml</literal>.
		</para>
		<itemizedlist>
			<listitem>
				<para>
					When Facelets searches the classpath, it will attempt to load any file with the extension <literal>*.taglib.xml</literal> from the <literal>/meta-inf</literal> folder of your Jars.  For example, <literal>/meta-inf/mycompany.taglib.xml</literal> would be found by Facelets while <literal>/mycompany.taglib.xml</literal> and <literal>/meta-inf/mycompany.xml</literal> would not.  See <xref linkend="config-logging"/> for information on recieving debug information on the libraries loaded.
				</para>
			</listitem>
			<listitem>
				<para>
					Facelets will check for an initialization parameter from your <literal>web.xml</literal> and load all libraries specified there relative to your application's root. See <xref linkend="config-webapp-init"/> for details on the parameter.  This is an ideal way to declare specialized tags for a particular application; tags that aren't necessarily distributed with code in Jars.
				</para>
			</listitem>
		</itemizedlist>
	</sect1>
	
	<sect1 id="taglib-create">
        <title>Creating Tag Libraries</title>
        
        <preface id="taglib-create-overview">
			<title>Overview</title>
			<para>
				Facelets allows you to configure custom tag libraries in a short amount of time.  This section will focus on defining tag libraries in XML which can be automatically loaded by Facelets compiler as described in <xref linkend="taglib-web"/>.
			</para>
        </preface>
        
        <sect2 id="taglib-create-schema">
			<title>Tag Library Schema</title>
			<para>
				The schema (or DTD) for Facelets is extremely simple.  Future releases of Facelets will actually just use your <literal>faces-config.xml</literal> files the same way a visual tool would for determining required attributes and namespaces.
			</para>
			<para>
				Facelets currently uses the following doc type:
			</para>
			<programlisting><![CDATA[<!DOCTYPE facelet-taglib PUBLIC
  "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN"
  "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">]]></programlisting>
			<para>
				This is the (simple) DTD that Facelets uses:
			</para>
			<programlisting><![CDATA[<!ELEMENT facelet-taglib (library-class|(namespace,(tag|function)+))>
<!ATTLIST facelet-taglib xmlns CDATA #FIXED "http://java.sun.com/JSF/Facelet">
<!ELEMENT namespace (#PCDATA)>
<!ELEMENT library-class (#PCDATA)>
<!ELEMENT tag (tag-name,(handler-class|component|converter|validator|source))>
<!ELEMENT tag-name (#PCDATA)>
<!ELEMENT handler-class (#PCDATA)>
<!ELEMENT component (component-type,renderer-type?)>
<!ELEMENT component-type (#PCDATA)>
<!ELEMENT renderer-type (#PCDATA)>
<!ELEMENT converter (converter-id)>
<!ELEMENT converter-id (#PCDATA)>
<!ELEMENT validator (validator-id)>
<!ELEMENT validator-id (#PCDATA)>
<!ELEMENT source (#PCDATA)>
<!ELEMENT function (function-name,function-class,function-signature)>
<!ELEMENT function-name (#PCDATA)>
<!ELEMENT function-class (#PCDATA)>
<!ELEMENT function-signature (#PCDATA)>]]></programlisting>
			<para>
				As you can see, JSF entities are treated as first class citizens in Facelets' tag libraries.  A couple things to observe from the schema above:
			</para>
			<itemizedlist>
			<listitem>
				<para>
					The definition of a tag library (including namespace) can be delegated to the class specified in the <literal>library-class</literal> element.  The class specified must implement <literal>com.sun.facelets.tag.TagLibrary</literal>.  This is useful if you would like to maintain your tag library in Java, but would like to have it automatically picked up by the compiler by placing an XML file in your Jar's <literal>meta-inf</literal> folder.
				</para>
			</listitem>
			<listitem>
				<para>
					Each document (not specified by <literal>library-class</literal>) requires a <literal>namespace</literal> element which will match the namespace used in your document, see <xref linkend="taglib-use-normal"/>.
				</para>
			</listitem>
			<listitem>
				<para>
					The rest of the document is made up of <literal>tag</literal> and <literal>function</literal> elements.  Tag elements require a <literal>tag-name</literal> and can take on different behavior depending on what you would like Facelets to handle for you.  Functions can also be specified under the library's namespaces and follow the same signature as in JSP TLD files.
				</para>
			</listitem>
			</itemizedlist>
			<para>
				The following sections describe how to integrate your objects within the XML tag library.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-component">
			<title>UIComponents</title>
			<para>
				<literal>UIComponents</literal> can be auto-wired by using the <literal>component</literal> element in your tag library.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>bar</tag-name>
  <component>
    <component-type>com.mycompany.Data</component-type>
    <renderer-type>com.mycompany.Bar</renderer-type>
  </component>
</tag>]]></programlisting>
			<para>
				In the above example, we are binding a component of type (not Class) <literal>com.mycompany.Data</literal> to the tag name <literal>bar</literal>.  A <literal>renderer-type</literal> is also provided, but not required since <literal>UIComponents</literal> can easily render themselves.
			</para>

			<para>
				Based on if your component implements
				<literal>ActionSource[2]</literal>,
				<literal>ValueHolder</literal>, or
				<literal>EditableValueHolder</literal>,
				Facelets will take care of auto-wiring
				those standard attributes according to
				the specification.  Facelets differs
				greatly from JSP in this important
				regard, and this difference is a feature
				of Facelets that takes advantage of the
				dynamism in JavaServer Faces that is
				wasted on JSP.  Specifically, any tag
				attribute in a Facelets page is
				tolerated.  If the value of the
				attribute is a ValueExpression, and tag
				is associated with a UIComponent, the
				expression is stored in the components's
				ValueExpression Map.  Otherwise,
				Facelets looks for a JavaBeans property
				on the component whose name is equal to
				the tag attribute name.  If it exists,
				its setter is called with the value of
				the tag attribute.  If it doesn't exist,
				an entry is created in the generic
				attribute set for the component, the
				value of which is the value of the tag
				attribute.  The upshot of all this is
				that turnaround time is greatly reduced
				because you can modify the component
				and/or renderer without having to change
				a TLD.  Of course, the downside is that
				any attribute is legal, but errors in
				that regard are logged in the logging
				system.</para>

                                <para>This approach exemplifies a
                                general philosophy of Facelets, sensible
                                default behavior from the perspective of
                                the page developer.</para>

                                <para>The attribute wiring behavior also
                                applies to validators, EL expressions,
                                converters, etc.  Any additional
                                properties on your component will also
                                be wired for you too, just as JSP sets
                                the properties on a
                                <literal>JspTag</literal>.  If you think
                                that Facelets can't handle the special
                                wiring your component needs, then skip
                                to <xref linkend="dev-meta-component"/>.
			</para>

			<para>
				If you've just created a <literal>UIComponent</literal> from scratch and you are not sure how to integrate it into JavaServer Faces, here's all the code you need:
			</para>
			<programlisting><![CDATA[<faces-config>
  <component>
    <component-type>com.mycompany.Data</component-type>
    <component-class>com.mycompany.jsf.components.UIDataComponent</component-class>
  </component>
</faces-config>]]></programlisting>
			<para>
				Notice that the <literal>component-type</literal> matches the one used in the Facelets tag library XML.  This degree of indirection by referencing components by type increases the maintainability and portability of JavaServer Faces components.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-validator">
			<title>Validators</title>
			<para>
				<literal>Validators</literal> can also be added to Facelets with the <literal>validator</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>validateEmail</tag-name>
  <validator>
    <validator-id>faces.validator.Email</validator-id>
  </validator>
</tag>]]></programlisting>
			<para>
				Again, we reference JSF entities by type or id.  Facelets will also take care of wiring attributes directly to your <literal>Validator</literal> by matching attribute name to property name.  If you would like to provide special behavior or wire odd properties, you can jump ahead to <xref linkend="dev-meta-validator"/>.
			</para>
			<para>
				If you've just written your own <literal>Validator</literal>, you can add it to your JSF Application with the following snippet in your <literal>faces-config.xml</literal>:
			</para>
			<programlisting><![CDATA[<faces-config>
  <validator>
    <validator-id>faces.validator.Email</validator-id>
    <validator-class>com.mycompany.jsf.validate.EmailValidator</validator-class>
  </validator>
</faces-config>]]></programlisting>
        </sect2>
        
        <sect2 id="taglib-create-converter">
			<title>Converters</title>
			<para>
				<literal>Converters</literal> can be registered with Facelets by adding a <literal>converter</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>convertMoney</tag-name>
  <converter>
    <converter-id>faces.convert.Money</converter-id>
  </converter>
</tag>]]></programlisting>
			<para>
				Converters are referenced by id.  Facelets will take care of wiring attributes directly to your <literal>Converter</literal> by matching attribute name to property name.  If you would like to provide special behavior or wire odd properties, you can jump ahead to <xref linkend="dev-meta-converter"/>.
			</para>
			<para>
				If you've just written your own <literal>Converter</literal>, you can add it to your JSF Application with the following snippet in your <literal>faces-config.xml</literal>:
			</para>
			<programlisting><![CDATA[<faces-config>
  <converter>
    <converter-id>faces.convert.Money</converter-id>
    <converter-class>com.mycompany.jsf.convert.ConvertMoney</converter-class>
  </converter>
</faces-config>]]></programlisting>
        </sect2>
        
        <sect2 id="taglib-create-source">
			<title>Tag (Source) Files</title>
			<para>
				Facelets has a feature similar to JSP's Tag Files.  Within your tag library definition, you can provide a <literal>source</literal> element that points to a another file, that will be compiled into another Facelet.  Since this file can be referenced by <literal>tag-name</literal>, you can easily include that Facelets into another and pass variable data to it.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>echo</tag-name>
  <source>tags/echo.xhtml</source>
</tag>]]></programlisting>
			<para>
				The <literal>echo.xhtml</literal> will be included anytime a developer uses the <literal>echo</literal> tag.  The following is an example tag file:
			</para>
			<programlisting><![CDATA[<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets">
  <span class="message">#{msg}</span>
</ui:composition>]]></programlisting>
			<para>
				This tag file can be included and any variable used within the tag file can be passed as an attribute:
			</para>
			<programlisting><![CDATA[<my:echo msg="#{bean.warningMessage}"/>]]></programlisting>
			<para>
				In this example, the <literal>msg</literal> attribute is assigned to <literal>#{bean.warningMessage}</literal> and then referenceable within <literal>echo.xhtml</literal> under the variable <literal>msg</literal>.
			</para>
			<para>
				This was a simple example, but you can do some fairly cool things with building reusable components in your pages.  Going one step further, you may provide a body to your custom tag, by placing a <literal><![CDATA[<ui:insert/>]]></literal> as a place for body inclusion.  See <xref linkend="template"/> for more information.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-custom">
			<title>Custom Tags</title>
			<para>
				Facelets allows you to write stateless tags that can be used in dictating component tree creation.  This includes JSTL-like functionality that may be tied to business logic.  Including your custom tag into your library requires using the <literal>handler-class</literal> element.
			</para>
			<programlisting><![CDATA[<tag>
  <tag-name>if</tag-name>
  <handler-class>com.mycompany.IfHandler</handler-class>
</tag>]]></programlisting>
			<para>
				All tags in a Facelets extend <literal>com.sun.facelets.tag.TagHandler</literal> which provides some base functionality for tying XML data to your Java code.  To read more about creating custom tags, jump to <xref linkend="dev-taghandler"/>.
			</para>
        </sect2>
        
        <sect2 id="taglib-create-function">
			<title>Function Specification</title>
			<para>
				You may reference functions within your tag library.  Functions are represented by static methods in Java.
			</para>
			<programlisting><![CDATA[<function>
  <function-name>reverse</function-name>
  <function-class>com.mycompany.Functions</function-class>
  <function-signature>java.lang.String reverse(java.lang.String)</function-signature>
</function>]]></programlisting>
			<para>
				The <literal>function</literal> element is a top level entity like the <literal>tag</literal> element.  You need to specify both the class type and the method signature that Facelets should use.  All class names in the signature must be fully qualified, with the exception of primitives such as <literal>int</literal> or <literal>boolean</literal>.
			</para>
			<para>
				In this example, you would be able to reference this function with a namespace prefix in your document, such as <literal>#{my:reverse(employee.name}}</literal>.  See <xref linkend="taglib-function"/> for more information on function use in your pages.
			</para>
        </sect2>
        
	</sect1>
	
</chapter>



{'fraction_non_alphanumeric': 0.11077786841978982, 'fraction_numerical': 0.0035990210662699747, 'mean_word_length': 3.412343849248359, 'pattern_counts': {'":': 0, '<': 1093, '<?xml version=': 0, '>': 1093, 'https://': 0, 'lorem ipsum': 0, 'www.': 12, 'xml': 34}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5863100', 'n_tokens_mistral': 13489, 'n_tokens_neox': 11783, 'n_words': 4207}