| |
This blog is the first from a series of blogs that i plan to release regarding the Enterprise Portal. I'm part of the portal consultant team at a company that would have stong influence on the way portal consulting is done in the future. Please reference to our External Facing Portal (http://www.ibsolution.de) - built all on Portal technology and compatible with all other Netwaever components (MDM, Visual Composer, GP, etc.).
Let me introduce you to the topics that I plan to cover in the future blogs:
Styles - cross-browser CSS, how to integrate my CSS in the portal, SAP CSS styles modification
JSP's - nested JSP's, JSP or an AbstractComponentClass?, hard coded features - yes or no?
0.1. Flash within EP part 1 - basic ActionScript and introduction to Flash
0.2. Flash within EP part 2 - Flash navigation in the Portal
0.3. Dynamic navigation (recode) - Make it slim for EFP
0.4. Content area (recode) - Code optimization for EFP
0.5. Custom login screen for External Facing Portal
0.6. Portal development with Portal DCs
This list can be further updated, if I get the right ideas anytime soon, otherwise I risk to loose the string that is leading me between the different topics.
If you haven't read my blogs regarding the Server Observer Widgets, you can do that here:
NetWeaver 2004s Server Administration as easy as 1-2-3 Part 1NetWeaver 2004s Server Administration as easy as 1-2-3 Part 2
(NetWeaver 2004s Server Administration as easy as 1-2-3 Part 2)
Let us now focus on the portalapp.xml. What does it include, where does it reside and do we actually need it? If I have to answer those questions shortly and in the sequence they were asked, then the answers would be - lots of things, inside your PAR file and yes we need it (pretty badly). As you can imagine those answers doesn't bring you much benefit, so let me bring you one idea closer to the magic behind the portal application deployment descriptor.
Basically the portalapp.xml file is nothing else, but a reference to what your application provides and needs to run successfully within the portal. The file should always reside in the PORTAL-INF folder of your project or PAR file. A PAR(Portal application ARchive) is nothing else than a ZIP archive so you can always rename a PAR file to ZIP and unzip it to reveal its contents. However a much better way would be to use the PAR file as it is and just import it in Netweaver Developer Studio. In this case I'm using the "com.sap.portal.runtime.logon.par" PAR file just for the example. Here is where you find the portalapp.xml file in both cases (NWDS and Windows Explorer):
On first sight not much of a difference between the two methods, but in any case I would recommend using the NWDS studio when editing PAR files since as you would see later it offers a much more conviniet environment for editing that file. In the other case you would end up editing the file with an advanced XML Editor or even Adobe Dreamweaver, but that won't still give you the advantage of the built-in portal application deployment descriptor of the NWDS. In the following example I'll be assuming you listened to my advice and used the NetWeaver Developer Studio to edit the portalapp.xml. But before we get into editing, let's shortly analyze the structure of an empty portalapp.xml file:
<?xml version="1.0" encoding="iso-8859-1"?><br /><application><br /> <application-config/><br /> <components/><br /> <services/><br /></application>
As you can see there is not much in an empty portalapp.xml, but its important to understand this structure so that later when the file grows you can still track and understand its structure. Just by understanding the semantic meaning of the tags we can already assume that the portalapp.xml file can contain some application configuration details, components and services. The first tag is just the standard one that implies that the document is actually a XML file using the described encoding. The application tag is always the root tag of the portalapp.xml. No matter what you insert in that document it has to be between an opening and a closing tag called application. I guess here is a good spot to make an official warning:
* !!! Only one simple syntax error, or misplaced element within the portalapp.xml could render your complete application unstable or even unusable, so please re-check your syntax if you use an external editor. Using the built-in NWDS editor seriously reduces the chance of an error !!!</p><p align="left">Back to the descirption of the empty portalapp.xml. So the application-config tag can basically contain one or more property tags, which include two attributes - a name and a value. Here an example:</p><p align="left">+*</p><p>If the value field is multi-valued then you can separate the entries with commas. The application-config tag includes properties that affect the whole application package. There are a number of standard properties that can be added within the application-config tag. Here is a list and description of the most used:</p><table border="1" width="700" align="left" style="border: #000000 1px solid"><tbody><tr style="background-color: #d7d4d6"><td> property name</td><td>* description</td><td>allowed values </td></tr></tbody><tbody><tr><td>ServicesReference</td><td> This property allows references to other Portal Services</td><td>comma-separated list of other Portal Service's names or aliases</td></tr><tr><td>SharingReference</td><td> This property allows references to other Portal Applications whose API definitions are to be used in this application's API definition</td><td>comma-separated list of other Portal Application's names or aliases</td></tr><tr><td>PrivateSharingReference</td><td>This property allows references to other Portal Applications whose API definitions are to be used in this application's (non-public) implementation</td><td> comma-separated list of other Portal Application's names or aliases</td></tr><tr><td>testable</td><td>The PRT uses this information to indicates to the PAR Unit Test Studio if the application contains testable entities. In that all testable Portal Components will be invoked with the Portal Runtime Test Framework.</td><td><p>false<br />true*<br /></p></td></tr><tr><td>releasable</td><td>Because PRT allows hot deployment, all applications are releasable and the application instance can be dropped at any time by the system. Nevertheless some critical applications may want to avoid the release of their instance when the system runs low in memory. They should then set this property to false.</td><td>false<br />true</td></tr><tr><td>startup</td><td> If set to true, the application as a whole will be started (initialized) on startup of the server. In particular this means that it will be locally deployed.</td><td>false<br />true</td></tr></tbody></table><p> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br />The components tag is an important one since it contains all the components that you write within your application. In general the next child element of components should be called "component". Here an example of how a component tag may look like:</p><p align="left"><component name="testComponent"><br /> <component-config><br /> <property name="ClassName" value="de.ibsolution.test.testComponent"/><br /> </component-config><br /> <component-profile><br /> <property name="userProperty" value="testValue"><br /> <property name="personalization" value="dialog"/><br /> </property><br /> </component-profile><br /></component></p><p align="left">The displayed XML represents one component, which has a representative class implementation in the package de.ibsolution.test.testComponent. The component-config tag is similiar to the application-config, but the properties defined within the component-config are only relevant for the component itself and do not affect other components or services within the same application package. The component-profile tag contains properties, which are used to render the component with the proper default values. This means that those properties are used somewhere inside the component and can be modified to influence the component output. As you see in the example the nested property tag has a strictly defined name "personalization", which defines that the property "userProperty" should be available if a user clicks on the personalization link of the component. There are a number of standard properties that can be nested inside the component-profile properties. You can get overview in the following table:</p><table border="1" width="700" align="left" style="border: #000000 1px solid"><tbody><tr style="background-color: #d7d4d6"><td> property name</td><td>* description</td><td>allowed values </td><td> default*</td></tr></tbody><tbody><tr><td> description</td><td> a locale sensitive descriptive text for the property that is used in user interfaces. It can be resolved by accessing the component's resource bundle</td><td> any</td><td>N.A.</td></tr><tr><td> plainDescription</td><td> plain text used in user interfaces to describe the property. Will be used if no description is defined</td><td> any</td><td> property name</td></tr><tr><td> type</td><td> "visual" data type of the property</td><td> Select<br /> Boolean<br /> String <none></td><td> String <none></td></tr><tr><td> personalization</td><td> specifies how to treat the property with respect to personalization</td><td> none - cross-user storage, not shown in personalization<br /> no-dialog - per-user storage, not shown in personalization<br /> dialog - per-user storage and shown in personalization</td><td> dialog</td></tr><tr><td> inheritance</td><td> specifies if the property can be overridden by derivation (e.g. iView chain)</td><td> final<br /> non-final</td><td> non-final</td></tr></tbody></table><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> </p><p align="left">There are also standard properties for the component-config and the component-profile tags. For the component-config tag are as follows:</p><table border="1" width="700" align="left" style="border: #000000 1px solid"><tbody><tr style="background-color: #d7d4d6"><td> property name</td><td>* description</td><td>mandatory</td><td> default*</td></tr></tbody><tbody><tr><td>ClassName</td><td> name of the implmentation class of the portal component</td><td> no</td><td>N.A.</td></tr><tr><td> componentType</td><td> type of the component: none, jspnative, servlet</td><td> no</td><td>none</td></tr><tr><td> JSP</td><td><p> used in case the componentType is "jspnative" to specify the path to the JSP file that implements the component</p></td><td> no</td><td> N.A.</td></tr><tr><td> ResourceBundleName</td><td> the application's resource bundle</td><td> no</td><td> "localization"</td></tr><tr><td colspan="4">note: using jspnative as componentType means that the JSP file you specify will be rendered to a class during runtime.</td></tr></tbody></table><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"> </p><p align="left"><br /><br /><br /><br /><br /><br /><br /><br /> </p><p align="left">The standard properties for the component-profile are as follows:</p><table border="1" width="700" align="left" style="border: #000000 1px solid"><tbody><tr style="background-color: #d7d4d6"><td> property name</td><td>* description</td><td>allowed values </td><td> default*</td></tr></tbody><tbody><tr><td> AuthRequirement</td><td>the minimal authentication required to execute the portal component</td><td> user<br /> admin<br /> none<br /> role list</td><td>none</td></tr><tr><td> CachingLevel</td><td>Define the cache content authorizations</td><td>Shared : The cache content is shared among all users.<br />User: The content is private for each user.<br />Session: The content of the component is cached all the time the (servlet) session is running, whether or not a user is connected.</td><td>N.A.</td></tr><tr><td> ValidityPeriod</td><td>Validity time period for the cache in milliseconds.</td><td> any number</td><td>N.A.</td></tr><tr><td> EPCFLevel</td><td>defines whether to use the client framework or not</td><td> 0 - no JavaScript, no Java applets, no iView communication<br />* 1 - JavaScript only<br /> 2 - JavaScript and Java applets</td><td>N.A.*</td></tr><tr><td> ConfigRootFolder</td><td>String representing the path within the overall configuration structure of the component specific configuration.</td><td> String</td><td> /component.path</td></tr></tbody></table><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> </p><p> </p><p>The services tag is not much different that the components tag. It includes always as a first child a <service> tag, or is left empty as in the first example of the empty portalapp.xml. Here is a short example:</p><p><services><br /> <service name="testService"><br /> <service-config><br /> <property name="className" value="de.ibsolution.test.testService"/><br /> <property name="startup" value="true"/><br /> <property name="releasable" value="true"/><br /> </service-config><br /> <service-profile><br /> <property name="testProperty" value="test"/><br /> </service-profile><br /> </service><br /></services>+
As with the components there are some standard propeties that apply to the service-config tag. They are as follows:
property name| |
* description</td><td>required value</td><td> default*| ClassName | The name of the implementation class of the Portal Service. This class must implement the IService interface. | |
yes| |
N.A.| startup | Inform on when the service will be started (on runtime or on demand). | |
no| |
false
The service-profile tag doesn't have any standard properties, but in order to see your service in the Service Navigation within the Portal under System Administration -> System Configuration -> Service Configuration you would have to specify at least one property within that tag.
And now before we go to the last phase, where i'll show you how to use the bult-in editor of NWDS, let me build a quick complete example of an portalapp.xml file:
<?xml version="1.0" encoding="iso-8859-1"?><br /><application alias="testApplication"><br /><application-config><br /><property name="ServicesReference" value="service1,service2"/><br /><property name="SharingReference" value="application1,application2"/><br /><property name="PrivateSharingReference" value="applicationInCore"/><br /></application-config><br /><components><br /><component name="testComponent"><br /> <component-config><br /> <property name="ClassName" value="de.ibsolution.test.testComponent"/><br /> </component-config><br /> <component-profile><br /> <property name="userProperty" value="testValue"><br /> <property name="personalization" value="dialog"/><br /> </property><br /> </component-profile><br /></component><br /></components><br /><services><br /> <service name="testService"><br /> <service-config><br /> <property name="className" value="de.ibsolution.test.testService"/><br /> <property name="startup" value="true"/><br /> <property name="releasable" value="true"/><br /> </service-config><br /> <service-profile><br /> <property name="testProperty" value="test"/><br /> </service-profile><br /> </service><br /></services><br /></application>
As you see a I just put the separate parts together and I have a complete portalapp.xml file including one component and one portal service in it. The only thing that I added is the alias attribute in the application tag. This attribute is also common for the component and service tags and is used to give short names to the application, component or service. Now let's see how to use the built-in editor of the NWDS to speed up the creation of the portalapp.xml file. To start the editor just right-click the portalapp.xml file in NWDS and choose the appropriate editor as shown on the picture below:
The editor opens up and you are presented with 5 different views of the portalapp.xml file:
7 Comments
