Skip to content

Commit

Permalink
[ADF-3682] Review of main README and other information pages (#3892)
Browse files Browse the repository at this point in the history 
* [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
  • Loading branch information
@therealandeeee @eromano
therealandeeee authored and eromano committed Oct 16, 2018
1 parent 90dcca6 commit 392bd62
Show file tree
Hide file tree
Showing 6 changed files with 103 additions and 126 deletions.
80 changes: 45 additions & 35 deletions ALFRESCOCORS.md
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: {
Expand Down Expand Up @@ -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
{
Expand All @@ -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:

Expand All @@ -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.

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)
You can modify all these values at their respective `location` directive in the
[nginx.conf](/nginx.conf) file.

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>
Expand Down Expand Up @@ -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>
Expand Down
5 changes: 3 additions & 2 deletions BROWSER-SUPPORT.md
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:

Expand Down Expand Up @@ -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.
33 changes: 18 additions & 15 deletions CONTRIBUTING.md
View file
Expand Up @@ -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:

Expand All @@ -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 don’t 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

Expand All @@ -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*** ].
21 changes: 10 additions & 11 deletions INTRODUCTION.md
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:

Expand All @@ -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>
Expand Down
34 changes: 9 additions & 25 deletions PREREQUISITES.md
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:

- 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
```
See our tutorial
[Preparing the development environment](docs/tutorials/preparing-environment.md)
for full details of what you need to install before using ADF.

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.

0 comments on commit 392bd62

Please sign in to comment.