Added more informations to manual
authorŁukasz Dywicki <ldywicki@apache.org>
Tue, 6 Sep 2011 09:59:50 +0000 (09:59 +0000)
committerŁukasz Dywicki <ldywicki@apache.org>
Tue, 6 Sep 2011 09:59:50 +0000 (09:59 +0000)
git-svn-id: https://svn.apache.org/repos/asf/karaf/sandbox/webconsole/trunk@1165582 13f79535-47bb-0310-9956-ffa450edef68

manual/src/main/webapp/WEB-INF/scalate/layouts/headers.jade
manual/src/main/webapp/css/style.css
manual/src/main/webapp/developers-guide/branding.conf [new file with mode: 0644]
manual/src/main/webapp/developers-guide/extending.conf [new file with mode: 0644]
manual/src/main/webapp/developers-guide/index.conf
manual/src/main/webapp/developers-guide/security.conf [new file with mode: 0644]

index f17cab5..9710148 100644 (file)
@@ -15,9 +15,9 @@ html(lang="en")
       = include("/org/fusesource/scalate/console/console_head.scaml")
       link(href={uri("/css/scalate/console.css")} rel="stylesheet" type="text/css")
 
+    link(href={uri("/css/reset.css")} rel="stylesheet" type="text/css")
     link(href={uri("/css/grid.css")} rel="stylesheet" type="text/css")
     link(href={uri("/css/style.css")} rel="stylesheet" type="text/css")
-    link(href={uri("/css/reset.css")} rel="stylesheet" type="text/css")
 
     link(href={uri("/css/sh/shCore.css")} rel="stylesheet" type="text/css")
     link(href={uri("/css/sh/shThemeDefault.css")} rel="stylesheet" type="text/css")
index 7b91e12..1cf6d19 100644 (file)
@@ -45,4 +45,20 @@ a:link, a:active, a:visited {
 
 pre {
     font-family: monospace;
+}
+
+h1, h2, h3 {
+    margin-top: 15px;
+}
+
+h1 {
+    font-size: 24px;
+}
+
+h2 {
+    font-size: 20px;
+}
+
+h3 {
+    font-size: 16px;
 }
\ No newline at end of file
diff --git a/manual/src/main/webapp/developers-guide/branding.conf b/manual/src/main/webapp/developers-guide/branding.conf
new file mode 100644 (file)
index 0000000..cda8a8c
--- /dev/null
@@ -0,0 +1,17 @@
+h1. Branding
+
+Every product requires sometimes more or less fancy look and feel. We try to provide working project which may be customized by vendors in many different ways - first of all by building extensions, but also by changing webconsole layout easily.
+
+h2. Brand provider
+
+Brand provider is an interface which is used by default in core and other modules. Every page which extends *org.apache.karaf.webconsole.core.BasePage* will use it. An instance of this interface is looked up in OSGi service registry. Brand provider is asked for header image and list of behaviors to add in every page. These behaviors may add own CSS and JavaScript files.
+
+You can use only one brand provider in webconsole, so if you will have multiple brand providers please use *service.ranking* when you register your OSGi service.
+
+h2. Shipping new translations
+
+New translations should be attached to modules as a fragments. That's easiest way to extend module classpath and add new resources.
+
+h2. Security customization
+
+TODO
\ No newline at end of file
diff --git a/manual/src/main/webapp/developers-guide/extending.conf b/manual/src/main/webapp/developers-guide/extending.conf
new file mode 100644 (file)
index 0000000..c8bc8c2
--- /dev/null
@@ -0,0 +1,51 @@
+h1. Extending Webconsole
+
+Webconsole extensions may be done by different ways. In this section we going to cover followin topic - new pages, new navigation elements and new widgets.
+
+h2. New pages
+
+Webconsole ships four different types of pages which should be used in different cases.
+* BasePage
+* SecuredPage
+* SinglePage
+* SidebarPage
+
+h3. BasePage
+
+BasePage is used to load shared resources and keep same look and feel on all webconsole pages. You should use this page for non-secured operations for example to build your own LoginPage and so on.
+
+h3. SecuredPage
+
+SecuredPage will be rendered to users which have 'admin' role assigned. Others will see error page. By default this page renders navigation bar and adds logout link.
+
+h3. SinglePage
+
+SinglePage is secured. If you have no additional navigation or your content requires full screen width then use this page. You will have all screen to display data.
+
+h3. SidebarPage
+
+SidebarPage is secured. If you have additional navigation then Sidebar is what you need. In your extension you have to call *setSidebarProvider* method othervise your sidebar won't be displayed.
+
+h2. New navigation elements
+
+When you implement own modules you honestly want to add new tab or new link somewhere to let user navigate directly to your logic without address bar usage.
+
+To do this we shipped a *ConsoleTabProvider* interface. Just register an implementation of it under OSGi as a service and when webconsole will be ready to serve content it will ask your service for module home link and sub items.
+
+h2. Widgets
+
+Every management tool requires widgets. ;) We know about this and we provided also a *WidgetProvider* interface. It works in same way as a ConsoleTabProvider but it doesn't return links - it returns panels. Please remember following rule - because widgets may be used in different places you need to directly specify your widget provider 'intention'. Webconsole uses 'intention' service property to group providers. Please take a look for example below:
+{code:xml}
+<?xml version="1.0" encoding="utf-8" ?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+    <service ref="widgetProvider" interface="org.apache.karaf.webconsole.core.widget.WidgetProvider">
+        <service-properties>
+            <entry key="intention" value="dashboard" />
+        </service-properties>
+    </service>
+
+    <bean id="widgetProvider" class="com.example.extension.MyWidgetProvider" />
+</blueprint>
+{code}
+
+Widgets created by MyWidgetProvider will be used in dashboard.
\ No newline at end of file
index 8b6d000..b9c70a7 100644 (file)
@@ -2,5 +2,8 @@ h1. Developer guide
 
 This part of manual contains informations for extensions developers.
 
+ * [Extending webconsole|extending]
+ * [Security|security]
  * [Displaying tables|tables]
- * [Serialization|serialization]
\ No newline at end of file
+ * [Serialization|serialization]
+ * [Branding|branding]
\ No newline at end of file
diff --git a/manual/src/main/webapp/developers-guide/security.conf b/manual/src/main/webapp/developers-guide/security.conf
new file mode 100644 (file)
index 0000000..1edf4c7
--- /dev/null
@@ -0,0 +1,22 @@
+h1. Security
+
+Every management application requires authentication and authorization. In our case both are controlled by Wicket. But from technology point of view there is also second element which provides information about users and roles - JAAS.
+
+By default Webconsole uses JAAS to authenticate users and grant them roles.
+
+h2. JAAS Configuration
+
+Realm used by webconsole is named "karaf". If you would like to change realm name please check the [branding] page. This realm may be configured in different ways, depending on environment you run. If you run webconsole on Karaf this realm is default. How to add new users and grant them new roles then? Using *$KARAF_HOME/etc/users.properties* file. Let check what do we have by default in this file:
+
+{code}
+karaf=karaf
+{code}
+
+We have user named 'karaf' with password 'karaf' and no roles assigned. Because we do require roles we need to modify this file a bit:
+
+{code}
+karaf=karaf,admin
+{code}
+
+After password we can pass list of roles separated by commas assigned to account.
+