Table of Contents
- JBoss Portal - Overview
- Feature List
- Target Audience
- Acknowledgements
- 1. JBoss Portal Basics
- 2. Administration - Portal Object Management (Dynamicity)
- 3. Administration - Content Management System
- 3.1. Introduction
- 3.2. Actions
- 3.2.1. Viewing Directories
- 3.2.2. Viewing File Properties
- 3.2.3. Copying Files/Directories
- 3.2.4. Moving Files/Directories
- 3.2.5. Deleting Files/Directories
- 3.2.6. Creating Directories
- 3.2.7. Creating Text/HTML Files
- 3.2.8. Uploading Files
- 3.2.9. Uploading Archives
- 3.2.10. Exporting Archives
- 3.2.11. Editing Text/HTML Files
- 4. Administration - Users and Roles
 |
Many IT organizations look to achieve a competitive advantage for the enterprise by improving business productivity and reducing costs. Today's top enterprises are realizing this goal by deploying enterprise portals within their IT infrastructure. Enterprise portals simplify access to information by providing a single source of interaction with corporate information. Although today?s packaged portal frameworks help enterprises launch portals more quickly, only JBoss Portal can deliver the benefits of a zero-cost open source license combined with a flexible and scalable underlying platform.
JBoss Portal provides an open source and standards-based environment for hosting and serving a portal's Web interface, publishing and managing its content, and customizing its experience. It is entirely standards-based and supports the JSR-168 portlet specification, which allows you to easily plug-in standards-compliant portlets to meet your specific portal needs. JBoss Portal is available through the business-friendly LGPL open source license and is supported by JBoss Inc. Professional Support and Consulting . JBoss support services are available to assist you in designing, developing, deploying, and ultimately managing your portal environment. JBoss Portal is currently developed by JBoss, Inc. developers, Novell developers, and community contributors.
The JBoss Portal framework and architecture includes the portal container and supports a wide range of features including standard portlets, single sign-on, clustering and internationalization. Portal themes and layouts are configurable. Fine-grained security administration down to portlet permissions rounds out the security model. JBoss Portal includes a rich content management system and message board support.
JBoss Portal Resources:
The following list details features found in this document's related release. For a technical view of our features, view the Project Roadmap and Task List .
Technology and Architecture
- JEMS: Leverages the power of JBoss Enterprise Middleware Services : JBoss Application Server, JBoss Cache, JGroups, and Hibernate.
- DB Agnostic: Will work with any RDBMS supported by Hibernate
- SSO/LDAP: Leverages Tomcat and JBoss single sign on (SSO) solutions.
- JAAS Authentication: Custom authentication via JAAS login modules.
- Cacheing: Utilizes render-view caching for improved performance.
- Clusterable: Cluster support allows for portal state to be clustered for all portal instances.
- Hot-Deployment: Leverages JBoss dynamic auto deployment features.
- SAR Installer: Browser-based installer makes installation and initial configuration a breeze.
Supported Standards
- Portlet Specification and API 1.0 (JSR-168)
- Content Repository for Java Technology API (JSR-170)
- Java Server Faces 1.2 (JSR-252)
- Java Management Extension (JMX) 1.2
- Full J2EE 1.4 compliance when used with JBoss AS
Portal and Portal Container
- Multiple Portal Instances: Ability to have multiple Portal instances running inside of one Portal container.
- IPC™ Inter-Portlet Communication API enables portlets to create links to other objects such as a page, portal or window .
- Dynamicity™ The ability for administrators and users to create and destroy objects such as portlets, pages, portals, themes, and layouts at runtime.
- Internationalization: Ability to use internationalization resource files for every portlet.
- Pluggable services: Authentication performed by the servlet container and JAAS make it possible to swap the authentication scheme.
- Page-based Architecture: Allows for the grouping/division of portlets on a per-page basis.
- Existing Framework support: Portlets utilizing Struts, Spring MVC, Sun JSF-RI, AJAX, or MyFaces are supported.
Themes and Layouts
- Easily swappable themes/layouts: New themes and layouts containing images can be deployed in WAR archives.
- Flexible API: Theme and Layout API are designed to separate the business layer from the presentation layer.
- Per-page layout strategy: Different layouts can be assigned to different pages.
User and Group Functionality
- User registration/validation: Configurable registration parameters allow for user email validation before activation.
- User login: Makes use of servlet container authentication.
- Create/Edit Users: Ability for administrators to create/edit user profiles.
- Create/Edit Roles: Ability for administrators create/edit roles.
- Role Assignment: Ability for administrators to assign users to roles.
Permissions Management
- Extendable permissions API: Allows custom portlets permissions based on role definition.
- Administrative interface: Allows for permissions assignments to roles at any time for any deployed portlet, page, or portal instance.
Content Management System
- JCR-compliant: The CMS is powered by Apache Jackrabbit, an open source implementation of the Java Content Repository API.
- DB or Filesystem store support: Configurable content store to either a filesystem or RDBMS.
- External Blob Support: Configurable content store allowing large blobs to reside on filesystem and content node references/properties to reside in RDBMS.
- Versioning support: All content edited/created is autoversioned with a history of edits that can be viewed at any time.
- Content Serving Search-engine-friendly URLS: http://yourdomain/portal/content/index.html (Does not apply to portlet actions.)
- No long portal URLS: Serve binaries with simple urls. (http://domain/files/products.pdf)
- Multiple HTML Portlet instance support: Allows for extra instances of static content from the CMS to be served under separate windows.
- Directory Support: create, move, delete, copy, and upload entire directory trees.
- File Functions: create, move, copy, upload, and delete files.
- Embedded directory-browser: When copying, moving, deleting, or creating files, administrators can simply navigate the directory tree to find the collection they want to perform the action on.
- Ease-of-use architecture: All actions to be performed on files and folder are one mouse-click away.
- Full-featured HTML editor: HTML Editor contains WYSIWYG mode, preview functionality, and HTML source editting mode. HTML commands support tables, fonts, zooming, image and url linking, flash movie support, bulleted and numbered list, and dozens more.
- Editor style-sheet support: WYSIWYG editor displays current Portal style-sheet, for easy choosing of classes.
- Internationalization Support: Content can be attributed to a specific locale and then served to the user based on his/her browser settings.
Message Boards
- Instant reply: Instant reply feature, makes for one-click replies to posts.
- Post quoting: Quote an existing topic and poster within a reply.
- Flood control: Prevents abuse of multiple posts withing a set configurable time-frame.
- Category creation: Create a category that contains forums within it.
- Forum creation: Create a forum and assign it to a specific category.
- Forum modification: Edit, move, delete forums.
- Forum and category reordering: Reorder categories and forums in the order you would like them to appear on the page.
This document is intended for those using JBoss Portal as End-Users. This is a "Where do I Click?" Guide.
For Portlet developers, Portal administrators, and those wishing to implement/extend the JBoss Portal framework, there is a Reference Guide available from our documentation page .
We would like to thank all the developers that participate in the JBoss Portal project effort.
Specifically,
- Thomas Heute, for his help on the first-ever version of JBoss Portal and the corresponding documentation. ;-)
- Remy for his help with Tomcat configuration.
- Mark Fernandes and Paul Tamaro from Novell, for their hard work in supplying the portal project with usable and attractive themes and layouts.
- Kev "kevs3d" Roast for supplying us with two working portlets that integrate existing frameworks in to the portal: Sun JSF-RI and Spring MVC Portlet.
- Swarn "sdhaliwal" Dhaliwal for supplying us with the Struts-Bridge, that will allow for existing struts applications to work with the Portal.
- Julien Viet for creating a scalable and flexible architecture... and putting up with all of my crazy ideas.
Contributions of any kind are always welcome, you can contribute by providing ideas, filling bug reports, producing some code, designing a theme, writing some documentation, etc... To report a bug please use our Jira system .
This section will introduce the reader to some basic portal concepts and terms, used within JBoss Portal and this document.
JBoss Portal supports mutliple portal instances running within one container. A portal instance can be viewed as a 'bucket', containing portal objects such as, Portal Pages, Themes, Layouts, and Portlet Windows. It also manages the relationship between the user and the portal itself. The hierarchy of portal objects is depicted as follows:
 |
