------
 Introduction
 ------
 Hervé Boutemy, Simone "Simo" Tripodi
 ------
 2012-06-28
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Welcome to ${project.name}!

 The Apache Maven Fluido Skin is an Apache Maven site skin built on top of
 {{{http://twitter.github.com/bootstrap/}Twitter's bootstrap}}.

 A {{{./sample.html}sample page}} is provided to see the skin in action, and 2 complete sites to show skin
 configurations: one for {{{./sidebar/}sidebar layout (default)}} and the other for {{{./topbar/}topbar layout}}.

* Usage

 To use this skin in your project, use the skin element of
 {{{/doxia/doxia-sitetools/doxia-decoration-model/decoration.html}the <<<site.xml>>> site descriptor}}:

+-----+
<project name="xxx">
  [...]
  <skin>
    <groupId>${project.groupId}</groupId>
    <artifactId>${project.artifactId}</artifactId>
    <version>${project.version}</version>
  </skin>
  [...]
</project>
+-----+

** TopBar and/or sideBar

 The skin supports different layouts, enabling/disabling the left sidebar menu and the topbar menu.
 Users have just play with flags in the <<<custom.fluidoSkin>>> element in <<<site.xml>>>:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <topBarEnabled>true</topBarEnabled>
      <sideBarEnabled>false</sideBarEnabled>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 That allows users having 4 skins in only 1!

  [[1]] sidebar only;

  [[2]] topbar only;

  [[3]] both side/top bars;

  [[4]] none at all.

  []

 Default skin setting is the option <<1>>.

** TopBarIcon

 When users decide to enable the topbar, they can plug a small icon/logo there (typically 108*20 px) just configuring
 the <<<custom.fluidoSkin.topBarIcon>>> element in <<<site.xml>>>:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <topBarEnabled>true</topBarEnabled>
      <topBarIcon>
        <name>Maven Fluido Skin</name>
        <alt>Maven Fluido Skin</alt>
        <src>/images/topbar-logo.png</src>
        <href>/index.html</href>
      </topBarIcon>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** TopBarContainerStyle

  You can configure the style attribute value of the div container for your topbar

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <topBarEnabled>true</topBarEnabled>
      <topBarContainerStyle>width: 90%;</topBarContainerStyle>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** NavBarStyle

  You can configure style of your top bar nav (since bootstrap 2.1.0 is not anymore black by default).
  Use navbar-inverse to have the black one.

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <topBarEnabled>true</topBarEnabled>
      <navBarStyle>navbar-inverse</navBarStyle>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** Configuring column class

  When using sidebar, the left column used by default span3 class and body column use span9.
  To prevent weird/ugly result, the sum must be 12.
  You can change that using:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <leftColumnClass>span2</leftColumnClass>
      <bodyColumnClass>span10</bodyColumnClass>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** GoogleSearch

 Users can optionally enable the <<Google Search>> for the generated site, requirements are:

 * the <<<project.url>>> property in <<<pom.xml>>>, unless the <<<custom.fluidoSkin.googleSearch.sitesearch>>> property is set in the <<<site.xml>>>:

+-----+
<project name="xxx">
  [...]
  <url>http://maven.apache.org/skins/${project.artifactId}</url>
  [...]
</project>
+-----+

 * the <<<custom.fluidoSkin.googleSearch>>> element in <<<site.xml>>>:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <googleSearch>
        <sitesearch/>
      </googleSearch>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 []

 By default, the search form:

 * is <not> enabled; adding <<<custom.fluidoSkin.googleSearch>>> is enough to enable the searchbox.

 * is rendered in the sidebar, if the topbar only is available it will be rendered there.

 []

 External links are either rendered in the sidebar or the topbar. When both sidebar and topbar are enabled,
 they are rendered as dropdown in the topbar only.

** SourceLineNumbers

 Source code sections are enhanced by {{{http://code.google.com/p/google-code-prettify/}Google Code Prettify}}, users can
 optionally enable line numbers rendering (disabled by default):

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** Footers placeholders

 Since <<<#eval>>> Velocity macro is not supported yet, the only placeholder
 available in additional footers is <<<@project.name@>>>.

** GitHub ribbons

 Since version <<1.1>>, fluido-skin supports {{{https://github.com/blog/273-github-ribbons}GitHub ribbons}} to simplify
 the <Fork me on GitHub> banner integration. Users must define:

 * <<<custom.fluidoSkin.gitHub.projectId>>>: <<required>>, it is the project id on GitHub and will be used to build the project page URL;

 * <<<custom.fluidoSkin.gitHub.ribbonOrientation>>>: <<optional>>, it is the the ribbon position, <<<left>>>/<<<right>>> only accepted (<<<left>>> by default);

 * <<<custom.fluidoSkin.gitHub.ribbonColor>>>: <<optional>>, it is the the ribbon color, <<<red>>>/<<<green>>>/<<<black>>>/<<darkblue>>/<<<orange>>>/<<<gray>>> only accepted only accepted (<<<red>>> by default).

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <gitHub>
        <projectId>99soft/backport-spi</projectId>
        <ribbonOrientation>right</ribbonOrientation>
        <ribbonColor>black</ribbonColor>
      </gitHub>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** Project profile

 As shown in the MOJOs {{{http://mojo.codehaus.org/plugins.html}list}}, plugins life-cycle are characterized by
 different status/stages:

 * Production

 * Pre-release

 * Sandbox

 * Graveyard (retired projects)

 Users can configure different backgrounds depending on the project status (except the production) to warrant users they
 are not using a production ready software:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <profile>(pre-release|sandbox|retired)</profile>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

** Twitter follow button

 Since version <<1.1>>, fluido-skin supports the Twitter {{{https://dev.twitter.com/docs/follow-button}follow button}}
 to simplify its integration. Users must define:

 * <<<custom.fluidoSkin.twitter.user>>>: <<required>>, it is the Twitter id to suggest to follow;

 * <<<custom.fluidoSkin.twitter.showUser>>>: <<optional>>, flag to mark the user has to be shown (<<<false>>> by default);

 * <<<custom.fluidoSkin.twitter.showFollowers>>>: <<optional>>, flag to mark the followers ribbon has to be shown (<<<false>>> by default).

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <twitter>
        <user>simonetripodi</user>
        <showUser>true</showUser>
        <showFollowers>true</showFollowers>
      </twitter>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 By default, it is rendered in the sidebar, if the topbar only is available it will be rendered there.

** Ohloh widgets

 Since version <<1.1>>, fluido-skin supports the Ohloh {{{https://www.ohloh.net/p/maven2/widgets}widgets}}
 to simplify its integration. Users must define:

 * <<<custom.fluidoSkin.ohloh.projectId>>>: <<required>>, it is the project identifier in Ohloh (could be the numeric id or the project name);

 * <<<custom.fluidoSkin.ohloh.widget>>>: <<optional>>, it is the kind of widget has to be rendered, admitted values are:

   * <<<users-logo>>> (default)

   * <<<users-green>>>

   * <<<users-red>>>

   * <<<users-blue>>>

   * <<<users-gray>>>

   * <<<users-rainbow>>>

   * <<<users>>>

   * <<<thin-badge>>>

   * <<<partner-badge>>>

   * <<<languages>>>

   * <<<factoids>>>

   * <<<cocomo>>>

   * <<<stats>>>


+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <ohloh>
        <projectId>3499</projectId>
        <widget>factoids</widget>
      </ohloh>
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 Ohloh widgets will be rendered always in the footer as last element

** Facebook like button

 Since version <<1.2>>, fluido-skin supports the Facebook {{{http://developers.facebook.com/docs/reference/plugins/like/}like}}
 integration. Users have just to declare:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <facebookLike />
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 By default, it is rendered in the sidebar, if the topbar only is available it will be rendered there.

 <<Note>> in order the Facebook like button appears, <<<$\{project.url\}>>> property <<must>> be set in the <<<pom.xml>>>!

** Google plusone button

 Since version <<1.2>>, fluido-skin supports the Google {{{https://developers.google.com/+/plugins/+1button/}plusone}}
 integration. Users have just to declare:

+-----+
<project name="xxx">
  [...]
  <custom>
    <fluidoSkin>
      <googlePlusOne />
    </fluidoSkin>
  </custom>
  [...]
</project>
+-----+

 By default, it is rendered in the sidebar, if the topbar only is available it will be rendered there.

 <<Note>> in order the Google plusone button appears, <<<$\{project.url\}>>> property <<must>> be set in the <<<pom.xml>>>!

Acknowledgment

  ${project.name} contains/redistributes {{{http://glyphicons.com}Glyphicons Halflings}} as part of Bootstrap by Twitter,
  released under {{{http://creativecommons.org/licenses/by/3.0/deed.en}Creative Commons Attribution 3.0 Unported (CC BY 3.0)}}.