https://github.com/binduwavell/generator-alfresco
A Yeomen generator based on the Alfresco all-in-one Maven archetype with some generators and an opinionated project structure.
https://github.com/binduwavell/generator-alfresco
alfresco yeoman
Last synced: 6 months ago
JSON representation
A Yeomen generator based on the Alfresco all-in-one Maven archetype with some generators and an opinionated project structure.
- Host: GitHub
- URL: https://github.com/binduwavell/generator-alfresco
- Owner: binduwavell
- License: apache-2.0
- Created: 2015-03-18T02:47:11.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-07-26T12:25:49.000Z (about 4 years ago)
- Last Synced: 2025-04-14T07:07:40.458Z (6 months ago)
- Topics: alfresco, yeoman
- Language: JavaScript
- Homepage: https://github.com/binduwavell/generator-alfresco#readme
- Size: 1.91 MB
- Stars: 29
- Watchers: 12
- Forks: 15
- Open Issues: 59
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# generator-alfresco
[![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Join the Chat][gitter-image]][gitter-url]
## Getting Started
### What is [Alfresco](http://www.alfresco.com)?
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](http://yeoman.io)?
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](http://yeoman.io/generators/) to actually perform the coding tasks for you.
Yeoman lives in the [npm](https://npmjs.org) package repository. Assuming you have a recent
version of [node.js](http://www.nodejs.org) installed, you can use the following command
to install Yeoman.
```bash
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][installing-node] 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:
```bash
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:
```bash
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.
```bash
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
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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
```bash
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
```bash
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:
```bash
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
```bash
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
```bash
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
```bash
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:
```bash
yo alfresco:module-add-source
```
#### alfresco:webscript
```bash
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](./CODE_OF_CONDUCT.md#readme).
If you plan to to make changes to the generator itself, there are detailed
instructions in the [contributing](./CONTRIBUTING.md#readme) 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:
```bash
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](https://github.com/binduwavell/generator-alfresco/issues) or create a [new issue](https://github.com/binduwavell/generator-alfresco/issues/new). If you'd like to chat, you can reach out on our [Gitter](https://gitter.im/binduwavell/generator-alfresco) channel.
## License
Apache 2.0
[travis-image]: https://img.shields.io/travis/com/binduwavell/generator-alfresco/master.svg
[travis-url]: https://travis-ci.com/binduwavell/generator-alfresco
[daviddm-image]: https://david-dm.org/binduwavell/generator-alfresco.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/binduwavell/generator-alfresco
[codecov-image]: https://codecov.io/github/binduwavell/generator-alfresco/coverage.svg?branch=master
[codecov-url]: https://codecov.io/github/binduwavell/generator-alfresco?branch=master
[coveralls-image]: https://coveralls.io/repos/binduwavell/generator-alfresco/badge.svg?branch=master&service=github
[coveralls-url]: https://coveralls.io/github/binduwavell/generator-alfresco?branch=master
[gitter-image]: https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg
[gitter-url]: https://gitter.im/binduwavell/generator-alfresco?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
[installing-node]: https://github.com/binduwavell/generator-alfresco/wiki/Supported-Platforms-Node-Versions#user-content-installing-node