Commit f623dfee authored by mindthegab's avatar mindthegab
Browse files

-- fixed site staging for SDK pom (now running 'mvn clean site site:stage' to... 

-- fixed site staging for SDK pom (now running 'mvn clean site site:stage' to preview multimodule actually *works*)
-- Added full plugin documentation
-- Fixed layout issues on fluido-skin
-- added main index.html for the aggregator

git-svn-id: http://maven-alfresco-archetypes.googlecode.com/svn/trunk@631 04253f4f-3451-0410-a141-5562f1e59037
parent 11ff4a29

plugins/alfresco-maven-plugin/src/site/apt/advanced-usage.apt.vm

0 → 100644
+166 −0
Original line number Diff line number Diff line 
  ------

  Advanced Usage

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------



Managing AMP packaging projects



  See {{{./usage.html} Usage page}} for the different approaches to AMP projects development with the Alfresco Maven Plugin. 

  

Overlay and installation of AMPs to WAR  

 

  There are two ways you can install AMP artifacts (either GA or produced by your builds) on your Maven WAR projects:

  

  [[1]] By using standard {{{http://maven.apache.org/plugins/maven-war-plugin/overlays.html} Maven War Plugin Overlays}}

  

  [[2]] Manually invoking the <<<alfresco:install>>> goal in your POM

 

* Method 1 - AMP to WAR Overlay



  This method allows you specify artifacts of type <<<amp>>> as <<<dependencies>>> of your WAR project and have them

  automatically installed in the current WAR project. Note that AMP can be installed either on Alfresco or Share.

  

  Follows an example which installs the Web Quick Start Repository AMP as overlay an <<<alfresco.war>>> extension project: 

  

+---+

<project>

    <artifactId>my-alfresco-customization</artifactId>

    <name>Alfresco Repository and Explorer Client Extension</name>

    <packaging>war</packaging>

    

    ...



    <dependencies>

        <dependency>

            <groupId>\${alfresco.groupId}</groupId>

            <artifactId>alfresco</artifactId>

            <type>war</type>

        </dependency>

        <!-- Add the depdendency on a well known GA AMP (Web Quick Start Repository component) -->

        <dependency>

            <groupId>\${alfresco.groupId}</groupId>

            <artifactId>alfresco-wcm-quickstart-repo</artifactId>

            <version>\${alfresco.version}</version>

            <type>amp</type>

        </dependency>

    </dependencies>



    <build>

        <plugins>

            <plugin>

                <artifactId>maven-war-plugin</artifactId>

                <configuration>

                    <!--  Here is can control the order of overlay of your (WAR, AMP, etc.) dependencies

                        | NOTE: At least one WAR dependency must be uncompressed first

                        | NOTE: In order to have a dependency effectively added to the WAR you need to 

                        | explicitly mention it in the overlay section.

                        | NOTE: First-win resource strategy is used by the WAR plugin

                         -->

                    <overlays>

                        <!-- Current project customizations -->

                        <overlay/>

                        <!-- The Alfresco WAR -->

                        <overlay>

                            <groupId>\${alfresco.groupId}</groupId>

                            <artifactId>alfresco</artifactId>

                            <type>war</type>

                            <!-- To allow inclusion of META-INF, needed for MMT WAR file validation-->

                            <excludes/>

                        </overlay>

                        <!-- Add / order your AMPs here -->

                        <overlay>

                            <groupId>\${alfresco.groupId}</groupId>

                            <artifactId>alfresco-wcm-quickstart-repo</artifactId>

                            <type>amp</type>

                        </overlay>

                    </overlays>

                </configuration>

            </plugin>

        </plugins>

    </build>

</project>

+---+



 <<NOTE:>> the <<<overlay>>> mechanism allow to also control include/excludes for each module as well as the order of overlay. 

 By default the Maven WAR plugin uses a <first-win> resource writing strategy.



 The resulting WAR will have all the AMPs present in both <<<<dependency>>>> and <<<<overlay>>>> section installed.

  

* Method 2 - Custom invocation of install goal



   The {{{./install-mojo.html}alfresco:install}} goal can be used to install AMPs directly, without using maven-war-plugin <<<<overlays>>>. 

   

   This goal allows to install a single AMP or a folder containing AMPs onto an Alfresco / Share WAR (or exploded WAR).



** Multiple AMP installation

    

   The plugin is thoroughly documented in the {{{./install-mojo.html} mojo page}}, but we provide here an example of how to mimic the 

   <<<apply_amps.sh>>> (Alfresco script), using the Alfresco Maven Plugin to install a full folder of AMPs (<<NOTE:>> The install goal

   is bound in this case to the <<<package>>> phase, it's up to you to make sure an exploded WAR or WAR is present in warLocation

   during that phase): 

      

+---+

<project>

  [...]

  <build>

    <plugins>

      ...

      <plugin>

          <groupId>org.alfresco.maven.plugin</groupId>

          <artifactId>alfresco-maven-plugin</artifactId>

          <version>${project.version}</version>

          <extensions>true</extensions>

          <execution>

            <id>install-amps</id>

            <goals>

                <goal>install</goal>

            </goals>

            <phase>package</phase>

          </execution>

          <configuration>

            <ampLocation>/my/folder/containing/amps</ampLocation>

          </configuration>

        </plugin>

        ...

    </plugins>

  </build>

  [...]

</project>

+---+



** Single AMP installation (with custom WAR location)



 This example shows how to install instead a single amp onto a WAR file in a custom location (<<NOTE:>> <<<warLocation>>> could be an exploded WAR folder): 

      

+---+

<project>

  [...]

  <build>

    <plugins>

      ...

      <plugin>

          <groupId>org.alfresco.maven.plugin</groupId>

          <artifactId>alfresco-maven-plugin</artifactId>

          <version>${project.version}</version>

          <extensions>true</extensions>

          <execution>

            <id>install-amps</id>

            <goals>

                <goal>install</goal>

            </goals>

            <phase>package</phase>

          </execution>

          <configuration>

            <ampLocation>/my/custom/folder/containing/only/one/ampFile.amp</ampLocation>

            <warLocation>/my/internal/or/external/alfresco/alfresco.war</warLocation>

          </configuration>

        </plugin>

        ...

    </plugins>

  </build>

  [...]

</project>

+---+
 
 No newline at end of file

plugins/alfresco-maven-plugin/src/site/apt/index.apt.vm

0 → 100644
+31 −0
Original line number Diff line number Diff line 
  ------

  Introduction

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------



Alfresco Maven Plugin - Part of the Maven Alfresco SDK\x99



  The Alfresco Maven Plugin provides development features to manage {{{http://www.alfresco.com}Alfresco ECM}} WAR and {{{https://wiki.alfresco.com/wiki/AMP_Files}AMP}} project lifecycles.



* Goals Overview



  The Alfresco Maven plugin has three goals:



  *{{{./amp-mojo.html}alfresco:amp}} Packages an AMP file



  *{{{./install-mojo.html}alfresco:install}} Installs one or multiple AMPs into an Alfresco WAR / exploded WAR folder

  

  *{{{./version-mojo.html}alfresco:version}} Parses ${project.version} removing literals (for AMP compatibility) and making the ${noSnapshot} property available in the POM  



* Usage



  General instructions on how to use the Alfresco Maven Plugin can be found on the {{{./usage.html}usage page}}.

  

  The Alfresco Maven Plugin provides support for <<<amp>>> packaging in your Maven projects and allows you to

  build AMPs as well as used them as standard Maven dependencies. You can also use AMPs as part of the standard

  {{{http://maven.apache.org/plugins/maven-war-plugin/overlays.html}maven-war-plugin}} <<< <overlays> >>> configuration.

  

  For more complex usage of the Alfresco Maven Plugin check the {{{./advanced-usage.html}advanced usage page}}.  
 No newline at end of file

plugins/alfresco-maven-plugin/src/site/apt/plexus-components.apt.vm

0 → 100644
+45 −0
Original line number Diff line number Diff line 
    -----

    Alfresco Maven Plugin Components

    -----

    The Alfresco Maven Plugin defines support components to manage AMP (Alfresco Module Package) lifecycle.

    

    AMP Lifecycle

    

    This plugin provides support for <<<<packaging>amp</packaging>>>> type of projects. \

    

    The lifecycle of an <<<amp>>> follows:



+---+

    <component>

      <role>org.apache.maven.lifecycle.mapping.LifecycleMapping</role>

      <role-hint>amp</role-hint>

      <implementation>org.apache.maven.lifecycle.mapping.DefaultLifecycleMapping</implementation>

      <configuration>

        <phases>

          <initialize>org.alfresco.maven.plugin:alfresco-maven-plugin:set-version</initialize>

          <process-resources>org.apache.maven.plugins:maven-resources-plugin:resources</process-resources>

          <compile>org.apache.maven.plugins:maven-compiler-plugin:compile</compile>

          <process-test-resources>org.apache.maven.plugins:maven-resources-plugin:testResources</process-test-resources>

          <test-compile>org.apache.maven.plugins:maven-compiler-plugin:testCompile</test-compile>

          <test>org.apache.maven.plugins:maven-surefire-plugin:test</test>

          <package>org.alfresco.maven.plugin:alfresco-maven-plugin:amp</package>

          <install>org.apache.maven.plugins:maven-install-plugin:install</install>

          <deploy>org.apache.maven.plugins:maven-deploy-plugin:deploy</deploy>

        </phases>

      </configuration>

    </component> 

+---+

    

    This build produces an Alfresco compatible AMP as main build product. 

    

    AMP -> WAR Unarchiver

    

    A Plexus UnArchiver (<<<role-hint="amp">>>) is configured to be used by default by Maven for AMP dependencies.

    This UnArchiver invokes the MMT therefore allowing proper AMP installation according to {{{http://wiki.alfresco.com/wiki/AMP_Files} convention}} .

    This component allows any plugin to manage <<<amp>>> dependencies and in particular enables AMPs to be used as part 

    of the standard maven-war-plugin <<<<overlay>>>> section.

    

    AMP Artifact Handler

    

    Instructs maven which type of Archive is the AMP, providing info about its inclusion in the classpath or the fact that already contains

    its dependencies.

plugins/alfresco-maven-plugin/src/site/apt/usage.apt.vm

+92 −29
Original line number Diff line number Diff line 
-----

Maven AMP Plugin Plexus Components

-----

  ------

  Usage

  ------

  Gabriele Columbro

  ------

  Nov 2012

  ------



How to use this plugin?



  There are fundamentally 3 methods to use this plugin:

  

AMP Lifecycle Mapping

  [[1]] Using Archetypes provided in the Maven Alfresco SDK

    

This plugin provides support for <packaging>amp</packaging> type of projects. \

Lifecycle of an Alfresco modules is mapped in the file:

  [[2]] By using the Alfresco SDK Parent POM

  

{{	${site_tags_url}/${site_pom_artifactId}-${site_pom_version}/src/main/resources/META-INF/plexus/components.xml }}

  [[3]] Via direct configuration in your POM

  

This build produces an Alfresco compatible AMP as main build product. It supports (being derived from maven-war-plugin)

overlay of modules and transitive AMP dependency packing.

* Method 1 - Using Maven Alfresco SDK Archetypes



An AMP depending on one ore more AMP will package those AMP in the final product of the build:

overlays can be configured same as in {{ http://maven.apache.org/plugins/maven-war-plugin/overlays.html }}.

A plain zip UnArchiver is used for this overlay.

  Two sample archetypes already use the plugin and provide best practice example on how to use it:

  

  [[1]] The {{{../../archetypes/alfresco-amp-archetype/index.html} Alfresco AMP Archetype}} provides a sample of AMP packaging

  

  [[2]] The {{{../../archetypes/alfresco-allinone-archetype/index.html} Alfresco All-in-One Archetype}} provides a sample using AMPs as dependencies and WAR overlay

  

AMP -> WAR Unarchiver

  

The default UnArchiver (role-hint="amp") used by the default maven infrastructure for .amp files is a custom UnArchiver

which behaves as the MMT, unarchiving AMPs in the proper places as dictated by {{{http://wiki.alfresco.com/wiki/AMP_Files} Alfresco AMP convention}} .

This little component allows any plugin to manage .amp dependencies in case the maven-amp-plugin is declared with <extensions>true</extensions> in

the current POM, basically supporting AMPs in Maven with no need for custom external tools like MMT.

 This is the <<recommended>> and less error-prone way of using the plugin.

 

See  {{	${site_tags_url}/${site_pom_artifactId}-${site_pom_version}/src/main/resources/META-INF/plexus/components.xml }}

* Method 2 - Using Maven Alfresco SDK Parent POM



  The {{{../../poms/alfresco-sdk-parent/index.html}Maven Alfresco SDK Parent POM}} provides a single entry point for all SDK features.

  

AMP Artifact Handler

  By using it as parent as follows:

  

Instructs maven which type of Archive is the AMP, providing info about its inclusion in the classpath or the fact that already contains

its dependencies.
 
+---+

<project>

     ...

     <parent>

        <groupId>org.alfresco.maven</groupId>

        <artifactId>alfresco-sdk-parent</artifactId>

        <version>1.0</version>

    </parent>

    ...

</project>

+---+



  you will have automatic support for AMP packaging of your project (just add you sources in <<<src/main/amp>>>).

  

* Method 3 - Direct configuration in POM



   If you want more control over the plugin behavior you can use it directly in your POM.

   

   <<NOTE>>: The following configuration is not required when using the SDK parent, as it's already included there.  

   

   In order to manage AMP artifacts with the Alfresco Maven plugin you need to:

   

   * Declare the plugin in your POM with <<<<extensions>>>> enabled, to allow AMP packaging lifecycle:

      

+---+

<project>

  [...]

  <build>

    <plugins>

      ...

      <plugin>

          <groupId>org.alfresco.maven.plugin</groupId>

          <artifactId>alfresco-maven-plugin</artifactId>

          <version>${project.version}</version>

          <extensions>true</extensions>

        </plugin>

        ...

    </plugins>

  </build>

  [...]

</project>

+---+



  * If you want to package an Alfresco Module Package from your <<<amp>>> packaging project you also need to make sure

  your AMP content gets copied to <<<\${project.build.directory}/\${project.build.finalName}>>> so the plugin can pick them up.

  Supposing your AMP sources are in <<<src/main/amp>>> you should configure the following <<<<resource>>>> block:

  

+---+

<project>

  [...]

  <build>

    <resources>

        ...

        <resource>

            <directory>src/main/amp</directory>

            <!-- This is relative to \${project.build.outputDirectory} -->

            <targetPath>../\${project.build.finalName}</targetPath>

            <filtering>${app.filtering.enabled}</filtering>

        </resource>

    </resources>

  </build>

  [...]

</project>

+---+ 
 No newline at end of file

plugins/alfresco-maven-plugin/src/site/site.xml

+32 −53
Original line number Diff line number Diff line 
<project>

  <skin>

    <groupId>org.apache.maven.skins</groupId>

    <artifactId>maven-fluido-skin</artifactId>

    <version>1.2.1</version>

  </skin>

  <custom>

    <fluidoSkin>

      <topBarEnabled>true</topBarEnabled>

      <sideBarEnabled>true</sideBarEnabled>

      <topBarIcon>

        <name>Maven Alfresco Lifecycle</name>

        <alt>Maven Alfresco Lifecycle</alt>

        <src>/img/Alfresco-logo-transparent.gif</src>

        <href>/index.html</href>

      </topBarIcon>

      <twitter>

        <user>mindthegabz</user>

        <showUser>true</showUser>

        <showFollowers>true</showFollowers>

      </twitter>

      <facebookLike />

      <googlePlusOne />

    </fluidoSkin>

  </custom>

  <poweredBy>

    <logo name="Maven" href="http://maven.apache.org" img="http://maven.apache.org/images/logos/maven-feather.png"/>

    <logo name="Alfresco - Open source ECM" img="http://alfresco.com/assets/images/icons/powered_by_alfresco.gif" href="http://www.alfresco.com" />

  </poweredBy>

  <publishDate position="navigation-bottom" format="MM-dd-yy"/>

  <bannerLeft>

    <name>Alfresco Maven Plugin - v. ${project.version}</name>

    <href>${site_site_url}</href>

  </bannerLeft>

  <body>

    <links>

      <item name="Maven" href="http://maven.apache.org/"/>

      <item name="Apache" href="http://www.apache.org/"/>

    </links>

        <menu ref="parent" inherit="bottom"/>

        

        <menu name="Plugin info">

            <item name="Goals" href="plugin-info.html"/>

            <item name="Usage" href="usage.html"/>

      <item name="Advanced Usage" href="components.html"/>

            <item name="Advanced Usage" href="advanced-usage.html"/>

            <item name="Plexus Components" href="plexus-components.html"/>

        </menu>

        

    <menu name="Used by">

        <menu name="Archetypes using this plugin">

          <!-- @TODO update href -->

      <item name="Maven Alfresco AMP Archetype" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-lifecycle/maven-alfresco-archetypes/maven-alfresco-amp-archetype/index.html"/>

      <item name="Maven Alfresco All In One Archetype" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-lifecycle/maven-alfresco-archetypes/maven-alfresco-amp-archetype/index.html"/>

          <item name="Maven Alfresco AMP Archetype" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest/archetypes/alfresco-amp-archetype/index.html"/>

          <item name="Maven Alfresco All In One Archetype" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest/archetypes/alfresco-allinone-archetype/index.html"/>

        </menu>

        

    <!--<menu name="See also">-->

    <!--</menu>-->

        <menu name="SDK Resources">

            <item name="FAQ" href="faq.html" />

            <item name="Alfresco SDK POM" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest/poms/alfresco-sdk-parent/index.html" />

            <item name="Alfresco Platform Distribution POM" href="https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-platform-distribution/latest/index.html" />

            <item name="Maven AMP Plugin" href="http://maven.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-lifecycle/latest/plugins/maven-amp-plugin/index.html" />

        </menu>

        

        <menu name="Maven Alfresco Community">

            <item name="Alfresco Maven Wiki Docs" href="http://wiki.alfresco.com/wiki/Maven_Alfresco_SDK" />

            <item name="Alfresco with Maven for Dummies" href="https://wiki.alfresco.com/wiki/Maven_For_Dummies" />

            <item name="Developer Access (Google Code)" href="http://code.google.com/p/maven-alfresco-archetypes/" />

            <item name="Gabriele Columbro's blog" href="http://www.mindthegab.com/" />

            <item name="Maurizio Pillitu's blog" href="http://www.session.it/" />

            <item name="Carlo Sciolla's blog" href="http://skuro.tk/" />

            <item name="Enterprise adoption" href="http://www.slideshare.net/guest67a9ba/maven-application-lifecycle-management-for-alfresco" />

        </menu>



        <!--<menu ref="reports"/>-->