mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-3745] Updates for doc review (#3963)
* [ADF-3745] Updates for doc review * [ADF-3745] Updated tutorial index * [ADF-3745] Updated document list doc page
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
aab19708a2
commit
89fcdec5ef
@@ -14,12 +14,12 @@ The tutorials are graded as follows:
|
||||
|
||||
| Name | Level | Abstract |
|
||||
| -- | -- | -- |
|
||||
| [**Preparing the development environment**](preparing-environment.md) | Beginner | Here you will find the prerequisites for all the tutorials and descriptions of the entire documentation. This document contains the development environment description, along with the details of the suggested versions for each tool, library and module. |
|
||||
| [**Creating your first ADF application**](creating-your-first-adf-application.md) | Basic | This tutorial shows you how to set up your development environment and create an ADF application. |
|
||||
| [**Creating your ADF application using Yeoman**](creating-the-app-using-yeoman.md) | Basic | In this tutorial you are going to see how to create an ADF application from scratch, using the [Yeoman scaffolding tool](http://yeoman.io/). This is a "getting started" task that should enable you to start developing your own ADF application. |
|
||||
| [**Creating your Alfresco JavaScript application**](creating-javascript-app-using-alfresco-js-api.md) | Basic | In this tutorial you will learn how to create an application in JavaScript from scratch to interact with Alfresco. This is a "getting started" task that should enable you to start developing your own JavaScript application on top of Alfresco Content Services or Alfresco Process Services. |
|
||||
| [**Adding a new component**](new-component.md) | Basic | By definition, a _component_ controls a patch of screen called a _view_. For example, individual components define and control menus, tabs, forms, buttons and every simple or complex portion ofan application's layout. In this tutorial, you will learn how to create a component using [Angular CLI](https://cli.angular.io/) within an existing application. |
|
||||
| [**Adding a new view**](new-view.md) | Beginner | Every application developed in Angular is a single page application where the concepts of _view_ and _routing_ play a key role in the user experience. Being a single page application, the navigation between the different layouts (called _views_) is enabled through the _routing_. In this tutorial you will learn how to create a new view in your application and how to access it using a defined endpoint. |
|
||||
| [**Using components**](using-components.md) | Beginner | There are three different ways to use, extend and configure an ADF component: configuration properties, event listeners, and content projection / HTML extensions. In this tutorial you will see a practical example of each approach using the [Login component](../core/login.component.md). |
|
||||
| [**Using ADF Components**](using-components.md) | Basic | In this tutorial you will learn how to extend, use and configure ADF Components. |
|
||||
| [**Basic theming**](basic-theming.md) | Beginner | As detailed in the [user guide page about theming](../user-guide/theming.md), you can easily customize the [Cascading Style Sheets](https://en.wikipedia.org/wiki/Cascading_Style_Sheets) used by an ADF application. In this tutorial you will see how to modify the CSS, using a step-by-step approach. The focus of this tutorial is [ADF apps built using Yeoman](./creating-the-app-using-yeoman.md), but you can use the same principles to customize the themes in any ADF application. |
|
||||
| [**Customizing the Login component**](customising-login.md) | Intermediate | In this tutorial you will learn how to customize the [`Login` component](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) following the [technical documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html). The task will be very simple. See the documentation for further details about customizing this component, along with examples. |
|
||||
| [**Working with a Data Table**](working-with-data-table.md) | Intermediate | In this tutorial you will learn how to populate a [`DataTable` component](https://alfresco.github.io/adf-component-catalog/components/DataTableComponent.html) with custom data from a generic back-end service or third party API. As an example we are going to use data from one of the available services on Alfresco Content Services. However, the procedure is much the same if want to use an Alfresco Process Services endpoint or a third party API. |
|
||||
|
||||
99
docs/tutorials/creating-your-first-adf-application.md
Normal file
99
docs/tutorials/creating-your-first-adf-application.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
Level: Basic
|
||||
---
|
||||
|
||||
# Creating your first ADF application
|
||||
|
||||
This tutorial shows you how to set up your development environment and create an ADF application.
|
||||
|
||||
In order to get up and running with ADF development, you will need to install a few prerequisites: `node.js`, `Yeoman` and a code editor.
|
||||
Once you have the prerequisites installed, you need to create the application using the ADF Yeoman generator, then configure your ADF application to point to your Alfresco Content Services repository.
|
||||
|
||||
## Install node.js
|
||||
|
||||
You need the latest `node.js` `8.x` release, which you can download from [https://nodejs.org/en/](https://nodejs.org/en/). Choose the installer for your OS and follow the install instructions. Once completed, open a terminal and verify the installation with the following command:
|
||||
|
||||
node -v
|
||||
|
||||
Node `10.x` should work too, but we have had a few reports that it might not work out of the box for everyone.
|
||||
|
||||
**TIP**: If you are planning to do extensive development with ADF, `node.js` and Angular, you might consider installing a version manager for `node.js` such as [n](https://github.com/tj/n) or [nvm](https://github.com/creationix/nvm/). This tool will allow you to have multiple `node.js` versions installed at the same time, and easily switch between versions.
|
||||
|
||||
## Installing a code editor
|
||||
|
||||
All Angular development will be done using [Typescript](https://www.typescriptlang.org). With this in mind, it a great thing to have tools that make development a little easier, but really any text editor will do just fine.
|
||||
|
||||
We recommend [Visual Studio Code](http://code.visualstudio.com) - it's a free, lightweight and *very* powerful tool from Microsoft that works well with Angular development and has a [big ecosystem of plugins](https://marketplace.visualstudio.com/VSCode) to make the developer experience even better.
|
||||
|
||||
Other recommendations include IntelliJ IDEA or WebStorm from [JetBrains](https://www.jetbrains.com) *but note that the community edition does not support [Typescript](https://www.typescriptlang.org).*
|
||||
|
||||
|
||||
## Install ADF Yeoman generator
|
||||
|
||||
**Note:** If you're on Linux or macOS you might need to run these commands with `sudo`
|
||||
|
||||
|
||||
|
||||
|
||||
You need to ensure you have `Yeoman` installed by running `yo --version`. If this is not in your system you should run:
|
||||
|
||||
npm install -g yo
|
||||
|
||||
Now install the latest version of the `generator-alfresco-adf-app`:
|
||||
|
||||
npm install -g generator-alfresco-adf-app
|
||||
|
||||
|
||||
## Create your first ADF application
|
||||
|
||||
Now that we have all the prerequisites in order, it's time to generate an application:
|
||||
|
||||
yo alfresco-adf-app
|
||||
|
||||
Enter a name and choose `Content Services` as the application blueprint, then enter `Y` to install the dependencies.
|
||||
|
||||
The `Yeoman` generator will now create a new project and install all dependencies required for your application.
|
||||
|
||||
## Configure ADF to work with Alfresco Content Services
|
||||
|
||||
The next step is to open up the newly-created project in your code editor, and open the file `proxy.conf.json`. Change the `target` property in this file so it points to your Alfresco Content Services URL and port. Please refer to your installation guide to find this URL, or if you're running an online trial you will find the information in the email.
|
||||
|
||||
Modify `"target": "http://localhost:8080",` so that it matches your URL and save the file.
|
||||
|
||||
Please note that you do not need `/alfresco` at the end of the target URL. Let's say you've launched Alfresco Content Services 6.1 using [Docker Compose](https://docs.alfresco.com/6.0/tasks/deploy-docker-compose.html). Your Alfresco Content Services repository might be available at `http://localhost:8082/alfresco`. In this case you will want the `proxy.conf.json` file to look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"/alfresco": {
|
||||
"target": "http://localhost:8082",
|
||||
"secure": false,
|
||||
"changeOrigin": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Start the application
|
||||
|
||||
To run the project, open a terminal and run
|
||||
|
||||
npm start
|
||||
|
||||
A browser will automatically open up at `http://localhost:4200`.
|
||||
|
||||
|
||||
|
||||
Click the key icon in the side navigation and you can now log in!
|
||||
|
||||
*Note:* If you're running an online trial you can find your login credentials in the welcome email.
|
||||
|
||||
Take a few minutes to explore your application. You have the basic features: Browsing the repository, uploading and previewing documents.
|
||||
|
||||
|
||||
# Next step
|
||||
|
||||
Congratulations! You're now ready to start developing your first ADF application!
|
||||
|
||||
In the next tutorial you will explore how you can extend, use and configure ADF Components by customizing the login screen.
|
||||
|
||||
* [Extend, use and configure ADF Components](customising-login.md)
|
||||
|
||||
@@ -1,148 +1,174 @@
|
||||
---
|
||||
Level: Beginner
|
||||
Level: Basic
|
||||
---
|
||||
|
||||
# Using components
|
||||
# Using ADF Components
|
||||
|
||||
There are three different ways to use, extend and configure an ADF component: configuration properties, event listeners, and content projection / HTML extensions. In this tutorial you will see a practical example of each approach using the [Login component](../core/login.component.md).
|
||||
In this tutorial you will learn how to extend, use and configure ADF Components.
|
||||
|
||||
The ADF documentation is always a good starting point when you plan to use a component. In general,
|
||||
there are three different ways to use, extend and configure an ADF component:
|
||||
|
||||
|
||||
1. Configuration properties.
|
||||
2. Event listeners.
|
||||
3. Content projection / HTML extensions.
|
||||
We will be customizing the [Login component](../core/login.component.md) as an example, where we will remove the `Remember me`, `Need Help?` and `Register` links in the footer and setup an event listener that displays an alert when the login form is submitted. We will finish off by setting up a custom footer.
|
||||
|
||||
## Configuration properties
|
||||
The final result will look like this:
|
||||
|
||||
Angular components can easily be configured via properties in the HTML template. In this example we will
|
||||
work with the "Remember me" checkbox and "Need Help?" and "Register" links in the footer of the [Login component](../core/login.component.md).
|
||||
|
||||
|
||||
To prepare for the task, make sure you have your ADF application up and running by executing `npm start`
|
||||
in a terminal from the root folder of the project. Access the login page using your browser and edit the [`login.component`](../core/login.component.md)`.html` file stored in the `src/app/.../login` folder. The content of the [`login.component`](../core/login.component.md)`.html` file should look like the following:
|
||||
We have carefully picked these three customizations because they cover the three fundamental ways you can ways to use, extend and configure ADF Components:
|
||||
|
||||
1. Configuration Properties
|
||||
2. Event Listeners
|
||||
3. HTML Extensions / _Content Projection_
|
||||
|
||||
You should always consult the documentation for the component you are looking to use. For this exercise it would be useful to open a browser window with the [Login Component](../core/login.component.md)
|
||||
documentation.
|
||||
|
||||
Let's do a practical example with each approach.
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
Angular components can easily be configured via properties in the HTML template. In this example we will remove the `Remember me`, `Need Help?` and `Register` links in the footer.
|
||||
|
||||
Make sure you have the application running from the [previous tutorial](creating-your-first-adf-application.md).
|
||||
|
||||
Open the project in a code editor. It's best to open the entire folder so it will be easier to switch between files.
|
||||
|
||||
Open the `src/app/login/login.component.html` file. The contents will look like this:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
copyrightText="© 2017 - 2018 Alfresco Software, Inc. All rights reserved."
|
||||
providers="ECM"
|
||||
...
|
||||
>
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Looking at the documentation, you can see that the `<adf-login/>` component has a lot of different
|
||||
properties. As an example we will toggle `showRememberMe` and `showLoginActions` (all set to `true`
|
||||
by default). If you haven't specified any values for these properties in the source code then set them both
|
||||
to `false` using the syntax shown in the example below. If you have specified values in the source code then
|
||||
set them to the opposite value in the HTML template (set them to `true` if they are `false` in the source
|
||||
and vice versa).
|
||||
Looking at the documentation, we can see that the `<adf-login/>` component has a lot of different properties. The ones we are interested in are `showRememberMe` and `showLoginActions`. These are set to `true` by default, but we can easily change them like this:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
copyrightText="© 2017 - 2018 Alfresco Software, Inc. All rights reserved."
|
||||
providers="ECM"
|
||||
[showRememberMe]="..."
|
||||
[showLoginActions]="..."
|
||||
...
|
||||
>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
After saving the HTML template, you will see the login page updated with a different layout matching the
|
||||
new property values.
|
||||
Save the file. The browser will automatically reload once the file is saved. The result will look like this:
|
||||
|
||||
**Note:** The two new properties are specified with `[]` around them. There are three ways to configure a
|
||||
property:
|
||||
|
||||
|
||||
1. `[property]=""` This sets the property using an expression or another property from the Typescript
|
||||
controller. Use this syntax for boolean expressions or variables.
|
||||
2. `property=""` This value will be passed as raw text.
|
||||
3. `[(property)]` This is called _banana in a box_ and is used for two way binding.
|
||||
**Note:** The two new properties are specified with `[]` around them. There are three ways to configure a component property:
|
||||
|
||||
## Event listeners
|
||||
1. `[property]=""` This will be an expression or property from the typescript controller. Use this for boolean expressions or variables
|
||||
2. `property=""` This will be passed in as raw text
|
||||
3. `[(property)]` This is called _banana in a box_ and is used for two way binding
|
||||
|
||||
Now that you've successfully configured properties on the `<adf-login/>` component, it's time to look at events.
|
||||
## Event Listeners
|
||||
|
||||
Looking now at the events section of the
|
||||
[Login component documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html)
|
||||
we can see that it emits three events: `success`, `error` and `executeSubmit`.
|
||||
Now that we've successfully configured properties on the `<adf-login/>` component, it's time to look at events.
|
||||
|
||||
We can subscribe to these events and have our custom code executed when they are emitted. We will
|
||||
hook into the `executeSubmit` event and show a simple `alert()` when the form is submitted.
|
||||
Again, looking at the [Login Component](../core/login.component.md)
|
||||
docs, we can see that it emits three events: `success`, `error` and `executeSubmit`.
|
||||
|
||||
Back in the [`login.component`](../core/login.component.md)`.html` file, add `(success)="mySuccessMethod($event)"` to the `<adf-login/>` component (the position is not relevant).
|
||||
We can subscribe to these events and have our custom code executed when these events are emitted. Let's hook into the `executeSubmit` and do a simple `alert()` when the form is submitted.
|
||||
|
||||
Open `src/app/login/login.component.html` and add `(success)="mySuccessMethod($event)"` to the `<adf-login/>` component:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
...
|
||||
(executeSubmit)="myExecuteSubmitMethod($event)"
|
||||
>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
(success)="mySuccessMethod($event)"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Next, implement `myExecuteSubmitMethod` in the Typescript class that defines the component. Edit
|
||||
the [`login.component`](../core/login.component.md)`.ts` file stored in the same `src/app/.../login` folder and add the implementation
|
||||
of `myExecuteSubmitMethod` as follows:
|
||||
Next we need to implement `mySuccessMethod` in the typescript. Open `src/app/login/login.component.ts` and add a new method:
|
||||
|
||||
```ts
|
||||
// Add this!
|
||||
mySuccessMethod(event: any) {
|
||||
alert('Form was submitted!');
|
||||
console.log(event);
|
||||
}
|
||||
```
|
||||
|
||||
The complete file should now look like this:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
|
||||
@Component({
|
||||
...
|
||||
selector: 'app-login',
|
||||
templateUrl: './login.component.html',
|
||||
styleUrls: ['./login.component.css']
|
||||
})
|
||||
export class LoginComponent {
|
||||
|
||||
...
|
||||
|
||||
// Add this!
|
||||
myExecuteSubmitMethod(event: any) {
|
||||
// Add this!
|
||||
mySuccessMethod(event: any) {
|
||||
alert('Form was submitted!');
|
||||
console.log(event);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After saving both files, the [login component](../core/login.component.md) will be refreshed in your browser. Enter random values for
|
||||
the username and password and you should see the alert after pressing the submit button. Looking in the
|
||||
console of the browser, you'll see the `event` data containing all the details of the form.
|
||||
Save the files, go to the [login component,](../core/login.component.md) enter a valid username and password and you should now see an alert. Looking in the console in the browser, you'll see the event data. Here we get all the details for the form.
|
||||
|
||||
**Bonus objective:** Add a custom logo and background to the login view using the relevant properties
|
||||
described in the documentation.
|
||||
## Content Projection / HTMl Extensions
|
||||
|
||||
## Content projection / HTML extensions
|
||||
The last way a component can be configured or extended is through an approach called Content Projection. This allows components to put placeholders in their template, allowing developers to "project" their own code or components into pre-defined locations within the component.
|
||||
|
||||
The final way to configure or extend a component is through an approach called _Content projection_. This
|
||||
involves adding placeholders to a component template, allowing developers to "project" their own code or
|
||||
components into pre-defined locations within the component.
|
||||
|
||||
In regular HTML, elements can be nested. For example:
|
||||
In normal HTML, elements can be nested, for example:
|
||||
|
||||
```html
|
||||
<div>
|
||||
<p>
|
||||
<b>Here we have some bold text</b>
|
||||
</p>
|
||||
<p>
|
||||
<b>Here we have some bold text</b>
|
||||
</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
We can use the same approach with ADF components to inject custom code or entire components into another
|
||||
component. The documentation shows which targets are available. For example, the `<adf-login/>` component
|
||||
supports two targets: `login-header` and `login-footer`. Let's add a simple "Hello World" message in the
|
||||
footer. Edit the template [`login.component`](../core/login.component.md)`.html` and add a new tag _inside_ the `<adf-login/>` tag:
|
||||
We can use the same approach with ADF Components to inject custom code or whole components into the ADF component.
|
||||
|
||||
The documentation gives information about which targets are in place. Components that support content
|
||||
project have a
|
||||
[Transclusions](../user-guide/transclusion.md)
|
||||
section in the doc page with all the relevant details.
|
||||
|
||||
The `<adf-login/>` component supports two targets: `login-header` and `login-footer`.
|
||||
|
||||
Let's add a simple Hello World message in the footer. Open the template `src/app/login/login.component.html` and add a new tag _inside_ the `<adf-login/>` HTML tag:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
...
|
||||
>
|
||||
<login-footer>
|
||||
<ng-template>
|
||||
Hello World!
|
||||
</ng-template>
|
||||
</login-footer>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
(executeSubmit)="myExecuteSubmitMethod($event)"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
<login-footer>
|
||||
<ng-template>
|
||||
Hello World!
|
||||
</ng-template>
|
||||
</login-footer>
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Make sure that you place the `<login-footer/>` tag _inside_ the `<adf-login/>` tag. Inside the
|
||||
`<login-footer/>` or `<login-header/>` tags you can put anything you want, as long as you wrap it inside
|
||||
an `<ng-template/>` tag. You can also add custom or 3rd party components.
|
||||
Be careful that you place the `<login-footer/>` tag _inside_ the `<adf-login/>` tag.
|
||||
|
||||
When you are done, save the template and you should see a "Hello World!" message in the footer of your
|
||||
login page when the browser refreshes.
|
||||
Inside the `<login-footer/>` or `<login-header/>` tags we can put anything we want, as long as we wrap it inside an `<ng-template/>` tag. We can also source in custom or 3rd party components.
|
||||
|
||||
### Bonus objective: Add a custom logo and background to the login screen
|
||||
|
||||
Are you up for a challenge? Explore the [Login component](../core/login.component.md)
|
||||
docs to find out how you can change the logo and background image!
|
||||
|
||||
# Next steps
|
||||
|
||||
We have a number of tutorials for you to explore. Here are a few suggested ones to try next:
|
||||
|
||||
- [Basic theming](basic-theming.md)
|
||||
- [Create a new page](new-view.md)
|
||||
- [Adding a new component](new-component.md)
|
||||
|
||||
Reference in New Issue
Block a user