A portal instance is reachable by the url format http://[domain]/[context]/portal/[portal_name] . In a default/local install, the default portal instance can be reach by http://localhost:8080/portal/portal/default .
Note
Consult your portal administrator for information on the available portal instances - some of which may have restricted logins, not found in others.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.
A portal page is reachable by the url format http://[domain]/[context]/portal/[portal_name]/[page_name] . In a default/local install, the default page can be reach by http://localhost:8080/portal/portal/default/default . Likewise, the News Page in a default install can be reached by http://localhost:8080/portal/portal/default/News .
More, on navigating the portal pages and what they contain can be found in, Section 1.2, “The Portal Pages”
Portlet Windows are found on Portal Pages and contain the HTML markup for a specific portlet instance.
 |
The diagram above, shows the default JBoss Portal page with certain window-related items highlited (in red). Lets look at these items:
Window Title Defines the content and purpose of the individual portlet window.
Window Fragment The generated HTML markup produced by the portlet on the server-side.
Window Controls Window controls are divided in to two categories: Window State and Portlet Mode .
Window State:
(Normal)
- Normal window state, is what you see in the illustration above. All portlet
windows take up a similar amount of space on the page.
(Minimized)
- The portlet window renders, minimal-to-no markup.
(Maximized)
- The portlet window takes up a maximum amount of real estate on the page.
Portlet Mode:
(View)
- In View mode, the portlet renders markup reflecting the current window state of
the portlet. The diagram above has all portlet windows in View mode.
(Edit)
- Allows a user to customize the portlet's behaviour.
(Help)
- A portlet should provide help information to the user.
Navigating the portal pages is normally performed either by typing in a specific URL ( Section 1.1.2, “Portal Pages” ), or using the Navigation Tabs at the top of the page.
 |
