generator-alfresco

Getting Started

What is Alfresco?

Alfresco is an open-source content management application. This project provides some tools for setting up and working with Alfresco extension/enhancement projects. It wraps and extends the Alfresco SDK and specifically the All in One maven archetype.

What is Yeoman?

Yeoman is a command line tool that helps you to automate coding tasks. Out of the box, Yeoman doesn't do very much. It relies on a library of thousands of generators to actually perform the coding tasks for you.

Yeoman lives in the npm package repository. Assuming you have a recent version of node.js installed, you can use the following command to install Yeoman.

npm install -g yo

NOTE: that we now require Node 4.5 or above. Information on installing Node is linked from our Supported Platforms / Node Versions wiki page.

Installing and using the generator

You have a couple of options for installing the Alfresco generator for Yeoman. Your choice will depend on if you plan to extend the generator or if you simply want to use it.

Checkout the next section for what to do if you plan to work on the generator code.

You can install the latest published release of the generator from npm with this command:

npm install -g generator-alfresco

WARNING: you will likely need to update this occasionally as the project is under active development.

Now, assuming you have all of the pre-requisites installed (including appropriate versions of node, npm, yeoman, this generator, Java and Maven.) You can create an Alfresco extension project using this generator. First of all you should create a new folder for your project and change into the new folder. Then run the following command:

yo alfresco

This will ask you a number of questions and then generate a project based on your answers. yo alfresco will make sure you have an appropriate version of Java and Maven available for the version of the SDK you select. It will then use the all-in-one Alfresco SDK archetype from the selected version of the SDK to create a project. Finally it will add (and potentially remove) some additional files and folders to the project.

Here is an example of what the top level folder structure might look like:

TODO.md
customizations
debug.sh
modules
pom.xml
repo
run-without-springloaded.sh
run.bat
run.sh
runner
scripts
share
solr-config
source_templates

Notice that for SDK 2 we provide a run-without-springloaded.sh in addition to the default run.sh. The generator automatically makes these executable. There are some other helpful scripts in the scripts folder.

As part of the generation process, we actually copy the repo-amp and share-amp folders to source_templates. That way we have SDK specific instances of these folder structures that we can use later on when you want to add Source AMPS to your project.

One of the questions the we ask is ? Should we remove the default source amps? (Y/n). Notice that the default here is Y and in the project listing above there are no folders for repo-amp or share-amp. Of course if you answer N to this question then the default AMPs will be left in place.

If you accept the default behavior of removing the default source amps, we remove those top level folders. We also, remove them from the top level pom.xml. We remove the references from repo/pom.xml, share/pom.xml and even from the Tomcat context files in the runner module.

yo alfresco --help
yo alfresco:action --help
yo alfresco:amp --help
yo alfresco:behavior --help
yo alfresco:jar --help
yo alfresco:jsrootobject --help
yo alfresco:model --help
yo alfresco:module --help
yo alfresco:webscript --help

Will print out information about cli arguments and options.

alfresco:amp

yo alfresco:amp

This starts by asking if you would like to add source, local, remote or common AMPs. This sub-generator is deprecated starting with SDK3, use yo alfresco:module instead.

alfresco:amp-add-source

When you select Source AMP, we'll ask a few questions and then create additional repo/share source AMPs under the customizations folder (unless you don't have one, in which case they will be created in the project root). These are created by copying the appropriate platform/repo/share folders from source_templates. Of course, we update paths and names appropriately. We also automatically plug them into your project files (including maven and spring/tomcat contexts.)

You can use the following as a shortcut for adding source AMPs:

yo alfresco:amp-add-source

alfresco:amp-add-local

If you have AMP files you'd like to incorporate into your project, you can place repository AMPs into the customizations/amps folder. Similarly you can place your pre-packaged Share AMP files into the customizations/amps_share folder. In order to get these plugged into the project you use the Local AMP option with the yo alfresco:module sub-generator. Here is an example command you could use:

yo alfresco:amp-add-local

When you use this command, we'll go through the amps and amps_share folders and find any AMP files that are not already linked into your project structure. You select the AMP files one at a time, you'll be asked to provide a Maven groupId, artifactId and version for the AMP. If this information is included inside the AMP file, we'll try to provide you with sane default values. At the end of the day, it's not super important what values you provide. Of course you'll probably be happy if you choose meaningful values when you come back to the project in a month or a year.

alfresco:amp-add-remote

The Remote AMP option allows you to specify if an AMP should be installed into the repository or Share. It also asks you to provide Maven groupId, artifactId and version for an AMP file that is in a Maven repository that your build has access to. For example, the Uploader Plus plugin is available in Maven Central, so you can provide information for one of these AMPs and the build will automatically download and install the AMP the next time you run your project.

Here is a sample command line you can use:

yo alfresco:amp-add-remote

alfresco:amp-add-common

The final option for installing AMPs is Common AMPS, this lists AMPs that are available via a public maven repo that we can plug into your project on your behalf. Currently these include:

Alfresco Office Services (AOS)
Developer Helper
JavaMelody
JavaScript Console
JScript Extensions
Order of the Bee Support Tools
Records Management (RM)
Share Inbound Calendar Invites
Share Site Announcements
Share Site Creators
Share Site Space Templates
Support Tools
Uploader Plus
Xenit Care4Alf
Xenit Dynamic Extensions

