Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-page-templates.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-page-templates.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-page-templates.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-page-templates.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,382 @@ +<?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 Page Templates</title> + <subtitle>A guide to using Page Templates in Jetspeed</subtitle> + <authors> + <person name="David Taylor" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Introduction to PSML Templates"> +<p> +In the 2.2.1 release of Jetspeed, we introduced three new kinds of PSML templates: +<ul> + <li>1. <a href="#TPSML">Template Pages (TPSML)</a></li> + <li>2. <a href="#FPSML">Fragment Definitions (FPSML)</a></li> + <li>3. <a href="#DPSML">Dynamic Template Pages (DPSML)</a></li> +</ul> +</p> +<p> +Templates are a special kind of re-usable <a href="../devguide/guide-psml.html">PSML</a> page. Templates centralize the declaration of portlets and page layout once, which can then be reused on many pages. Templates can save you +lots of configuration time maintaining portlets on your pages. And administrator can add or remove a portlet to a template, and all pages associated with that template will pick up those portlets immediately. +When you have many pages, templates can save you lots of administration time in publishing changes to each and every page in the system. Templates can also be secured, so that only administrators can modify them. This means +that you can enforce sets of pages to always display certain portlets, for example in the left or right column. By securing the template, the templasized portlets are locked in place: they cannot be deleted or moved by the end user, only the administrator +can edit the portlets in the template. However, the portlets declared on the merged page can be maintained normally by the end user, based on the security constraints of the target page. +</p> +<p>As of version 2.3.0, you cannot edit templates (TPSML, FPSML, DPSML) using the Jetspeed configuration tools. This means they must be edited as XML and then imported into the system. Future versions will support full customization of templates.</p> +<a name="TPSML"/> +<subsection name="TPSML - Template Pages"> +<p> +Template pages are used in combination with addressable PSML pages to create a merged view of a PSML page with the template. Template Pages are not addressable by URL: +therefore you can never visit a template page. Templates are usually defined in enclosing folders, and are automatically merged with all pages in that folder and subfolders. +There is a limitation that only one page template can be defined per folder. Templates placed in subfolders will override the template placed in a parent folder. Introducing a template page into the PSML system is as simple +as dropping the .tpsml file into the file system (or you can use the <a href="../adminguide/import.html">Import</a> administrative tool if you are storing PSML in the database). +</p> +<p> +Templates were first introduced in version 2.2.1. If you download and run the <a href="http://portals.apache.org/jetspeed-2/download.html";>Jetspeed demo</a>, navigate to <a href='http://localhost:8080/jetspeed/portal'>http://localhost:8080/jetspeed/portal</a>, +you will see an example of templates in action on the welcome page as shown in the screen shot below... +</p> +<img src="images/welcome-page.png" border="0"/> +<p> + The two portlets found in the far left and far right column are the Jetspeed Toolbox and Page Navigator portlets. These portlets are declared in a template, not in the actual pages (.psml). + On the Page Navigator, press the <b>Websites</b> link, navigating to <a href='http://localhost:8080/jetspeed/portal/frames.psml'>http://localhost:8080/jetspeed/portal/frames.psml</a>. + You will again see the Jetspeed Toolbox and and Page Navigator portlets. These two portlets were declared only once, in a Page Template, not on each page. +</p> +<p> +As the visual below demonstrates, page templates merge a template with an addressable page, resulting in the displaying of a merged page: +</p> +<img src="images/PageTemplateMerged.png" border="0" /> +<p> +</p> +<b>How to Create a Page Template</b> +<p> +In this section, you will learn how to create your own template pages (TPSML) in Jetspeed. +Note that all the examples included here were testing on the Classic (Portal) Pipeline (/jetspeed/portal) with the 2.3.0 release of Jetspeed. Templates are designed to work with both the JetUI Pipeline as well as the Classic Pipeline. +However, the JetUI pipeline has some special requirements, most notably is that it treats the Page Navigator and Toolbox as special portlets, and expects them to always be on all templates. +The Classic Pipeline does not have any restrictions as of version 2.3.0. +Another important issue to be aware of - up through version 2.3.0, templates may only be defined in XML definitions. +There are no customization features for creating these templates with the Jetspeed customizer. Future releases will provide template customizers. To learn more about using templates with the JetUI Pipeline, +read the <a href="guide-jetui.html">JetUI documentation</a>. The remainder of this document assumes you are using the Classic (/portal) pipeline. To learn more about using pipelines, read the <a href="guide-pipelines.html">Pipelines documentation</a> +</p> +<p> +Lets get started creating a new page template. You will need to have Jetspeed running in order to facilitate demonstrating how templates work. +First, start up Jetspeed, navigate to <a href='http://localhost:8080/jetspeed/portal'>http://localhost:8080/jetspeed/portal</a>, and login to the demo system with the <i>admin</i> user, password also <i>admin</i>. Navigate to any other page with the Page Navigator. + You will always see the Page Navigator portlet in the left column, and the Jetspeed Toolbox in the right column. The end user cannot remove +these portlets with the Jetspeed Customizer, not even the admin user. No matter which page you navigate to, you will see the default system template that comes with the demo. +This template file is <b>template.tpsml</b>, and it is located in the <i>pages</i> directory of the demo +distribution. (If you built Jetspeed from source, it will be located in WEB-INF/pages). +Lets override the page template for the Admin user home space. Remember that spaces are accessible from the drop down menu in the Jetspeed header. From the Spaces menu, select <b>My Pages</b>. Selecting My Pages will display a page located at the +URL <a href='http://localhost:8080/jetspeed/portal/_user/admin'>http://localhost:8080/jetspeed/portal/_user/admin</a> +On the file system, the home space for the admin user is actually located under <b>pages/_user/admin</b>. Go ahead and find that directory on your file system before proceeding. +</p> +<p> +Now bring up a text editor, and create an empty file named <b>template.tpsml</b>. Place that file in the <b>pages/_user/admin</b> folder. Jetspeed will now automatically use your new template for all pages in that folder (and any subfolder of the pages/_user/admin space folder). +When creating a Page Template, you will want to reference the Jetspeed 2.2 XML Schemas. You can find the XML Schema declaration here: <a href="http://portals.apache.org/jetspeed-2/2.2/schemas/tpsml.xsd";>http://portals.apache.org/jetspeed-2/2.2/schemas/tpsml.xsd";</a> +All of your page template TPSML pages should start as follows... +</p> + <source><![CDATA[ +<page-template id="definition" + xmlns="http://portals.apache.org/jetspeed"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://portals.apache.org/jetspeed http://portals.apache.org/jetspeed-2/2.2/schemas/tpsml.xsd";> +]]></source> +<p> +The root tag must always be declared as <b><page-template></b>. Page templates are an extension of plain PSML pages. Page templates can have many of the same XML elements as a page such as titles and fragments. +Recommend becoming familiar with <a href="../devguide/guide-psml.html">standard PSML pages</a> before continuing. +However, there are some important differences: +<ul> +<li>The fragments that you define in your page template will be merged with all pages in the same folder, and sub-folders, unless a sub-folder overrides it with its own template</li> +<li>You must declare one and only one <b><page-fragment></b> tag. This is the place holder for the referenced page which will be merged with the template </li> +</ul> +</p> +<p> +The <b><page-fragment></b> tag is important. It declares where the current page will be inserted and merge into your template. +</p> +<source><![CDATA[ +.. + <page-fragment id="template-admin-home"> + <property name="row" value="0"/> + </page-fragment> +... +]]></source> +<p> +Notice that a page-fragment can have typical fragment attributes like <i>id</i> as well as sub-elements like <i>row</i> and <i>column</i>. The page-fragment +tag is the place holder for the addressable page. The addressable page is merged in at this point, specified by the optional <i>row</i> and <i>column</i> properties, combining the template fragments with the fragments from the addressable page. +Here is a complete template page definition for the admin home space. Go ahead and cut and paste this example into your text editor and save the file under <b>pages/_user/admin/template.tpsml</b>: +</p> + <source><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<page-template id="admin-definition" + xmlns="http://portals.apache.org/jetspeed"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://portals.apache.org/jetspeed http://portals.apache.org/jetspeed-2/2.2/schemas/tpsml.xsd";> + + <title>Example Template</title> + <fragment id="example-template-top" type="layout" name="jetspeed-layouts::VelocityThreeColumns"> + <property name="sizes" value="15%,70%,15%"></property> + + <fragment id="example-left" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + <property name="row" value="0"></property> + <property name="column" value="0"></property> + <fragment id="example-locale" type="portlet" name="j2-admin::LocaleSelector"> + <property name="row" value="0" /> + <property name="column" value="0" /> + </fragment> + </fragment> + + <page-fragment id="example-page-template"> + <property name="column" value="1"/> + <property name="row" value="0"/> + </page-fragment> + + <fragment id="example-right" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + <property name="row" value="0"></property> + <property name="column" value="2"></property> + <fragment id="example-forgotten" type="portlet" name="j2-admin::ForgottenPasswordPortlet"> + <property name="row" value="0" /> + <property name="column" value="0" /> + </fragment> + </fragment> + + </fragment> +</page-template> +]]></source> +<p> +Refresh the page <a href='http://localhost:8080/jetspeed/portal/_user/admin'>http://localhost:8080/jetspeed/portal/_user/admin</a>. You should now see some differences: like the Navigator and Toolbox are gone, and in their place are the portlets +that you defined above, namely the Local Selector and Forgotten Password Portlet. Take a closer look at the XML file. +Notice that we are using Jetspeed layout portlets to define the layout of the templacized page. In this example, we have a three column layout. The left column is defined by the <i>example-left</i> fragment. The middle column is key: + this is our page-template and it will hold the actual PSML page. The right column is defined by the <i>example-right</i> fragment. When the template is merged with the page that you navigate to, the end result will contain a left and right column + from the template, and a middle column containing the referenced page. This referenced page can have its own layout. For example if the referenced page has two columns, then the resulting merged page will have four columns, two from the template, and + two from the included page. +</p> +<p>There is a problem though. First problem, you are stuck on this page, there are no longer any navigations available to you. Lets fix that by adding a Space Navigator to your template. Paste this code fragment into your file just above the +fragment with an id of <i>example-left</i> and save the file:</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> +Refresh the page. You should now see a Space Navigator in the top area of your page. An interesting aspect of this fragment is that it is detached and placed at a specific coordinate on the page. Detached portlets are placed in a different +plane than flow-driven layout portlets, whose positions are relative to their placement in the PSML definition. To read more about detached portlets see the <a href="guide-jetui.html">JetUI documentation</a>. +</p> +<p>There is another problem. We cannot navigate within the My Pages folder. In order to do that we need a Page Navigator. Lets add one to the template, so that all the pages in this folder can use it. Paste in the code snipped below immediately +after the fragment end tag of the fragment with an id of <b>example-locale</b>: +</p> +<source><![CDATA[ + <fragment id="jsPageNavigator" type="portlet" name="j2-admin::PageNavigator"> + <property name="row" value="1"></property> + <property name="column" value="0"></property> + <property name="state" value="normal"></property> + <property name="tool" value="true"></property> + </fragment> +]]></source> +<p> +Refresh the page. You should now see a page navigator portlet immediately below the Locale Selector portlet on the left hand side of the page. As you navigate to other pages in this folder, such as the <i>My Account</i> page, you should +always still see our four portlets from the template (Locale Selector, Page Navigator, Forgotten Password, and the Space Navigator). +</p> +<p> +We hope these examples helped getting you started using page templates in Jetpeed. If you have further questions, do not be shy about asking questions on the Jetspeed Users List. +</p> +</subsection> +<a name="FPSML"/> +<subsection name="FPSML - Fragment Definitions"> +<p> +Fragment Definition Pages are buckets for declaring reusable portlet definitions which can then be referenced and placed in normal PSML files. + Whereas TPSML pages also follow a reuse pattern, FPSML is similar but solves a slightly different case. +TPSML is reuse by template. You will always get the entire layout of the template. Your page is included inside the template. The FPSML use case is different. With FPSML, your page will is the container where fragment definitions are included into the your page. +</p> +<p> +As the visual below demonstrates, fragment definitions are included into any page (or page template) resulting in a merged page of both normal portlet fragments as well as fragment references to fragment definitions: +</p> +<img src="images/FragmentDefs.png" border="0" /> +<p> +In the diagram above, four fragment definitions have been defined. Three of these definitions (Fragment Def A, Fragment Def B, Fragment Def C) are portlet fragments. +The fourth is a layout fragment (Fragment Layout D), which contains two portlet fragments (Fragment Def D-1, Fragment Def D-2). +</p> +<p> +On Page X, four portlets are defined directly on that page (1,2,14,23). There are also two fragment references (A,B). The fragments are not directly defined on Page X, they are only referenced. +</p> +<p> +On Page Y, four portlets are defined directly on that page (1,6,7,22). There are also two fragment references (B,C). The fragments are not directly defined on Page Y, they are only referenced. +Additionally, Page Y has a fragment layout reference (D). Inside this fragment layout reference, there are two fragment portlet references (D-1, D-2). +</p> +<p> +At this point, you may be asking: what benefit is it to declare a fragment definition outside of the page definition? +<b>Benefits of Using Fragment Definitions</b> +<ul> +<li>Centralized definitions of portlets or groups of portlets</li> +<li>Only define the page preferences once</li> +<li>Lock down sections of pages so the user cannot customize them</li> +<li>Combine with portlet templates </li> +</ul> +</p> +<b>How to Create a Fragment Definition</b> +<p> +In this section, you will learn how to create your own fragment definition pages (FPSML) in Jetspeed, and then use those fragment definitions in a PSML page using fragment references. +Note that all the examples included here were testing on the Classic (Portal) Pipeline (/jetspeed/portal) with the 2.2.2 release of Jetspeed. Fragment definitions are designed to work with both the JetUI Pipeline as well as the Classic Pipeline. +An important issue to be aware of - up through version 2.2.2, fragment definitions and fragment references may only be defined in XML definitions. +There are no customization features for creating these fragment definitions with the Jetspeed customizer. Future releases will provide fragment definition editors. +</p> +<p> +Lets get started creating a new fragment definition. You will need to have Jetspeed running in order to facilitate demonstrating how fragment definitions work. +First, start up Jetspeed, navigate to <a href='http://localhost:8080/jetspeed/portal'>http://localhost:8080/jetspeed/portal</a>, and login to the demo system with the <i>admin</i> user, password also <i>admin</i>. +</p> +<p> +One important rule to follow: there may only be one fragment definition per FPSML file. If you would like to create another fragment definition, then create another file and store it there. +Lets create a new fragment reference file. Bring up a text editor, and create an empty file named <b>example.fpsml</b>. Place that file in the <b>pages/</b> folder. + When creating a fragment definition, you will want to reference the Jetspeed 2.2 XML Schemas. You can find the XML Schema declaration here: <a href="http://portals.apache.org/jetspeed-2/2.2/schemas/fpsml.xsd";>http://portals.apache.org/jetspeed-2/2.2/schemas/fpsml.xsd";</a> +All of your fragment definition FPSML pages should start as follows... +</p> + <source><![CDATA[ + <fragment-definition id="definition" + xmlns="http://portals.apache.org/jetspeed"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://portals.apache.org/jetspeed http://portals.apache.org/jetspeed-2/2.2/schemas/fpsml.xsd";> +]]></source> +<p> +The root tag must always be declared as <b><fragment-definition></b>. Fragment definitions can have a few of the same XML elements as a page fragments. The main element they have in common is the fragment tag. +If you have not already, we recommend becoming familiar with <a href="../devguide/guide-psml.html">standard PSML pages</a> before continuing. +However, there are some important differences: +<ul> +<li>The fragments that you define in your fragment definition are never displayed directly on a page. They must be referenced and then merged in on a real page by fragment id (see below)</li> +<li>You must declare one and only one root <b><fragment></b> tag per fragment definition.</li> +</ul> +</p> +<p> +The second limitation is not really so different than a PSML page, which are also limited to only root fragment per page as well. But on a PSML page, this fragment must be a layout fragment. +With fragment definitions, this fragment may be a single portlet fragment. +</p> +<source><![CDATA[ +.. + <fragment id="hometown-weather-def" type="portlet" name="demo::WeatherPortlet"> + <preference name="city"> + <value>Miami, Florida</value> + </preference> + </fragment> +... +]]></source> +<p> +Notice that a fragment definition can have typical fragment attributes like <i>id</i> as well as sub-elements like <i>preference</i>. Declaring preferences here is one of the more important techniques for using fragment references. +By declaring the preference on this page, you can reuse variations of portlets based on their preferences, and lock down these preferences on a many pages. +Here is a complete fragment definition for our example. Go ahead and cut and paste this example into your text editor and save the file under <b>pages/example.fpsml</b> +</p> +<source><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<fragment-definition id="definition" + xmlns="http://portals.apache.org/jetspeed"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://portals.apache.org/jetspeed http://portals.apache.org/jetspeed-2/2.2/schemas/fpsml.xsd";> + + <title>Weather</title> + <fragment id="hometown-weather-def" type="portlet" name="demo::WeatherPortlet"> + <preference name='weather_state'> + <value>FL</value> + </preference> + <preference name='weather_city'> + <value>Miami</value> + </preference> + + </fragment> + +</fragment-definition> +]]></source> +<p> +Jetspeed will now automatically know about your fragment definition. The next step is to reference that definition. +</p> +<b>How to Reference a Fragment Definition</b> +<p> +With fragment references, you can place your fragment definitions on any page or template page. Fragment references have almost the same XML schema as fragments, the only difference is in the name of the tag <b>fragment-reference</b>, +and the <b>refid</b> attribute on that tag. Here is a fragment reference, referencing our fragment definition: +</p> +<source><![CDATA[ +.. + <fragment-reference id="dp-25-wp-reference" refid="hometown-weather-def"> + <property name="row" value="5"/> + <property name="column" value="0"/> + </fragment-reference> +... +]]></source> +<p> +It is important to always give the id attribute a unique id attribute across all fragments and fragment references. The refid attribute is <b>hometown-weather-def</b>, linking this reference to the actual fragment definition. Lets add +this fragment reference to the home page. Edit <b>pages/default-page.psml</b>, and add the fragment reference anywhere under the root fragment collection (the layout fragment), for example right before the very last ending fragment tag. +Save the file, and visit the home page <a href='http://localhost:8080/jetspeed/portal'>http://localhost:8080/jetspeed/portal</a>, and login to the demo system with the <i>admin</i> user, password also <i>admin</i>. The referenced fragment +will show up in the first column, fifth row. It should now be using the preference from the fragment definition (Miami, Florida). +</p> +</subsection> +<a name="DPSML"/> +<subsection name="Dynamic Template Pages (DPSML)"> +<p> +Dynamic templates are reusable portal page used with matching content URLs within the portal. Like page templates, dynamic pages are merged with pages. You can also put fragments +and fragment references on a dynamic page. Dynamic pages are matched to portal content page requests by URL and content type mappings: matching pages + are selected from current or parent folders. Only one dynamic page per content type should be defined per folder. +</p> +<p> +Dynamic Pages are used in combination with <a href="guide-content-mapping-psml.html">Content and Request URL Mapping</a> configuration. URL mapping configuration handles the dynamic part +of mapping a request URL to portlets designed to retrieve content from content management systems or other web sites. This makes it possible to map the content space of an external system +directly onto the URL space of the portal. Jetspeed can, out of the box, map the URL space of a website into the portal, using the DynamicWebContentPortlet combined with +our virtual DPSML (Dynamic Template Pages). To see an example of this running with JetUI, startup Jetspeed, login as admin, and navigate to <a href="http://localhost:8080/jetspeed/ui/content/";>http://localhost:8080/jetspeed/ui/content/</a>. +(Do not forget the ending /, it is necessary.) You will see the Apache Portals website running inside a Dynamic Web Content Portlet. +</p> +<img src="images/dpsml.png"/> +<p>Notice how there is a Page Navigator on the left side, and on the right the usual Toolbox. The Apache Portals website is hosted in the middle. Additionally, there is a Weather portlet next to it. Here is where the interesting part +comes in. Click on any of the links in the Apache Portals navigation panel, such as the <b>News and Status</b> link. Notice how when you click on links inside the hosted website, the whole +page is re-rendered. Look at the URL. When you clicked on the News and Status link, the URL should have changed to <a href="http://localhost:8080/jetspeed/ui/content/news.html";>http://localhost:8080/jetspeed/ui/content/news.html</a> +Dynamic pages allow you to frame external websites inside a Jetspeed template, and mix the content of the websites along with configured portlets and layouts. And, the URL space of the +external website is mapped and mounted onto the URL space of the portal. Mounting URL spaces is configured in the <a href="guide-content-mapping-psml.html">Content and Request URL Mapping Guide</a>. +In this example, we are mapping a base URL of http://portals.apache.org/. Any path beyond the base URL is mounted onto the Jetspeed base URL, http://localhost:8080/ui/content/. +</p> +<p> +Taking a slightly more complicated example, click on the <b>Jetspeed-2</b> link in the top area of the dynamic web content portlet, and then navigate to the <b>Features</b> link. +Inside the portlet, you have navigated to http://portals.apache.org/jetspeed-2/features.html. The mounted URL is http://localhost:8080/jetspeed/ui/content/jetspeed-2/features.html. +</p> +<p> +The configuration of a DPSML page is not much different than the configuration of a TPSML page. Lets take a look at the DPSML page used in the above example. First, there is the +<b>dynamic-page</b> element, telling Jetpeed we are defining a Dynamic PSML page: + </p> + <source><![CDATA[ +<dynamic-page id="default-content" content-type="*" + xmlns="http://portals.apache.org/jetspeed"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://portals.apache.org/jetspeed http://portals.apache.org/jetspeed-2/2.2/schemas/dpsml.xsd";> +]]></source> +<p>From here on, the page does not look any different from any other PSML page. It is up to the portlet developer to create a portlet capable of using the Jetspeed Dynamic Content Mapping API. +Jetspeed provides one: <b>j2-admin::DynamicWebContentPortlet</b>. This portlet uses two preferences to configure dynamic content. The <b>SRC</b> preference provides the URL of the +website being proxied. The <b>PORTALPATH</b> preferences defines the mounted path prefix onto the Jetspeed URL namespace. +</p> + <source><![CDATA[ + <fragment id="dcdp-2-dynamic-content" type="portlet" name="j2-admin::DynamicWebContentPortlet" decorator="gray-gradient-noborder"> + <preference name="SRC"> + <value>http://portals.apache.org/</value> + </preference> + <preference name="PORTALPATH"> + <value>/content/</value> + </preference> + </fragment> +]]></source> + +<p>Besides supporting virtual websites, DPSML plus the Jetspeed Dynamic Content Mapping API can be used to integrate other content systems such as Content Management Systems or Wikis into the portal.</p> +</subsection> +</section> + +</body> +</document>
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-pipelines.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-pipelines.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-pipelines.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-pipelines.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,239 @@ +<?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>Jetspeed 2 Pipelines</title> + <subtitle>Guide to Jetspeed Pipelines</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Jetspeed Pipelines"> + <p> + Pipelines are based on the inversion of control pattern. + The request processing pipeline is assembled to run in the Spring + container. A portal is largely driven by a request/response processing + data flow, much like the servlet or HTTP request/response paradigm. + Requests are made by client agents such as HTML or WAP browsers, + and the portal processes the request on the thread provided by the + application server for which Jetspeed is running. Request processing is + achieved in a workflow like pipeline, where valves are plugged into the + request pipeline. The workflow of the valves is configurable just like + any other Spring component. Pipelines reference (via Spring + constructor based dependency) one or more valves. Valves are also + Spring components. + </p> + <p> + Requests to the portal always come in via a Portal URL. Jetspeed has + URI entry points. The servlet context (/jetspeed) is also easily + configurable. Additionally, the request URL can be mapped to a portlet + pipeline. The default pipeline aggregates portlet pages. Portlet pages + are usually defined with the extension .PSML. If a page is not + supplied, default pages can be configured. + </p> + <subsection name='Pipeline Driven Processing'> + <p> + Requests to the portal always come in via a Portal URL. Jetspeed has + URI entry points. The servlet context (/jetspeed) is also easily + configurable. Additionally, the request URL can be mapped to a portlet + pipeline. The default pipeline aggregates portlet pages. Portlet pages + are usually defined with the extension .PSML. If a page is not + supplied, default pages can be configured. + </p> + <p> + <img src="images/pipeline-driven-processing.jpg" border="0"/><br/><br/> + </p> + </subsection> + <subsection name='Pipeline Architecture'> + <p> + In Jetspeed-2 requests are processed through a series + of Valve assembled together as a pipeline. + </p> + <p> + <img src="images/pipelines.jpg" border="1"/><br/><br/> + </p> + </subsection> + <subsection name='Pipeline Mappings'> + <p> + Pipelines mappings allow for prefixed mappings of / + context path + servlet path to be mapped to a + pipeline. For example: + </p> + <p> +<source><![CDATA[ +/jetspeed/portal --> Jetspeed Pipeline +/jetspeed/ajax --> Ajax Pipeline +/jetspeed/portlet --> Portlet Pipeline +/jetspeed/fileserver/file.pdf --> File Servlet Pipeline +/jetspeed/fileserver.file.html --> File Servlet Pipeline +/jetspeed/desktop --> Desktop Pipeline +]]></source> + </p> + </subsection> + <subsection name='Pipeline Mapping Configuration'> + <p> + The Pipeline Mapping Configuration can be found in <strong><code>/WEB-INF/assembly/pipelines.xml</code></strong>. + </p> + <p> +<source><![CDATA[ + <bean id='pipeline-map' + class='java.util.HashMap'> + <constructor-arg> + <map> + <entry key='/portlet'> + <value>portlet-pipeline</value> + </entry> + <entry key='/portal'> + <value>jetspeed-pipeline</value> + </entry> + <entry key='/ajaxapi'> + <value>ajax-pipeline</value> + </entry> + <entry key='/login'> + <value>jetspeed-pipeline</value> + </entry> + <entry key='/fileserver'> + <value>fileserver-pipeline</value> + </entry> + <entry key='/ajax'> + <value>ajax-direct-pipeline</value> + </entry> + <entry key='/desktop'> + <value>desktop-pipeline</value> + <!-- for jetspeed desktop, the keys /desktop, /action and /render cannot be changed --> + <!-- without also editing src/webapp/javascript/jetspeed/common.js and these beans: --> + <!-- the JetspeedDesktop bean expects argument for /desktop (3rd arg in constructor) --> + <!-- the DesktopPluto bean expects arguments for /desktop, /action and /render --> + <!-- the DesktopPortalURL bean expects arguments for /render and /action --> + <!-- the desktopEncoderRedirectValve bean expects arguments for /desktop and /render --> + </entry> + <entry key='/action'> + <value>desktop-action-pipeline</value> + </entry> + <entry key='/render'> + <value>desktop-render-pipeline</value> + </entry> + <entry key='/configure'> + <value>configure-pipeline</value> + </entry> + <entry key='/dtconfigure'> + <value>dtconfigure-pipeline</value> + </entry> + <entry key='/healthcheck'> + <value>healthcheck-pipeline</value> + </entry> + </map> + </constructor-arg> + </bean> +]]></source> + </p> + </subsection> + <subsection name='Pipeline Valves'> + <p> + Valves are units of work along the pipeline workflow. Typically valves + represent access to a Jetspeed feature or component, such as + aggregation, security, action processing, or device capabilities. + </p> + <p> + <img src="images/pipeline-valve.jpg" border="0"/><br/><br/> + </p> + <p> + The Jetspeed Pipeline has a request context associated with the entire + request pipeline. Using the Request Context API, valves can add or + retrieve bits of information to the pipeline request process. + </p> + <table> + <tr> + <th>Valve</th> + <th>Description</th> + </tr> + <tr> + <td>Capabilities Valve</td> + <td>Identifies the Capability Map, character encoding, media and + Mime types for the browser to the Request Context, sets the + content type in the response. + </td> + </tr> + <tr> + <td>Portal URL Valve</td> + <td>Creates the internal Portal URL from the request URL and + parameters using the Navigational State component. + </td> + </tr> + <tr> + <td>Security Valve</td> + <td>Builds the Java Security subject for the request, and runs all + remaining valves for this request under a privileged action, + enabling Java Security checks against the default Jetspeed + (JAAS) security policy, or, if configured, another standard + JAAS policy. + </td> + </tr> + <tr> + <td>Localization Valve</td> + <td>Sets the Locale (java.util.Locale) into the request context for + Java standard internationalization support. + </td> + </tr> + <tr> + <td>Profiler Valve</td> + <td>Uses the Profiler, Site Manager, and Page Manager components + to locate the requested page and menu "site" navigations. + </td> + </tr> + <tr> + <td>Action Valve</td> + <td>Determines the targeted action window in the request, if + found, executes the action via the portlet container. This is + the standard âaction phaseâ, blocking all rendering. At + completion of the action phase, the action valve redirects + back to the portal to process the render phase. + </td> + </tr> + <tr> + <td>Decorator Valve</td> + <td>Builds the actions available on the page and all portlet windows.</td> + </tr> + <tr> + <td>Aggregator Valve</td> + <td>Executes the standard ârender phaseâ, where the actual + rendering of all portlets and page decorations occurs. + </td> + </tr> + <tr> + <td>Desktop Valve</td> + <td>Renders the skeleton of the Jetspeed Desktop. All desktop + portlet rendering is controlled on the client side, with + javascript and the portlet pipeline. + </td> + </tr> + <tr> + <td>Desktop Action Valve</td> + <td>Executes Jetspeed Desktop actions over the span of one + request. The client-side desktop controls the execution of + the action phase, and then the subsequent render phases, + achieving parallel processing from the client-side. + </td> + </tr> + </table><br/> + </subsection> + + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-profile.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-profile.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-profile.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-profile.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,226 @@ +<?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>Profiler Configuration</title> + <subtitle>Profiler Configuration</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + </authors> + </properties> + <body> + +<section name="Profiler"> + + <p> + The Jetspeed Profiler is a portal resource location rule-based + engine. The profiler locates the following kinds of portal + resources: + <ul> + <li>PSML pages</li> + <li>Folders</li> + <li>Menus</li> + </ul> + </p> + + <p> + When a request is received by the portal, the profiler will map the + request to a resource based on a normalized set of runtime + parameters and state such as request parameters, HTTP headers, + and session attributes. The Profiler is invoked during the Jetspeed + request processing pipeline in the profiler valve. This valve + requires that the request context is already populated with the + portal request and response, capabilities, language and user + information. The runtime parameters make up the profile criterion + which the profiler uses to locate portal resources. The profiler + works hand in hand with the Site and Page Manager components. + </p> + + <subsection name="Profiler Rules and Rule Criteria"> + <p> + A Profiling Rule defines a list of criteria used when evaluating a + request to determine the location of a specific resource. Profiling + rules are used by the profiler to generically locate portal resources + based on the decoupled criteria for known portlet request data. A + rule consists of an ordered list of criteria which should be applied in + a given order. Following this rule's order, the profiling engine applies + each criteria of the rules using a less-specific algorithm until the + least specific resource criterion is considered. When all criteria are + exhausted, the rule will fail and a fallback resource will be required. + </p> + <p> + Rule Criteria are templates for locating profile properties. Jetspeed has + a profiling policy based on resource-specific URLs, Mime-Types and + language preferences. More complex implementations will need to + use other inputs in mapping to resources such as Cookies, IP + Address Ranges, Statistical Resource Usage Analysis, Business + Rules inside of servlets or EJBs,... + </p> + </subsection> + + <subsection name="Resolvers"> + <p> + Resolvers are Java classes that try to match criteria to find resources. Jetspeed provides several resolvers 'out of the box'. + </p> + <p> + <table> + <tr> + <td>request</td> + <td>match request parameter</td> + </tr> + <tr> + <td>session</td> + <td>match session parameter</td> + </tr> + <tr> + <td>path</td> + <td>match the path portion of the URL to the PSML page</td> + </tr> + <tr> + <td>hard.coded</td> + <td>a hard-coded value, such as âdefault-page.psmlâ </td> + </tr> + <tr> + <td>user</td> + <td>match the name of the current authenticated user</td> + </tr> + <tr> + <td>mediatype</td> + <td>match the mediatype (HTML,XHTML..) </td> + </tr> + <tr> + <td>language</td> + <td>the browserâs preferred language</td> + </tr> + <tr> + <td>country</td> + <td>the browsers preferred country code</td> + </tr> + <tr> + <td>user.attribute</td> + <td>match a named user attribute (Portlet API) </td> + </tr> + <tr> + <td>user.agent</td> + <td>the name of the agent (browser) </td> + </tr> + <tr> + <td>hostname</td> + <td>match the hostname in the URL</td> + </tr> + <tr> + <td>navigation</td> + <td>directive: move algorithm to start search in new location</td> + </tr> + <tr> + <td>group.role.user</td> + <td>use fallback algorithm</td> + </tr> + + </table> + </p> + </subsection> + + <subsection name="PSML Pages"> + <p> + The Profiler searches over a directory tree of + PSML pages trying to locate a PSML page to + be displayed. By default, this directory + structure is found under <strong><code>/WEB-INF/pages</code></strong>. The + âdirectoryâ can also be stored in the database. + There are several system directories known by + the profiler: + </p> + <p> + <table> + <tr> + <td>_user</td> + <td>Holds all user-specific pages.</td> + </tr> + <tr> + <td>_role</td> + <td>Holds all role-specific pages.</td> + </tr> + <tr> + <td>_group</td> + <td>Holds all group-specific pages.</td>> + </tr> + <tr> + <td>_subsite-root</td> + <td>Contains complete subsite trees, exactly like root tree.</td> + </tr> + </table> + </p> + <p> + <img src="images/psml-pages.jpg" border="0"/><br/><br/> + </p> + </subsection> + + <subsection name="Common Profiler Rules Provided"> + <p> + <table> + <tr> + <td>J1</td> + <td>Uses a most-specific to least-specific algorithm from Jetspeed-1 (Page-Path + User + Media Type + Language + Country)</td> + </tr> + <tr> + <td>J2</td> + <td>Default. Looks at the URL path combined with User + Media. (Page-Path + User + Media Type)</td> + </tr> + <tr> + <td>Role Fallback</td> + <td>Look for page in each role dir for the given user.</td>> + </tr> + <tr> + <td>User-Role Fallback</td> + <td>Look for page in userâs home dir, if not found, look in each role dir for the given user.</td> + </tr> + <tr> + <td>Variants</td> + <td>Path, Group Fallback, User-Role-Combo Fallback, Subsite-Roll Fallback.</td> + </tr> + </table> + </p> + </subsection> + + <subsection name="Profiler Component Configuration"> + <p> + The profiler.xml Spring configuration file configures the profiler component. + <table> + <tr> + <th>Constructor Argument</th> + <th>Description</th> + </tr> + <tr> + <td>(0) JETSPEED-INF/ojb/profiler_repository.xml</td> + <td>Holds the OJB database to POJO mapper for marshalling profile information to and from the persistent store.</td> + </tr> + <tr> + <td>(1) j1</td> + <td>The default profiling rule. If a user does not have a profiling rule defined in the association table, this profiling rule is used.</td> + </tr> + <tr> + <td>(2) ProfileResolvers (ref bean)</td> + <td>The map of profiler resolver names to implementing resolver classes. New resolvers should be added to the ProfileResolver table.</td> + </tr> + </table> + </p> + </subsection> +</section> +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-registry.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-registry.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-registry.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-registry.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,233 @@ +<?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>Jetspeed 2 Registry</title> + <subtitle>Guide to Jetspeed Registry</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Registry"> + <p> + The Portlet Registry persists the entire contents of the portlet + deployment descriptors in the Jetspeed database: + <ul> + <li>portlet.xml</li> + <li>jetspeed-portlet.xml (Jetspeed-specific extensions)</li> + </ul> + When a portlet application is deployed, Jetspeed updates the + registry with the definitions defined in these portlet + descriptors including: + <ul> + <li>One Portlet Application definition</li> + <li>One or more portlet definitions</li> + <li>Supported User Attributes</li> + <li>Supported custom portlet modes and window states</li> + </ul> + </p> + + <subsection name='portlet.xml'> + <p>The portlet.xml is the Portlet API descriptor for portlets. The entire contents of the file is indexed and stored + in the Jetspeed registry database. Typical content includes:</p> + <ul> + <li>Portlet Name, description, display name</li> + <li>Implementing class</li> + <li>Init Parameters</li> + <li>Supported Mime Types / Modes</li> + <li>Supported Locales</li> + <li>Resource Bundle Information / Localization (titles, keywords)</li> + <li>Default Portlet Preferences</li> + </ul> + <p>Refer to the Portlet Specification for more information on the portlet.xml. + </p> + </subsection> + <subsection name='jetspeed-portlet.xml'> + <p> + The jetspeed-portlet.xml is used for configuration of specific Jetspeed features not found in other + portals such as parallel rendering. The jetpeed-portlet.xml is made up of a set of elements extending the portlet application definition, + and then repeatable sections for each portlet (very much like the portlet.xml). Here is a look at an example portlet application + elements: + </p> + +<source><![CDATA[ + <js:security-constraint-ref>admin</js:security-constraint-ref> + + <dc:title>Jetspeed-2 Administration Portlets</dc:title> + <dc:title xml:lang="en">Jetspeed-2 Administration Portlets</dc:title> + <dc:creator>J2 Team</dc:creator> + <js:metadata name="pa-version">2.2</js:metadata> +]]></source> + <p>Notice the <code>dc:</code> prefixed settings refer to a Dublin Core XML schema. The <code>js:metadata</code> tag provides the version number + of the portlet application. This is used by Jetspeed's <a href='config-cluster.html'>Versioned deployment</a> for clusters in + order to determine when a new version of the application WAR is ready for deployment.</p> + <p>Addtionally, a portlet application can be secured with the js:security-constraint-ref tag, referencing a security constraint. + <a href='../adminguide/constraints.html'>Security constraints</a> allow you to protect an entire portlet application securely. + For instance you may want to require the 'admin' role restricting edit mode on all portlets in this application. Or you may require the 'developer' + role to restrict users from viewing portlets in this application. Constraints secure access to portlets or applications. + </p> +<p>By default, render-time checking of these global security constraints is disabled. So for 'view', if someone with appropriate permissions has added a portlet to a page visible to a user, the user will be able to view (but only view) the portlet. This happens even if there is a global portlet-level constraint intended to prevent the user viewing all instances of the portlet. +Access is therefore controlled by pages and fragments in the PSML, and by controls on the selection and adding of portlets.</p> + +<p>If render-time checking is enabled (default: false), a portlet which is not accessible to be viewed by the user, regardless of the current page or fragment, will not be rendered, and an "Access Denied" error message will be rendered instead. +To enable this feature, change a Spring configuration setting +in WEB-INF/assembly/aggregation.xml. +Find the bean with id="org.apache.jetspeed.aggregator.PortletRenderer" and +change the 5th constructor-arg element from false -> true +(see also inline comment in the bean definition)</p> +<source><![CDATA[ +<!-- Portlet Renderer --> +<bean id="org.apache.jetspeed.aggregator.PortletRenderer" +class="org.apache.jetspeed.aggregator.impl.PortletRendererImpl" +init-method="start" destroy-method="stop"> +<meta key="j2:cat" value="default" /> +<constructor-arg> +<ref bean="org.apache.pluto.PortletContainer" /> +</constructor-arg> +<constructor-arg> +<ref bean="org.apache.jetspeed.aggregator.WorkerMonitor" /> +</constructor-arg> +<constructor-arg> +<ref bean="PortalStatistics" /> +</constructor-arg> +<constructor-arg> +<ref bean="org.apache.jetspeed.aggregator.PortletTrackingManager" /> +</constructor-arg> +<!-- flag indicating whether to check jetspeed-portlet.xml security +constraints +before rendering a portlet. If security check fails, do not display +portlet content +--> +<constructor-arg type="boolean"> +<value>true</value> +</constructor-arg> +<constructor-arg> +<ref bean="org.apache.jetspeed.security.SecurityAccessController" /> +</constructor-arg> +<constructor-arg> +<ref bean="portletContentCache" /> +</constructor-arg> +</bean> +]]></source> + <p>Portlets can also be further defined in the <code>jetspeed-security.xml</code> file. The <code>portlet-name</code> tag allows us to map back + to the main <code>portlet.xml</code> file, matching the portlet by name. Again, we have a js:security-constraint-ref tag. This time, + we are assigning a security constraint to just one portlet. This constraint overrides the portlet application wide security + constraint tag. We also have similar Dublin Core tags for extended metadata. + </p> +<source><![CDATA[ + <portlet> + <portlet-name>LoginPortlet</portlet-name> + <js:security-constraint-ref>public-view</js:security-constraint-ref> + <dc:title>Login Portlet</dc:title> + <dc:creator>J2 Team</dc:creator> + </portlet> +]]></source> + <p>Another setting is a hint to the Jetspeed Customizer's Portlet Selector feature:</p> +<source><![CDATA[ + <js:metadata name="selector.conditional.role">admin</js:metadata> +]]></source> +<p>The js:metadata tag with the name attribute set to <code>selector.conditional.role</code> means that only users with the role named +<code>admin</code> will be able to see this portlet in the portlet selector. All other users will not see this portlet in the selector. +By setting the conditional role to <code>*</code>, you are telling Jetspeed that this portlet should never appear in the +portlet selector.</p> + +<p>There is a global setting in the <a href='jetspeed-properties.html'>jetspeed.properties</a> file allowing you to merge servlet +request parameters with portlet parameters. This is useful in Portlet 1.0 applications that need shared render parameters, or if you +need to communicate with your portlet via the URL in some rare cases. This global feature is also available on a per portlet basis + with the <code>merge.portal.parameters.with.portlet.parameters</code> setting. The second line below, <code>merge.portal.parameters.before.portlet.parameters</code> + simply determines whether servlet parameters should be merged before or after portlet parameters</p> +<source><![CDATA[ + <js:metadata name="merge.portal.parameters.with.portlet.parameters">true</js:metadata> + <js:metadata name="merge.portal.parameters.before.portlet.parameters">true</js:metadata> +]]></source> +<p> +When you have portlets in certain frameworks, they may submit actions when they should be submitting render navigations. +If this is the case, we consider this non-standard action behavior. In this case, we do not want cached portlets to be required +to refresh while navigating around the portlet. To handle this, we have the <code>nonStandardAction</code> setting. +</p> +<source><![CDATA[ + <js:metadata name="nonStandardAction">true</js:metadata> +]]></source> + +<p>Jetspeed allows you to define mapping window states in the jetspeed-portlet.xml. In the example below, +we are mapping the window state named <code>popup</code> to an existing window state named <code>solo</code>. +Note this setting is portlet application wide.</p> +<source><![CDATA[ + <custom-window-state> + <name>popup</name> + <mapped-name>solo</mapped-name> + </custom-window-state> +]]></source> + +<p>Finally, for enabling <a href='guide-aggregation.html'>parallel rendering</a>, you can set the metadata attribute <code>timeout</code>. +This value is in milliseconds. It serves two purposes: (1) the presence of it enables parallel rendering, and (2) the value determines how long Jetspeed will +give this portlet to complete rendering before it times out and abandons rendering the portlet.</p> +<source><![CDATA[ + <js:metadata name="timeout">3000</js:metadata> +]]></source> +<p>Extended metadata can also be added to the portlets using Dublin Core. +This metadata conforms to the <a href='http://dublincore.org/'>Dublin Core DCMI format</a> +DCMI allows for extended metadata, including localized data for example: +</p> +<source><![CDATA[ + <dc:title>Title 1</dc:title> + <dc:title xml:lang="en">Eng Title</dc:title> + <dc:title xml:lang="fr">Fr Title</dc:title> + <dc:subject xml:lang="sp">Spanish Subject</dc:subject> + <dc:creator>Default Jeremy Ford</dc:creator> + <dc:coverage>Default Coverage</dc:coverage> + <dc:contributor>Default Contributor</dc:contributor> + <dc:description>Default Description</dc:description> + <dc:format>Default Format</dc:format> + <dc:identifer>Default Identifier</dc:identifer> + <dc:language>Default Language</dc:language> + <dc:publisher>Default Publisher</dc:publisher> + <dc:relation>Default Relation</dc:relation> + <dc:right>Default Right</dc:right> + <dc:source>Default Source</dc:source> + <dc:type>Default Type</dc:type> +]]></source> +</subsection> +<subsection name='Services'> +<p>The jetspeed-portlet.xml is also used to define required Jetspeed services. +If your portlet requires a <a href='guide-services.html'>Jetspeed service</a> it must reference the service by name in the descriptor, for example: +</p> +<source><![CDATA[ + <js:services> + <js:service name='ApplicationServerManager'/> + <js:service name='DeploymentManager'/> + <js:service name='EntityAccessor'/> + <js:service name='GroupManager'/> + <js:service name='PageManager'/> + </js:services> +]]></source> + +</subsection> + <subsection name="Registry Administration"> + <p> + Jetspeed provides several Registry Administrative portlets: + <ul> + <li><a href='../adminguide/pam.html'>Portlet Application Manager</a></li> + <li><a href='../adminguide/palm.html'>Portlet Application Life Cycle Manager</a></li> + </ul> + </p> +</subsection> +</section> +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-search.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-search.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-search.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-search.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,230 @@ +<?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>Jetspeed 2 Search</title> + <subtitle>Guide to Jetspeed Search</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Search"> + <p> + Jetspeed-2 provides an integration with the popular Apache Lucene search engine + and Apache Solr search engine, high-performance, full-featured text search engine libraries; + technologies suitable for nearly any application that requires full-text search, especially cross-platform. + You can either embed Solr based search engine component in Jetspeed-2 or connect to an external Solr engine via http connection. + By default, Apache Lucene based search engine component is used, but you can switch to + Solr based search engine component easily by copying one of alternate Spring xml confiugration files. + </p> + <p> + By default, Jetspeed-2 indexes all registry information: portlet + instances and portlet definitions as searchable entities. + </p> + <subsection name="Default Lucene based search engine configuration"> + <p>Configuration for the Search Engine is in the Spring configuration file <code>search.xml</code> + You can configure the location of your search indices in this Spring configuration file. + Note you may want to move the location of your indices outside the Jetspeed web application + </p> +<source><![CDATA[ + <bean id="org.apache.jetspeed.search.SearchEngine" + class="org.apache.jetspeed.search.lucene.SearchEngineImpl" + > + <constructor-arg index="0"><value>${applicationRoot}/WEB-INF/search_index</value></constructor-arg> + .... +]]></source> + </subsection> + <subsection name="Embedded Solr based search engine configuration"> + <p> + If you copy /WEB-INF/assembly/alternate/search-embedded-solr-override.xml + to /WEB-INF/assembly/override/ folder, you can switch to an embedded Solr based search engine component + instead of the default Lucene based one. + </p> +<source><![CDATA[ + .... + + <bean id="org.apache.solr.core.CoreContainer" class="org.apache.solr.core.CoreContainer" destroy-method="shutdown"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg value="${search.embedded.solr.solr.home}" /> + <constructor-arg> + <bean class="java.io.File"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg value="${search.embedded.solr.solr.home}/solr.xml" /> + </bean> + </constructor-arg> + </bean> + + <bean id="org.apache.solr.client.solrj.SolrServer" class="org.apache.solr.client.solrj.embedded.EmbeddedSolrServer" depends-on="_embeddedSolrDataDirPropSetter"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg ref="org.apache.solr.core.CoreContainer" /> + <constructor-arg value="js" /> + </bean> + + <bean id="org.apache.jetspeed.search.SearchEngine" class="org.apache.jetspeed.search.solr.SolrSearchEngineImpl"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg ref="org.apache.solr.client.solrj.SolrServer" /> + <constructor-arg type="boolean" value="${search.index.optimizeAfterUpdate}" /> + <constructor-arg ref="org.apache.jetspeed.search.HandlerFactory" /> + </bean> +]]></source> + <p> + In the example configuration above, the embedded Solr based search engine component will + initialize search index as configured by properties in /WEB-INF/conf/jetspeed.properties: +<source><![CDATA[ +# Optionally you can configure embedded solr home and data dir paths +# if you enable embedded solr instead of the default lucene +search.embedded.solr.solr.home=${applicationRoot}/WEB-INF/solr +search.embedded.solr.data.dir=${applicationRoot}/WEB-INF/solr/data +]]></source> + </p> + <p> + The Solr configurations are located in /WEB-INF/solr directory. + For more extensibility, it is provided as multi-core setup as follows: +<source><![CDATA[ +<solr persistent="true"> + <cores adminPath="/admin/cores"> + <core name="js" instanceDir="js"></core> + </cores> +</solr> +]]></source> + </p> + </subsection> + <subsection name="External Solr based search engine configuration"> + <p> + If you copy /WEB-INF/assembly/alternate/search-http-solr-override.xml + to /WEB-INF/assembly/override/ folder, you can switch to an external Solr based search engine component + instead of the default Lucene based one. + </p> +<source><![CDATA[ + .... + + <bean id="org.apache.solr.client.solrj.SolrServer" class="org.apache.solr.client.solrj.impl.CommonsHttpSolrServer"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg value="${search.http.solr.url}" /> + <property name="soTimeout" value="1000" /> + <property name="connectionTimeout" value="100" /> + <property name="defaultMaxConnectionsPerHost" value="100" /> + <property name="maxTotalConnections" value="100" /> + <property name="followRedirects" value="false" /> + <property name="allowCompression" value="true" /> + <property name="maxRetries" value="1" /> + <property name="parser"> + <bean class="org.apache.solr.client.solrj.impl.XMLResponseParser"> + <meta key="j2:cat" value="default or search" /> + </bean> + </property> + </bean> + + <bean id="org.apache.jetspeed.search.SearchEngine" class="org.apache.jetspeed.search.solr.SolrSearchEngineImpl"> + <meta key="j2:cat" value="default or search" /> + <constructor-arg ref="org.apache.solr.client.solrj.SolrServer" /> + <constructor-arg type="boolean" value="${search.index.optimizeAfterUpdate}" /> + <constructor-arg ref="org.apache.jetspeed.search.HandlerFactory" /> + </bean> + + .... +]]></source> + <p> + In the example configuration above, the Solr based search engine component will + connect to the external Solr engine as configured by properties in /WEB-INF/conf/jetspeed.properties: +<source><![CDATA[ +# Optionally you can configure external solr http(s) url +# Note: If you have multi-core setup, you should put the core name at the end. e.g., '/js'. +search.http.solr.url=http://localhost:8983/solr/js +]]></source> + </p> + <p> + + </p> + </subsection> + <subsection name="Solr based search schema confiugration"> + <p> + An example schema configuration for Jetspeed-2 can be found in /WEB-INF/solr/js/conf/schema.xml. + Jetspeed-2 requires the following fields at least: +<source><![CDATA[ + <!-- Core Search Fields --> + <field name="fieldname.key" type="string" indexed="true" stored="true" required="true" /> + <field name="fieldname.type" type="text" indexed="true" stored="true" required="false" /> + <field name="fieldname.content" type="text" indexed="true" stored="false" required="false" /> + <field name="fieldname.description" type="text" indexed="true" stored="true" multiValued="true" required="false" /> + <field name="fieldname.title" type="text" indexed="true" stored="true" multiValued="true" required="false" /> + <field name="fieldname.language" type="text" indexed="true" stored="true" multiValued="true" required="false" /> + <field name="fieldname.fields" type="text" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="fieldname.keywords" type="string" indexed="true" stored="true" multiValued="true" required="false" /> + <field name="fieldname.url" type="text" indexed="true" stored="true" multiValued="true" required="false" /> + <field name="fieldname.score" type="text" indexed="true" stored="false" required="false" /> + <field name="fieldname.className" type="text" indexed="true" stored="true" required="false" /> + <field name="fieldname.synthetic" type="text" indexed="true" stored="false" required="false" /> + <!-- Metadata Search Fields --> + <field name="ID" type="string" indexed="true" stored="true" required="false" /> + <field name="url" type="text" indexed="true" stored="true" required="false" /> + <field name="portlet" type="string" indexed="true" stored="true" required="false" /> + <field name="portlet_application" type="string" indexed="true" stored="true" required="false" /> + <field name="title" type="string" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="description" type="string" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="subject" type="string" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="creator" type="string" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="publisher" type="string" indexed="true" stored="false" multiValued="true" required="false" /> + <field name="contributor" type="string" indexed="true" stored="false" multiValued="true" required="false" /> +]]></source> + Therefore, please be sure that the schema should be configured properly like the example above + when you want to use an external Solr search engine. + </p> + <p> + If you want easy steps to test an external Solr based search engine component, here are simple ones as an example: + <ol> + <li>Copy /WEB-INF/assembly/alternate/search-http-solr-override.xml to /WEB-INF/assembly/override/ folder.</li> + <li>Instal Solr war file onto a servlet container. For example, copy solr.war to $CATALINA_HOME/webapps/.</li> + <li> + Copy the example Solr home and data directory to somewhere you want to keep the search index. + For example, copy /jetspeed/WEB-INF/solr/ directory to /tmp/solr/. + </li> + <li> + Start the servlet container with specifying Solr home and data directory. + <br/> + <br/> + $ export CATALINA_OPTS="-Xmx256m -XX:MaxPermSize=128m -Dsolr.solr.home=/tmp/solr -Dsolr.data.dir=/tmp/solr/data" + <br/> + </li> + <li> + If you didn't deploy portlet applications again and the search index was not refreshed, then + redeploy all the portlet applications or refresh the search index for each portlet application + in the Portlet Application Manager portlet. + </li> + </ol> + </p> + </subsection> + <subsection name="Search UIs"> + <h4>Registry Applications List Portlet in Portlet Application Manager Page</h4> + <p> + <img src="images/registry-applications-list.png" border="0"/> + <br/> + </p> + <br/> + <h4>Application Details Portlet in Portlet Application Manager Page</h4> + <p> + <img src="images/application-details.png" border="0"/> + <br/> + <br/> + <em>You can refresh search index for each application.</em> + </p> + </subsection> + </section> + </body> +</document>