Each page, in the default installation of JBoss Portal is explained in the following sections, along with the portlets found within them.
The default page contains the following portlets:
 |
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 using the UserPortlet to login.
Note
Administrators should view, Section 4.1, “Managing Users” , for managing the portal Userbase. Only user operations are covered in this section...
 |
The User Portlet allows a user to:
Login to the Portal
Login using the credentials (by clicking the Standard Login link):
Username: user Password: useror
Username: admin Password: adminOnce successfully logged in, the user will have additional functionality at his disposal, that is covered in the following sections.
Create a new account
Create a new account by clicking on the Create link in the portlet. A User can then fill in the necessary information to create an account on the system:
Edit personal information.
A user has the ability to edit his personal information at any time by clicking on the Edit Info link.
 |
Allows a user to navigate to different Portal Pages, by clicking on the page names. Similar to the Navigation Tabs at the top of the page.
 |
Renders data from the Content Management System embedded with the Portal. Users are able to navigate the content, view images, binary files, etc.. via this portlet.
Displaying content is done by the portal using a path mapper. For example, if we wanted to display a zip file, located in /default/foo/bar.zip , we would type in the URL http://localhost:8080/content/default/foo/bar.zip . Notice how the path to the content, is prefixed with the '/content' term. Although in this example we are describing binary content retrieval, the same is to be said for text/html files. Keep in mind, however, that binary files are displayed outside of the portal pages, but text/html are displayed inside the CMSPortlet Window.
Serving Logic: The CMS Portlet now serves content based on the user's locale setting. For example: if a user's locale is set to Spanish in his browser, and he requests URL: default/index.html , the CMSPortlet will first try and retrieve the Spanish version of that file. If a Spanish version is not found, it will then try and retrieve the default language version set for the CMSPortlet (set to English, by default).
Note
Administrators should view, Chapter 3, Administration - Content Management System , for managing the data in the CMS.
 |
The News Page contains customizable weather and news displays from common internet feeds. An open internet connection on the server-side is therefore required for them to operate. ;-)
This page contains the following portlets:
 |
