PLT.22 Portlet Tag Library

portlet tag library 可以放在 JSPs 的檔案之中去直接存取 portlet 特殊的元素,

例如 RenderRequest 及 RenderResponse.

他也提供了 JSPs 去存取 portlet 的一些功能如 portlet 的 URLs.

Portlet container 必須提供 portlet tag library 的實作. Portlet 的開發人員可以使用定義在 JSP Specification 1.2 中 JSP.7.3.9 Well-Know URIs 的機制來實作.

而 JSP 該如何使用 tab library 呢 ? 如同下面的程式碼

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

PLT.22.1 defineObjects Tag

defineObjects tag 必須定義以下的變數讓 JSPs 可以使用

• RenderRequest renderRequest
• RenderResponse renderResponse
• PortletConfig portletConfig

這些變數必須參照 Portlet API 的物件並且放在 request scope 的物件中 ( 定義在 PLT.16.3.1 Included Request Attributes 章節 )

一個 JSP 程式中可以透過 scriptlet 利用到 defineObjects tag 在所有的地方.

defineObjects tag 不可以定義任何屬性, 也不可以包含任何 body content.

簡單的 JSP 範例如下

<portlet:defineObjects/>
<%=renderResponse.setTitle("my portlet title")%>

這就是透過 defineObjects tag, JSP 可以呼叫 renderResponse 的 setTitle() 去設定 portlet 的標題.

PLT.22.2 actionURL Tag

portlet 中 actionURL 是為了建立一個 URL 可以連結到目前的 portlet 並且可以透過帶有參數的 request 動作去驅動.

而 URL 的傳遞參數必須使用 param tag 放在 actionURL 的起始以及結束的 tag 之間.

• windowState ( 型態: String, 非必要的)

當這個 link 被執行的時候, 這個 portlet windowState 應該要執行的動作. 預先設定的 windowState 有 minimized, normal, 以及 maximized . 假如這些標準的視窗狀態在這個 request 是非法的, 應該就要丟出 JspException. 非法的理由有可能是 portal 不支援這些狀態, portlet 無法宣告他們在 Deployment Descriptor 之中讓 portal 支援這些狀態, 或是現在這個使用者不被允許使用到這些狀態. 假如視窗狀態不能讓 URL 設定, portlet 將待在和現在這個 request 相同的狀態. WindowState 的屬性應該是不分大小寫的.

• portletMode (型態: String, 非必要的)

假如當這個 link 被執行的時候沒有錯誤發生, 這個 portlet 應該要具備的 mode. 預先設定的 portlet mode 有 edit, help, 以及 view . 假如這些標準的 portlet mode 在這個 request 是非法的, 應該就要丟出 JspException. 非法的理由有可能是 portal 不支援這些 mode, portlet 無法宣告他們在 Deployment Descriptor 之中讓 portal 支援這些 mode, 或是現在這個使用者不被允許切換到這些 mode . 假如 portlet mode 不能讓 URL 設定, portlet 將待在和現在這個 request 相同的 mode . PortletMode 的屬性應該是不分大小寫的.

• var (型態: String, 非必要的)

為了 action URL 輸出到某個 scope 變數的名稱. 這輸出到 scope 的變數名稱應該是 String. 預設 URL 執行是把結果寫到現在這個 JspWriter. 假如結果輸出成為 JSP 的 scope 變數, 透過 var 的屬性定義, 將不會有任何東西寫到現在這個 JspWriter.

注意: 在 URL 被建立之後, 將不可能利用變數和 String 串聯去 extend 那 URL 或增加任何更多的參數值. 假如被給定的參數名稱已經存在在這個 page 的 scope 或他已經被使用在一個重複的迴圈中, 新的屬性值將覆蓋舊有的.

• secure (型態: String, 非必要的)

假如結果的 URL 必須是 secure 的連結 ( secure="true" ) 或一個 insecure one ( secure="false"). 假如 run-time 環境不支援標準的安全性設定, 將會丟出 JspException. 假如這 URL 沒有設定任何 security, 他必須待在和現在 request 相同的 security 設定.

JspException 具有 PortletException 將產生一些錯誤視為 root 產生會丟出以下的狀況.

• If an illegal window state is specified in the windowState attribute.
• If an illegal portlet mode is specified in the portletMode attribute.
• If an illegal security setting is specified in the secure attribute.

以下是一個使用 actionURL tag 的例子

<portlet:actionURL windowState="maximized" portletMode="edit">
<portlet:param name="action" value="editStocks"/>
</portlet:actionURL>

這個範例是建立一個 URL 將讓 portlet 進入 EDIT 的狀態並且 window state 最大化 ( MAXIMIZED )的去編輯股票報價列表.

