Date: Fri, 29 Mar 2024 12:33:30 +0100 (CET) Message-ID: <1160489509.279.1711712010551@yoda.gx.local> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_278_923412960.1711712010549" ------=_Part_278_923412960.1711712010549 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
A plugin may contain Java files, images, JSPs, etc. Some of the resource= types are covered by the component types that XperienCentral supports. For= example, XperienCentral supports deploying JSPs for the website environmen= t by the presentation component and deploying static files by all component= types.
This part describes the deployment of any resource that is not covered b= y a component type. Examples are:
web.xml
A tag library is a collection of JSP tags you can import and use in a JS= P. JSP tags are in fact functions you can invoke from any JSP in the same w= ay you define methods in a Java class and import that class into another.= p>
To deploy a custom tag library onto a normal web application, follow the= se steps:
Define the tag library in the <jsp-config>
sectio=
n of the web.xml
, for example:
<taglib>= ; =09<taglib-uri>http://www.gx.nl/taglib/idg_functions</taglib-uri&g= t; =09<taglib-location>/WEB-INF/prj/tld/gx_functions.tld</taglib-loca= tion> </taglib>
The taglib-location
in the web.xml
must po=
int to the location of the .TLD file which defines the contents of that tag=
library. This .TLD may define a function that points to a method in a part=
icular Java class on the Application server=E2=80=99s classpath, for exampl=
e:
<function&= gt; =09<name>getAllBooks</name> =09<function-class>nl.gx.product.BookTag</function-class> =09<function-signature>Book[] getAllBooks()</function-signature>= ; </function>
/WEB-INF/lib
in order to ensure that they are on th=
e application server=E2=80=99s classpath.Because the web.xml
must be =
changed and this cannot be done at runtime, it is not possible to add a cus=
tom tag or tag library from a plugin, therefore, in order to add a custom t=
ag or tag library, you must perform the steps above. You must restart the a=
pplication server in order to apply the changes.
A custom JSP tag file is very similar to a custom JSP tag, the only diff=
erence is that the actual function is not implemented in Java but in JSP. T=
he extension of the custom tag file is by convention .tag
.
To deploy a custom tag file, perform the following steps:
/tags
subdirectory within the /src/main/res=
ources
directory of your plugin./tags
dir=
ectory.When the plugin is deployed, the tag file is automatically available thr= ough the following path:
/WEB-INF/tags/[=E2=80=A6BUNDLE_ID=E2=80=A6]
Where the [=E2=80=A6BUNDLE_ID=E2=80=A6]
is the actual bundl=
e ID of the plugin, for example nl.gx.webmanager.mypresentation
.
To use the tag file, you must add the following line to your plugin:
<%@ taglib= tagdir=3D"/WEB-INF/tags/[=E2=80=A6BUNDLE_ID=E2=80=A6]" prefix=3D"myprefix"= %>
You can then call the tag as you would normally do using the prefix and = tag filename.
This part describes how to distribute and access an arbitrary resource w= ithin a plugin. For example, suppose that you want to distribute along with= a plugin a static .properties file containing configuration properties use= d by some Java class within the plugin.
This example describes static properties - If you want the properties to=
be configurable, you must use the ConfigurationManagement
ser=
vice instead.
To distribute the resource with the plugin you need to simply put it som=
ewhere in /src/main/resources
. It can be stored in any subfold=
er. To access this resource from Java, simply retrieve the resource from th=
e classloader of that class by invoking getResourceAsStream
on=
the class. For example, if we distributed a file called config.prope=
rties
in /src/main/resources/conf/books
we could access=
this resource from Book.java
like this:
Class<Book= > clazz =3D Book.class; InputStream propFile =3D clazz.getResourceAsStream("conf/books/config.prope= rties" ); Properties props =3D new Properties(); props.load( propFile);
By static files we mean files that are typically static within the conte= xt of a web application like images, JavaScript files, HTML files and style= sheets. Such static files can have two purposes:
To deploy static files to the Workspace, simple copy the resources to /wm/b/wcb/<Component bundle definition ID>.
Since this directory is not accessible from the website environment, the=
file will not be accessible. To access static files from Java, the URL can=
be calculated by:
public String= getIcon() { =09return "/wm/b/wcb/" + Activator.BUNDLE_DEFINITION_ID + "/icon.gif"; }
Alternatively, some API classes contain methods to retrieve the static bac=
kend directory:
CmsItemBase.g= etStaticResourceDir(); ElementComponentDefinition:getStaticBackendDir();
If the full path name to the file is needed, the pathname of the static we=
b root directory can be retrieved from the Configuration management service=
:
confManagemen= t.getParameter("website_settings.www_root_directory");
To point to this resource from a JSP, the easiest way is to set the path=
into the reference data of the controller. The controller always has acces=
s to the Activator of the component by which it is contained. For example:<=
br>
public Map<= ;String, Object> referenceData(HttpServletRequest req, Object command, E= rrors errors) throws Exception { =09Map<String, Object> data =3D super.referenceData(req,command, erro= rs); data.put("staticBackendDir","/wm/b/wcb/" + =09Activator.BUNDLE_DEFINITION_ID + "/"); =09return data; }
All properties written to the reference data are available directly in the=
JSP, so to define the URL to an icon called icon.gif
, the fol=
lowing code snippet would display that icon in a JSP:
<img src= =3D=E2=80=9D${staticBackendDir}icon.gif=E2=80=9D/>
To deploy static files to the website environment, the presentation comp=
onent methodology as described in Presentation Component=
a> should be used. For this reason resources should be placed in /src=
/main/resources/presentationtype/static
- The files will be copied t=
o /static
, inside the web root directory of the static web app=
lication when the plugin is deployed.
In order to make this work, the plugin must define a presentation compon= ent, therefore in order to develop a plugin containing an element component= also containing such static files, a presentation component must be define= d in the activator of that plugin also.
To access the static files from Java, the method website.getStatic=
FilesUrl
can be invoked which returns the web root of the static web=
application. Note that /static
must be appended to the filena=
me since the method returns only the web root.
To access the static files from a JSP, the same method can easily be use=
d since the website is available in the presentationcontext
wh=
ich is available in any JSP. For example:
<c:set var= =3D"staticFilesUrl" value=3D"${presentationcontext.website.staticFilesUrl}" /> <img src=3D=E2=80=9D${staticFilesUrl}/static/project/icon.gif=E2=80=9D/&= gt;
There is an important difference between static files or JSPs for the webs=
ite environment distributed with the plugin and those distributed with a se=
parate presentation component. Static files and JSPs distributed with a plu=
gin that contain only resources for that plugin are intended for demonstrat=
ion purposes only. They provide a default layout which ensures that the plu=
gin has a presentation on any website onto which it is deployed.
Because each website uses a different presentation, a plugin should neve= r contain the actual presentation itself. A website usually has one active = presentation component which contains all JSPs and static files used to ren= der the complete website environment which overwrites all presentations and= static files in a plugin (if it contains these resources).
To ensure that the presentation plugin overwrites all presentations and = static files from the individual plugins, it must be deployed after deployi= ng all other plugins.
Using Java libraries which are available in the Maven repository is quit=
e simple. Defining the artifact dependency in the pom.xml
of t=
he plugin will automatically bundle the JAR with the plugin and class loadi=
ng issues will be handled by the framework automatically upon using the lib=
rary at runtime.
It becomes more complicated when a Java library is used that is not cont= ained by the Maven repository. The best approach in this case is to simply = upload the JAR file to the (local or remote) Maven repository.
The following steps must be performed in order to use a custom Java libr= ary in a plugin:
pom.xml
. An example =
is given below.MANIFEST.MF
, and if=
the library should also be available to other plugins, copy the value of <=
code>Import-Package from the Manifest into a new attribute imp=
ortPackage
in the build/plugins/plugin/configuration/osgiManif=
est
section of the pom.xml
. Import-Package
from the manifest into a =
new attribute exportPackage
in the build/plugins/plugin/=
configuration/osgiManifest
section of the pom.xml
.Import-Package
from the Manifest into a new attribute importPackage
in the build/plugins/plugin/ configuration/osgi=
Manifest
section of the pom.xml
. For this situation, th=
e Import-Package
value contains too many packages: remove all =
packages that are contained by the Java library.In both situations, follow the rule: =E2=80=9CImport what you export=E2= =80=9D.
The Maven command to upload a JAR file and create a new artifact for it = in the Maven repository has the following syntax:
mvn install:install-file -Dfile=3D[filename] -DgroupId=3D[groupId]=
-DartifactId=3D[artifactId] -Dpackaging=3Djar -Dversion=3D[version] -s [pa=
th to settings.xml]
where:
filename
is the name of the JAR file to uploadgroupId
is the group ID that the new Maven artifact should=
havearticfactId
is the artifact ID that the new Maven artifact=
should haveversion
is the version number that the new Maven artifact =
should haveAs an example we describe how to use an external library called ko=
nakart.jar
which we will not share with other plugins:
mvn install:install-file -Dfile=3Dkonakart.jar -DgroupId=3Dcom.=
konakart -DartifactId=3Dkonakart -Dpackaging=3Djar -Dversion=3D1.0.0 -s set=
tings.xml
com.konakart
and the artifact Id konakart
=
.Define a dependency for this new artifact with scope provided in the=
pom.xml
:
<dependenc= y> <groupId>com.konakart</groupId> <artifactId>konakart</artifactId> <scope>provided</scope> <version>1.0.0</version> </dependency>
Build the plugin.
Open the MANIFEST.MF
file inside the generated JAR file=
and copy the value of the Import-Package
property to the clip=
board.
Open the pom.xml
and create a new attribute impor=
tPackage
in the build/plugins/plugin/configuration/osgiManifes=
t
section.
Paste the value from the clipboard into the importPackage attribute. Remove all packages exported by the
konakart
lib=
rary (this can be looked up by opening the konakart.jar
).