AUI Taglib Creation Workflow #

1. Create a new component definition #

X:\portal_dir\util-taglib\src\com\liferay\taglib\liferay-aui.xml

<taglibs>
    ...
    <component name="NewTaglibNameTag"></component>
    ...

You could copy a similar, existing taglib as a base.

• name="PascalCasing"(matches java class, used in inheritance)
• alloyComponent="false" is only for porting existing liferay taglibs (defaults to true). <-- Is this correct?
• module="..." attribute that allows taglib to write JSPs to a different folder, for example, module="aui-util-test" would write the jsps to a folder called aui-util-test.
• bodyContent="true|false" changes support for passing body content into taglibs. If true, creates a start.jsp, otherwise, creates page.jsp.
• taglibs>component>attributes>attribute
• <name>camelCasing</name>
• <inputType> is what the developer can pass into the taglib.
• java.lang.Object (most generic)
• [1,2,3] (ArrayList)
• {a:1,b:2} (HashMap)
• java.lang.String
• This is a sample string (no quotes)
• boolean
• true | false
• java.lang.Integer | java.lang.Double | java.lang.Long
• 1 | 2 | ...
• java.lang.Float
• 1.123 | 32.3 | ...
• <outputType> is the type of variable that the taglib jsp uses internally (does conversion in between)
• java.util.ArrayList
• [1,2,3] (ArrayList)
• java.lang.HashMap
• {a:1,b:2} (HashMap)
• java.util.Map
• java.util.Map vs java.lang.HashMap?
• <defaultValue>
• <required> (defaults to false).

2. Build taglibs #

X:\portal_dir\util-taglib>ant build-taglibs

You only need to do this once, unless your taglib definition, in liferay-aui.xml, changes.

Files that build-taglibs modifies:

X:\portal_dir\util-taglib\src\META-INF\aui.tld

Files that build-taglibs creates:

X:\portal_dir\util-taglib\src\com\liferay\taglib\aui\NewTaglibNameTag.java
X:\portal_dir\util-taglib\src\com\liferay\taglib\aui\base\BaseNewTaglibNameTag.java
X:\portal_dir\portal-web\docroot\html\taglib\aui\new_taglib_name
    init.jsp
    init-ext.jspf
    page.jsp  //(if bodyContent="false" or missing)
    start.jsp //(if bodyContent="true")

3. Create end.jsp (if needed) #

• When using bodyContent="true",  for use in body content wrapping.
• Copy from start.jsp as a base.

X:\portal_dir\portal-web\docroot\html\taglib\aui\new_taglib_name\end.jsp

4. Modify taglib #

• Your new attributes from liferay-aui.xml are available as variables.

...
<%= exampleAttributeName %>
...

• init.jsp
• Avoid modifying this file because rebuilding (ant build-taglibs) your taglib will overwrite it.
• init-ext.jspf
• If needed, put the majority of JSP logic here, rather than in the JSPs below. 
• page.jsp | start.jsp | end.jsp
• Write HTML, <%= JSP Scriptlets  %>, and JSTL in these files.
• Java files:
• You may need to modify these, depending on your taglib usage. A compile/deploy/restart is required if you do so.
• Avoid modifying BaseNewTaglibNameTag.java because rebuilding (ant build-taglibs) your taglib will overwrite it.

X:\portal_dir\util-taglib\src\com\liferay\taglib\aui\NewTaglibNameTag.java
X:\portal_dir\util-taglib\src\com\liferay\taglib\aui\base\BaseNewTaglibNameTag.java

5. Make use of the new taglib in an existing portlet (for convenience) #

X:\portal_dir\portal-web\docroot\html\portlet\some_portlet\view.jsp

• Important note: When mixing strings and variables within your taglib attributes, you must wrap everything within a single JSP Scriptlet.
• Incorrect: <aui:new-taglib-name attribute1="some string" attribute2="years:<%= someVariable %>">
• Incorrect: <aui:new-taglib-name attribute1="some string" attribute2="<%= 'years:' + someVariable %>"> (because of single quotes)
• Correct: <aui:new-taglib-name attribute1="some string" attribute2='<%= "years:" + someVariable %>'>

...
<aui:new-taglib-name taglibAttribute='<%= "years:" + someVariable %>'>
    <p>test 2</p>
    <p><%= someVariable %></p>
</aui:new-taglib-name>
...

6. Deploy Portal (if not using Tomcat "Hot Deploy") #

X:\portal_dir>ant all

7. Launch Portal in browser #

http://localhost:8080/

8. Add "Some Portlet" to a page and test the taglib. #

9. Continue modifications under tomcat to avoid having to deploy. (if not using Tomcat "Hot Deploy") #

X:\tomcat_dir\webapps\ROOT\html\portlet\some_portlet\view.jsp
X:\tomcat_dir\webapps\ROOT\html\taglib\aui\new_taglib_name\

10. Back port changes done under tomcat to portal version. (if not using Tomcat "Hot Deploy") #

X:\portal_dir\portal-web\docroot\html\taglib\aui\new_taglib_name