PLT.22.3 renderURL Tag

portlet 中 renderURL 是為了建立一個 URL 可以連結到目前的 portlet 並且可以透過帶有參數的 request 動作去驅動.

而 URL 的傳遞參數必須使用 param tag 放在 renderURL 的起始以及結束的 tag 之間.

• windowState ( 型態: String, 非必要的)

當這個 link 被執行的時候, 這個 portlet windowState 應該要執行的動作. 預先設定的 windowState 有 minimized, normal, 以及 maximized . 假如這些標準的視窗狀態在這個 request 是非法的, 應該就要丟出 JspException. 非法的理由有可能是 portal 不支援這些狀態, portlet 無法宣告他們在 Deployment Descriptor 之中讓 portal 支援這些狀態, 或是現在這個使用者不被允許使用到這些狀態. 假如視窗狀態不能讓 URL 設定, portlet 將待在和現在這個 request 相同的狀態. WindowState 的屬性應該是不分大小寫的.

• portletMode (型態: String, 非必要的)

假如當這個 link 被執行的時候沒有錯誤發生, 這個 portlet 應該要具備的 mode. 預先設定的 portlet mode 有 edit, help, 以及 view . 假如這些標準的 portlet mode 在這個 request 是非法的, 應該就要丟出 JspException. 非法的理由有可能是 portal 不支援這些 mode, portlet 無法宣告他們在 Deployment Descriptor 之中讓 portal 支援這些 mode, 或是現在這個使用者不被允許切換到這些 mode . 假如 portlet mode 不能讓 URL 設定, portlet 將待在和現在這個 request 相同的 mode . PortletMode 的屬性應該是不分大小寫的.

• var (型態: String, 非必要的)

為了 render URL 輸出到某個 scope 變數的名稱. 這輸出到 scope 的變數名稱應該是 String. 預設 URL 執行是把結果寫到現在這個 JspWriter. 假如結果輸出成為 JSP 的 scope 變數, 透過 var 的屬性定義, 將不會有任何東西寫到現在這個 JspWriter.

注意: 在 URL 被建立之後, 將不可能利用變數和 String 串聯去 extend 那 URL 或增加任何更多的參數值. 假如被給定的參數名稱已經存在在這個 page 的 scope 或他已經被使用在一個重複的迴圈中, 新的屬性值將覆蓋舊有的.

• secure (型態: String, 非必要的)

假如結果的 URL 必須是 secure 的連結 ( secure="true" ) 或一個 insecure one ( secure="false"). 假如 run-time 環境不支援標準的安全性設定, 將會丟出 JspException. 假如這 URL 沒有設定任何 security, 他必須待在和現在 request 相同的 security 設定.

JspException 具有 PortletException 將產生一些錯誤視為 root 產生會丟出以下的狀況.

• If an illegal window state is specified in the windowState attribute.
• If an illegal portlet mode is specified in the portletMode attribute.
• If an illegal security setting is specified in the secure attribute.

以下是一個使用 renderURL tag 的例子

<portlet:renderURL portletMode="view" windowState="normal">
<portlet:param name="showQuote" value="myCompany"/>
<portlet:param name="showQuote" value="someOtherCompany"/>
</portlet:renderURL>

這個範例將產生一個 URL 去提供一個 link 可以去顯示公司其他公司的股票報價及改變 portlet mode 成為 VIEW 並且將 window state 改成 NORMAL.

PLT.22.4 namespace Tag

這個 tag 產生一個目前 portlet 中唯一的數值.

這個 tag 應該被 named elements 使用在 portlet 的輸出, 例如 javascript 的功能或變數. 而 namespacing 就是確認給定的名稱是這個 portlet 唯一的值, 是避免名稱重複影響了其他 portal 的 element 以及這一頁的其他 portlets.

namespace tag 不允許任何 Body Content.

以下是一個使用 namespace tag 的例子

<A HREF="javascript:<portlet:namespace/>doFoo()">Foo</A>

這個範例預先設定 javascript function 加上 namescape + 'doFoo', 以確認這個功能在portal page 中是唯一的.

PTL.22.5 param Tag

這個 tag 是定義一個參數值, 可能是放在 actionURL 或 renderURL 之中. param Tag 不准包含任何 Body Content.

下面是 param Tag 一些必要的屬性

• name (型態: String, 必要的)

增加在 URL 之中參數的屬性名稱. 假如 name 是空值 (NULL) 或 空白字串 ( empty ), 將不會執行任何動作.

• value (型態: String, 必要的)

增加在 URL 之中參數的屬性值. 假如 value 是空值 (NULL) 他將視同空白字串 (empty) 處理.

以下是一個使用 param tag 的例子

<portlet:param name="myParam" value="someValue"/>