-
Notifications
You must be signed in to change notification settings - Fork 34
/
README.html
183 lines (139 loc) · 14.6 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
<!DOCTYPE html><html><head><title>README</title><link href="http://static.jboss.org/ffe/0/www/vendor/redhat/documentation.css" rel="stylesheet"></link><link href="http://static.jboss.org/ffe/0/www/vendor/redhat/pygments.css" rel="stylesheet"></link></head><body><!--~ Do not edit this derived file! See jboss-portal-quickstarts/src/main/freemarker/portal-extension/README.html.ftl ~-->
<h1><a id="portalextension-portal-extension" class="anchor" href="#portalextension-portal-extension"><span class="anchor-icon"></span></a>portal-extension: Portal Extension</h1>
<p>Author: Thomas Heute, Peter Palaga<br/>
Level: Beginner<br/>
Technologies: Red Hat JBoss Portal, Portal Extension<br/>
Summary: This project demonstrates how it is possible - using a Portal Extension - to customize a portal without modifying the files included in portal.ear.<br/>
Target Product: Portal<br/>
Source: <a href="https://github.com/jboss-developer/jboss-portal-quickstarts.git">https://github.com/jboss-developer/jboss-portal-quickstarts.git</a> </p>
<h2><a id="what-is-it" class="anchor" href="#what-is-it"><span class="anchor-icon"></span></a>What is it?</h2>
<p>This project demonstrates a simple Portal Extension. It shows how it is possible to extend and customize a portal without
modifying the files included in portal.ear. The main advantage of this approach to customization is that upgrades to new
versions of Red Hat JBoss Portal will be easier to handle as all the customization can be embedded in separate
deployable packages.</p>
<p>Portal Extension customizes the default portal available at <a href="http://localhost:8080/portal">http://localhost:8080/portal</a> by doing few changes:</p>
<ul>
<li>Replace the front page image</li>
<li>Customize the login page</li>
<li>Change few translation strings</li>
<li>Add a few pages</li>
</ul>
<p>For more details, see <a href="https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Portal/6.2/html/Development_Guide/chap-Portal_Extension.html">Portal Extension</a> page of
Red Hat JBoss Portal Developer Guide.</p>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/system-requirements.md.ftl ~-->
<h2><a id="system-requirements" class="anchor" href="#system-requirements"><span class="anchor-icon"></span></a>System Requirements</h2>
<p>All you need to build this example project is Java 6.0 (Java SDK 1.6) or newer and Maven 3.0 or newer.</p>
<p>The project is designed to be deployed on Red Hat JBoss Portal 6.2 running on JBoss EAP.</p>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/configure-maven.md.ftl ~-->
<h2><a id="configure-maven" class="anchor" href="#configure-maven"><span class="anchor-icon"></span></a>Configure Maven</h2>
<p>You have two options how you can configure Maven: A. Use hosted Maven repository or B. Download & setup zipped Maven repository.</p>
<h3><a id="a-use-hosted-maven-repository" class="anchor" href="#a-use-hosted-maven-repository"><span class="anchor-icon"></span></a>A. Use hosted Maven repository</h3>
<p>This is the easier and thus recommended option. You need to configure the Maven user settings as follows:</p>
<ul>
<li><p>Look for the <code>settings.xml</code> file in the <code>${user.home}/.m2/</code> directory. For example:</p>
<div class="highlight"><pre><span class="vg">For</span><span class="w"> </span><span class="vg">Linux</span><span class="w"> </span><span class="vg">or</span><span class="w"> </span><span class="nl">Mac:</span><span class="w"> </span><span class="o">~/.</span><span class="vg">m2</span><span class="o">/</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span>
<span class="vg">For</span><span class="w"> </span><span class="nl">Windows:</span><span class="w"> </span><span class="o">\</span><span class="vg">Users</span><span class="o">\</span><span class="vg">USER_NAME</span><span class="o">\.</span><span class="vg">m2</span><span class="o">\</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span><span class="w"> </span><span class="vg">or</span><span class="w"> </span><span class="o">\</span><span class="vg">Documents</span><span class="w"> </span><span class="vg">and</span><span class="w"> </span><span class="vg">Settings</span><span class="o">\</span><span class="vg">USER_NAME</span><span class="o">\.</span><span class="vg">m2</span><span class="o">\</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span>
</pre></div></li>
<li><p>If you have an existing <code>settings.xml</code> file, modify it with the configuration information from the <code>settings-hosted-repo.xml</code>
file located in the root folder of Red Hat JBoss Portal quickstarts. This effectivelly results in
adding <code>http://maven.repository.redhat.com/techpreview/all</code> as <code><repository></code> and <code><pluginRepository></code> to your <code>settings.xml</code>.</p></li>
<li><p>If there is no <code>settings.xml</code> file, copy the <code>settings-hosted-repo.xml</code> file to the <code>.m2</code> directory for your
operating system and rename it to <code>settings.xml</code>.</p></li>
</ul>
<h3><a id="b-download-amp-setup-zipped-maven-repositories" class="anchor" href="#b-download-amp-setup-zipped-maven-repositories"><span class="anchor-icon"></span></a>B. Download & setup zipped Maven repositories</h3>
<ol>
<li><p>Download the following zipped Maven repositories from <a href="https://access.redhat.com/">Red Hat Customer Portal</a>,
Downloads > JBoss Enterprise Middleware:</p>
<ul>
<li>Red Hat JBoss Portal 6.2.0 Maven Repository</li>
<li>Red Hat JBoss Portal 6.1.1 Maven Repository</li>
<li>JBoss Portal Platform 6.1.0 Maven Repository</li>
<li>JBoss Enterprise Portal Platform (EPP) 6.0.0 Maven Repository</li>
<li>Web Framework Kit 2.4.0 Maven Repository</li>
<li>Web Framework Kit 2.3.0 Maven Repository</li>
<li>Web Framework Kit 2.2.0 Maven Repository</li>
<li>Web Framework Kit 2.1.0 Maven Repository</li>
<li>Web Framework Kit 2.0.0 Maven Repository</li>
<li>Application Platform 6.4.0 Maven Repository</li>
<li>Application Platform 6.2.0 Maven Repository</li>
<li>Application Platform 6.1.0 Maven Repository</li>
<li>Application Platform 6.0.1 Maven Repository</li>
<li>Application Platform 6.0.0 Maven Repository</li>
</ul>
<p>Unpack each of these files to a separate directory.</p></li>
<li><p>Modify the <code>settings-zipped-repos.xml</code> file located in the root directory of Red Hat JBoss Portal
quickstarts:</p>
<ul>
<li>For each zipped repository unpacked in the previous step, replace <code>/path/to/repo/</code> within <code>file:///path/to/repo/...</code>
with the fully qualified path of the directory where you unpacked the given zipped Maven repository in the previous
step.</li>
<li>Note that path to each repository needs tobe set twice: one within <code><repository></code> tag and one within
<code><pluginRepository></code> tag.</li>
<li><p>Be sure to use 3 forward slashes after <code>file:</code>. Two slashes are there for the protocol and one for the fully qualified
path. For example:</p>
<div class="highlight"><pre><span class="nl">file:</span><span class="o">///</span><span class="vg">home</span><span class="o">/</span><span class="vg">joedoe</span><span class="o">/</span><span class="vg">Quickstarts</span><span class="o">/</span><span class="vg">jpp</span><span class="mf">-6.2</span><span class="o">-</span><span class="vg">quickstarts</span>
</pre></div></li>
</ul></li>
<li><p>Configure the Maven user settings.</p>
<ul>
<li><p>Look for the <code>settings.xml</code> file in the <code>${user.home}/.m2/</code> directory. For example:</p>
<div class="highlight"><pre><span class="vg">For</span><span class="w"> </span><span class="vg">Linux</span><span class="w"> </span><span class="vg">or</span><span class="w"> </span><span class="nl">Mac:</span><span class="w"> </span><span class="o">~/.</span><span class="vg">m2</span><span class="o">/</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span>
<span class="vg">For</span><span class="w"> </span><span class="nl">Windows:</span><span class="w"> </span><span class="o">\</span><span class="vg">Users</span><span class="o">\</span><span class="vg">USER_NAME</span><span class="o">\.</span><span class="vg">m2</span><span class="o">\</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span><span class="w"> </span><span class="vg">or</span><span class="w"> </span><span class="o">\</span><span class="vg">Documents</span><span class="w"> </span><span class="vg">and</span><span class="w"> </span><span class="vg">Settings</span><span class="o">\</span><span class="vg">USER_NAME</span><span class="o">\.</span><span class="vg">m2</span><span class="o">\</span><span class="vg">settings</span><span class="o">.</span><span class="vg">xml</span>
</pre></div></li>
<li><p>If you have an existing <code>settings.xml</code> file, modify it with the configuration information from the <code>example-settings.xml</code>
file.</p></li>
<li><p>If there is no <code>settings.xml</code> file, copy the modified <code>example-settings.xml</code> file to the <code>.m2</code> directory for your
operating system and rename it to <code>settings.xml</code>.</p></li>
</ul></li>
</ol>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/build-and-deploy-portal-container-or-extension.md.ftl ~-->
<h2><a id="build-and-deploy" class="anchor" href="#build-and-deploy"><span class="anchor-icon"></span></a>Build and Deploy</h2>
<p>Portal Extensions and Portal Containers are not hot-deployable. Therefore, it is not possible to deploy them using
<code>mvn jboss-as:deploy</code> or copying to the default JBoss EAP deployment folder when
Red Hat JBoss Portal is running. Instead of that you will need to:</p>
<ol>
<li><p>Make sure that the Portal is not running, e.g. by running </p>
<div class="highlight"><pre><span class="err">$</span><span class="vg">JBOSS_HOME</span><span class="o">/</span><span class="vg">bin</span><span class="o">/</span><span class="vg">jboss</span><span class="o">-</span><span class="vg">cli</span><span class="o">.</span><span class="vg">sh</span><span class="w"> </span><span class="o">--</span><span class="vg">connect</span><span class="w"> </span><span class="vg">controller</span><span class="o">=</span><span class="mf">127.0.0.1</span><span class="o">:</span><span class="il">9999</span><span class="w"> </span><span class="vg">command</span><span class="o">=:</span><span class="vg">shutdown</span>
</pre></div></li>
<li><p>Open a command line and navigate to the root directory of this quickstart.</p></li>
<li><p>Run the following command to build the archive:</p>
<div class="highlight"><pre><span class="vg">mvn</span><span class="w"> </span><span class="vg">clean</span><span class="w"> </span><span class="vg">package</span>
</pre></div>
<p>This will create <code>ear/target/portal-extension.ear</code>.</p></li>
<li><p>Copy this file into the Red Hat JBoss Portal extension deployment folder: <code>$JBOSS_HOME/gatein/extensions</code></p></li>
</ol>
<h2><a id="access-the-extension" class="anchor" href="#access-the-extension"><span class="anchor-icon"></span></a>Access the Extension</h2>
<p>To ensure that the Portal Extension has been deployed successfully, visit the the base URL of your Portal. Which is
<a href="http://127.0.0.1:8080/portal/">http://127.0.0.1:8080/portal</a> in the most common case.</p>
<p>You should see some differences compared to the original Portal.</p>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/start-the-portal.md.ftl ~-->
<h2><a id="start-the-portal" class="anchor" href="#start-the-portal"><span class="anchor-icon"></span></a>Start the Portal</h2>
<ol>
<li>Open a command line and navigate to the root of the JBoss server directory.</li>
<li><p>The following shows the command line to start the server with the web profile:</p>
<div class="highlight"><pre><span class="vg">For</span><span class="w"> </span><span class="nl">Linux:</span><span class="w"> </span><span class="vg">JBOSS_HOME</span><span class="o">/</span><span class="vg">bin</span><span class="o">/</span><span class="vg">standalone</span><span class="o">.</span><span class="vg">sh</span>
<span class="vg">For</span><span class="w"> </span><span class="nl">Windows:</span><span class="w"> </span><span class="vg">JBOSS_HOME</span><span class="o">\</span><span class="vg">bin</span><span class="o">\</span><span class="vg">standalone</span><span class="o">.</span><span class="vg">bat</span>
</pre></div></li>
</ol>
<h2><a id="undeploy-the-archive" class="anchor" href="#undeploy-the-archive"><span class="anchor-icon"></span></a>Undeploy the Archive</h2>
<p>To delete a Portal Extension or Portal Container:</p>
<ol>
<li>Delete <code>JBOSS_HOME/gatein/extensions/portal-extension.ear</code></li>
<li>Restart Red Hat JBoss Portal</li>
</ol>
<p>Please note that the content written to the database by the Extension or Portal Container (such as adding new pages) is not
reversible.</p>
<h2><a id="use-jboss-developer-studio-or-eclipse-to-run-this-quickstart" class="anchor" href="#use-jboss-developer-studio-or-eclipse-to-run-this-quickstart"><span class="anchor-icon"></span></a>Use JBoss Developer Studio or Eclipse to Run this Quickstart</h2>
<p>Portal Extensions and Portal Containers are not directly deployable from JBoss Developer Studio nor Eclipse at this time.
See Build and Deploy section above for an alternative. </p>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/debug.md.ftl ~-->
<h2><a id="debug-the-application" class="anchor" href="#debug-the-application"><span class="anchor-icon"></span></a>Debug the Application</h2>
<p>If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following
commands to pull them into your local repository. The IDE should then detect them.</p>
<div class="highlight"><pre><span class="vg">mvn</span><span class="w"> </span><span class="nl">dependency:</span><span class="vg">sources</span>
<span class="vg">mvn</span><span class="w"> </span><span class="nl">dependency:</span><span class="vg">resolve</span><span class="w"> </span><span class="o">-</span><span class="vg">Dclassifier</span><span class="o">=</span><span class="vg">javadoc</span>
</pre></div>
<!--~ Included from gatein-portal-quickstarts-parent/src/main/freemarker/include/feedback.md.ftl ~-->
<h2><a id="feedback" class="anchor" href="#feedback"><span class="anchor-icon"></span></a>Feedback</h2>
<p>Please post feedback on this quickstart or Red Hat JBoss Portal on <a href="https://access.redhat.com/discussions?title=&product=8&category=All&tags=All">Online User Group</a>.</p>
</body></html>