The Weather Portlet retrieves an RSS weather feed, based on a key (commonly a US Postal Code), and displays it as HTML to the user.
Additionally, a user is able to modify his preference in location by going in to the Portlet's Edit
Mode (click
). Any valid US Postal Code can be inputted here. Once the form is submitted, this property will be saved
in the user's preference, so he will always see the same weather data for his location, when logged in.
 |
Not in the United States? Follow these steps to configure the Weather portlet to display information for your area.
Enter your city name in the location field, found on the page:
Find your location on the list under the form and click on it (In this case, its Marseille, France ):
Copy the location digits from the address bar in your browser (In this case, its FRXX0059 ):
Paste these numbers in to the weather portlet edit form (In this case, its FRXX0059 ):
Hit submit ...
 |
The News Portlet retrieves an RSS news feed, based on a url, and displays it as HTML to the user.
Additionally, a user is able to modify his preference in RSS feed source by going in to the Portlet's
Edit
Mode (click
). Once the form is submitted, this property will be saved
in the user's preference, so he will always see the same news source, when logged in.
 |
Note
This portlet is capable of handling most RSS 1.0 and RSS 2.0 feeds.Items in this test page change frequently. They are used mainly by the JBoss Portal Development team to debug and test new functionality. For that reason, these items are not covered in this document. It is recommended that Portal Administrators remove this page for that reason.
Note
You must be logged in as an administrator, or have proper priviledges to see this page.
 |
The Admin Page's purpose is to allow an administrator to manage all aspects of the portal (Follow the links for in-depth reviews of these functions):
Users/Roles (See: Section 4.1, “Managing Users” , Section 4.2, “Managing Roles” )
Content Management System (See: Chapter 3, Administration - Content Management System )
Portal Objects (themes, layouts, portal instances, pages, windows, security, and deployed portlets) (See: Chapter 2, Administration - Portal Object Management (Dynamicity) )
Note
Viewing the Management Portlet is accomplished by logging in as an admin (admin/admin) and navigating to the Admin page.The concept of dynamicity is that all portal objects are able to dynamically be modified at runtime, eliminating the need to struggle with large xml files, or restarting the application server for changes to take effect. In the scope of dynamicity, Portal objects are defined and can be altered as follows:
- Portal Instances: Multiple Portal instances can be launched at any time, secured, and skinned.
- Pages: Multiple pages, composed of windows, can coexist inside a portal instance, secured and each could have its own theme applied, if desired.
- Portlets: Can be hot-deployed and will instantly register with the portal, appearing in the management portlet.
- Portlet Instances: Instances can be created/destroyed. Their preference variables can be modified at runtime, instances assigned to windows and secured.
- Windows: Windows can be secured, created/destroyed, and assigned to specific pages.
- Themes/Layouts: Can be hot-deployed and will register with the portal, appearing the management portlet, allowing for dynamic customization of any of the above components.
Note
Many of the operations that can be done via the Management portlet are done in the context of the current user session. In order to see the changes on the affected pages, please log out and log back in.Dynamicity allows an administrator to manage the entire portal deployment from within a portlet. Some of the many tasks available to administrators are:
Note
For the remainder of this chapter, the term object will be used to mean any Portal, Page, Portlet, or Window.Administrators may manage the portal, pages, subpages, and windows at any time, by clicking on the "Portal" tab at the top of the Management Portlet. The components currently deployed in the portal container are displayed in a tree-structure for ease-of-navigation and modification.
 |
Expanding the tree structure will reveal all pages and portlet windows deployed in a particular portal instance.
 |
Selecting the Security option, allows an administrator to secure the portal instance. On this screen, you can select and unselect portal-wide security settings for a given role. Security settings are defined as follows:
- view Users can view the object.
- viewrecursive Users can view the object and child objects.
- personalize Users are able to view AND personalize the object.
- personalizerecursive Users are able to view AND personalize the object AND its child objects.
 |
Clicking on the Portlet tab and then clicking on a specific portlet allows you to create a new instance of this portlet.
 |
