diff --git a/ALFRESCOCORS.md b/ALFRESCOCORS.md index ec39f66e8a..3f2450875a 100644 --- a/ALFRESCOCORS.md +++ b/ALFRESCOCORS.md @@ -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 CORS com.thetransactioncompany.cors.CORSFilter @@ -189,11 +199,11 @@ Modify *$ALF_INSTALL_DIR/tomcat/webapps/alfresco/WEB-INF/web.xml* and uncomment ``` -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 CORS /api/* diff --git a/BROWSER-SUPPORT.md b/BROWSER-SUPPORT.md index 16a9283ae8..8bd1bc2e3c 100644 --- a/BROWSER-SUPPORT.md +++ b/BROWSER-SUPPORT.md @@ -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: ``` -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b787b46130..d6b7d12e59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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 @@ -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*** ]. diff --git a/INTRODUCTION.md b/INTRODUCTION.md index c6b01b45fe..8a2cb8bdbe 100644 --- a/INTRODUCTION.md +++ b/INTRODUCTION.md @@ -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:

alfresco diff --git a/PREREQUISITES.md b/PREREQUISITES.md index b08a6f08eb..ffd3fd2fdf 100644 --- a/PREREQUISITES.md +++ b/PREREQUISITES.md @@ -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. + \ No newline at end of file diff --git a/README.md b/README.md index 05b4969a89..0a8ad26ca8 100644 --- a/README.md +++ b/README.md @@ -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.

yeoman logo

-### 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 - -

- AmazonWebservices Logo.svg -

- -To deploy directly on your AWS instance our demo shell click the button below: - - - ## 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.