Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-federated-security.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-federated-security.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-federated-security.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-federated-security.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,37 @@ +<?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>Guide to Federated Security</title> + <subtitle>Federated Security Configuration Overview</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> +</properties> +<body> +<section name="Configuring Jetspeed-2 Federated Security"> +<p> +1. override web.xml in custom build +2. edit web.xml + * remove security-constraints "Login" + * remove LoginProxy, LoginServlet, LoginError, LoginRedirector, ... + * remove servlet-mapping for above servlets +</p> +</section> +</body> +</document> \ No newline at end of file
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-jetui.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-jetui.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-jetui.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-jetui.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,616 @@ +<?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>Guide to JetUI</title> + <subtitle>A guide to using the JetUI Pipeline in Jetspeed</subtitle> + <authors> + <person name="David Taylor" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Introduction to JetUI"> +<p> +Jetspeed version 2.2.1 introduces JetUI rendering engine. JetUI is a replacement for the now deprecated and removed Jetspeed Desktop pipeline. JetUI is primary concerned with advanced portal +customization and rendering features. With JetUI, we have not abandoned pure server-side rendering. Jetspeed will still fully support classic server side rendering of portal pages. +With version 2.2.1, two rendering engines are made available to you directly from the installer: +<ol> +<li>The Classic (Portal Page) rendering engine</li> +<li>The JetUI Rendering engine</li> +</ol> +In this document, we introduce the many new features of JetUI... +<ul> +<li><a href="#spaces">Jetspeed Spaces</a>, secured areas of the portal site for workgroups and projects</li> +<li><a href="#spacesNavigator">The Space Navigator</a>, to quickly navigate to spaces</li> +<li>JetUI uses a simpler algorithm to <a href="#mappingURLs">map URLs</a> directly to spaces and pages, it does not use the profiler</li> +<li><a href="#dragDrop">Drag and Drop of portlets</a></li> +<li><a href="#docking">Docking toolbars</a></li> +<li><a href="#detached">Detaching and Closing portlets</a></li> +<li><a href="#resizing">Resizing of portlets</a></li> +<li><a href="#toolbox">The Jetspeed Toolbox</a>, a dockable portlet selector, layout selector, and theme selector</li> +<li><a href="#navigator">Jetspeed Navigator</a> to navigate over spaces, maintenance over pages, folders, links</li> +<li><a href="#preview">Preview Portlet Mode</a> from Jetspeed Toolbox</li> +<li><a href="#clone">Portlet Cloning</a> from Jetspeed Toolbox</li> +<li><a href="http://portals.apache.org/jetspeed-2/devguide/guide-rest-api.html";>JAX RS Services</a> for Portal Customization and Registry manipulations built into JetUI</li> +<li>Integration with <a href="guide-page-templates.html">Page and Dynamic templates</a></li> +<li><a href="#extensions">Extensions to PSML to support JetUI constructs</a></li> +<li><a href="#properties">Jetspeed Properties Configurations</a></li> +<li><a href="#pipeline">Pipeline Configurations</a></li> +</ul> +As of version 2.3.0 of Jetspeed, there are some limitations to what JetUI can currently do: +<ul> +<li>no support for customization of nested layouts</li> +<li>only four themes supported (one column, two column, three column, four column)</li> +<li>no support for <a href="guide-page-templates.html">advanced templating</a> (DPSML, TPSML) customization</li> +<li>JetUI does not work with the Jetspeed Profiler. JetUI does not support subsites. Instead of subsites, use the Spaces features.</li> +</ul> +</p> +<b>Switching on JetUI</b> +<p> +There are a few options for turning on the JetUI rendering and customization engine. The first option is to install Jetspeed using our <a href='http://portals.apache.org/jetspeed-2/download.html'>packaged installer</a> +The installer will ask you if you would like to install the <b>JetUI</b> or <b>Classic</b> portal pipeline. You cannot run both at once. The default is JetUI. +</p> +<img src="images/installer.png"/> +<p> +The second option is to build Jetspeed using the <a href="http://portals.apache.org/jetspeed-2/buildguide/jetspeed-mvn-plugin.html";>Custom Builder</a>. + The <a href="http://portals.apache.org/jetspeed-2/buildguide/index.html";>Build Guide</a> is a bit long winded and has a lot of information about Maven internals. + Here are a few commands distilled to help you get past all that... + </p> +<p>List all build commands available to from the custom builder:</p> +<source><![CDATA[ +mvn jetspeed:mvn -Dlist +]]></source> +<p>Build and deploy the entire JetUI-enabled portal demo with several portlet apps and deploy it to Tomcat</p> +<source><![CDATA[ +mvn jetspeed:mvn -Dtarget=ui +]]></source> +<p>Build and deploy the JetUI-enabled minimal with only j2-admin portlet app and deploy it to Tomcat</p> +<source><![CDATA[ +mvn jetspeed:mvn -Dtarget=min-ui +]]></source> +<p>Variants of the two options above, with <a href="config-overrides.html#DBPSML">DBPSML</a>L-enabled</p> +<source><![CDATA[ +mvn jetspeed:mvn -Dtarget=ui-dbpsml +mvn jetspeed:mvn -Dtarget=min-ui-dbpsml +]]></source> +<p> +The third option is to manually switch to using the JetUI portal on a deployed installation of Jetspeed. Editing the WEB-INF/conf/jetspeed.properties (or WEB-INF/conf/override.properties), +you can manually switch from Classic mode to JetUI mode and back by setting the <b>jetui.customization.method</b> to Classic: <b>server</b>; or JetUI: <b>ajax</b>. +</p> +<source><![CDATA[ +jetui.customization.method=ajax +]]></source> +<p> +Additionally, you can set the default pipeline, although it is not necessary if you directly hit the JetUI pipeline by addressing all URLs with /jetspeed/ui instead of /jetspeed/portal +</p> +<source><![CDATA[ +pipeline.default = jetui-pipeline +]]></source> +<p> +Finally, if you would like for /jetspeed/portal to go to the JetUI pipeline, change the pipelines.xml pipeline-map bean to: +</p> +<source><![CDATA[ + <entry key='/portal'> + <value>jetui-pipeline</value> + </entry> +]]></source> +<br/> +<a name="spaces"/> +<subsection name="Jetspeed Spaces"> +<p> +If you will be deploying a JetUI site, it is important to understand how spaces are configured. A space is a top +level organization of the Jetspeed site. You can use spaces to organize or group projects or teams into a common area. +Spaces have a lot in common with folders, and they support all folder functionality and metadata. Just like folders, Spaces can have specific security constraints on them. + There are two administrative tools available for managing Spaces: + the <a href='../adminguide/space-manager.html'>Space Manager</a> and the Space Navigator. The Space Manager allows you to maintain spaces, for example if you want to add or modify + a space, use the Space Manager. + </p> +<b>Configuring a Space</b> +With a two exceptions, Spaces can only be top level folders. You can configure your spaces by editing the <b>folder.metadata</b> file of any space. +In a <b>folder.metadata</b> file of any top level directory, you can make that folder a space by adding the <b>space-owner</b> metadata property: +<source><![CDATA[ + <metadata name='space-owner' xml:lang='en'>admin</metadata> +]]></source> +<p> +Once you have added this single property, the folder will be promoted from a normal folder to a space. You can also use the Space Manager to create spaces. +There are two other kinds of Spaces: +</p> +<ul> + <li>The default or Public Space</li> + <li>User Spaces, every user gets their own space</li> +</ul> +<p> +The Public Space is really the root directory of the Jetspeed site. It has a security constraint of <b>public-view</b>, meaning that only the administrator can edit it, and that all +other users can view the public space. The Public Space is important in that you can set metadata here that is inherited by all other spaces and folders in the system. For example, +you can set the theme or default security policy for the entire site in the folder.metadata file in the root Public Space. Of course Spaces can override these settings. +</p> +<p> +Every user gets their own space. User spaces are located in the <b>/_user/{username}</b> folders. The username is usually set as the space-owner in the +space-owner metadata tag. +</p> +<p> +When a new user is added to the system, Jetspeed will create a Home space for that user, and copy in the contents of a template folder as the default home space for that user. +You can configure the new user template in the <b>/_template/new-user</b> folder. Here you will find a folder.metadata file, along with several other page files which are all +copied into a new user home space when that user is created. The space-owner metadata tag is added automatically to the folder-metadata by Jetspeed. Additionally, certain +regular expression rules are used to build the menus fro the Jetspeed Page Navigator. The regex below is the default, and it tells the Page Navigator to show menus for +pages and folders in the current directory, as well as all links in the home space of the user. +</p> +<source><![CDATA[ + <menu name="space-navigations" regexp="true" options="+/*/,+/*.psml" depth="-1"/> + <menu name="space-links" regexp="true" options="+/*.link"/> +]]></source> +<p> +There is also a template that is used for when new spaces are created. This template is found under <b>/_template/space</b>. Here you can configure which default pages, links and +security constraints are applied when creating a new space. Feel free to modify the files, or add more pages in the user and space templates found in /_template for your systems. +</p> +<b>Future Directions - Spaces</b> + <p> +Spaces also support an additional organization of content called Environments. Environments are a collection of spaces. JetUI does not currently support environment administration. +Spaces were introduced to Jetspeed with version 2.2.1, along with JetUI. Future versions of Jetspeed will support full domain mappings to spaces. Domain mapping will enable use cases +like white label portals, where different URLs map to different Spaces or Environments. In an upcoming release, Jetspeed will support multi-domain security. This means you +can setup a domain of users, and associate those users with a domain and set of Spaces. +</p> +</subsection> + +<a name="spacesNavigator"/> +<subsection name="The Space Navigator"> +<p>The Space Navigator is a special navigational portlet giving users quick access to spaces. From the Space Navigator, you can navigate to any space in the system where you +have secure access to view that space. Additionally, from the Space Navigator, the Admin can Edit the current space, as well as create a new space. The Space Navigator is +implemented using two new features introduced with JetUI: page templates and detached portlets. In order for the Space Navigator to appear on every page in the system, we have +configured the Space Navigator in the root folder in the page template named <b>template.tpsml</b>. Since this portlet definition is in the system wide page template, it will +automatically appear on every page in the system, allowing your users to always have access to space navigation. +</p> +<source><![CDATA[ +<fragment id="jsSpaceNavigator" type="portlet" name="j2-admin::SpaceNavigator" decorator='clear'> + <property name="y" value="300"></property> + <property name="x" value="20"></property> + <property name="state" value="detach"></property> + </fragment> +]]></source> +<p> +Additionally, the Space Navigator is a detached portlet. JetUI introduced a new special property to fragments named <b>state</b>. We set this property to the value <b>detach</b>. + If a portlet is detached, it is not limited +to the flow layout control of most portal pages. Instead it can be placed at a specific area on the page. See the <b>x and y</b> properties, which are used to locate the +portlet at a specific location in the page header area. Detached portlets can also be dragged and moved around. However, we do not want the portlet to be moved, so we use +a <b>clear</b> decorator, meaning the portlet has no title bar. Since JetUI drags and drops portlets by the title bar, if we use a clear decorator, the portlet cannot be moved. +</p> +<img src='images/space-navigator.png'/> +</subsection> + +<a name="mappingURLs"/> +<subsection name="Mapping URLs"> +<p>In Classic Jetspeed, URLs are mapped using the <a href="guide-profile.html">Jetspeed Profiler</a>. The Profiler uses a powerful set of rules to locate a page, based on +runtime parameters such as language, country code or media type. While the profiler is powerful, it is also complicated to configure. JetUI simplifies URL mapping by having not +using the profiler. This means that a URLs map directly to the logical folder or page in the Jetspeed site. JetUI does not support subsites, since subsites are driven by profile rules. +</p> +</subsection> + +<a name="dragDrop"/> +<subsection name="Drag and Drop of portlets"> +<p>Portlets can be moved around the page by clicking on their title bar, holding the mouse down, and dragging the portlet to another location on the page. By default, you can only +drag portlets by their title bar. There are two modes of drag and drop: +<ul> +<li>Flow Control Drag and Drop</li> +<li>Z-Order Drag and Drop</li> +</ul> +With flow control drag and drop, portlets will always stay in rows and columns. If you drag over another portlet, +that portlet will be shifted out of the way in order to make space for the dragged portlet to be placed. Z-Order drag and drop is only available when a portlet is detached. Where +ever you drag the portlet to and drop it, that is where the portlet stays. The dragged portlet can actually overlap other portlets. The last dragged portlet gets the highest z-order, meaning +that it will stay on top of all other portlets, until a new portlet is selected (by clicking on its title bar) or moved. By default, all portlets use flow control. You can press the detach +button on a portlet title bar to detach the portlet and put it in z-order drag and drop mode. Likewise, pressing the attach action will put the portlet back in flow control drag and drop mode. +</p> +<p>There is a CSS style configured in jetspeed.properties to indicate which div of a portal is the draggable part. This property is <b>jetui.style.drag.handle</b> which defaults to the decorator +style named <b>.PTitle</b></p> +</subsection> + +<a name="docking"/> +<subsection name="Docking toolbars"> +<p>JetUI supports two toolbars, one docked on the left-side, and one docked on the right-side of the page. These toolbars are optional, but out of the box they are configured to be enabled. +In the demo distribution of JetUI, we have placed the toolbars in the system wide <a href="guide-page-templates.html">page template</a>, <b>template.tpsml</b>, meaning that all pages will by default display the toolbars. You can +easily configure the page template to not have toolbars, or only have one toolbar, by editing the template.tpsml file and removing the two fragment definitions. The fragment definitions +must use a special fragment id by convention. For the left toolbar, the fragment id must be <b>jstbLeft</b>. For the right toolbar, the fragment id must be <b>jstbRight</b>. If these fragments +are not found on a page, the toolbar will not be displayed. +</p> +<source><![CDATA[ + <fragment id="jstbLeft" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + <property name="row" value="0"></property> + <property name="column" value="0"></property> + <property name="state" value="normal"></property> + <property name='toolbar' value='true'></property> + <property name='class' value='jsLeftToolbar'></property> + <fragment id="jsPageNavigator" type="portlet" name="j2-admin::PageNavigator"> + <property name="row" value="0"></property> + <property name="column" value="0"></property> + <property name="state" value="normal"></property> + <property name="tool" value="true"></property> + </fragment> + </fragment> +]]></source> +<p> + Notice that there are special properties for a toolbar. A toolbar is a layout. It requires a special property to denote that it is a toolbar. This property is aptly named <b>toolbar</b> and is set to true. + A toolbar fragment has a location on the page specified by <b>row</b> and <b>column</b> properties. It also has a <b>state</b> + property, which can be either <b>normal</b> or <b>closed</b>. There are arrow buttons at the top of the toolbar, which allows you to hide or open the toolbar. This state is persisted + per user in the state property of the fragment. When the toolbar is open, the state is normal, when closed, the state is closed. Finally, a toolbar has a CSS class which is used to + format the layout. The layout is a single column containing one portlet, the Page Navigator, which is flagged as a tool. Tools can not be drop targets when using flow control drag and drop. + In this case there is only one portlet in the toolbar. Of course more than one portlet could be placed in the toolbar. +</p> +<p>Here is the definition for the right toolbar, which holds the Jetspeed Toolbox</p> +<source><![CDATA[ + <fragment id="jstbRight" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + <property name="row" value="0"></property> + <property name="column" value="2"></property> + <property name="state" value="normal"></property> + <property name='toolbar' value='true'></property> + <property name="state" scope="user" scopeValue="guest" value="closed"></property> + <property name='class' value='jsRightToolbar'></property> + <fragment id="jsToolbox" type="portlet" name="j2-admin::JetspeedToolbox"> + <property name="row" value="0"></property> + <property name="column" value="0"></property> + <property name="state" value="normal"></property> + <property name="tool" value="true"></property> + </fragment> + </fragment> +]]></source> +<img src="images/nav-toolbar.png"/><img src="images/toolbox-toolbar.png"/> +</subsection> + +<a name="detached"/> +<subsection name="Detaching and Closing portlets"> +<p>JetUI introduces a three new portlet window actions: detach, attach and close. Actually detach and attach are toggles, a portlet is either detached or attached, it can never be both. +A close up look at the portlet title bar shows the two new action icons, the X is the close button, which will remove the portlet from the page. The button to its right, with the arrow hooking to the left, +is the detach button. <img src="images/close-detach.png"/> Once a portlet is detached, the detach button becomes an re-attach button, the one with the arrow hooking to the right <img src="images/close-attach.png"/> +Detaching a portlet puts the portlet in Z-Order drag and drop mode, meaning it always tries to stay on top of all other portlets. By pressing the attach button, the portlet is put back into +the nearest slot in a column, going back to flow control drag and drop and rendering. The detached state is stored on the fragment, and the state can be on a per user basis. +Here we see both the row, column and x,y properties set on this fragment. The row and column or only relevant for an attached portlet being rendering in flow control mode. The x,y properties +are only relevant when the portlet is detached. Also notice the state of this fragment is <b>detach</b>. Additionally, there is a new attribute on properties named <b>scope</b>. Below you can see the x,y values are scoped for a user, with +the <b>scopeValue</b> set to the username admin. Each user can have their portlet positioning customized to their settings. As you can see, the XML can get quite large with many users. It is therefore recommended to always store PSML in the database with JetUI. +</p> +<source><![CDATA[ + <fragment id="dp-22" type="portlet" name="j2-admin::ForgottenPasswordPortlet"> + <property name="row" value="1"></property> + <property name="column" value="0"></property> + <property name="x" scope="user" scopeValue="admin" value="536.0"></property> + <property name="y" scope="user" scopeValue="admin" value="88.0"></property> + <property name="width" scope="user" scopeValue="admin" value="1121.0"></property> + <property name="height" scope="user" scopeValue="admin" value="120.0"></property> + <property name="state" scope="user" scopeValue="admin" value="detach"></property> + <property name="row" scope="user" scopeValue="admin" value="4"></property> + </fragment> +]]></source> +<p> +Here is a screen shot of a bunch of portlets all detached. As you can see, it is like a desktop. All +portlets get can get focus when clicked on, going to the top of the rendering order for the page. +</p> +<img src="images/detached.png"/> +</subsection> + +<a name="resizing"/> +<subsection name="Resizing of portlets"> +<p>Only detached portlets can be resized. Resizing is rather easy to do. Simply grab the portlet by the bottom right hand corner, where you will see a gradient icon, and drag it away to make +it bigger, or in towards itself to make the portlet window smaller. <img src='images/resize.png'/> If a portlet is attached, the gradient will not be visible. +When a portlet is resized, two new attributes are stored with the fragment, <b>height</b> +and <b>width</b>. This is how Jetspeed stores the width and height of a resized portlet. Notice how the height and witdth properties are store with a <b>user</b> scope, and for the scopeValue the +name of the user is stored as <b>dave</b>. Each user can have their portlet window sizes customized to their settings. +As you can see, the XML can get quite large with many users. It is therefore recommended to always store PSML in the database with JetUI. +</p> +<source><![CDATA[ + <fragment id="dp-22" type="portlet" name="j2-admin::ForgottenPasswordPortlet"> +... + <property name="width" scope="user" scopeValue="dave" value="1121.0"></property> + <property name="height" scope="user" scopeValue="dave" value="120.0"></property> + <property name="state" scope="user" scopeValue="dave" value="detach"></property> + </fragment> +]]></source> + +</subsection> + +<a name="toolbox"/> +<subsection name="The Jetspeed Toolbox"> +<p> +The Jetspeed Toolbox is a dockable portlet, designed to make user customizations very easy in just one click. +The toolbox can be docked to the left or right side of the page, or it can float freely on top of the page. +The toolbox contains three panels giving you quick access to adding portlets, changing layouts, or changing themes: +</p> +<ul> +<li>Portlet Selector</li> +<li>Layouts</li> +<li>Themes</li> +</ul> +<b>Portlet Selector</b> +<p> +The Portlet Selector is the first tab. This new feature gives you fast access to page customization by allowing you to search for portlets by keyword or category, and then add the portlets +to your page with one click. The first feature you will see is the search capability of the toolbox. You can type in +a search string, and the portlet selector will return a list of portlets matching your search criteria. The search is on fully-indexed portlet metadata, like keywords and titles, +over all automatically indexed content in the portlet registry. The search index is Lucene, and the Solr enterprise search engine is also supported. + </p> + <img src="images/toolbox.png"/> + <p> + Additionally, portlets can be categorized and filtered based on categories (see the drop down list). + One click addition of portlets is now possible without ever leaving the page being customized. + Portlets are also filtered by secure access. Only portlets that are configured to be viewable to the current user are displayed in the Jetspeed Toolbox. +</p> +<p>Categories are configured in either the j2-admin portlet.xml deployment descriptor, or with the Portlet Application Manager as shown below. Remember when adding a new category, +to give it a new category name prefixed by <b>Keywords:</b>, and then add all the keywords relevant to the category in a comma separated list in the corresponding Value field. +When the search engine searches over portlet content, +it will match the keywords to the search results. The preference named <b>Categories</b> is also important, dont forget to add your category name to this comma-separated list or +your Category will not show up. Finally, +the number of rows of portlets displayed in the portlet selector is controlled by the Rows preference. Ignore the Columns preference. There is also a DefaultCategory preference, which +is the initial category displayed in the portlet selector.</p> +<img src='images/category-prefs.png'/> +<br/> +<b>Theme Selector</b> +<p> +Selecting the theme for the current page is as easy as selecting the theme tab and then clicking on the theme. Jetspeed introduces several new themes in 2.2.1. +Themes are still implemented as page decorators, with a few extensions made in the page decorator decorator.properties. You can find the page decorators in the Jetspeed webapp, +under decorations/layout directory. There are currently for layouts supporting JetUI: Green Earth, Jetspeed, Purple Planet, and Turbo. In order for a decorator to appear in the +theme selector, you will need to add two properties to the decorator.properties file. +</p> +<source><![CDATA[ +icon = images/greenearth.png +compatibility=2.2.1 +]]></source> +<p> +The compatibility setting tells JetUI which version this decorator is compatible. In order to be used with JetUI, the value of the compatibility property must be 2.2.1 or higher. +The icon property is used in the Toolbox to provide a visual of the colors that will be used in the theme. The file should be placed in the decorations/layout/{decoratorName}/images directory. +</p> +<img src="images/theme.png"/> +<br/> +<b>Layout Selector</b> +<p> +Page layouts, selected from the Layout tab, allow the end user the ability to customize the layout of a page with one click. There are four supporte layouts: OneColumn, TwoColumn, ThreeColumn, and FourColumn. +The layouts in JetUI are currently limited to these four choices. +We hope to improve on that in the new future. The images you see are stored under the Jetspeed webapp in the layouts directory. +</p> +<img src="images/layout.png"/> +</subsection> + +<a name="preview"/> +<subsection name="Preview Portlet Mode"> +<p>The Portlet Selector supports previewing portlets, in case you don't want to place the portlet on the page before first having a look at it. There are two ways for a portlet +to support previewing. First, the portlet can provide an image of the portlet, and tell Jetspeed about it in the jetspeed-portlet.xml deployment descriptor of the portlet app +Enter a <b>js:metadata</b> for the given portlet, with the name attribute set to <b>portlet.preview.image</b> where the image path is a portlet application relative path to +a preview image. +</p> +<source><![CDATA[ + <portlet id="WeatherPortlet"> + <portlet-name>WeatherPortlet</portlet-name> + <js:metadata name="portlet.preview.image">/images/preview/weatherportlet.png</js:metadata> + </portlet> + <portlet id="GoogleMapsPortlet"> + <portlet-name>GoogleMapsPortlet</portlet-name> + <js:metadata name="portlet.preview.image">/images/preview/googlemapsportlet.png</js:metadata> + </portlet> +]]></source> +<p> +Portlets can also implement an extended Custom Preview Mode. This requires actually coding in the portlet, as well as the following deployment elements in the portlet.xml on a portlet definition: +</p> +<source><![CDATA[ + <supports> + <mime-type>text/html</mime-type> +... + <portlet-mode>preview</portlet-mode> +]]></source> +<p>Additionally the custom portlet mode must be declared for the portlet applications</p> +<source><![CDATA[ +. .. + <custom-portlet-mode> + <description>Custom Preview Mode</description> + <portlet-mode>preview</portlet-mode> + </custom-portlet-mode> +]]></source> +<img src="images/preview.png"/> +</subsection> + +<a name="clone"/> +<subsection name="Cloning Portlets"> +<p>Portlets can be cloned from the Jetspeed Toolbox. Cloning a portlet creates an actual copy (clone) of the portlet in the portlet registry. When cloning +a portlet, the end user is presented with a dialog for entering different preference values for the cloned portlet. This new feature is meant to facilitate the creation of variations of portlets, +without the need to cut and paste the definitions in the portlet.xml. A typical use case could be a Weather portlet as shown below. For each city, the end user could create cloned variations of the +base Weather portlet using the Clone dialog. The variation is based on the preferences, for example changing the title and city. Note that you must always change the name of the portlet, or you +will not be allowed to create a new portlet. Portlet names must be unique in a portlet application. +Note that when redeploying a portlet application, portlet clones will not be deleted. Clones can also be created and deleted from the Portlet Application Manager</p> +<img src="images/clone.png"/> + +</subsection> + +<a name="navigator"/> +<subsection name="Jetspeed Page Navigator"> +<p> +The Jetspeed Page Navigator enables end users to navigate over and manage their own spaces, pages and folders. Additionally, in the hands of an administrator, + the entire site can be easily managed using the Jetspeed Navigation. The view of the navigator is separated into three sections: + </p> + <ul> + <li>The top section shows the current folder, and all of its contents</li> + <li>An optional second section, showing the Links in the current folder</li> + <li>A third section for adding new pages, folders, and links</li> + </ul> + <p> + The top two sections are really just menus, which can be customized. The menus are looked for in the current folder or spaces folder.metadata. If there isn't a menu definition, then + the menu navigator will search up the folder tree to find a higher definition of a menu. For spaces, the default menus are defined with regular expressions: +</p> +<source><![CDATA[ + <menu name="space-navigations" regexp="true" options="+/*/,+/*.psml" depth="-1"/> + <menu name="space-links" regexp="true" options="+/*.link"/> +]]></source> +<br/> +<b>Context Menus</b> +<p> +All menu options have a context menu. The context menus only appear when you hover near the menu option name, appearing as a down arrow. Folders only have one context menu: Document Ordering. +</p> +<img src="images/doc-ordering.png"/> +<p> +Document ordering allows you to change the order of menu options (pages) in the navigators menu. Pages items have four context menu options for managing pages: +</p> +<ol> +<li>Rename</li> +<li>Move</li> +<li>Copy</li> +<li>Delete</li> +</ol> +<p> +Pages, Folders and Links can be Added to the current folder or space with the Add button at the bottom of the navigator. To add a page, give it a name, select a template, and press add. +</p> +<img src="images/pagenav.png"/> +<p> +Adding Folders and Links works the same as adding pages. The templates made available in the template option are configured in the portlet.xml of the j2-admin app +</p> +<source><![CDATA[ + <portlet-preferences> + <preference> + <name>defaultTemplatePage</name> + <value> + /_template/new-user/min.psml + </value> + </preference> + <preference> + <name>templatePages</name> + <value> + /_template/new-user/min.psml + /_template/new-user/default-page.psml + </value> + </preference> + <!-- If the following pref is blank, then the default admin role and admin user is used. --> + <preference> + <name>spaceAdminRoles</name> + <value></value> + </preference> + </portlet-preferences> +]]></source> +<p>The templates can also be configured in the Portlet Application Manager</p> +</subsection> + +<a name="extensions"/> +<subsection name="Extensions to PSML"> +<p>PSML was extended in version 2.2.1 to support many of the JetUI features. <a href="guide-page-templates.html">PSML Templates</a> are a new feature allowing for toolbars +and space navigators to appear across all pages without needing to declare the portlets and layouts for each and every page. Instead, fragments can be automatically merged +with any page using page templates or fragment references. +</p> +<p> +Fragments had two new attributes added to support multi-user customizations of fragment properties. These two attributes are <b>scope</b> and <b>scopeValue</b>. The one scope +supported is <b>user</b>, where the scopeValue is set to the name of the user. This allows for per user fragment customizations. Beware that if lots of users start customizing +fragments, you might want to store your pages in the database and not the file system. Scope and scopeValue can be combined with any fragment property, including the new set of properties +described below. +</p> +<source><![CDATA[ + <fragment id="dp-22" type="portlet" name="j2-admin::ForgottenPasswordPortlet"> +... + <property name="width" scope="user" scopeValue="dave" value="1121.0"></property> + <property name="height" scope="user" scopeValue="dave" value="120.0"></property> + <property name="state" scope="user" scopeValue="admin" value="detach"></property> + </fragment> +]]></source> +<p> +New properties were added to support drag and drop, resizing, detaching, and docking. Here are some examples: +</p> +<source><![CDATA[ +... + <property name="y" value="300"></property> + <property name="x" value="20"></property> + <property name="state" value="detach"></property> +... + <property name='toolbar' value='true'></property> + <property name="state" scope="user" scopeValue="guest" value="closed"></property> + <property name='class' value='jsRightToolbar'></property> + <fragment id="jsToolbox" type="portlet" name="j2-admin::JetspeedToolbox"> + <property name="row" value="0"></property> + <property name="column" value="0"></property> + <property name="state" value="normal"></property> + <property name="tool" value="true"></property> + </fragment> +... +]]></source> +<table> +<tr> +<th>property</th><th>values</th><th>description</th> +</tr> +<tr><td>state</td><td>normal,detach,closed</td><td>the window state of a fragment, either detached or attached (normal) or closed (for a user or set of users)</td></tr> +<tr><td>toolbar</td><td>true,false</td><td>Is this fragment a toolbar</td></tr> +<tr><td>toolbar</td><td>true,false</td><td>Is this fragment a tool in a toolbar?</td></tr> +<tr><td>x</td><td>numeric screen value</td><td>The x position of a detached portlet</td></tr> +<tr><td>y</td><td>numeric screen value</td><td>The y position of a detached portlet</td></tr> +<tr><td>width</td><td>numeric screen value</td><td>The width of a resized, detached portlet</td></tr> +<tr><td>height</td><td>numeric screen values</td><td>The height of a resized, detached portlet</td></tr> +<tr><td>class</td><td>a CSS class name</td><td>The CSS style to apply to a given fragment</td></tr> +</table> +</subsection> + +<a name="properties"/> +<subsection name="Jetspeed Properties Configurations"> +<p> +To manually configure JetUI properties, edit the WEB-INF/conf/jetspeed.properties (or WEB-INF/conf/override.properties) +</p> +<table> +<tr> +<th>property</th><th>values</th><th>description</th> +</tr> +<tr><td>jetui.customization.method</td><td>ajax,server</td><td>To use JetUI customization engine, set to <b>ajax</b>. To turn on Jetspeed Classic rendering engine, set to <b>server</b></td></tr> +<tr><td>jetui.render.engine</td><td>CSRE,SSRE</td><td>Set the JetUI rendering engine to Client Side Rendering Engine or Server Side Rendering Engine.</td></tr> +<tr><td>jetui.ajax.transport</td><td>json</td><td>Transport for all <a href="http://portals.apache.org/jetspeed-2/devguide/guide-rest-api.html";>REST API</a> calls made by the JetUI customization engine. Currently only JSON supported.</td></tr> +<tr><td>jetui.render.template</td><td>/WEB-INF/jetui/yui/jetui.jsp</td><td>The out of the box JetUI rendering JSP template for rendering merged pages</td></tr> +<tr><td>jetui.drag.mode</td><td>full</td><td>Only supports full, which drag entire window full size, drop on other portlets targets. Future support would drag a small icon.</td></tr> +<tr><td>jetui.style.portlet</td><td>.portal-layout-cell</td><td>CSS style for JetUI portlet windows, also used to identify and find all portlets</td></tr> +<tr><td>jetui.style.layout</td><td>.portal-layout-column</td><td>CSS style for JetUI layout windows, also used to identify and find all layout containers</td></tr> +<tr><td>jetui.style.drag.handle</td><td>.PTitle</td><td>CSS style for JetUI title bars, also used as a handle of portlet windows to drag from</td></tr> +<tr><td>pipeline.default</td><td>jetspeed-pipeline</td><td>set the default pipeline, although it is not necessary if you directly hit the JetUI pipeline by addressing all URLs with /jetspeed/ui instead of /jetspeed/portal</td></tr> +</table> +</subsection> + +<a name="pipeline"/> +<subsection name="JetUI Pipeline Configurations"> +<p> +A key component of the Jetspeed-2 portal engine is its request pipeline. All requests to the portal are ran through a set of Spring configurable pipelines, where each node in the pipeline flow +is called a Valve. Pipelines are configured in the <b>WEB-INF/assembly/pipelines.xml</b> file. See the <a href="../devguide/guide-pipeline.html">Pipelines Guide</a> for more information. +The JetUI rendering engine is configured through its own pipeline in pipelines.xml. Look for the configuration bean named <b>jetui-pipeline</b>. +</p> +<source><![CDATA[ +<bean id="jetui-pipeline" class="org.apache.jetspeed.pipeline.JetspeedPipeline" init-method="initialize"> + <meta key="j2:cat" value="default" /> + <constructor-arg> + <value>JetuiPipeline</value> + </constructor-arg> + <constructor-arg> + <list> + <ref bean="capabilityValve" /> + <ref bean="portalURLValve" /> + <ref bean="securityValve" /> +... + <ref bean="jetuiValve" /> + <ref bean="cleanUpValve" /> + </list> + </constructor-arg> + </bean> + +]]></source> +<p> +You may want the classic pipeline to be completely turned off. Out of the box, it is not. To get /jetspeed/portal to go to the JetUI pipeline, change the pipelines.xml pipeline-map bean to: +</p> +<source><![CDATA[ +<bean id='pipeline-map' class='java.util.LinkedHashMap'> + <meta key="j2:cat" value="default" /> + <constructor-arg> + <map> +... + <entry key='/portal'> + <value>jetui-pipeline</value> + </entry> +]]></source> +</subsection> +</section> + +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-menus-declarative-psml.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-menus-declarative-psml.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-menus-declarative-psml.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-menus-declarative-psml.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,528 @@ +<?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>Guide to Declarative Menus in PSML</title> + <subtitle>Guide to Declarative Menus in PSML</subtitle> + <authors> + <person name="Randy Watler" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Declarative Menus"> +<p> +Declarative menus are used to add new or customize default navigation elements in displayed portal pages. +These PSML declarations are part of the <a href="../devguide/guide-psml.html#Page">page</a> and <a href="../devguide/guide-psml.html#Folder">folder</a> elements. +As with other PSML elements, effective menu declarations available for a given page are those that are explicity +defined in the page along with all defined in parent folders. For this reason, global site menus are defined in +the PSML associated with the site root folder. Menu definitions in a specific page or folder override +menus with the same name found in parent folders. +</p> +<p> +Portal layout decorators access page menu declarations by name while rendering portal content. Menus are +used to create dynamic navigation panes, portal page tabs, bread crumb links, and pull downs. +The Portal Site Component is responsible for fleshing out the dynamic menu definition options with page specific PSML +elements from the site. For instance, a global menu declaration would typically be involved in the following +sequence of events while a portal page is being composed: +<ol> + <li>The portal layout decorator would request a menu definition by name,</li> + <li>the definition would be inherited by the current page and located in the root folder PSML,</li> + <li>the Portal Site Component would interpret the menu definition in the context of the current page and populate <a href="../devguide/guide-psml.html#Page">page</a>, <a href="../devguide/guide-psml.html#Folder">folder</a>, and <a href="../devguide/guide-psml.html#Link">link</a> menu options,</li> + <li>the decorator would display the menu rendering titles and text from the menu definition itself and the computed menu options into portal navigation content.</li> +</ol> +</p> +<p> +There are default global menu declarations supported internally by the Portal Site Component that do not need to +be explicitly defined in any page or folder PSML elements of the site: +<ul> + <li><b>pages</b>: relative pages menu used to define the page tabs above the portal.</li> + <li><b>breadcrumbs</b>: paths to page used to provide history links below the page tabs.</li> + <li><b>navigations</b>: relative subfolders and root level links menu used to define the navigation pane beside the portal.</li> + <li><b>back</b>: parent folder menu used to define the single "back" link above the portal page tabs.</li> +</ul> +As one would expect, these built in menu definitions can be overridden by declaring menus in the site PSML with the same name. +</p> +<p> +The remainder of this guide provides more information on specifying and using declarative menu definitions within Jetspeed2: +<ul> + <li><a href="#Menu_Definition">Menu Definition</a></li> + <ul> + <li><a href="#Menu_Options_Definition">Options</a></li> + <li><a href="#Menu_Separator_Definition">Separator</a></li> + <li><a href="#Menu_Include_Definition">Include</a></li> + <li><a href="#Menu_Exclude_Definition">Exclude</a></li> + </ul> + <li><a href="#Page_Layout_Decorators">Page Layout Decorators</a></li> + <li><a href="#Portal_Site_Component">Portal Site Component</a></li> + <li><a href="../devguide/guide-psml-dtd.html#PSML_DTDs">PSML Document DTDs</a></li> +</ul> +</p> +</section> + +<section name='Menu Definition'> +<p> +The <menu> element defines a menu to be used by the layout decorators or a nested menu within another menu. +There are many valid attributes for the menu element: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>name</td> + <td>Identifies menu name for retrieval from template code and/or menu reference. This attribute is required for top level nodes and ignored for nested menus.</td> + </tr> + <tr> + <td>options</td> + <td>Specifies root document path for this menu if deep inclusion of documents and folders is specified by this menu. This attribute may also define document paths that specify page, folder, or link menu options. Paths specified in this attribute are <a href="#Portal_Site_Component">Page URIs</a>; these URIs may or may not directly reflect the folder and page hierarchy. The <a href="#Portal_Site_Component">Portal Site Component</a> maps these options paths to PSML folder and page elements. Multiple option paths can be specified as a comma separated list of paths and/or regular expression patterns. Relative paths are interpreted as relative to the current page. Special patterns, '~' or '@', can be used to reference the current page. Elements of the current page path can be referenced within options using one of the following special patterns: '@0', '@1'..'@N', or '@$'. The '@0' pattern is replaces with the whole current path, (trimmed of leading and trailing separators). The '@N' pattern is replaced with the Nth, (one based index), path element of the current path. Finally, the '@$' pattern is replaced with the last element, (normally a page name), of the current path. Finally, the special pattern '+' can be used to reference the trimmed path of folder that the menu is defined within, (if the menu is defined on a page or template, the parent folder path is used). This pattern can be used to "pin" a menu to a specific folder.</td> + </tr> + <tr> + <td>depth</td> + <td>Specifies deep inclusion of documents from option folders, (depth < 0 specifies infinite depth). Menu options are created to represent each visible page or link in the site; folders are converted into nested menus constrained by this setting.</td> + </tr> + <tr> + <td>paths</td> + <td>Boolean attribute to enable the "path" expansion of options: specified options are expanded to include paths from the root to the specified options. For example, if options is specified to be "/folder/page.psml", setting this attribute would result in the menu containing options for "/", "/folder", and "/folder/page.psml". This setting is typically used to generate "history" or "bread crumb" menus.</td> + </tr> + <tr> + <td>regexp</td> + <td>A boolean attribute the specifies whether wild card/regular expression processing be performed on options values. File system command line regular expression syntax is supported.</td> + </tr> + <tr> + <td>profile</td> + <td>Specified name of Profile Locator to be used when evaluating option values. This attribute also sets the default profile value for options and nested menus. Specifying '*' forces the acceptance of all Profile Locator names; this can be used to override parent menu selects a profile name.</td> + </tr> + <tr> + <td>order</td> + <td>Comma separated list of regexp patterns matched against list or regular expression document path values to determine order of matched options. This attribute will be applied as a default options value for any options elements, but is not used to reorder multiple options children matches. If not specified, multiple options are included in the order returned by the underlying folder document orderings. Option paths not matched by this attribute are appended after ordered matches.</td> + </tr> + <tr> + <td>skin</td> + <td>Optional decorator defined layout hint for the menu. This attribute is also used as the default skin value for options and nested menus. This hint is not currently used by Jetspeed2 decorators.</td> + </tr> +</table> +<p> +The <menu> element contains a number of other menu definition PSML elements. With the exception of the title and metadata elements, the relative order of these elements determines the order that the layout decorators present them: +</p> +<table> + <tr> + <th>Element</th> + <th>Description</th> + </tr> + <tr> + <td>title?</td> + <td>Simple element text specifies default locale-independent title for the menu. The title of the menu is considered its long description and is used as rollover text in some decorators if the short title is available for the menu text. If not specified, the name of the menu will be used.</td> + </tr> + <tr> + <td>short-title?</td> + <td>Simple element text specifies default locale-independent short title for the menu. The short title, if available, is used as menu text in some decorators. If not specified, the title text is used.</td> + </tr> + <tr> + <td><a href="../devguide/guide-psml.html#PSML_Titles_and_Metadata">metadata</a>*</td> + <td>Optionally specifies additional locale-specific titles and short titles.</td> + </tr> + <tr> + <td><a href="#Menu_Options_Definition">options</a>*</td> + <td>This ordered menu element specifies content elements for this menu definition.</td> + </tr> + <tr> + <td><a href="#Menu_Separator_Definition">separator</a>*</td> + <td>An ordered menu element used to specify text lines to be included inline in this menu definition.</td> + </tr> + <tr> + <td>menu*</td> + <td>Another ordered menu element used to define a nested menu contained in this menu definition.</td> + </tr> + <tr> + <td><a href="#Menu_Include_Definition">include</a>*</td> + <td>Specifies a menu to nest within or options from a another menu to be included in this menu definition. The name of the menu to include is the text of this ordered menu element.</td> + </tr> + <tr> + <td><a href="#Menu_Exclude_Definition">exclude</a>*</td> + <td>Specifies options and nested menus from another menu to be excluded from this menu definition. The name of the menu with elements to exclude is the text of this ordered menu element.</td> + </tr> +</table> +<p>Examples:</p> +<source><![CDATA[ +<!-- simple menu composed of 2 pages --> +<menu name="simple"> + <options>/some-top-page.psml,/custom/some-other-page.psml</options> +</menu> +]]></source> +<source><![CDATA[ +<!-- site menu for the top 2 levels: folders result in nested menus --> +<menu name="top-2-levels" options="/" depth="2" skin="dhtml-pull-down"/> +]]></source> +<source><![CDATA[ +<!-- menu containing top level elements profiled by roles --> +<menu name="top-role-pages" regexp="true" options="/*" profile="roles"/> +]]></source> +<source><![CDATA[ +<!-- contrived example demonstrating element syntax --> +<menu name="top-custom"> + <title>Top Menu</title> + <metadata name="title" xml:lang="fr">Haut</metadata> + <options regexp="true" profile="groups">/group-pages/*</options> + <menu options="/" profile="page"> + <separator> + <text>-- Top Pages --</text> + <title>Top Pages</title> + </separator> + <options regexp="true">/*</options> + <separator> + <title>Custom Pages</title> + </separator> + <options depth="2">/custom-folder/</options> + </menu> + <exclude>top-role-pages</exclude> + <separator>More Top Pages</separator> + <include nest="true">top-role-pages</include> +</menu> +]]></source> +<p>The definitions for the default global menu declarations supported internally by the Portal Site Component:</p> +<source><![CDATA[ +<!-- standard pages tabs menu --> +<menu name="pages" regexp="true" options="*.psml"/> +]]></source> +<source><![CDATA[ +<!-- standard history breadcrumbs menu --> +<menu name="breadcrumbs" options="~" paths="true"/> +]]></source> +<source><![CDATA[ +<!-- standard navigations panel menu --> +<menu name="navigations"> + <separator>Folders</separator> + <options regexp="true">./*/</options> + <include>page-navigations</include> + <separator>Additional Links</separator> + <options regexp="true">/*.link</options> +</menu> +]]></source> +<source><![CDATA[ +<!-- standard parent folder link menu --> +<menu name="back" options="../"/> +]]></source> +<p>Note that the separator text of these definitions is localized internally.</p> +</section> + +<section name='Menu Options Definition'> +<p> +The <options> element defines a single or multiple options within a <a href="#Menu_Definition">menu</a>. The text of this simple element specifies document paths that yield page, folder, or link menu options. Paths specified in this element are <a href="#Portal_Site_Component">Page URIs</a>; these URIs may or may not directly reflect the folder and page hierarchy. The <a href="#Portal_Site_Component">Portal Site Component</a> maps these options paths to PSML folder and page elements. Multiple option paths can be specified as a comma separated list of paths and/or regular expression patterns. Relative paths are interpreted as relative to the current page. Special patterns, '~' or '@', can be used to reference the current page. Elements of the current page path can be referenced within options using one of the following special patterns: '@0', '@1'..'@N', or '@$'. The '@0' pattern is replaces with the whole current path, (trimmed of leading and trailing separators). The '@N' pa ttern is replaced with the Nth, (one based index), path element of the current path. Finally, the '@$' pattern is replaced with the last element, (normally a page), of the current path. This element shares many attributes in common with the menu element: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>depth</td> + <td>Specifies deep inclusion of documents from option folders, (depth < 0 specifies infinite depth). Menu options are created to represent each visible page or link in the site; folders are converted into nested menus constrained by this setting.</td> + </tr> + <tr> + <td>paths</td> + <td>Boolean attribute to enable the "path" expansion of options: specified options are expanded to include paths from the root to the specified options. For example, if options is specified to be "/folder/page.psml", setting this attribute would result in the menu containing options for "/", "/folder", and "/folder/page.psml". This setting is typically used to generate "history" or "bread crumb" menus.</td> + </tr> + <tr> + <td>regexp</td> + <td>A boolean attribute the specifies whether wild card/regular expression processing be performed on options values. File system command line regular expression syntax is supported.</td> + </tr> + <tr> + <td>profile</td> + <td>Specified name of Profile Locator to be used when evaluating option values. This attribute also sets the default profile value for options and nested menus. Specifying '*' forces the acceptance of all Profile Locator names; this can be used to override parent menu selects a profile name.</td> + </tr> + <tr> + <td>order</td> + <td>Comma separated list of regexp patterns matched against list or regular expression document path values to determine order of matched options. This attribute will be applied as a default options value for any options elements, but is not used to reorder multiple options children matches. If not specified, multiple options are included in the order returned by the underlying folder document orderings. Option paths not matched by this attribute are appended after ordered matches.</td> + </tr> + <tr> + <td>skin</td> + <td>Optional decorator defined layout hint for the menu options. Skin attribute values from each page, folder, or link will be used to populate menu options if this hint is not specified here. Otherwise, the skin hint from the containing menu will be used. This hint is not currently used by Jetspeed2 decorators.</td> + </tr> +</table> +<p>Example:</p> +<source><![CDATA[ +<menu> + ... + <options regexp="true" order="*.psml,*.link">/some-top-page.psml,/custom/some-other-page.psml,/*.link</options> + ... +</menu> +]]></source> +</section> + +<section name='Menu Separator Definition'> +<p> +The <separator> element defines a separator to be included in a <a href="#Menu_Definition">menu</a>. The separator will be included only if <a href="#Menu_Options_Definition">options</a> or nested menus appear below this element within a menu definition. The text of the separator can be specified in the contained text of this element or in the text menu definition element. +There is only one attribute accepted by the separator element: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>skin</td> + <td>Optional decorator defined layout hint for the menu separator. This hint is not currently used by Jetspeed2 decorators.</td> + </tr> +</table> +<p> +The <separator> element contains a number of other menu definition PSML elements: +</p> +<table> + <tr> + <th>Element</th> + <th>Description</th> + </tr> + <tr> + <td>title?</td> + <td>Simple element text specifies default locale-independent title for the separator. The title of the separator is considered its long description and is used as rollover text in some decorators if the separator text is available.</td> + </tr> + <tr> + <td>text?</td> + <td>Simple element text specifies default locale-independent text for the separator. The required separator text, whether specified by this attribute or as the contained text of the separator element, is the text to be inserted in the menu by the layout decorator.</td> + </tr> + <tr> + <td><a href="../devguide/guide-psml.html#PSML_Titles_and_Metadata">metadata</a>*</td> + <td>Optionally specifies additional locale-specific titles and separator text.</td> + </tr> +</table> +<p>Examples:</p> +<source><![CDATA[ +<menu> + ... + <separator>-------------</separator> + ... + <separator> + <text>-- Top 10 Pages --</text> + <metadata name="text" xml:lang="fr">Haut Pages</metadata> + <title>Top 10 pages as voted by the Jetspeed2 users!</title> + </separator> + ... +</menu> +]]></source> +</section> + +<section name='Menu Include Definition'> +<p> +The <include> element includes <a href="#Menu_Options_Definition">options</a> or nested <a href="#Menu_Definition">menus</a> from another menu. The name of the menu to include is specified as the text value of this element. +There is only one valid attribute for the include element: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>nest</td> + <td>Boolean flag that controls whether the specified menu is to be nested. If this attribute is set to 'true', the included menu will be nested as a submenu; otherewise, all options and nested menus from the specified menu will be inserted inline into this menu.</td> + </tr> +</table> +<p>Examples:</p> +<source><![CDATA[ +<menu> + ... + <include nest="true">navigations</include> + ... +</menu> +]]></source> +</section> + +<section name='Menu Exclude Definition'> +<p> +The <exclude> element excludes <a href="#Menu_Options_Definition">options</a> or nested <a href="#Menu_Definition">menus</a> from another menu. This option is used primarily to remove menu options that already appear on the portal page in another menu from this menu. Matching options or menus will be excluded only if they appear above this element within a menu definition. The name of the menu to include is specified as the text value of this simple element. +</p> +<p>Examples:</p> +<source><![CDATA[ +<menu> + ... + <exclude>pages</exclude> + ... +</menu> +]]></source> +</section> + +<section name='Page Layout Decorators'> +<p> +The page layout decorators request menus from the Portal Site Component when the page is being rendered in the Jetspeed2 pipeline. +The decorators expect certain menus to be provided by the PSML declarations. Before custom menus can be displayed in the portal, +the decorators need to be modified to render the custom menu. Here is an example taken from a Velocity layout decorator header.vm file: +</p> +<source><![CDATA[ +... +#set($pagesStandardMenu = $site.getMenu("pages")) +#if(!$pagesStandardMenu.empty) + <div class="tabs"> +#includeTabsNavigation($pagesStandardMenu $LEFT_TO_RIGHT) + </div> +#end +... +]]></source> +<p> +This code block renders the standard pages tabs menu within a portal page. The Portal Site Component is exposed as the <i>$site</i> +Velocity context variable. The test for an empty menu definition is designed to ensure that empty menus are not rendered into the page +content. Finally, a decorator macro is executed to expand the menu content. This approach is taken in general to support the rendering +of nested menus with recursive invocations of the macro. In this case, the decorator is expecting only page options. Here is the +macro implementation used to render the pages tabs menu: +</p> +<source><![CDATA[ +#macro (includeTabsNavigation $_menu $_orientation) + <table border="0" cellpadding="0" cellspacing="0"> + <tr> + #foreach($element in $_menu.elements.iterator()) + #if($element.elementType == "option") + #set($tabTitle = $element.getTitle($preferedLocale)) + #set($tabName = $element.getShortTitle($preferedLocale)) + #if($_orientation == $LEFT_TO_RIGHT) + #if($element.isSelected($site)) + <td class="LTabLeft" nowrap="true"> </td> + <td class="LTab" align="center" valign="middle" nowrap="true" title="$!tabTitle">${tabName}</td> + <td class="LTabRight" nowrap="true"> </td> + #else + #set($tabUrl = $jetspeed.getAbsoluteUrl($element.url)) + <td class="LTabLeftLow" nowrap="true"> </td> + <td class="LTabLow" align="center" valign="middle" nowrap="true" title="$!tabTitle"><a href="$tabUrl">${tabName}</a></td> + <td class="LTabRightLow" nowrap="true"> </td> + #end + #end + #end + #end + </tr> + </table> +#end +]]></source> +<p> +This macro iterates over the computed page menu options supplied by the Portal Site Component, rendering a series of table +data HTML elements that make up each displayed tab. The whole menu is rendered as a HTML table with a single row. +</p> +<p> +The declarative menu Portal Site Component objects exposed to the layout decorators are documented in the +<a href="../apidocs/index.html">Jetspeed API</a>. Here is a list of the primary interfaces +that make up this interface: +<ul> + <li><a href="../apidocs/org/apache/jetspeed/portalsite/Menu.html">org.apache.jetspeed.portalsite.Menu</a></li> + <li><a href="../apidocs/org/apache/jetspeed/portalsite/MenuElement.html">org.apache.jetspeed.portalsite.MenuElement</a></li> + <li><a href="../apidocs/org/apache/jetspeed/portalsite/MenuOption.html">org.apache.jetspeed.portalsite.MenuOption</a></li> + <li><a href="../apidocs/org/apache/jetspeed/portalsite/MenuSeparator.html">org.apache.jetspeed.portalsite.MenuSeparator</a></li> + <li><a href="../apidocs/org/apache/jetspeed/portalsite/PortalSiteRequestContext.html">org.apache.jetspeed.portalsite.PortalSiteRequestContext</a></li> +</ul> +Please refer to the <a href="../apidocs/index.html">javadocs</a> for these interfaces and +sample Velocity decorators for more information. +</p> +<p> +Jetspeed2 provides many sample decorators including those that will render tabs, navigation panes with nested submenus, +history breadcrumb links, and even DHTML JSCookMenu nested pulldown menus... all from the declarative menu elements +documented here. +</p> +</section> + +<section name='Portal Site Component'> +<p> +In conjunction with the <a href="../devguide/guide-profiler.html">Jetspeed Profiler Component</a>, the Portal Site Component +performs two closely related functions: +<ol> + <li>Map portal request URLs from a user to PSML <a href="../devguide/guide-psml.html#Page">page</a> or <a href="../devguide/guide-psml.html#Folder">folder</a> elements in the site, and</li> + <li>construct site navigational menus and their options that reflect what is available to the user from the site.</li> +</ol> + At first glance, these functions seem relatively simple: searching within and traversing the <a href="../devguide/guide-psml.html">PSML site definition</a>. +However, once the complexities of Profiler composition and <a href="guide-security-declarative-psml.html">Security Constraints</a> +filtering are taken into account, the mapping is often not trivial. +</p> +<p> +Menu definition options paths are specified as Page URIs to leverage this mapping functionality. A Page URI is essentially +the tail portion of a portal request URL that is used to address a page or folder. Using Page URIs for options allows menu +definitions to be shared by all users of the portal: the user specific profile and effective security constraints are applied +to generate the menu options. This implies that the physical paths used internally within the Page Manager file system +or database cannot be specified to directly address a specific PSML element. +</p> +<p> +For example, suppose the following: +<ul> + <li>the default "j2" profiling rules are in effect for the 'someone' user,</li> + <li>the following physical PSML site structure is available in the Page Manager,</li> + <ul> + <li>.../page0.psml</li> + <li>.../page1.psml</li> + <li>.../page2.psml</li> + <li>.../hidden-page0.psml</li> + <li>.../_user/someone/page0.psml</li> + </ul> + <li>security constraints denied access to '/page2.psml' for the user, and</li> + <li>'/hidden-page.psml' is declared hidden in the page PSML.</li> +</ul> +The current <a href="../devguide/guide-profiler.html">Profile Locator</a> for the user would specify that the Portal Site Component map the +following portal request URLs to the specific PSML elements: +<table> + <tr> + <th>Portal Request URL</th> + <th>PSML Element Selected</th> + </tr> + <tr> + <td>http://.../jetspeed/portal/page0.psml</td> + <td>.../_user/someone/page0.psml</td> + </tr> + <tr> + <td>http://.../jetspeed/portal/page1.psml</td> + <td>.../page0.psml</td> + </tr> + <tr> + <td>http://.../jetspeed/portal/page2.psml</td> + <td><b>Fails security test.</b></td> + </tr> + <tr> + <td>http://.../jetspeed/portal/hidden-page.psml</td> + <td>.../hidden-page.psml</td> + </tr> +</table> +The same Profile Locator is used to evaluate menu options. Here are several valid menu options paths and how they are resolved: +<table> + <tr> + <th>Menu Options Page URIs</th> + <th>PSML Elements Included in Menu</th> + </tr> + <tr> + <td>/page0.psml</td> + <td>.../_user/someone/page0.psml</td> + </tr> + <tr> + <td>/page0.psml,/page1.psml</td> + <td>.../_user/someone/page0.psml,.../page1.psml</td> + </tr> + <tr> + <td>/*.psml</td> + <td>.../_user/someone/page0.psml,.../page1.psml</td> + </tr> + <tr> + <td>/*</td> + <td>.../_user/someone/page0.psml,.../page1.psml</td> + </tr> + <tr> + <td>/_user/someone/page0.psml</td> + <td><b>Not a valid Page URI.</b></td> + </tr> +</table> +Notes: +<ul> + <li>Menu options attempting to use invalid Page URIs are ignored. Invalid URIs include those containing reserved folders such as '_user', '_role', etc. or other physical paths specific to the the Page Manager implementation.</li> + <li>Security constrained pages or folders cannot be referenced by requests and will not appear in menus.</li> + <li>Hidden pages, (or hidden and reserved folders), can be requested, but are not visible in menus. There is one exception for pages: a hidden page is considered visible if it is the request page.</li> +</ul> +</p> +</section> + +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-ntlm.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-ntlm.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-ntlm.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-ntlm.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,107 @@ +<?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>Guide to using NTLM Authentication</title> + <subtitle>How to configure NTLM authentication with an optional fallback authentication method.</subtitle> + <authors> + <person name="Dennis Dam" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="NTLM Authentication in Jetspeed"> + <p> + NTLM Authentication can be used for Single Sign On (SSO) from a Windows client/browser. A nice explanation about NTLM can be found <a href="http://jcifs.samba.org/src/docs/ntlmhttpauth.html";>here</a>. + Jetspeed-2 supports NTLM Authentication based on the <a href="http://jcifs.samba.org";>jCIFS</a> Servlet filter. With the approach described below + you can use NTLM Authentication with an optional fallback to the default active authentication and as such this solution can be used as a drop-in replacement. + A typical application for a fallback login method would be when users log on to an intranet from a different domain: these users can + be redirected to a login screen.<br/> + The solution below can also be used as a replacement for the default Security Valve: + if you don't configure the filters, then Jetspeed's default authorization will be applied. + </p> + </section> + <section name="Configuring NTLM Authentication"> + <p> + Jetspeed-2 security configuration is explained + <a href="../devguide/guide-security.html"> + here + </a> + . + </p> + <subsection name="Configuring NTLM servlet filters"> + <p> + The first step is to configure jCIFS NTLM HTTP Authentication, which is explained <a href="http://jcifs.samba.org/";>here</a>. + You configure jCIFS as a filter in the web.xml of your webapp. Next, you must configure + a second Jetspeed servlet filter, which must be placed right <i>after</i> the jCIFS filter. An example configuration: + </p> + <source><![CDATA[ +<filter> + <filter-name>NtlmHttpFilter</filter-name> + <filter-class>jcifs.http.NtlmHttpFilter</filter-class> + <init-param> + <param-name>jcifs.smb.client.domain</param-name> + <param-value>SOME_DOMAIN</param-value> + </init-param> +</filter> + +<filter> + <filter-name>NtlmHttpServletRequestFilter</filter-name> + <filter-class>org.apache.jetspeed.security.impl.ntlm.NtlmHttpServletRequestFilter</filter-class> + <init-param> + <param-name>org.apache.jetspeed.security.ntlm.ignoreUrls</param-name> + <param-value>/login/login</param-value> + </init-param> +</filter> + +<filter-mapping> + <filter-name>NtlmHttpFilter</filter-name> + <url-pattern>/*</url-pattern> +</filter-mapping> + +<filter-mapping> + <filter-name>NtlmHttpServletRequestFilter</filter-name> + <url-pattern>/*</url-pattern> +</filter-mapping>]]></source> + </subsection> + <subsection name="Configuring NTLM Security Valve"> + <p> + The above filters set the correct credentials on the request. To use these credentials, you + have to configure the <code>org.apache.jetspeed.security.impl.ntlm.NtlmSecurityValve</code> in the + Jetspeed pipelines you want to secure. This Valve can be used as a <i>replacement</i> for the default <code>SecurityValveImpl</code>. For explanation about how to set up pipelines, see + <a href="guide-pipelines.html">here</a>. An example of how to configure the NtlmSecurityValve bean: + </p> + <source> + <![CDATA[ +<bean id="securityValve" class="org.apache.jetspeed.security.impl.ntlm.NtlmSecurityValve" init-method="initialize"> + <constructor-arg> + <ref bean="org.apache.jetspeed.security.UserManager" /> + </constructor-arg> + <!-- Network domain. This value is optionally stripped from the authenticated user name --> + <constructor-arg><value>SOME_DOMAIN</value></constructor-arg> + <!-- Omit domain in user principal --> + <constructor-arg><value>true</value></constructor-arg> + <!-- + NTLM Authorization required. + If set to true, only users authenticated by NTLM authentication will be authorized. + --> + <constructor-arg><value>false</value></constructor-arg> +</bean>]]></source> + </subsection> + </section> + </body> +</document> \ No newline at end of file