Clicking on the Instance tab and selecting a portlet instance, displays a screen which allows an administrator to edit the portlet instance preferences.
 |
Selecting the Security option, allows an administrator to secure the portlet instance. Security settings are defined as follows:
- view Users can view the object.
- viewrecursive Users can view the object and child objects.
- personalize Users are able to view AND personalize the object.
- personalizerecursive Users are able to view AND personalize the object AND its child objects.
Note
Depending on whether you are securing a portlet or an instance, keep in mind that instance security constraints take precedence over portlet security settings.
|
Expanding the tree structure will reveal all pages deployed in a particular portal instance, that an administrator can then customize.
 |
By selecting a portal instance, and then selecting the Manage option, you can create a new page. Simply assign a name to a page and submit the form.
 |
Selecting a portal page, allows you to Manage the order in which windows appear and the layout column in which they will appear. Additionally, you can name and assign portlet windows on the selected page, create subpages, or even delete the page.
 |
Selecting a portlet window, allows you to Manage which portlet instance is assigned to it, and even delete/remove the window from the page.
 |
Selecting a portal window under the Portal tab, and selecting the Theme option, allows an administrator to modify the look-and-feel for the chosen portal page.
Note
From this screen, an administrator can elect to set all values to emptyrenderer so the portlet window is displayed with no decorations and appears to be part of the layout.
 |
Selecting the Security option, allows an administrator to secure the portal page. On this screen, you can select and unselect page security settings for a given role. Security settings are defined as follows:
- view Users can view the object.
- viewrecursive Users can view the object and child objects.
- personalize Users are able to view AND personalize the object.
- personalizerecursive Users are able to view AND personalize the object AND its child objects.
The CMSAdmin Portlet allows control over the content management system.
Viewing the CMSAdmin Portlet is accomplished by logging in as an admin (admin/admin) and navigating to the Admin page.
You should then be presented with a page that is similar to this:
 |
It is important for a user to note the action icons used throughout the portlet and their meanings. The action options change depending on what type of resource the user is dealing with. All possible actions are listed here:
- Launches HTML WYSIWYG Editor window for HTML files. Launches upload dialog
windoe for binary type files.
- Opens the copy file/folder dialog window.
- Opens the move file/folder dialog window.
- Launches HTML WYSIWYG Editor window.
- Opens the create folder dialog window.
- Opens the upload file dialog window.
- Opens the upload archive dialog window.
- Opens the export archive dialog window.
- Opens the delete confirmation dialog window.
- In the case of files, opens the file properties view. In the case of
folders, opens the folder listing.
- Moves up the folder tree when clicked on.
- Expands directory tree.
Additionally, there are icons that help describe the types of resources present on the page:
- Denotes this resource as a file.
- Denotes this resource as a folder.
This section describes common actions an administrator can perform from within the AdminCMS Portlet:
 |
A user can list directory contents by either clicking on the
icon, or clicking on the directory's "DisplayName". All actions are possible
from this screen.
 |
Clicking on the
icon or the "DisplayName" of a file brings up the File Properties page.
 |
The File Properties window displays all the possible actions available to perform on a file.
Version and Locale Information are also contained on this screen. Note that any version
labeled with the
is the current "live" version shown to users.
Clicking on the
icon displays the copy file/directory dialog window.
 |
The copy resource window allows a user to copy files to any folder on the system, as
well as copy whole directory trees to any directory on the system. A user can select which
destination directory to copy the resource to, by using the directory browser. Clicking the
icon expands the directory tree. Clicking on the name of the directory within
the tree, sets it as the destination directory for the copied resource.
Clicking on the
icon displays the move file/directory dialog window.
 |
The move resource window allows a user to move files to any folder on the system, as
well as move whole directory trees to any directory on the system. A user can select which
destination directory to move the resource to, by using the directory browser. Clicking the
icon expands the directory tree. Clicking on the name of the directory within
the tree, sets it as the destination directory for the moved resource.
Clicking on the
icon displays the delete file/directory confirmation window.
 |
