inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-05-19 17:14:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updates to README and additional documentation

Browse Source
This commit is contained in:
Martin Bergljung 2016-06-28 10:47:30 +01:00
parent 6049032241
commit 26563ab512
4 changed files with 197 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
Introduction.md Normal file
View File

@ -0,0 +1,30 @@
# Introduction to the Alfresco Application Development Framework
The Alfresco application development framework is based on the [Angular 2 JavaScript library](https://angular.io/).
The framework is provided by Alfresco to make it easy to build custom web applications that
should manage and view content in the [Alfresco Platform Repository](http://docs.alfresco.com/5.1/concepts/content-repo-about.html) in a custom way.
As you probably know, there is a general user interface called [Alfresco Share](http://docs.alfresco.com/5.1/concepts/gs-intro.html) available out-of-the-box.
This framework is to be used when the requirements for the content web client deviates from what is available in the standard general Alfresco Share webapp.
The framework consists of a number of components that can be combined together to form a customized content management application.
Here is a list of some of the available web components:
- [Core library](ng2-components/ng2-alfresco-core/README.md)
- [DataTable](ng2-components/ng2-alfresco-datatable/README.md)
- [DocumentList](ng2-components/ng2-alfresco-documentlist/README.md)
- [Viewer](ng2-components/ng2-alfresco-viewer/README.md)
- [Login](ng2-components/ng2-alfresco-login/README.md)
- [Upload](ng2-components/ng2-alfresco-upload/README.md)
You can browse all the components at this [page](http://devproducts.alfresco.me/).
An architecture overview looks like this:
<p align="center">
<img title="alfresco-dev-framework-architecture" alt='alfresco' src='assets/alfresco-app-dev-framework-architecture.png'></img>
</p>
Here we can also see that there is an Alfresco JavaScript framework in use that wraps the Alfresco REST API. To make things easier for the client developer.

132
Prerequisites.md Normal file
View File

@ -0,0 +1,132 @@
# Prerequisites for building and running apps with the Alfresco Application Development Framework
The [Angular 2](https://angular.io/) based application development framework requires the following:
- An Alfresco Platform Repository to talk to, which has [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) enabled.
- [Node.js](https://nodejs.org/en/) JavaScript runtime.
- [npm](https://www.npmjs.com/) package manager for JavaScript.
- Access to the [Alfresco private npm repository](http://devproducts.alfresco.me) that contains the web components (note, you need VPN access to view)
## Installing Alfresco
Alfresco comes with installers that will install all the servers, webapps, and tools needed to run Alfresco.
- Download Alfresco Community from this [page](https://www.alfresco.com/products/community/download).
- Install Alfresco following these [instructions](http://docs.alfresco.com/5.1/concepts/installs-eval-intro.html).
This will install the following Alfresco web applications:
- Alfresco Platform with the Content Repository, which we need so we can access content from our custom web client
- Alfresco Solr, which we need so we can search for content from our custom web client
- Alfresco Share, not technically needed, but can be useful for creating users and groups, and to access and upload content to the repository while we are developing the custom web client
### Enable CORS in Alfresco
The web client that we are building with the application development framework will be loaded from a different web server than the Alfresco Platform is running on.
So we need to tell the Alfresco server that any request that comes in from this custom web client should be allowed access
to the Content Repository. This is done by enabling CORS.
To enable CORS in the Alfresco Platform do the following:
Modify *tomcat/webapps/alfresco/WEB-INF/web.xml* and uncomment the following section and update
`cors.allowOrigin` to `http://localhost:3000`:
```<filter>
<filter-name>CORS</filter-name>
<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
<init-param>
<param-name>cors.allowGenericHttpRequests</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.allowOrigin</param-name>
<param-value>http://localhost:3000</param-value>
</init-param>
<init-param>
<param-name>cors.allowSubdomains</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.supportedMethods</param-name>
<param-value>GET, HEAD, POST, PUT, DELETE, OPTIONS</param-value>
</init-param>
<init-param>
<param-name>cors.supportedHeaders</param-name>
<param-value>origin, authorization, x-file-size, x-file-name, content-type, accept, x-file-type</param-value>
</init-param>
<init-param>
<param-name>cors.supportsCredentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.maxAge</param-name>
<param-value>3600</param-value>
</init-param>
</filter>
```
When specifying the `cors.allowOrigin` URL make sure to use the URL that will be used by the web client.
Then uncomment filter mappings:
``` <filter-mapping>
<filter-name>CORS</filter-name>
<url-pattern>/api/*</url-pattern>
<url-pattern>/service/*</url-pattern>
<url-pattern>/s/*</url-pattern>
<url-pattern>/cmisbrowser/*</url-pattern>
</filter-mapping>
```
## Installing Node.js
If you don't have Node.js installed then access this [page](https://nodejs.org/en/download/) and use the appropriate installer for your OS.
## Installing npm
The npm package manager is included with Node.js, however it is not usually the latest version as npm is updated more frequently than node.js.
Update npm as follows:
`$ npm install npm -g`
## Configure Alfresco Private npm repository
All the distribution packages for the application development framework components are stored in Alfresco's private npm repository,
which is visible only from the internal Alfresco LAN (or through VPN). We need to tell npm about this repository.
Set up Alfresco's private npm repository as follows:
`$ npm set registry http://devproducts.alfresco.me:4873`
### Add a user to the private npm registry (OPTIONAL)
Note. This step is not needed if you are just going to use (i.e. read) the components.
You can add yourself as a user to the private npm repository so you can publish to it.
The user needs to have been registered with the repository beforehand.
Example:
```
$ npm adduser --registry http://devproducts.alfresco.me:4873
Username: <user name goes here>
Password:
Email: (this IS public) <alfresco email address goes here>
```
#### How to publish on it:
Add the repository to your *package.json* file:
```json
"publishConfig": {
"registry": "http://devproducts.alfresco.me:4873/"
}
```
*ATTENTION*: If you don't add these lines, then the package is published to the public npm repository.
Then run the command below each time you want to publish a new version of a component:
```sh
npm version patch
npm publish
```

95
README.md
View File

@ -17,80 +17,56 @@
<img title="angular2" alt='angular2' src='assets/angular2.png' width="150px" height="150px"></img> <img title="angular2" alt='angular2' src='assets/angular2.png' width="150px" height="150px"></img>
</p> </p>
## Introduction
See the following [page](Introduction.md) for an introduction to the Alfresco Application Development Framework.
## Prerequisites ## Prerequisites
- Alfresco repository with CORS enabled. A Docker-compose file is provided by the [demo-shell](demo-shell-ng2/README.md) app. Before you start using this development framework, make sure you have installed all required software and done all the
necessary configuration, see this [page](Prerequisites.md).
## Private Npm repository configuration ## Downloading the source code for the framework
All the distribution packages of our components are stored in our private repository visible only from the internal Alfresco lan: The source code comes in two parts, one for the JavaScript API that wraps the Alfresco REST API, and one part with the
actual application development framework, including the Angular 2 based web components:
http://devproducts.alfresco.me:4873 ```
$ git clone https://github.com/Alfresco/alfresco-js-api.git
##### How to configure it: $ git clone https://github.com/Alfresco/app-dev-framework.git
```sh
npm set registry http://devproducts.alfresco.me:4873
npm adduser --registry http://devproducts.alfresco.me:4873
``` ```
##### How to publish on it: ## Running a demo project
- Add the repository to your package.json. The Alfresco application development framework comes with a demo project that you can run to get a
ATTENTION: If you don't add the following lines, the package is published on the public Npm repository. feel for what's available.
```json Start by navigating into the app development framework source folder:
"publishConfig": {
"registry": "http://devproducts.alfresco.me:4873/"
}
```
- Then run the command below each time you want to publish a new version:
```sh `$ cd app-dev-framework`
npm version patch
npm publish
```
### Running demo project Start the demo and Install all the dependencies (*Note. do it this way only the first time, and be aware, it will take some time*)
*Steps below show the quickest way to get demo shell up and running.* `app-dev-framework$ ./start.sh -install`
##### Using setup script (recommended) Start the demo (*the standard way of starting the demo after first initialization*):
```sh `app-dev-framework$ ./start.sh`
git clone https://github.com/Alfresco/dev-platform-js-api.git
git clone https://github.com/Alfresco/app-dev-framework.git
cd app-dev-framework
```
* Start the demo and Install all the dependencies (do it the first time) Start the demo, install all the dependencies, and remove the previous version of the npm packages (*Note. do this only after big changes*):
```sh `app-dev-framework$ ./start.sh -cleanInstall`
./start.sh -install
```
* Start the demo and Install all the dependencies and remove the previous version of the npm package(do it after big changes) Start the demo and update the dependencies:
```sh `app-dev-framework$ ./start.sh -update`
./start.sh -cleanInstall
```
* Start the demo and update the dependencies
```sh
./start.sh -update
```
* Start the demo
```sh
./start.sh
```
For development environment configuration please refer to [project docs](demo-shell-ng2/README.md). For development environment configuration please refer to [project docs](demo-shell-ng2/README.md).
## Components ## Components
The following is a list of some of the components that you can use when building your custom Alfresco web client:
- [Core library](ng2-components/ng2-alfresco-core/README.md) - [Core library](ng2-components/ng2-alfresco-core/README.md)
- [DataTable](ng2-components/ng2-alfresco-datatable/README.md) - [DataTable](ng2-components/ng2-alfresco-datatable/README.md)
- [DocumentList](ng2-components/ng2-alfresco-documentlist/README.md) - [DocumentList](ng2-components/ng2-alfresco-documentlist/README.md)
@ -98,29 +74,28 @@ For development environment configuration please refer to [project docs](demo-sh
- [Login](ng2-components/ng2-alfresco-login/README.md) - [Login](ng2-components/ng2-alfresco-login/README.md)
- [Upload](ng2-components/ng2-alfresco-upload/README.md) - [Upload](ng2-components/ng2-alfresco-upload/README.md)
You can browse all the components at the following address: You can browse all the components at the following [page](http://devproducts.alfresco.me/).
http://devproducts.alfresco.me/
## Yeoman generators ## Yeoman generators
To speed up the development of your Alfresco Angular 2 application or Alfresco Angular 2 component use one of our Yeoman generators. These To speed up the development of your Alfresco Angular 2 application, or Alfresco Angular 2 component, use one of the Yeoman generators.
generators will create for you a full working project with all the right libraries and tools.
These generators will create a full working project with all the right libraries and tools.
<p align="center"> <p align="center">
<img title="yeoman generator" src='https://github.com/yeoman/media/blob/master/optimized/yeoman-150x150-opaque.png' alt='yeoman logo' /> <img title="yeoman generator" src='https://github.com/yeoman/media/blob/master/optimized/yeoman-150x150-opaque.png' alt='yeoman logo' />
</p> </p>
### How to build a new Alfresco Angular 2 component ### Generate an Alfresco web component starter project
To generate your Alfresco Angular 2 component you can use our Yeoman generator To generate your Alfresco Angular 2 component you can use the following Yeoman generator:
- [Yeoman Generator Angular 2 Alfresco component](https://github.com/Alfresco/generator-ng2-alfresco-component) - [Yeoman Generator Angular 2 Alfresco component](https://github.com/Alfresco/generator-ng2-alfresco-component)
### How to build a new Alfresco Angular 2 application ### Generate an Alfresco web application starter project
To generate your Alfresco Angular 2 application you can use our Yeoman generator To generate your Alfresco Angular 2 application you can use the following Yeoman generator:
- [Yeoman Generator Angular 2 Alfresco application](https://github.com/Alfresco/generator-ng2-alfresco-app) - [Yeoman Generator Angular 2 Alfresco application](https://github.com/Alfresco/generator-ng2-alfresco-app)

BIN
assets/alfresco-app-dev-framework-architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB