[portal-commits] JBoss Portal SVN: r7068 - docs/trunk/referenceGuide/en/modules.

Author: thomas.heute(a)jboss.com Date: 2007-04-26 08:27:02 -0400 (Thu, 26 Apr 2007) New Revision: 7068 Modified: docs/trunk/referenceGuide/en/modules/authentication.xml docs/trunk/referenceGuide/en/modules/installation.xml docs/trunk/referenceGuide/en/modules/supported.xml docs/trunk/referenceGuide/en/modules/themeandlayouts.xml Log: - Add chapter on modifying the header. - minor Modified: docs/trunk/referenceGuide/en/modules/authentication.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/authentication.xml 2007-04-26 12:08:39 UTC (rev 7067) +++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-04-26 12:27:02 UTC (rev 7068) @@ -20,7 +20,7 @@ To learn more about security in JBoss Application Server please read <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossSX">JBoss... documentation. </para> - <sect2 id="configuration"> + <sect2 id="authentication_configuration"> <title>Configuration</title> <para>You can configure the JAAS authentication stack in <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis>. It is important to remember that authorisation in portal starts at the JAAS level - Modified: docs/trunk/referenceGuide/en/modules/installation.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/installation.xml 2007-04-26 12:08:39 UTC (rev 7067) +++ docs/trunk/referenceGuide/en/modules/installation.xml 2007-04-26 12:27:02 UTC (rev 7068) @@ -8,8 +8,7 @@ </author> </chapterinfo> <title>Installation</title> - <para>There are 4 different methods to getting JBoss Portal up and running. The one you choose is up to you, but all - result in your being able to run/deploy the best Portal application in the world. ;-) + <para>Depending on your needs, there are several different methods to get JBoss Portal up and running. <itemizedlist> <listitem> <xref linkend="install_bundle"/> Modified: docs/trunk/referenceGuide/en/modules/supported.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/supported.xml 2007-04-26 12:08:39 UTC (rev 7067) +++ docs/trunk/referenceGuide/en/modules/supported.xml 2007-04-26 12:27:02 UTC (rev 7068) @@ -22,7 +22,7 @@ <itemizedlist> <listitem>JDK 1.4 or higher (1.4.2 is recommended)</listitem> <listitem>512 MB RAM</listitem> - <listitem>50 MB hard disk space</listitem> + <listitem>100 MB hard disk space</listitem> <listitem>400 MHz CPU</listitem> </itemizedlist> </para> @@ -30,15 +30,15 @@ <sect1> <title>Supported Operating Systems</title> <para>JBoss Portal is 100% pure Java and therefore interoperable with most operating systems - capable of running a Java Virtual Machine (JVM); including Windows, UNIX, and Linux. + capable of running a Java Virtual Machine (JVM); including Linux, Windows, UNIX, MacOS X. </para> </sect1> <sect1> <title>JBoss Application Server</title> - <para>JBoss Portal only works with JBoss Application Server.</para> + <para>As of today JBoss Portal only works with JBoss Application Server.</para> + <para>Currently we recommend using JBoss AS 4.0.5.GA, support for JBoss AS 4.2.x is on its way.</para> <warning> - <para>Currently we recommend using JBoss AS 4.0.4.GA, or greater. Previous versions of - JBoss Application Server are not supported with this version of JBoss Portal</para> + <para> Versions before 4.0.4 of JBoss Application Server are not supported with this version of JBoss Portal.</para> </warning> </sect1> <sect1 id="supportedversions-db"> @@ -58,14 +58,13 @@ <listitem>PostgreSQL 8.x</listitem> <listitem>HypersonicSQL</listitem> <listitem>Derby</listitem> - <listitem>Oracle 9 and 10g</listitem> - <listitem>MSSQL</listitem> + <listitem>Oracle 9 and 10g (make sure to use the latest driver of Oracle's 10 branch even when running Oracle 9)</listitem> + <listitem>Microsoft SQL Server</listitem> <listitem>MaxDB</listitem> </itemizedlist> </sect1> <sect1> <title>Source building</title> - <para>The source building mechanism works on Windows, Linux, MacOS X and any 'Unix like' - operating system.</para> + <para>The source building mechanism works on Linux, Windows, MacOS X and any 'Unix like' operating system.</para> </sect1> </chapter> Modified: docs/trunk/referenceGuide/en/modules/themeandlayouts.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/themeandlayouts.xml 2007-04-26 12:08:39 UTC (rev 7067) +++ docs/trunk/referenceGuide/en/modules/themeandlayouts.xml 2007-04-26 12:27:02 UTC (rev 7068) @@ -98,6 +98,149 @@ </para> </sect1> <sect1> + <title>Header</title> + <sect2> + <title>Overview</title> + <para>The default header is divided into two parts, links to pages displayed as tabs and links + to navigate between portals and dahsboards as well as loggin in and out. + </para> + <para>Screenshot:</para> + <para> + <imageobject> + <imagedata fileref="images/themeguide/portal-header.gif" format="gif"/> + </imageobject> + </para> + <note>Here, we use split content from rendering by using a CSS style sheet, it allow us to change the + display by switching the CSS without affecting the content. THe Maple theme will display the links + on the left side with a different font for example. THis is up to you to choose or not this approach + </note> + <para>To customize the header there are several options detailed after. + <itemizedlist> + <listitem>The first option would simply require to modify + the theme CSS, by doing this you could change the fonts, the way tabs are rendered, colors and many + other things but not change the content.</listitem> + <listitem>The second option is to modify the provided JSPs, <literal>header.jsp</literal> and + <literal>tabs.jsp</literal>. It gives you more flexibility than the previous solution on modifying + the content. Links to legacy application could easily be added, URLs could be arranged differently, the CSS + approach could be replaced by good old HTML, CSS style names could be changed... The drawback of + this method compare to the next one is the limitation in what is accessible from the JSP.</listitem> + <listitem>The third option is the most flexible and let you inject whatever you want, it consists in + replacing the default <literal>PageCustomizerInterceptor</literal> by your own.</listitem> + </itemizedlist> + </para> + <sect3> + <title>Writing his own JSPs</title> + <para>The content of those two parts are displayed thanks to two different JSP pages. By default + you would find those pages in the directory <literal>portal-core.war/WEB-INF/jsp/header/</literal>. + The file <literal>header.jsp</literal> is used to display the links that are displayed on the upper + right of the default theme. The file <literal>tabs.jsp</literal> is used to display the pages tabs + appearing on the left. + </para> + <para> Again, you have several choices, either to edit the included JSPs directly or create your own, + store them in a web application then edit the following file: <literal>portal-core.sar/META-INF/jboss-service.xml</literal>. + The interesting part in that file is the following: + <programlisting><![CDATA[ +<mbean + code="org.jboss.portal.core.aspects.controller.PageCustomizerInterceptor" + name="portal:service=Interceptor,type=Command,name=PageCustomizer" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <attribute name="JSPContext">/portal-core</attribute> + <attribute name="HeaderJSP">/WEB-INF/jsp/header/header.jsp</attribute> + <attribute name="TabsJSP">/WEB-INF/jsp/header/tabs.jsp</attribute> + <depends + optional-attribute-name="PortalAuthorizationManagerFactory" + proxy-type="attribute">portal:service=PortalAuthorizationManagerFactory</depends> +</mbean> + ]]></programlisting> + The three attibutes are: + <itemizedlist> + <listitem>JSPContext: Defines the web application context where the JSPs are located</listitem> + <listitem>HeaderJSP: Defines the location (in the web application previously defined) of the JSP in charge of writing the header links</listitem> + <listitem>TabsJSP: Defines the location (in the web application previously defined) of the JSP in charge of writing the pages links (note that it doesn't have to be renderer as tabs)</listitem> + </itemizedlist> + </para> + <para>Writing the header JSP</para> + <para>A couple of request attributes are set so that they can be used by the JSP, here is the list of attibutes and their meaning: + <itemizedlist> + <listitem><literal>org.jboss.portal.header.USER</literal>: A <literal>org.jboss.portal.identity.User</literal> object of the logged-in user, null if the user is not logged-in.</listitem> + <listitem><literal>org.jboss.portal.header.LOGIN_URL</literal>: URL to logging-in.</listitem> + <listitem><literal>org.jboss.portal.header.DASHBOARD_URL</literal>: URL to the dashboard, null if the user is already on the dashboard, null if the user is on the default portal already.</listitem> + <listitem><literal>org.jboss.portal.header.DEFAULT_PORTAL_URL</literal>: URL to the default page of the portal named 'default', null if the user is on the default portal already.</listitem> + <listitem><literal>org.jboss.portal.header.ADMIN_PORTAL_URL</literal>: URL to the default page of the admin portal (named 'admin'), null if the user is on the admin portal already.</listitem> + <listitem><literal>org.jboss.portal.header.EDIT_DASHBOARD_URL</literal>: URL to the page content editor of the dashboard, set only if the user is on the dashboard, null otherwise.</listitem> + <listitem><literal>org.jboss.portal.header.COPY_TO_DASHBOARD_URL</literal>: URL to copy a page from a portal to the personal dashboard, null if the user is on the dashboard.</listitem> + <listitem><literal>org.jboss.portal.header.SIGN_OUT_URL</literal>: URL to log out the portal.</listitem> + </itemizedlist> + With that in hand, if someone just wanted to display the logged-in username and a link to log out, he could write: + <programlisting><![CDATA[ +<%@ page import="org.jboss.portal.identity.User" %> + +<% + User user = (User) request.getAttribute("org.jboss.portal.header.USER"); + String signOutURL = (String) request.getAttribute("org.jboss.portal.header.SIGN_OUT_URL"); + String loginURL = (String) request.getAttribute("org.jboss.portal.header.LOGIN_URL"); + + + if (user == null) + { +%> + <a href="<%= loginURL %>">Login</a> +<% + } + else + { +%> +Logged in as: <%= user.getUserName() %> +<br/> +<a href="<%= signOutURL %>">Logout</a> +<% + } +%> + ]]></programlisting> + </para> + <para>Writing the tabs JSP</para> + <para>A couple of request attributes are set so that they can be used by the JSP, here is the list of attibutes and their meaning: + <itemizedlist> + <listitem><literal>org.jboss.portal.api.PORTAL_NODE</literal>: A <literal>org.jboss.portal.api.node.PortalNode</literal> object of the root Portal node. Authorized children and siblings + of this object are accessible.</listitem> + <listitem><literal>org.jboss.portal.api.PORTAL_RUNTIME_CONTEXT</literal>: A <literal>org.jboss.portal.api.PortalRuntimeContext</literal> object that can be used to render URLs.</listitem> + </itemizedlist> + </para> + <para>The default file in charge of displaying the tabs can be found in: <literal>portal-core.war/WEB-INF/jsp/header/</literal></para> + </sect3> + <sect3> + <title>Modifying the default PageCustomizerInterceptor</title> + <para>Instead of modifying the class directly, create your own Interceptor + (I suggest you copy the default PageCustomizerInterceptor look at the source in + <literal>core/src/main/org/jboss/portal/core/aspects/controller</literal>) then add it to: + <literal>portal-core.sar/META-INF/jboss-service.xml</literal> the same way it + is done by the default Interceptor. Then replace the default one by your own in + the following part: +<programlisting><![CDATA[ +<mbean + code="org.jboss.portal.server.impl.invocation.JBossInterceptorStackFactory" + name="portal:service=InterceptorStackFactory,type=Command" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends-list optional-attribute-name="InterceptorNames"> + <depends-list-element>portal:service=Interceptor,type=Command,name=Ajax</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=NavigationalState</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PortalNode</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PolicyEnforcement</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PageCustomizer</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=EventBroadcaster</depends-list-element> + </depends-list> +</mbean> +]]></programlisting> + Just replace the PageCustomizer by one of your own. + </para> + </sect3> + </sect2> + </sect1> + <sect1> <title>Layouts</title> <sect2> <title>How to define a Layout</title>