Title: Extend Apache Rave to build your own portal
Notice:    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.

One of the (main) goals of Apache Rave is to create an extendible platform. This document is to help Apache Rave users (developers) to customize Apache Rave based on needs.

To get you started we have created a Maven archetype that generates a Rave project. This project shows how to use a custom (Spring) component and to customize the look and feel.
Extension developers will be able to use the POM file provide and add additional project dependencies.

## Prerequisites

  - Java SE 6 or higher
  - Apache Maven 3+ (version 3.0.3 or later is *required*) [Download][3] and [install][4]

A Maven archetype will be available to generate a custom Rave project for the 0.19 release (January 2013) and future releases.
You can also build this archetype from the latest (snapshot) code. To do this, [check out Apache Rave from SVN][1] and build with "mvn clean install".

## Generate custom Rave project

In your console or terminal navigate to the folder where you store your projects. The archetype will create the folder of the project inside this folder. Then type:

    mvn archetype:generate -DarchetypeGroupId=org.apache.rave -DarchetypeArtifactId=rave-custom-project-archetype

Maven will try to download the `rave-custom-project-archetype`. Then asks you to define the custom project's groupId, artifactId etc. The default values are:

    groupId: org.example
    artifactId: myraveproject
    version: 1.01.00-SNAPSHOT
    package: org.example
    projectName: My Rave Project

### Run the project

If you use the defaults, the project is called `myraveproject` and its portal module `myraveproject-portal`

    cd myraveproject
    mvn install

    cd myraveproject-portal
    mvn cargo:run

You can now navigate to the portal on http://localhost:8080

## Custom project

The project will have the following structure:

![Project structure](/images/screenshot_custom_project.png)

### Customizations

  - User Service : implements Rave UserService interface as CustomUserService. To use CustomUserService for
  login a `customUserService` bean has been defined in the Application Security context provided in
  `./myraveportal-portal/src/main/webapp/WEB-INF/applicationContext-security.xml`.

  - [LDAP authentication][5] has been removed from the project by excluding its dependencies in
  the pom.xml file and removing the LDAP configuration in `./myraveportal-portal/src/main/webapp/WEB-INF/applicationContext-security.xml`.

  - Look and feel : This is to demonstrate that your own look and feel can be given to the portal by adding styles to
  `./myraveportal-portal/src/main/webapp/static/css/custom.css`

  - There is also a separate module to override the OpenSocial provider (Apache Shindig), but it builds the same configuration as the standard release.

### Best Practices

- Add new javascript functions to new file or copy existing functions to new file and customize them and change imports based on your need. Reason is, changes/fixes in rave libraries should come to your project.
- If you are are customizing css or adding new css methods add new files so that changes in default css files will come to your portal
- Report any bug or issue to [Apache Rave JIRA][2]

[1]: ../source.html
[2]: https://issues.apache.org/jira/browse/RAVE
[3]: http://maven.apache.org/download.html
[4]: http://maven.apache.org/download.html#Installation
[5]: ldap-authentication.html