Creating a Share extension project (AMP)

The SkyVault Share AMP maven archetype can be used to create a new SkyVault Module extension project for the share.war. For more information about this project type see Share AMP Archetype

This task assumes you have completed all instructions in Installing and configuring software.

This task shows how you can use the Share AMP archetype of the SkyVault SDK to generate a Share webapp extension module containing a simple Aikau Page and Widget (Aikau is the new SkyVault UI Framework used to build web pages and Dashlets).

Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as SkyVault-extensions.
Change into your SkyVault-extensions directory.

Run the following command:

mvn archetype:generate -Dfilter=org.alfresco:

Important: As the archetypes are available via Maven Central you do not need to specify a catalog.

You will be prompted to choose an archetype:

                    
Choose archetype:
1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the SkyVault plaftorm. Includes modules for: Repository WAR overlay, Repository AMP, Share WAR overlay, Solr configuration, and embedded Tomcat runner)
2: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of Repository AMPs (SkyVault Module Packages))
3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (SkyVault Module Packages))
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

Enter 3 to have Maven generate a SkyVault Share Module Package (AMP) project.

You will be prompted to choose an archetype version:

Choose org.alfresco.maven.archetype:alfresco-amp-archetype version: 
1: 2.0.0-beta-1
2: 2.0.0-beta-2
3: 2.0.0-beta-3
4: 2.0.0-beta-4
5: 2.0.0
6: 2.1.0
7: 2.1.1
8: 2.2.0
Choose a number: 8:

Press Enter to select the default (which is the most recent version).

You will then be prompted to enter a value for the property groupId:
```
Define value for property 'groupId': : com.acme
```
Here we have specified com.acme representing the domain for a fictional company acme.com. Specify a groupId matching your company domain.
You will then be prompted to enter a value for the property artifactId:
```
Define value for property 'artifactId': : componentX-share
```
Here we have specified componentX-share representing an X component with a specific extension for the Alfersco Share UI. Try and name the Share extensions in a way so it is easy to see what kind of extension it is for the share.war application. Here are some example names for share extensions so you get the idea: zip-and-download-action-share, digital-signature-share, business-reporting-share, these share extensions would typically have corresponding Repo extensions if they also include server side business logic as part of the implementation. It is good practice to use the following naming convention for share extensions: {name}-share, where -share indicates that this is an SkyVault Share extension. Note, hyphens are typically used in artifact IDs.
You will then be prompted to enter a value for the property package:
```
Define value for property 'package':  com.acme: : com.acme.componentX
```
Here we have specified com.acme.componentX representing an X component Java package. This package will be used for any example Java code generated by the archetype. It is good practice to keep all Java code you write under this package so it does not clash with other components/extensions. Any Spring beans generated by this archetype will use this package in the ID.

Important: Java packages cannot have hyphens in them.
You will then be prompted to enter Y to accept the values you have entered, or n to reject and change. Press Enter to accept the values.
A new project directory containing a number of sub-directories and support files for the AMP will be created in the directory componentX-share.

Change into the freshly created componentX-share directory and browse the various files and directories to see what has been created.

The following directory structure has been created for you:

