You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/23 21:54:18 UTC
[4/4] git commit: [KARAF-2511] Review and update the branding page of
the developers guide
[KARAF-2511] Review and update the branding page of the developers guide
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo
Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/40810dee
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/40810dee
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/40810dee
Branch: refs/heads/master
Commit: 40810dee0541d4cc1030189d8a1bee97928001ec
Parents: 9a0d8d0
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 21:53:09 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 21:53:09 2013 +0100
----------------------------------------------------------------------
.../main/webapp/developers-guide/branding.conf | 136 +++++++++++++++----
1 file changed, 109 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/40810dee/manual/src/main/webapp/developers-guide/branding.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/branding.conf b/manual/src/main/webapp/developers-guide/branding.conf
index bb7e065..2ce1a53 100644
--- a/manual/src/main/webapp/developers-guide/branding.conf
+++ b/manual/src/main/webapp/developers-guide/branding.conf
@@ -1,20 +1,25 @@
+h1. Branding
+h2. Console
-h1. Branding the Console
+You can "brand" the Apache Karaf console.
-This chapter will show you how to customize the user interface of the Karaf console, making changes such as a new
-welcome message and console prompt. This is what we refer to as "branding" Karaf.
+By branding, it means that you can define your own:
-By branding, it means that you can define your own welcome message and console prompt.
+* the welcome message (motd or Message Of The Day) displayed when you start the console
+* the prompt displayed to the users
-h2. Create your branding bundle
+h2. Branding bundle
-At startup, Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package containing a
-{{branding.properties}} file.
+At startup, Apache Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package, containing
+a {{branding.properties}} file.
-So you need to create a very simply bundle containing just a {{org/apache/karaf/branding/branding.properties}} file.
+Basically, a branding bundle is a very simple bundle, just containing a {{org/apache/karaf/branding/branding.properties}}
+file.
-The Maven POM of your branding bundle should look like this:
+It's easy to create such branding bundle using Apache Maven.
+
+The following {{pom.xml}} creates a branding bundle:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
@@ -33,7 +38,7 @@ The Maven POM of your branding bundle should look like this:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
- <version>2.2</version>
+ <version>2.4.0</version>
<extensions>true</extensions>
<configuration>
<instructions>
@@ -53,9 +58,16 @@ The Maven POM of your branding bundle should look like this:
</project>
{code}
-Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} similar to:
+You can put your {{branding.properties}} file in the project resources ({{src/main/resources/org/apache/karaf/branding/branding.properties}}):
+
+{code}
+welcome = This is my Karaf brand\r\n
+prompt = Hey ${USER}>
+{code}
-{{code}}
+For instance, the default Apache Karaf branding properties file contains:
+
+{code}
welcome = \
\u001B[36m __ __ ____ \u001B[0m\r\n\
\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
@@ -67,13 +79,11 @@ welcome = \
\r\n\
Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
-Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1msystem:shutdown\u001B[0m' to shutdown Karaf.\r\n
-
-prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
-{{code}}
+Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n
+{code}
As you can see, the {{branding.properties}} contains two properties:
-* welcome is the welcome message displayed when you start Karaf.
+* welcome is the welcome message displayed when you start Apache Karaf console.
* prompt is the string used to display the console prompt. This string supports variables:
** ${USER}} defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf",
however you can override here with your own static user name.
@@ -94,22 +104,94 @@ prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICAT
prompt = my-user@my-karaf>
{code}
-h2. Configuring Karaf to use the branding bundle
+h2. Installing the branding bundle
-In order for Karaf to pick up the branding jar please edit the
-$KARAF_HOME/etc/custom.properties file to include the following:
+Thanks to the {{pom.xml}}, we can use {{mvn}} to build the branding bundle:
+{code}
+mvn install
+{code}
- org.osgi.framework.system.packages.extra = \
- org.apache.karaf.branding
+You just have to drop the file in the {{lib}} directory:
-h2. Installing the branding bundle
+{code}
+cp branding.jar /opt/apache-karaf-3.0.0/lib/karaf-branding.jar
+{code}
+
+You can now start Apache Karaf to see your branded console.
+
+h2. WebConsole
-Build your branding bundle:
+It's also possible to brand the Apache Karaf WebConsole.
+
+You have to create a bundle, fragment of the Apache Karaf WebConsole.
+
+This WebConsole branding bundle contains a {{META-INF/webconsole.properties}} containing branding properties:
{code}
-mvn install
+#
+# This file contains branding properties to overwrite the default
+# branding of the Apache Felix Web Console when deployed in an
+# Apache Karaf application.
+
+
+webconsole.brand.name = My Web Console
+
+webconsole.product.name = My Karaf
+webconsole.product.url = http://karaf.apache.org/
+webconsole.product.image = /res/karaf/imgs/logo.png
+
+webconsole.vendor.name = The Apache Software Foundation
+webconsole.vendor.url = http://www.apache.org
+webconsole.vendor.image = /res/karaf/imgs/logo.png
+
+webconsole.favicon = /res/karaf/imgs/favicon.ico
+webconsole.stylesheet = /res/karaf/ui/webconsole.css
+
{code}
-and simply drop the generated jar file into the Karaf lib directory.
+The bundle also provides the css stylesheet and images defined in this properties file.
+
+As for console, you can use the following {{pom.xml}} to create the WebConsole branding bundle:
+
+{code}
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>my.group.id</groupId>
+ <artifactId>branding</artifactId>
+ <packaging>bundle</packaging>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>2.4.0</version>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL>
+ <Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host>
+ <Export-Package>!*</Export-Package>
+ <Import-Package>
+ javax.servlet;version=2.4,
+ javax.servlet.http;version=2.4,
+ !org.apache.felix.webconsole*,
+ org.apache.aries.blueprint,
+ org.osgi.service.blueprint.container,
+ org.osgi.service.blueprint.reflect,
+ *
+ </Import-Package>
+ </instructions>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
+{code}
-Start Karaf and you will see your branded Karaf console.
+With the {{webconsole}} feature installed, you can install this bundle (using {{bundle:install}} or by editing the
+{{etc/startup.properties}}), you will see the WebConsole with your branding.
\ No newline at end of file