Here is a summary of which versions of common AMPS are available with each version of the SDK:

	SDK 3.0.1 Community	SDK 3.0.1 Enterprise	SDK 2.2.0 Community	SDK 2.2.0 Enterprise	SDK 2.1.1 Community	SDK 2.1.1 Enterprise	SDK 2.1.0 Community	SDK 2.1.0 Enterprise	SDK 2.0.0 Community	SDK 2.0.0 Enterprise	local SDK Community	local SDK Enterprise
Alfresco Office Services	1.1.7	1.1.7	1.1.7	1.1.7
Developer Helper	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1	1.0.1
JavaMelody			1.62.0	1.62.0
JavaScript Console	0.6	0.6	0.6	0.6	0.6	0.6	0.6	0.6	0.6	0.6	0.6	0.6
JScript Extensions			1.3	1.3	1.3.1	1.3.1	1.3.1	1.3.1	1.3.1	1.3.1
Order of the Bee Support Tools	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0	1.0.0.0
Records Management			2.5.a	2.5.0	2.3	2.3	2.3	2.3
Share Inbound Calendar Invites	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0
Share Site Announcements	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2	0.0.2
Share Site Creators	0.0.5	0.0.5	0.0.5	0.0.5
Share Site Space Templates	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2	1.1.2
Support Tools				1.11		1.11		1.11		1.11		1.11
Uploader Plus	1.2	1.2	1.2	1.2	1.2	1.2	1.2	1.2	1.2	1.2	1.2	1.2
Xenit Care4Alf			1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0	1.1.0
Xenit Dynamic Extensions			1.5.1	1.5.1	1.5.1	1.5.1	1.5.1	1.5.1	1.5.1	1.5.1

You don't need to worry about this too much as it will automatically detect the SDK version and if you are using Community or Enterprise and even which AMPs you have already applied and only show you ones that are valid for your project.

Here is a sample command line you can use:

yo alfresco:amp-add-common

You can actually specify more than one AMP to install at the same time; we'll even install both repo and share amps if necessary.

alfresco:action

yo alfresco:action

You'll be prompted for some basic information including which repo Source AMP you want to create the action in. We'll create a basic repository action for you. This includes a Java class, a properties file that causes the action and arguments to have pretty labels and a context file with bean definitions for the Java class and the resource bundle for loading the properties file.

alfresco:behavior

yo alfresco:behavior

You'll be prompted for some basic information including which repo Source AMP you want to create the behavior class in. We'll create a class that registers a behavior for the onUpdateProperties policy on all cm:content nodes. We'll also generate a context file that registers a bean for this class and passes in the minimal items you'll need to create behavior code.

alfresco:jar-add-local

If you have JAR files you'd like to incorporate into your project, you can place repository JARs into the customizations/modules/platform folder. Similarly you can place your pre-packaged Share JAR files into the customizations/modules/share folder. In order to get these plugged into the project you use the Local JAR option with the yo alfresco:module sub-generator. Here is an example command you could use:

yo alfresco:jar-add-local

When you use this command, we'll go through the platform and share modules folders and find any JAR files that are not already linked into your project structure. You select the JAR files one at a time, you'll be asked to provide a Maven groupId, artifactId and version for the JAR. If this information is included inside the JAR file, we'll try to provide you with sane default values.

alfresco:jsrootobject

yo alfresco:jsrootobject

You'll be prompted for some basic information including which repo Source Module you want to create the Javascript root object in. We'll create a class with a sample method callMe that can be called from the Javascript root object. We'll also generate a context file that registers a bean for this class and passes in the minimal items you'll need to create the Javascript root object code.

alfresco:model

yo alfresco:model

You'll be prompted for some basic information including which repo Source AMP you want to create the model in. We'll create a very bare model.xml file for you, this file has a bunch of commented out examples in it, so you should be able to create a valid model pretty easily. Of course we also provide a context file that registers the model.

alfresco:module

yo alfresco:module

This starts by asking if you would like to add a source module, a local AMP or JAR, a remote AMP or common AMPs. It delegates to other sub-generators.

alfresco:module-add-source

When you select Source Module, we'll ask a few questions and then create additional repo/share source modules under the customizations folder (unless you don't have one, in which case they will be created in the project root). These are created by copying the appropriate platform/repo/share folders from source_templates. Of course, we update paths and names appropriately. We also automatically plug them into your project files (including maven and spring/tomcat contexts.)

You can use the following as a shortcut for adding source AMPs:

yo alfresco:module-add-source

alfresco:webscript

yo alfresco:webscript

This will ask you a bunch of questions and then produce appropriate repo/share files for your WebScript. If you choose multiple HTTP methods you can in fact scaffold multiple webscripts with one pass through this sub-generator.

future sub-generators

We are planning to add many more sub-generators for things like: jobs, workflows, JavaScript root objects, metadata extractors, content transformers, etc. We may add sub-generators for doing a bunch of common tasks with Share customization.

Try The Project / Contribute

Before reporting issues or working on fixes/enhancements, please make sure you are familiar with and agree to our code of conduct.

If you plan to to make changes to the generator itself, there are detailed instructions in the contributing page.

Check out the generator-alfresco project (or ideally a fork of the same) and then run the following command from the checked out project directory:

npm install
npm link # may need sudo

This is essentially the same as the npm install -g generator-alfresco command above, but you'll have a project directory where you can tweak things, and push updates back to GitHub.

Getting Help

If you find a bug or something is confusing, you can review existing or create a new issue. If you'd like to chat, you can reach out on our Gitter channel.

License

Apache 2.0