[ADF-3682] Review of main README and other information pages (#3892)

* [ADF-3682] Updated text, links and info in README files

* [ADF-3682] Reviewed text of CORS info page

* [ADF-3682] Fixed minor typo in README.md
This commit is contained in:
Andy Stark 2018-10-16 18:03:44 +01:00 committed by Eugenio Romano
parent 90dcca61dd
commit 392bd62610
6 changed files with 102 additions and 125 deletions

View File

@ -1,25 +1,30 @@
# CORS solving strategies
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.
A web client built with ADF typically won't be loaded from the same web server that the Alfresco Platform is running on.
This means you need to tell the Alfresco server explicitly that any request coming in from this custom web client should be allowed access
to the Content Repository. This is done by enabling
[Cross Origin Resource Sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
(CORS).
If you are experiencing this kind of problem, see **one of the following**:
If you are experiencing this kind of problem, use **one of the following approaches**,
depending on your setup:
1. [Configure Webpack Proxy](#configure-webpack-proxy)
2. [Configure angular-cli Proxy](#configure-angular-cli-proxy)
3. [Configure nginx proxy](#configure-nginx-proxy)
4. [Enable CORS in CS and PS](#configure-webpack-proxy)
# Configure Webpack Proxy
## Configure Webpack Proxy
If you are using a project created with the [Yeoman Generator](https://github.com/Alfresco/generator-ng2-alfresco-app) or the demo shell (>=1.6.0), you already have
a suitable configuration out of the box in your `config/webpack.common.js` file.
If you are using a project created with the [Yeoman Generator](https://github.com/Alfresco/generator-ng2-alfresco-app) or the demo shell >=1.6.0, you have already out of the box in your `config/webpack.common.js` the following configuration.
Say we have an app running on http://localhost:3000/ and we want to redirect all calls with the following strategy:
* Content Service http://localhost:8080/ redirect to -> http://localhost:3000/ecm/
* Process Service http://localhost:9999/ redirect to -> http://localhost:3000/bpm/
Open the `config/webpack.common.js` file, find the `devServer` section and add the content:
Open the `config/webpack.common.js` file, find the `devServer` section and add the content:
```javascript
devServer: {
@ -55,18 +60,21 @@ devServer: {
```
Notes:
- With different configuration of webpack the `devServer` properties could be in other webpack files. Search in your configuration files
- With a different configuration of webpack, the `devServer` properties could be in other webpack files. Search your configuration files to find the correct location.
- If you are running the App, Content Service or Process Service on different ports change the ports accordingly in your local configuration.
For further details about how to configure a webpack proxy please refer to the [official documentation](https://webpack.js.org/configuration/dev-server/#devserver-proxy).
# Configure angular-cli Proxy
## Configure angular-cli Proxy
Say we have an app running on http://localhost:3000/ and we want to redirect all the calls with the following strategy:
* Content Service http://localhost:8080/ redirect to -> http://localhost:3000/ecm/
* Process Service http://localhost:9999/ redirect to -> http://localhost:3000/bpm/
Create a file next to project's `package.json`, call it `proxy.conf.json` and add the following content:
Create a file next to the project's `package.json`, call it `proxy.conf.json` and add the following content:
```javascript
{
@ -93,36 +101,37 @@ Create a file next to project's `package.json`, call it `proxy.conf.json` and ad
}
```
Note if you are running the App, Content Service or Process Service on different ports change the ports accordingly in your local configuration.
Note that if you are running the App, Content Service or Process Service on different ports, you should change the ports accordingly in your local configuration.
For further details about how to configure a webpack proxy please refer to the [official documentation](https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/proxy.md).
# Configure nginx proxy
## Configure nginx proxy
## Installing nginx
### Installing nginx
Most Linux distributions will come with nginx available to install via your
package manager and on Mac OS you can use [Homebrew](http://brew.sh/).
If you want to install manually however, you can follow the instructions on the
If you want to install manually, you can follow the instructions on the
[download page](http://nginx.org/en/download.html). See also the specific information for
[windows users](http://nginx.org/en/docs/windows.html).
[Windows users](http://nginx.org/en/docs/windows.html).
### Start nginx
#### Start nginx
Start nginx using the supplied configuration in [nginx.conf](nginx.conf)
nginx -c nginx.conf
### Review nginx configuration
#### Review nginx configuration
To correctly configure nginx use the following file [nginx.conf](/nginx.conf).
To correctly configure nginx, use the [nginx.conf](nginx.conf) file in the project root folder.
This will host Activiti, Alfresco and the app dev framework under the same origin.
* ECM : http://localhost:8888/alfresco/
* BPM : http://localhost:8888/activiti/
To make everything work, you should change the address of the ECM and BPM. In the demo app you can do that by clicking on the top right settings menu and change the bottom left options: *ECM host* and *BPM host*.
To make everything work, you should change the address of ECM and BPM. In the demo app you can do that by clicking on the top right settings menu and changing the bottom left options: *ECM host* and *BPM host*.
This configuration assumes a few things:
@ -132,30 +141,31 @@ This configuration assumes a few things:
* Alfresco: localhost:8080
* Activiti: localhost:9999
All those values can be modified at their respective `location` directive on the [nginx.conf](/nginx.conf) file.
You can modify all these values at their respective `location` directive in the
[nginx.conf](/nginx.conf) file.
If you want to know more on how to install and configure nginx to work with the Application Development Framework, information can be found [here](https://community.alfresco.com/community/application-development-framework/blog/2016/09/28/adf-development-set-up-with-nginx-proxy)
See the [Alfresco community page](https://community.alfresco.com/community/application-development-framework/blog/2016/09/28/adf-development-set-up-with-nginx-proxy) about using nginx with ADF for further information.
## Enable CORS in CS and PS
# Enable CORS in CS and PS
If you want to completely enable CORS calls on your Content Service and Process Service, please refer to the following Alfresco documents:
If you want to completely enable CORS calls in your Content Services and Process Services,
please refer to the following Alfresco documents:
* [Enable Cross Origin Resource Sharing (CORS) in Alfresco Process Services](http://docs.alfresco.com/process-services1.6/topics/enabling-cors.html)
* Enable Cross Origin Resource Sharing (CORS) in Alfresco Content Services
This is the easiest way, add the [enablecors](https://artifacts.alfresco.com/nexus/service/local/repositories/releases/content/org/alfresco/enablecors/1.0/enablecors-1.0.jar)
platform module JAR to the *$ALF_INSTALL_DIR/modules/platform* directory and restart the server.
The easiest approach is to add the [enablecors](https://artifacts.alfresco.com/nexus/service/local/repositories/releases/content/org/alfresco/enablecors/1.0/enablecors-1.0.jar)
platform module JAR to the `$ALF_INSTALL_DIR/modules/platform` directory and restart the server.
Note. by default, the CORS filter that is enabled will allow any origin.
Or - Manually update the web.xml file
Note that, by default, the CORS filter that is enabled will allow any origin.
Modify *$ALF_INSTALL_DIR/tomcat/webapps/alfresco/WEB-INF/web.xml* and uncomment the following section and update
`cors.allowOrigin` to `http://localhost:3000` :
Alternatively, you can update the `web.xml` file manually.
```
Modify `$ALF_INSTALL_DIR/tomcat/webapps/alfresco/WEB-INF/web.xml` and uncomment the following section and update
`cors.allowOrigin` to `http://localhost:3000`:
```xml
<filter>
<filter-name>CORS</filter-name>
<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
@ -189,11 +199,11 @@ Modify *$ALF_INSTALL_DIR/tomcat/webapps/alfresco/WEB-INF/web.xml* and uncomment
</init-param>
</filter>
```
When specifying the `cors.allowOrigin` URL make sure to use the URL that will be used by the web client.
When specifying the `cors.allowOrigin` URL, make sure that you use the URL that will be used by the web client.
Then uncomment filter mappings:
Then uncomment the filter mappings:
```
```xml
<filter-mapping>
<filter-name>CORS</filter-name>
<url-pattern>/api/*</url-pattern>

View File

@ -1,6 +1,6 @@
# Browser Support
Browser support and polyfills guide.
This page gives a guide to Browser support and polyfills.
Browser compatibility and support depends on targeted browsers and 3rd party libraries. ADF is based on the following libraries and components:
@ -50,4 +50,5 @@ ADF (demo shell) imports by default the following set of recommended polyfills:
<link rel="stylesheet" type="text/css" href="node_modules/dialog-polyfill/dialog-polyfill.css" />
```
For a complete code please refer to [demo shell](demo-shell/index.html) example.
See the [demo shell](demo-shell/index.html) example project for
further information and source code.

View File

@ -6,21 +6,21 @@
## Submitting a Pull Request (PR)
Before you submit please follow the steps below:
Before you submit a pull request please follow the steps below:
* Search in [GitHub PR](https://github.com/Alfresco/alfresco-ng2-components/pulls) for an open or closed PR
that could solve or already solves your issue.
* Search in the [GitHub release history](https://github.com/Alfresco/alfresco-ng2-components/releases) if your
* Search in the [GitHub release history](https://github.com/Alfresco/alfresco-ng2-components/releases) to see if your
issue has already been solved in a new version of ADF.
* Fork our repository - [if you don't know how to do it read this GitHub document](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
* Make your changes in a new git branch starting from development and following the [naming convention](https://github.com/Alfresco/alfresco-ng2-components/wiki/Branching-Strategy)
* Fork our repository (if you don't know how to do this, read [this GitHub document](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)).
* Make your changes in a new git branch starting from development and following our [naming convention](https://github.com/Alfresco/alfresco-ng2-components/wiki/Branching-Strategy)
```shell
git checkout -b dev-{developerName}-{GitIssuedId/JiraIssueId} development
```
* Create your PR **including appropriate test cases** following the [code contribution acceptance criteria](https://github.com/Alfresco/alfresco-ng2-components/wiki/Code-contribution-acceptance-criteria)
* Run the tests and make sure they are green. Please don't comment out or exclude the already existing tests
* Run the tests and make sure they are green. Please don't comment out or exclude the tests that are already in place.
* Commit your change using the [commit format message good practice](https://github.com/Alfresco/alfresco-ng2-components/wiki/Commit-format)
* Push your branch to GitHub:
@ -40,20 +40,23 @@ Before you submit please follow the steps below:
git rebase development -i
git push -f
```
Note: If you need more information about how to sync your fork, see [here](https://help.github.com/articles/syncing-a-fork/)
Note: If you need more information about how to sync your fork, see [this page](https://help.github.com/articles/syncing-a-fork/).
## Code style
The code style in the ADF code follows the [Angular style guide](https://angular.io/guide/styleguide) plus some internal rules.
The code style for ADF follows the [Angular style guide](https://angular.io/guide/styleguide) plus some internal rules.
You dont have to worry too much about those rules because they are automatically checked by tslint/codelyzer/adf-rules.
If your code is not compliant to one of these rules you will receive an error when you build the project with some help on how to fix it.
The ADF-Rules :
If your code is not compliant with one of these rules you will see an error when you build the project along with some help on how to fix it.
The ADF-Rules are as follows:
* File name component/directive cannot start with Alfresco/Activiti/adf - this rule is to help developers find files easily
* Class names cannot start with Alfresco/Activiti/adf for the same reason as above
* scss is mandatory. All the classes need to have the adf- prefix
* scss is mandatory. All the classes need to have the `adf-` prefix
## Test guide
In ADF we are encouraging the use of behavior-driven development (BDD)
In ADF, we encourage the use of behavior-driven development (BDD).
### General guidelines
@ -63,16 +66,16 @@ In ADF we are encouraging the use of behavior-driven development (BDD)
### File name
* The file name specification as to be the same of the component/service/pipe it test plus the .spec. suffix
* The specification file has to be in the same folder of the component/service/pipe it test
* The file name specification must be the same as the component/service/pipe it tests plus the .spec. suffix.
* The specification file must be in the same folder as the component/service/pipe it tests.
### Describer Name
* The Main describer of the test should be the name of the class under test
* The sub describe is used for grouping related behavior test. Do not over use it
* The sub describe is used for grouping related behavior test. Do not overuse it.
### Test Name
Any test should follow the naming convention:
[Should] [ ***Expected Behavior** ] [when/after/before] [ ***State Under Test*** ].
[Should] [ ***Expected Behavior*** ] [when/after/before] [ ***State Under Test*** ].

View File

@ -1,22 +1,21 @@
# Introduction to the Alfresco Application Development Framework
The Alfresco application development framework is based on the [Angular framework](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.
The Alfresco Application Development Framework (ADF) is based on the [Angular framework](https://angular.io/).
ADF is provided by Alfresco to make it easy to build custom web applications to manage and view content in the [Alfresco Platform Repository](https://docs.alfresco.com/5.2/concepts/content-repo-about.html).
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.
Share is usually used as a quick way of getting started with content management with Alfresco. It gives you access to pretty much all
the features provided by the Alfresco ECM system. And a lot of customers customize it for their specific domain.
As you probably know, there is a general user interface called [Alfresco Share](https://docs.alfresco.com/5.2/concepts/gs-intro.html) available out-of-the-box.
Share is usually used as a quick way of getting started with content management in Alfresco. It gives you access to pretty much all
the features provided by the ACS system and a lot of customers customize it for their specific domain.
However, there are use-cases that Share does not fit very well, such as:
However, there are use cases that Share does not fit very well, such as:
- Feature-based clients, exposing functionality to perform a specific task(s)
- Role-based clients, exposing functionality based on role
- Clients where the UI layout and style differs significantly from the Share layout and styling
- [Mashup clients](http://whatis.techtarget.com/definition/mash-up)
This is where this application development framework comes into play, it can be used to create exactly the user interface
(i.e. web client) that the requirements demand.
This is where ADF comes into play. You can use it to create exactly the user interface
(i.e. web client) that you require.
The framework consists of several libraries that can be used to form a customized content management application. The available libraries are:
@ -26,10 +25,10 @@ The framework consists of several libraries that can be used to form a customize
- [Insights](lib/insights/README.md)
You can browse all the components at the
You can browse documentation for all the components at the
[ADF Component Catalog](https://alfresco.github.io/adf-component-catalog/).
An architecture overview looks like this:
An overview of the architecture is shown below:
<p align="center">
<img title="alfresco-angular-components-architecture" alt='alfresco' src='assets/alfresco-app-dev-framework-architecture.png'></img>

View File

@ -1,27 +1,11 @@
# Prerequisites for building and running apps with the Alfresco Application Development Framework
The [Angular](https://angular.io/) based application development framework requires the following:
See our tutorial
[Preparing the development environment](docs/tutorials/preparing-environment.md)
for full details of what you need to install before using ADF.
- An Alfresco Platform Repository (version [201609 Early Access](https://community.alfresco.com/docs/DOC-6372-alfresco-community-edition-file-list-201609-ea) or newer)
- [Download and install the process service](https://www.alfresco.com/products/bpm/alfresco-activiti/trial)
- [Node.js](https://nodejs.org/en/) JavaScript runtime.
- [npm](https://www.npmjs.com/) package manager for JavaScript.
- (If you use CS and PS together) Make sure your user has the same username and password in both system
- [If you are experiencing CORS problem read this guide](/ALFRESCOCORS.md)
*Note: Default username for activiti is "admin@app.activiti.com" and "admin" for Alfresco, and also the default password are different. Change them to be equal.*
**Verify that you are running at least node `v5.x.x` and npm `3.x.x`**
by running `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors.
## 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.
Make sure the Node.js version is > 5:
```
$ node -v
v5.12.0
```
If you experience [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
issues then you should also read our
[CORS guide](ALFRESCOCORS.md)
to see the full range of solutions available.

View File

@ -1,4 +1,4 @@
# ALFRESCO ANGULAR COMPONENTS
# Alfresco Application Development Framework (ADF)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/d9eb873741da403bb3284778102372e7)](https://www.codacy.com/app/Alfresco/alfresco-ng2-components?utm_source=github.com&utm_medium=referral&utm_content=Alfresco/alfresco-ng2-components&utm_campaign=badger)
[![Join the chat at https://gitter.im/Alfresco/alfresco-ng2-components](https://badges.gitter.im/Alfresco/alfresco-ng2-components.svg)](https://gitter.im/Alfresco/alfresco-ng2-components?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@ -22,60 +22,40 @@
## Introduction
See the following [page](INTRODUCTION.md) for an introduction to the Alfresco Application Development Framework.
See the [Introduction page](INTRODUCTION.md) to get started with the Alfresco Application Development Framework.
## Prerequisites
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).
Before you start using this development framework, make sure you have installed all required software and done all the necessary configuration. See our tutorial
[Preparing the development environment](docs/tutorials/preparing-environment.md)
for full details.
## Components
To view the sources of all components that you can use to build your custom Alfresco (Content Services or Process Services) client follow this link:
[Components](/lib).
You can find the sources for all ADF components in the
[`lib`](/lib) folder.
You can browse all the components at the [ADF Component Catalog](https://alfresco.github.io/adf-component-catalog/).
Full documentation for all components is available at the
[ADF Component Catalog](https://alfresco.github.io/adf-component-catalog/).
## Demo Application
A separate application showcasing integration of components can be found [here](https://github.com/Alfresco/alfresco-ng2-components/tree/master/demo-shell).
You will find examples of basic interaction for both BPM and ECM sets of widgets.
A separate application showcasing integration of components can be found
[here](https://github.com/Alfresco/alfresco-ng2-components/tree/master/demo-shell).
The app has examples of basic interaction for both APS and ACS components.
## Yeoman generators
To speed up the development of your Alfresco Angular application, or Alfresco Angular component, use one of the Yeoman generators.
These generators will create a full working project with all the right libraries and tools.
To speed up the development of your ADF application, use the
[Yeoman Generator](https://github.com/Alfresco/generator-ng2-alfresco-app).
This will create a full working project with all the right libraries and tools.
<p align="center">
<img title="yeoman generator" src='https://github.com/yeoman/media/blob/master/optimized/yeoman-150x150-opaque.png' alt='yeoman logo' />
</p>
### Generate an Alfresco web component starter project
To generate your Alfresco Angular component you can use the following Yeoman generator:
- [Yeoman Generator Angular Alfresco component](https://github.com/Alfresco/generator-ng2-alfresco-component)
### Generate an Alfresco web application starter project
To generate your Alfresco Angular application you can use the following Yeoman generator:
- [Yeoman Generator Angular Alfresco application](https://github.com/Alfresco/generator-ng2-alfresco-app)
## Amazon AWS Elastic Beanstalk fast deploy
<p align="center">
<img alt="AmazonWebservices Logo.svg" src="https://upload.wikimedia.org/wikipedia/commons/1/1d/AmazonWebservices_Logo.svg" width="250" height="94">
</p>
To deploy directly on your AWS instance our demo shell click the button below:
<a title="Deploy to AWS" href="https://console.aws.amazon.com/elasticbeanstalk/home?region=us-west-2#/newApplication?applicationName=Alfresco&solutionStackName=Node.js&tierName=WebServer&sourceBundleUrl=https://s3-us-west-2.amazonaws.com/elasticbeanstalk-us-west-2-677901592050/ADF_1.0.zip" target="_blank"><img src="http://d0.awsstatic.com/product-marketing/Elastic%20Beanstalk/deploy-to-aws.png" height="40"></a>
## Browser Support
All components are supported in the following browsers:
|**Browser** |**Version** |
@ -86,6 +66,6 @@ All components are supported in the following browsers:
|Edge |13, 14 |
|Internet Explorer |11 |
* Due to a [Firefox known issue](https://bugzilla.mozilla.org/show_bug.cgi?id=1188880), the Alfresco Upload Component does not currently support folder upload functionality on Firefox.
* Due to a [known issue](https://bugzilla.mozilla.org/show_bug.cgi?id=1188880) in Firefox, the Alfresco Upload Component does not currently support folder upload functionality on Firefox.
Please refer to the [Browser Support](BROWSER-SUPPORT.md) article for more details.
See the [Browser Support](BROWSER-SUPPORT.md) article for more details.