Author: chris.laprun(a)jboss.com Date: 2007-06-27 19:36:21 -0400 (Wed, 27 Jun 2007) New Revision: 7598 Added: docs/trunk/userGuide/en/images/intro/greetings.png docs/trunk/userGuide/en/images/intro/logged.png docs/trunk/userGuide/en/images/intro/tabs.png docs/trunk/userGuide/en/images/intro/user_portlet_create.png docs/trunk/userGuide/en/images/intro/user_portlet_loggedin.png Removed: docs/trunk/userGuide/en/images/intro/greetings_portlet.gif docs/trunk/userGuide/en/images/intro/login.gif docs/trunk/userGuide/en/images/intro/login.jpg docs/trunk/userGuide/en/images/intro/nav2.gif docs/trunk/userGuide/en/images/intro/user_portlet_create.gif docs/trunk/userGuide/en/images/intro/user_portlet_loggedin.gif Modified: docs/trunk/userGuide/en/modules/intro.xml Log: - Started update of user guide: + Updated screenshots where needed. + Improved content to make it clearer and provide basic concept explanation. + Minor other improvements. Added: docs/trunk/userGuide/en/images/intro/greetings.png =================================================================== (Binary files differ) Property changes on: docs/trunk/userGuide/en/images/intro/greetings.png ___________________________________________________________________ Name: svn:mime-type + image/png Deleted: docs/trunk/userGuide/en/images/intro/greetings_portlet.gif =================================================================== (Binary files differ) Added: docs/trunk/userGuide/en/images/intro/logged.png =================================================================== (Binary files differ) Property changes on: docs/trunk/userGuide/en/images/intro/logged.png ___________________________________________________________________ Name: svn:mime-type + image/png Deleted: docs/trunk/userGuide/en/images/intro/login.gif =================================================================== (Binary files differ) Deleted: docs/trunk/userGuide/en/images/intro/login.jpg =================================================================== (Binary files differ) Deleted: docs/trunk/userGuide/en/images/intro/nav2.gif =================================================================== (Binary files differ) Added: docs/trunk/userGuide/en/images/intro/tabs.png =================================================================== (Binary files differ) Property changes on: docs/trunk/userGuide/en/images/intro/tabs.png ___________________________________________________________________ Name: svn:mime-type + image/png Deleted: docs/trunk/userGuide/en/images/intro/user_portlet_create.gif =================================================================== (Binary files differ) Added: docs/trunk/userGuide/en/images/intro/user_portlet_create.png =================================================================== (Binary files differ) Property changes on: docs/trunk/userGuide/en/images/intro/user_portlet_create.png ___________________________________________________________________ Name: svn:mime-type + image/png Deleted: docs/trunk/userGuide/en/images/intro/user_portlet_loggedin.gif =================================================================== (Binary files differ) Added: docs/trunk/userGuide/en/images/intro/user_portlet_loggedin.png =================================================================== (Binary files differ) Property changes on: docs/trunk/userGuide/en/images/intro/user_portlet_loggedin.png ___________________________________________________________________ Name: svn:mime-type + image/png Modified: docs/trunk/userGuide/en/modules/intro.xml =================================================================== --- docs/trunk/userGuide/en/modules/intro.xml 2007-06-27 23:30:36 UTC (rev 7597) +++ docs/trunk/userGuide/en/modules/intro.xml 2007-06-27 23:36:21 UTC (rev 7598) @@ -40,7 +40,7 @@ </note> </sect2> <sect2 id="intro_portal_pages"> - <title>Portal Pages</title> + <title>Pages</title> <para>A Portal Page is an aggregator of Portlet Windows. It is generated by the portal, during the reponse phase. During this phase, the portal aggregates all of the HTML markup created the individual portlets, decorates them with window controls, and presents them to the user as a consolidated page. @@ -77,28 +77,30 @@ <itemizedlist> <listitem> <para> - <emphasis role="bold">Window Title</emphasis> + <emphasis role="bold">Window Title:</emphasis> Defines the content and purpose of the individual portlet window. </para> </listitem> <listitem> <para> - <emphasis role="bold">Window Fragment</emphasis> - The generated HTML markup produced by the portlet on the server-side. + <emphasis role="bold">Window Fragment:</emphasis> + Generated HTML markup produced by the portlet on the server-side. </para> </listitem> <listitem> <para> - <emphasis role="bold">Window Controls</emphasis> - Window controls are divided in to two categories: - <emphasis role="bold">Window State</emphasis> - and - <emphasis role="bold">Portlet Mode</emphasis> - . + <emphasis role="bold">Window Controls:</emphasis> + Window controls are divided into two categories and control different aspects of how the user can + impact the generated markup. Each window control can be click to interact with the window in + specific way. <emphasis role="bold">Window State</emphasis> icons control how much room the window + will take on the page and how much markup will be shown. + <emphasis role="bold">Portlet Mode</emphasis> icons, on the other hand, control the mode in which + the portlet operate, thus impacting the type of generated markup. Note that not all portlets + support all defined window states and/or portlet modes. <itemizedlist> <listitem> <para> - <emphasis role="bold">Window State:</emphasis> + <emphasis role="bold">Window State icons and their meaning:</emphasis> <itemizedlist> <listitem> <para> @@ -106,8 +108,9 @@ <imagedata fileref="images/intro/ico_16_normal.gif" format="gif"/> </imageobject> <emphasis role="bold">(Normal)</emphasis> - - Normal window state, is what you see in the illustration above. All portlet - windows take up a similar amount of space on the page. + - Normal window state, is the most common state for portlets (portlets in the + above image are in the normal window state). All portlet + windows occupy a similar amount of space on the page. </para> </listitem> <listitem> @@ -116,7 +119,7 @@ <imagedata fileref="images/intro/ico_16_minimize.gif" format="gif"/> </imageobject> <emphasis role="bold">(Minimized)</emphasis> - - The portlet window renders, minimal-to-no markup. + - The portlet is instructed to render minimal-to-no markup. </para> </listitem> <listitem> @@ -124,34 +127,39 @@ <imagedata fileref="images/intro/ico_16_maximize.gif" format="gif"/> </imageobject> <emphasis role="bold">(Maximized)</emphasis> - - The portlet window takes up a maximum amount of real estate on the page. + - The portlet window can occupy as much space of real estate on the page. </listitem> </itemizedlist> </para> </listitem> <listitem> <para> - <emphasis role="bold">Portlet Mode:</emphasis> + <emphasis role="bold">Portlet Modes and their meaning:</emphasis> + Portlet modes are not always available (it depends on the portlet support for a given mode). + Moreover, the Edit mode is only available to logged in users, as in this mode, the portlet + preferences can be modified to be individually suited to a particular user's needs. <itemizedlist> <listitem> <para> <imageobject> - <imagedata fileref="images/intro/ico_cancel.gif" format="gif"/> + <imagedata fileref="images/intro/ico_edit.gif" format="gif"/> </imageobject> - <emphasis role="bold">(View)</emphasis> - - In View mode, the portlet renders markup reflecting the current window state of - the portlet. The button is labeled 'Cancel', so the user understand he is leaving - "Edit Mode" and reverting back to "View Mode". The diagram above has all portlet - windows in View mode. + <emphasis role="bold">(Edit)</emphasis> + - Only visible to logged-in users. Allows a logged-in user to customize the + portlet's preferences. </para> </listitem> <listitem> <para> <imageobject> - <imagedata fileref="images/intro/ico_edit.gif" format="gif"/> + <imagedata fileref="images/intro/ico_cancel.gif" format="gif"/> </imageobject> - <emphasis role="bold">(Edit)</emphasis> - - Allows a user to customize the portlet's behaviour. + <emphasis role="bold">(Return to View mode)</emphasis> + - The button labeled 'Cancel' is only visible when a user is logged in and the + portlet associated to the current window is in the Edit mode. This replaces the + Edit button so the user understands that by clicking it she will leave the + "Edit Mode" and reverting back to "View Mode". Portlets are by default in View + mode. </para> </listitem> <listitem> @@ -160,7 +168,8 @@ <imagedata fileref="images/intro/ico_16_help.gif" format="gif"/> </imageobject> <emphasis role="bold">(Help)</emphasis> - - A portlet should provide help information to the user. + - Allows a user to access helpful information about the portlet, if it provides + it (which is recommended). </para> </listitem> </itemizedlist> @@ -174,107 +183,89 @@ </sect2> </sect1> <sect1 id="contents_pages"> - <title>The Portal Pages</title> + <title>Default Portal installation</title> + <para> + This section will take a quick look at the default Portal installation and the pages and portlets that come + with it. + </para> <sect2> - <title>Navigating the Portal Pages</title> - <para>Navigating the portal pages is normally performed either by typing in a specific URL ( - <xref linkend="intro_portal_pages"/> - ), or using the Navigation Tabs at the top of the page. + <title>Default Portal Pages</title> + <para>Three pages are available in the default Portal: Home, News and Weather. You can access pages either by + entering the page URL in your browser location bar, as shown in <xref linkend="intro_portal_pages"/>, or + by clicking the tab associated to the page in the Navigation Tabs at the top of the page. <mediaobject> <imageobject> - <imagedata fileref="images/intro/tabs.gif" format="gif" align="center" valign="middle"/> + <imagedata fileref="images/intro/tabs.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> </para> - <para>Take note, also, that the navigation tabs support sub-page navigation as well. By hovering over a tab - with childPages, it will display a flyout menu for those subpages + <note>Navigation tabs support sub-page navigation as well. By hovering over a tab + with child Pages, it will display a flyout menu for those subpages: <mediaobject> <imageobject> <imagedata fileref="images/intro/nav_sub.gif" format="gif" align="center" valign="middle"/> </imageobject> </mediaobject> - </para> - <para>Altervatively, once logged in, you are able to navigate to your Dashboard or the Admin Portal by using - the navigation elements, located in the top-right of the main portal page. - <mediaobject> - <imageobject> - <imagedata fileref="images/intro/nav2.gif" format="gif" align="center" valign="middle"/> - </imageobject> - </mediaobject> - </para> + There are no pages with subpages in the default Portal installation. + </note> <para> - Each page, in the default installation of JBoss Portal is explained in the following sections, along with - the portlets found - within them. + While you can use a Portal anonymously, it is much more interesting to do so while logged in, as you get the + opportunity to customize the content you want to see or even create your own personal Dashboard, as + explained in <xref linkend="dashboard"/>. </para> </sect2> - <sect2 id="logging_ing"> + <sect2 id="logging_in"> <title>Logging in to the Portal</title> <para>Logging in to the portal is accomplished by clicking the - <emphasis>Login</emphasis> - link at the top-right of the portal page. You can login, using the following credentials: - <programlisting> - <![CDATA[ -user/user -admin/admin - ]]> - </programlisting> + <emphasis>Login</emphasis> link at the top-right of the portal page. Portal will present you with a logging + screen where you can enter your credentials: <mediaobject> <imageobject> <imagedata fileref="images/intro/login_ss.gif" format="gif" align="center" valign="middle"/> </imageobject> </mediaobject> + + The default Portal installation + defines two users: a regular user with no special privileges + (login: <literal>user</literal>, password: <literal>user</literal>) and an + administrator user who can alter Portal's content (login: <literal>admin</literal>, password: + <literal>admin</literal>). + </para> <para> - Once logged in, the top-right menu will change so you can then navigate to your personal dashboard and other - functionality that is included therein. + Once logged in, the top-right menu will change so you can then navigate to your personal dashboard or log + out. If you have access to other portal instances, they will be shown here as well. <mediaobject> <imageobject> - <imagedata fileref="images/intro/login.gif" format="gif" align="center" - valign="middle"/> + <imagedata fileref="images/intro/logged.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> <note>If you login as an administrator, you will also be presented with a link to the - <emphasis>Admin</emphasis> - portal. + <emphasis>Admin</emphasis> portal. </note> </para> </sect2> <sect2> - <title>Default Page</title> - <para>The default page contains the following portlets: - <itemizedlist> - <listitem> - <xref linkend="intro_greetings_portlet"/> - </listitem> - <listitem> - <xref linkend="intro_user_portlet"/> - </listitem> - <listitem> - <xref linkend="intro_cms_portlet"/> - </listitem> - </itemizedlist> - </para> + <title>Home Page</title> <sect3 id="intro_greetings_portlet"> <title>Greetings Portlet</title> <para> <mediaobject> <imageobject> - <imagedata fileref="images/intro/greetings_portlet.gif" format="gif" align="center" - valign="middle"/> + <imagedata fileref="images/intro/greetings.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> Displays hard-coded links to downloading JBoss Portal, downloading - portlets from PortletSwap.com, and the live online JBoss Portal demo. It also contains default - authentication information on loging in. + portlets from <ulink url="http://www.portletswap.com">PortletSwap</ulink>, and the live online JBoss + Portal demo. It also contains default authentication information on loging in, as well as a link to the + official Portal documentation. </para> </sect3> <sect3 id="intro_user_portlet"> <title>User Portlet</title> - <note>Administrators should view, - <xref linkend="useradmin"/> - , for managing the portal Userbase. Only user operations are covered in this section... + <note>Administrators should view <xref linkend="useradmin"/> for managing the portal user base. Only user + operations are covered in this section... </note> <para> <mediaobject> @@ -289,7 +280,7 @@ is covered in the following sections. <mediaobject> <imageobject> - <imagedata fileref="images/intro/user_portlet_loggedin.gif" format="gif" align="center" + <imagedata fileref="images/intro/user_portlet_loggedin.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> @@ -300,31 +291,23 @@ <emphasis role="bold">Create a new account</emphasis> </para> <para> + Create a new account by clicking on the <emphasis>"You can create an account"</emphasis> + link at the bottom of the portlet, when not logged. A User can then fill in the necessary + information to create an account on the system: <mediaobject> <imageobject> - <imagedata fileref="images/intro/user_portlet_create.gif" format="gif" align="center" + <imagedata fileref="images/intro/user_portlet_create.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> - Create a new account by clicking on the - <emphasis>Create</emphasis> - link in the portlet. A User can then fill in the necessary information to create an account on - the system: </para> </listitem> <listitem> <para> - <emphasis role="bold">Edit personal information.</emphasis> + <emphasis role="bold">Edit personal information</emphasis> </para> <para>A user has the ability to edit his personal information at any time by clicking on the - <emphasis>Edit Info</emphasis> - link. - <mediaobject> - <imageobject> - <imagedata fileref="images/intro/user_portlet_editinfo.gif" format="gif" align="center" - valign="middle"/> - </imageobject> - </mediaobject> + <emphasis>"Edit your profile"</emphasis> link, when logged in. </para> </listitem> </itemizedlist> @@ -332,6 +315,9 @@ </sect3> <sect3 id="intro_cms_portlet"> <title>CMS Portlet</title> + + TODO TODO TODO Update TODO TODO TODO + <para> <mediaobject> <imageobject>