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 yoNOTE: that we now require Node 4.5 or above. Information on installing Node is linked from our Supported Platforms / Node Versions wiki page.
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-alfrescoWARNING: 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 alfrescoThis 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 --helpWill print out information about cli arguments and options.
yo alfresco:ampThis 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.
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-sourceIf 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-localWhen 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.
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-remoteThe 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-commonYou can actually specify more than one AMP to install at the same time; we'll even install both repo and share amps if necessary.
yo alfresco:actionYou'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.
yo alfresco:behaviorYou'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.
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-localWhen 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.
yo alfresco:jsrootobjectYou'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.
yo alfresco:modelYou'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.
yo alfresco:moduleThis 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.
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-sourceyo alfresco:webscriptThis 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.
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.
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 sudoThis 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.
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.
Apache 2.0
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent