diff --git a/plugins/alfresco-maven-plugin/src/site/apt/advanced-usage.apt.vm b/plugins/alfresco-maven-plugin/src/site/apt/advanced-usage.apt.vm new file mode 100644 index 00000000..7bf10866 --- /dev/null +++ b/plugins/alfresco-maven-plugin/src/site/apt/advanced-usage.apt.vm @@ -0,0 +1,166 @@ + ------ + 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 <<>> goal in your POM + +* Method 1 - AMP to WAR Overlay + + This method allows you specify artifacts of type <<>> as <<>> 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 <<>> extension project: + ++---+ + + my-alfresco-customization + Alfresco Repository and Explorer Client Extension + war + + ... + + + + \${alfresco.groupId} + alfresco + war + + + + \${alfresco.groupId} + alfresco-wcm-quickstart-repo + \${alfresco.version} + amp + + + + + + + maven-war-plugin + + + + + + + + \${alfresco.groupId} + alfresco + war + + + + + + \${alfresco.groupId} + alfresco-wcm-quickstart-repo + amp + + + + + + + ++---+ + + <> the <<>> 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 resource writing strategy. + + The resulting WAR will have all the AMPs present in both <<<>>> and <<<>>> 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 <<<>>. + + 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 + <<>> (Alfresco script), using the Alfresco Maven Plugin to install a full folder of AMPs (<> The install goal + is bound in this case to the <<>> phase, it's up to you to make sure an exploded WAR or WAR is present in warLocation + during that phase): + ++---+ + + [...] + + + ... + + org.alfresco.maven.plugin + alfresco-maven-plugin + ${project.version} + true + + install-amps + + install + + package + + + /my/folder/containing/amps + + + ... + + + [...] + ++---+ + +** 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 (<> <<>> could be an exploded WAR folder): + ++---+ + + [...] + + + ... + + org.alfresco.maven.plugin + alfresco-maven-plugin + ${project.version} + true + + install-amps + + install + + package + + + /my/custom/folder/containing/only/one/ampFile.amp + /my/internal/or/external/alfresco/alfresco.war + + + ... + + + [...] + ++---+ \ No newline at end of file diff --git a/plugins/alfresco-maven-plugin/src/site/apt/index.apt.vm b/plugins/alfresco-maven-plugin/src/site/apt/index.apt.vm new file mode 100644 index 00000000..1c294ad8 --- /dev/null +++ b/plugins/alfresco-maven-plugin/src/site/apt/index.apt.vm @@ -0,0 +1,31 @@ + ------ + 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 <<>> 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}} <<< >>> configuration. + + For more complex usage of the Alfresco Maven Plugin check the {{{./advanced-usage.html}advanced usage page}}. \ No newline at end of file diff --git a/plugins/alfresco-maven-plugin/src/site/apt/plexus-components.apt.vm b/plugins/alfresco-maven-plugin/src/site/apt/plexus-components.apt.vm new file mode 100644 index 00000000..600c9dd8 --- /dev/null +++ b/plugins/alfresco-maven-plugin/src/site/apt/plexus-components.apt.vm @@ -0,0 +1,45 @@ + ----- + 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 <<<amp>>> type of projects. \ + + The lifecycle of an <<>> follows: + ++---+ + + org.apache.maven.lifecycle.mapping.LifecycleMapping + amp + org.apache.maven.lifecycle.mapping.DefaultLifecycleMapping + + + org.alfresco.maven.plugin:alfresco-maven-plugin:set-version + org.apache.maven.plugins:maven-resources-plugin:resources + org.apache.maven.plugins:maven-compiler-plugin:compile + org.apache.maven.plugins:maven-resources-plugin:testResources + org.apache.maven.plugins:maven-compiler-plugin:testCompile + org.apache.maven.plugins:maven-surefire-plugin:test + org.alfresco.maven.plugin:alfresco-maven-plugin:amp + org.apache.maven.plugins:maven-install-plugin:install + org.apache.maven.plugins:maven-deploy-plugin:deploy + + + ++---+ + + This build produces an Alfresco compatible AMP as main build product. + + AMP -> WAR Unarchiver + + A Plexus UnArchiver (<<>>) 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 <<>> dependencies and in particular enables AMPs to be used as part + of the standard maven-war-plugin <<<>>> 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. diff --git a/plugins/alfresco-maven-plugin/src/site/apt/usage.apt.vm b/plugins/alfresco-maven-plugin/src/site/apt/usage.apt.vm index 2a725917..49ea4de9 100644 --- a/plugins/alfresco-maven-plugin/src/site/apt/usage.apt.vm +++ b/plugins/alfresco-maven-plugin/src/site/apt/usage.apt.vm @@ -1,36 +1,99 @@ ------ -Maven AMP Plugin Plexus Components ------ + ------ + Usage + ------ + Gabriele Columbro + ------ + Nov 2012 + ------ +How to use this plugin? + There are fundamentally 3 methods to use this plugin: + + [[1]] Using Archetypes provided in the Maven Alfresco SDK + + [[2]] By using the Alfresco SDK Parent POM + + [[3]] Via direct configuration in your POM + +* Method 1 - Using Maven Alfresco SDK Archetypes -AMP Lifecycle Mapping + 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 + + + This is the <> and less error-prone way of using the plugin. + +* Method 2 - Using Maven Alfresco SDK Parent POM -This plugin provides support for amp type of projects. \ -Lifecycle of an Alfresco modules is mapped in the file: + The {{{../../poms/alfresco-sdk-parent/index.html}Maven Alfresco SDK Parent POM}} provides a single entry point for all SDK features. + + By using it as parent as follows: + ++---+ + + ... + + org.alfresco.maven + alfresco-sdk-parent + 1.0 + + ... + ++---+ -{{ ${site_tags_url}/${site_pom_artifactId}-${site_pom_version}/src/main/resources/META-INF/plexus/components.xml }} + you will have automatic support for AMP packaging of your project (just add you sources in <<>>). + +* Method 3 - Direct configuration in 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. + If you want more control over the plugin behavior you can use it directly in your POM. + + <>: 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 <<<>>> enabled, to allow AMP packaging lifecycle: + ++---+ + + [...] + + + ... + + org.alfresco.maven.plugin + alfresco-maven-plugin + ${project.version} + true + + ... + + + [...] + ++---+ -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. - - - -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 true in -the current POM, basically supporting AMPs in Maven with no need for custom external tools like MMT. - -See {{ ${site_tags_url}/${site_pom_artifactId}-${site_pom_version}/src/main/resources/META-INF/plexus/components.xml }} - - -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. + * If you want to package an Alfresco Module Package from your <<>> 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 <<>> you should configure the following <<<>>> block: + ++---+ + + [...] + + + ... + + src/main/amp + + ../\${project.build.finalName} + ${app.filtering.enabled} + + + + [...] + ++---+ \ No newline at end of file diff --git a/plugins/alfresco-maven-plugin/src/site/site.xml b/plugins/alfresco-maven-plugin/src/site/site.xml index 4d3c2ed9..970a67f4 100644 --- a/plugins/alfresco-maven-plugin/src/site/site.xml +++ b/plugins/alfresco-maven-plugin/src/site/site.xml @@ -1,59 +1,38 @@ - - org.apache.maven.skins - maven-fluido-skin - 1.2.1 - - - - true - true - - Maven Alfresco Lifecycle - Maven Alfresco Lifecycle - /img/Alfresco-logo-transparent.gif - /index.html - - - mindthegabz - true - true - - - - - - - - - - - - Alfresco Maven Plugin - v. ${project.version} - ${site_site_url} - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/pom.xml b/pom.xml index 6cb58274..9b8bbbfa 100644 --- a/pom.xml +++ b/pom.xml @@ -63,7 +63,7 @@ - + plugins/alfresco-maven-plugin @@ -94,7 +94,7 @@ 2.2 - https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-sdk/latest + https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest diff --git a/poms/alfresco-sdk-parent/pom.xml b/poms/alfresco-sdk-parent/pom.xml index e9e276c1..779a846a 100644 --- a/poms/alfresco-sdk-parent/pom.xml +++ b/poms/alfresco-sdk-parent/pom.xml @@ -105,6 +105,8 @@ 2.2.2 1.7 6.1.26 + + ../../target/staging/poms/alfresco-sdk-parent 1.0-SNAPSHOT 1.3.158 @@ -137,6 +139,10 @@ alfresco-snapshots https://artifacts.alfresco.com/nexus/content/repositories/snapshots + + alfresco-docs + dav:https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-lifecycle-aggregator/latest/poms/alfresco-sdk-parent/ + diff --git a/poms/alfresco-sdk-parent/src/site/site.xml b/poms/alfresco-sdk-parent/src/site/site.xml new file mode 100644 index 00000000..6085fefe --- /dev/null +++ b/poms/alfresco-sdk-parent/src/site/site.xml @@ -0,0 +1,67 @@ + + + org.apache.maven.skins + maven-fluido-skin + 1.3.0 + + + + + Alfresco Software + Maven Fluido Skin + http://people.apache.org/~gabriele/Alfresco-logo-transparent-thin.png + http://www.alfresco.com + + true + false + + mindthegabz + true + true + + + + + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 00000000..020bab4e --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,46 @@ + ------ + Maven Alfresco SDK + ------ + Gabriele Columbro + ------ + Nov 2012 + ------ + +Maven Alfresco SDK\x99 + + The Alfresco Maven SDK ${project.version} (formerly {{{https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/maven-alfresco-lifecycle/latest/} Maven Alfresco Lifecycle 3.9.1}} + provides a fully fledged Maven support for {{{http://www.alfresco.com}Alfresco ECM}} WAR and {{{https://wiki.alfresco.com/wiki/AMP_Files}AMP}} project development. + Being fully integrated with Maven it allows to both leverage the vast number of Maven plugins for your Alfresco project as well as integrated your + project easily in Open Source and Enterprise development processes. + +* Maven Alfresco SDK\x99 components + + The Maven Alfresco SDK relies on a number of components: + + *{{{./poms/alfresco-sdk-parent/index.html}An SDK POM}} providing full Alfresco project lifecycle feature, to be added as a <<<>>> in your projects + + * Archetypes like the {{{./archetypes/alfresco-amp-archetype/index/html}AMP}} or {{{./archetypes/alfresco-allinone-archetype/index.html}All-in-One}} providing sample project to kickstart your Alfresco development and boost it with best practices + + *{{{https://artifacts.alfresco.com/nexus/content/repositories/alfresco-docs/alfresco-platform-distribution/latest}Alfresco Platform Distribution POM}} can (optionally) be used to provide centralized <<<>>> on a particular Alfresco version / edition (Community / Enterprise) + + *The {{{https://artifacts.alfresco.com}Alfresco Artifacts Repository}} provides backing for this SDK. Check the {{{http://wiki.alfresco.com/wiki/Alfresco_Artifacts_Repository}Alfresco Wiki}} for Community / Enterprise access information. + +* Usage + + The Maven Alfresco SDK\x99 is fully documented in the single components websites (links above) as well as updated on {{{https://wiki.alfresco.com/wiki/Maven_Alfresco_SDK}the Alfresco Wiki}}. + +* Alfresco Compatibility + + Maven Alfresco SDK\x99 ${project.version} is compatible (for now) with Alfresco Community / Enterprise 4.2(.b)+. + The majority of the features might still work when using lower Alfresco versions, but certain artifacts might not be + available in the {{{https://artifacts.alfresco.com}Alfresco Artifacts Repository}}. You can probably fix this with some + Maven configuration, but use at your own risk. + +Project History + + * The Maven Alfresco SDK\x99 reached its version ${project.version}. + + * The project was formerly called Maven Alfresco Lifecycle (up to version 3.9.1), and has been re-branded to reflect a major restructuring and a better Alfresco support, + with the availability of Alfresco Community / Enterprise artifacts and {{{https://issues.alfresco.com/jira/browse/ALF-14353}POMs}} in the {{{https://artifacts.alfresco.com}Alfresco Artifacts Repository}}. + + * Other names used for this project: Maven Alfresco Archetypes, Maven Alfresco Plugin, Maven Alfresco Support. Any more suggestions? :) \ No newline at end of file diff --git a/src/site/resources/img/Alfresco-logo-transparent-large.png b/src/site/resources/img/Alfresco-logo-transparent-large.png new file mode 100644 index 00000000..de3bb99d Binary files /dev/null and b/src/site/resources/img/Alfresco-logo-transparent-large.png differ diff --git a/src/site/site.xml b/src/site/site.xml index e5b45463..047bb6e6 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -2,26 +2,32 @@ org.apache.maven.skins maven-fluido-skin - 1.2.1 + 1.3.0 + + Alfresco Software + Alfresco Software + http://people.apache.org/~gabriele/Alfresco-logo-transparent-thin.png + http://www.alfresco.com + true - true - - mindthegabz - true - true - + navbar-inversefalse + + + + true + - + @@ -37,7 +43,7 @@ - + @@ -49,9 +55,6 @@ - - - - +