<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file 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 KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<document>
  <properties>
    <title>Taglibs</title>
    <subtitle>Portlet API Taglib</subtitle>
	<authors>
		<person name="David Sean Taylor" email="taylor@apache.org" />
	</authors>
  </properties>
  <body>
    <section name="JSP and Portlet API Taglib">
    <p>      
    Lets create another portlet. This portlet will not have a Java class.
    Instead it will be written entirely in JSP.
    Note that you can mix JSP and a Java class for the implementation of your
    Java class as you will see in the Stock Quote portlet example.
    Go to the <i>express-demo</i> project, click on the <i>src/webapp/WEB-INF/view/</i> directory, and create a JSP 
    file named <b>tutorial.jsp</b>. Enter the following JSP code:
	</p>      
	 <source>	
	 <![CDATA[
<%@ page session="true" contentType="text/html;charset=utf-8"%>
<%@ taglib uri='/WEB-INF/portlet.tld' prefix='portlet'%>
<%@ taglib uri="http://java.sun.com/jstl/core" prefix='c' %> 

<portlet:defineObjects/>

<portlet:renderURL var="max" windowState='maximized'/>
<portlet:renderURL var="normal" windowState='normal'/>
<c:out value="${renderRequest.windowState}"/>
<c:if test="${renderRequest.windowState == 'maximized'}">
<a href='<%=normal%>'>Normal</a>
</c:if>
<c:if test="${renderRequest.windowState == 'normal'}">
<a href='<%=max%>'>Max</a>
</c:if>
	     ]]>
	</source> 	
	<p>
	Every portlet JSP page is required to have the <b>defineObjects</b> tag 
	at the top. Of course you also need the TLD reference.
	Portlets need to write their links to go back to the portal, not 
	back to each individual servlet or JSP. That is the main difference 
	between writing portlets and servlets. If you are using a framework like
	Struts or JSF correctly, these details should be hidden from you in 
	the framework. The tag that we are using here is the <b>&lt;portlet:renderURL&gt;</b>.
	It allows you to create a render phase link back to this portlet, going 
	through the portal. You can set window states, request parameters, and
	portlet mode changes on the URL. The other kind of link that you can create
	is an action URL: <b>&lt;portlet:actionURL&gt;</b>, which is usually
	used with a HTML form to post back parameters to the portlet and initial
	a blocking action phase event for the targeted portlet.    	
	The <b>&lt;portlet:defineObjects&gt;</b> tag declares three variables for your
	page:
	<table>
	<tr>
	<th>JSP variable</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>renderRequest</td>
	<td>The RenderRequest object</td>
	</tr>
	<tr>
	<td>renderResponse</td>
	<td>The RenderResponse object</td>
	</tr>
	<tr>
	<td>portletConfig</td>
	<td>The PortletConfig object</td>
	</tr>
	</table>
	</p>	
	<p>
	Here is the portlet.xml for our JSP portlet.
	It is based on the <b>GenericServletPortlet</b>, provided by Portals Bridges
	in a jar file dependency.
	Notice the init-param named <b>ViewPage</b>.
	This param defines which webapp-relative JSP to use for View Mode.
	Similiarly we have are <b>EditPage</b> for edit mode, and <b>HelpPage</b>
	for help mode.
	</p>
	 <source>	
	 <![CDATA[
 <portlet>   
    <description>The 2nd Tutorial with JSP</description>		
    <portlet-name>TutorialPortlet2</portlet-name>	
    <display-name>Tutorial Portlet 2</display-name>
    <portlet-class>org.apache.portals.bridges.common.GenericServletPortlet</portlet-class>	        
    <init-param>
        <name>ViewPage</name>
        <value>/WEB-INF/view/tutorial.jsp</value>
    </init-param>          
    <init-param>
        <name>EditPage</name>
        <value>/WEB-INF/view/tutorial.jsp</value>
    </init-param>          
    <init-param>
        <name>HelpPage</name>
        <value>/WEB-INF/view/tutorial.jsp</value>
    </init-param>              
    <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>VIEW</portlet-mode>
        <portlet-mode>EDIT</portlet-mode>        
        <portlet-mode>HELP</portlet-mode>                
    </supports>
    <supported-locale>en</supported-locale>      	
	<portlet-info>
        <title>Tutorial Portlet</title>
        <short-title>tutorial</short-title>
		<keywords>tutorial,hello,JSP,taglib</keywords>
    </portlet-info>
    <portlet-preferences>
        <preference>                            
            <name>test</name>                    
            <value>hello</value>    
        </preference>         
    </portlet-preferences>                      		
</portlet> 	 
	     ]]>
	</source> 
	<p>Add this portlet window fragment to the tutorial default page, underneath the BonjourMonde fragment:
	</p>
	 <source>
	 <![CDATA[
	  <fragment id="express-102" type="portlet" name="express-demo::TutorialPortlet2"/>
     ]]>
	</source> 				
	<p>And then deploy your changes:
	</p>
	 <source>
	 <![CDATA[
# Linux	 
cd /JetspeedTraining/workspace/jetexpress/
ant
cd applications/express-demo
mvn 
cp target/express-demo-1.0.war /JetspeedTraining/tomcat-express/webapps/express-demo.war

# Windows
cd \JetspeedTraining\workspace\jetexpress
ant
cd applications\express-demo
mvn 
copy target\express-demo-1.0.war \JetspeedTraining\tomcat-express\webapps\express-demo.war
     ]]>
	</source> 			
	  <p>
	    <a href='hello.html'>Previous</a> <a href='../05/jetspeed-service.html'>Next</a>
	  </p>            
    </section>
  </body>
</document>