The delete resource confirmation window allows a user to delete a file, or a directory on the system. Note that deleting a directory, will delete the entire tree, so all directories under the deleted one, will also be deleted.
Warning
Currently, there is no way to retrieve deleted files/directories! Deleting a file or directory is permanent!Clicking on the
icon displays the create directory dialog window.
 |
The create directory resource window allows a user to create a directory under chosen path. On this window, a user can specify a name for the new empty directory and assign it a description.
Clicking on the
icon displays the create file dialog window with the embedded WYSIWYG editor
and directory browser.
 |
The create file window allows a user to create a text or HTML file using the embedded
WYSIWYG HTML editor. The editor is a fully-functional HTML editor with a myriad of HTML
functions. It also includes a preview
button and a source view
button.
An in-depth walk-through of the editor is beyond the scope of this document. However,
the editor does contain help pages within it, that can be accessed by clicking the
icon.
Note
It is important to note here that when creating links to images or other resources within the system, as user must use the relative file path to that resource. ie: images/hello.gif. Keep in mind at all times that the document base is http://localhost/portal/ by default!Additionally, a user can set a title for the file that will be used in the portlet title bar, and a language for the file, used in serving localized content.
Clicking on the
icon displays the upload file dialog window.
 |
The upload file window allows a user to upload files to any directory on the system. The
upload process will work on files up to 1GB and of all types. A user can select which
destination directory to upload the resource to, by using the directory browser. Clicking
the
icon expands the directory tree. Clicking on the name of the directory within
the tree, sets it as the destination directory for the uploaded resource. Additionally, a
user can set a title for the file that will be used in the portlet title bar, and a language
for the file, used in serving localized content.
Clicking on the
icon displays the upload archive dialog window.
 |
The upload archive window allows a user to upload archives to any directory on the
system. The system will then explode the archive, create versions, and place all the files
in the repository. A user can select which destination directory to upload the resource to,
by using the directory browser. Clicking the
icon expands the directory tree. Clicking on the name of the directory within
the tree, sets it as the destination directory for the uploaded resource. Additionally, a
user can set a language for the archive files, used in serving localized content.
Clicking on the
icon displays the export archive dialog window.
 |
The export archive window allows a user to export entire directory structures as zip files. The system
will aggregate all contents of a specific directory, and present to the user to download it.
A user can select which source directory to export the resources from,
by using the directory browser. Clicking the
icon expands the directory tree. Clicking on the name of the directory within
the tree, sets it as the source directory for the export resource. Additionally, a
user can set a language for the files to be exported.
Note
Version information is not exported. Only versions labeled "Live" are exported!
 |
Clicking on the
icon displays the edit file dialog window with the embedded WYSIWYG editor
and directory browser.
 |
The edit file window allows a user to edit a text or HTML file using the embedded
WYSIWYG HTML editor. The editor is a fully-functional HTML editor with a myriad of HTML
functions. It also includes a preview
button and a source view
button.
A user may specify at this point if he would like to make the new edit "live", or available in production. Additionally, a user can set a title for the file that will be used as the portlet window title.
This section covers the administrator functions made available by the UserPortlet. For end-user operation, see: Section 1.2.2.2, “User Portlet” . Adminsitrative functions are available once you are logged in with the proper credentials (admin/admin)
 |
All administrative functions are available after clicking on the ' List of all users ' link.
Managing users using the UserPortlet consists of:
 |
Typing a partial username in the form text field, allows you to search for usernames matching that criteria.
Clicking on the Profile link on the search page will allow you to edit a user's profile data, and even reset his password.
 |
The role portlet is dedicated to create and edit roles. A role will be used to grant different permission level to different portlets, pages, or portal instances. A user can have several roles.
The RolePortlet is accessible once logged in as an administrator (admin/admin) from the Admin Page
 |
Managing roles using the RolePortlet consists of:
 |
To create a new role, you need to define a short name that will be used for reference, and a display name for displaying to the user, for example admin would be a good name for the display name Administrators , changing the display name will not affect the security rules.
 |
While editing a role, you just need to pick an exising role then change the display name. Additionally, you can delete existing roles from this screen.