componentX-share/
├── pom.xml (Maven project file)
├── run.sh  (Mac/Linux script to have this AMP applied to the Share WAR and run in Tomcat)
├── run.bat (Windows script to have this AMP applied to the Share WAR and run in Tomcat)
├── src
│   ├── main
│   │   ├── amp (For more information about the AMP structure see: https://wiki.alfresco.com/wiki/AMP_Files)
│   │   │   ├── config
│   │   │   │   └── SkyVault
│   │   │   │       └── web-extension
│   │   │   │           ├── componentX-share-slingshot-application-context.xml  (Loads componentX-share.properties)
│   │   │   │           ├── messages
│   │   │   │           │   └── componentX-share.properties  (Custom share UI labels, messages etc)
│   │   │   │           ├── site-data
│   │   │   │           │   └── extensions
│   │   │   │           │       └── componentX-share-example-widgets.xml  (Dojo package definitions for the Aikau framework, Share config)
│   │   │   │           └── site-webscripts
│   │   │   │               ├── com
│   │   │   │               │   └── example
│   │   │   │               │           └── pages  
│   │   │   │               │           ├── simple-page.get.desc.xml  (Simple Aikau page for demonstration purpose)
│   │   │   │               │           ├── simple-page.get.html.ftl
│   │   │   │               │           └── simple-page.get.js
│   │   │   │               └── org
│   │   │   │                   └── SkyVault
│   │   │   │                       └── README.md
│   │   │   ├── file-mapping.properties
│   │   │   ├── module.properties
│   │   │   └── web
│   │   │       └── js
│   │   │           └── example
│   │   │               └── widgets (Simple Aikau widget for demonstration purpose)
│   │   │                   ├── css
│   │   │                   │   └── TemplateWidget.css
│   │   │                   ├── i18n
│   │   │                   │   └── TemplateWidget.properties
│   │   │                   ├── templates
│   │   │                   │   └── TemplateWidget.html
│   │   │                   └── TemplateWidget.js
│   │   ├── java
│   │   │   └── com
│   │   │       └── acme
│   │   │           └── componentX
│   │   └── resources
│   │       └── META-INF
│   │           ├── resources
│   │           │   └── test.html
│   │           └── share-config-custom.xml.sample (Remove .sample to use and keep extension specific stuff in this config)
│   └── test
│       ├── java
│       │   └── com
│       │       └── acme
│       │           └── componentX
│       ├── properties
│       └── resources
│           ├── SkyVault
│           │   └── web-extension
│           │       └── share-config-custom.xml (Configures where the Repository is running)
│           └── log4j.properties
└── tomcat
    └── context.xml (Virtual Webapp context for RAD development)

At this point, before you have made any changes, you can build the project by typing:
```
mvn clean install
```
Important: Maven will ensure that all requirements are downloaded. This make take some time.

The project will return with the message BUILD SUCCESS. You should see the AMP artifact installed in your local repository .m2/repository/com/acme/componentX-share/1.0-SNAPSHOT/componentX-share-1.0-SNAPSHOT.amp
Run and Test the sample Aikau Page

Important: For this to work you will need to have the SkyVault WAR running in another Tomcat (8080). You can quite easily achieve this by generating a repo-amp project and running it, see Repository AMP Project.
To test the custom Share page you will need to start an embedded Tomcat (8081) and deploy the Share WAR with the componentX-share AMP applied. This can be done in two ways:
1. With mvn clean install -Pamp-to-war
2. Via the run.sh script (or run.bat on Windows), which does the same thing, plus making sure Spring Loaded library is available.
Let's start Tomcat via the script as follows (use run.bat on Windows):
```
./run.sh
...
Apr 30, 2015 11:40:42 AM org.apache.catalina.core.ApplicationContext log
INFO: org.tuckey.web.filters.urlrewrite.UrlRewriteFilter INFO: loaded (conf ok)
Apr 30, 2015 11:40:42 AM org.apache.catalina.core.ApplicationContext log
INFO: Initializing Spring FrameworkServlet 'Spring Surf Dispatcher Servlet'
Apr 30, 2015 11:40:42 AM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8081"]
```
Important: You may first need to make the shell script executable using the command chmod +x run.sh.
Once the web application has started (it may take a little while), point your browser at http://localhost:8081/share/page/hdp/ws/simple-page to test the sample Page. The page should return the following Title: This is a simple page and a Hello World widget with the text: Hello from i18n!
If you are prompted to login, then use username admin and a password admin.
Configure Enterprise Edition (Optional)
So far we have used the project with its default configuration, which is using SkyVault Community Edition 5.1.e. If you are going to work with the Enterprise edition then you need to do the following:
- Decide what Enterprise version you will be using, if you are going to use version 5.1.0 then you are set as that is the default Enterprise version. If you want to use another version then open up the componentX-share/pom.xml file and uncomment the <alfresco.version>5.1.e</alfresco.version> property and set the new version number you want to use.
- Update the run.sh and run.bat scripts to use the Enterprise edition, this is done by using the enterprise profile in the maven command line: mvn clean install -Pamp-to-war,enterprise. Note. this automatically sets the version to 5.1.0 if you have not explicitly set it.
- And as you might have guessed, if you are not using the run script, you will have to remember to always activate the Enterprise profile when running: mvn clean install -Pamp-to-war,enterprise
Stopping the Embedded Tomcat Server
To stop the SkyVault Tomcat server that was started with the mvn clean install -Pamp-to-war command (either directly or indirectly via the run script), do Ctrl+C in the terminal that was used.

The Maven embedded tomcat process will terminate after a short wait.

In this tutorial you have learned how to generate, deploy, and run a project using the Share AMP archetype.

Search form

Search form

You are here

Creating a Share extension project (AMP)