mirror of
https://github.com/Alfresco/alfresco-content-app.git
synced 2025-07-24 17:31:52 +00:00
Improve documentation extension (#2266)
* improve documentation step 1 * improve documentation step 2 * improve documentation step 3 * move in tutorials * tutotrials * fix * fix * fix * fix links * metadata extension configutation * tutorials links revamp
This commit is contained in:
Eugenio Romano
GitHub
@@ -13,3 +13,9 @@ Learn more about developing with the Alfresco Content Application.
|
||||
- [Dialog actions](/tutorials/dialog-actions)
|
||||
- [How to create your first extension](/tutorials/how-to-create-your-first-extension)
|
||||
- [How to install an existing extension](/tutorials/how-to-install-an-existing-extension)
|
||||
- [Custom Route](/tutorials/custom-route)
|
||||
- [Dialog Actions](/tutorials/dialog-actions)
|
||||
- [File Preview](/tutorials/file-preview)
|
||||
- [File Lists](/tutorials/file-lists)
|
||||
- [Search Form](/tutorials/search-form)
|
||||
- [Content Metadata](/tutorials/content-metadata)
|
||||
|
||||
187
docs/tutorials/content-metadata.md
Normal file
187
docs/tutorials/content-metadata.md
Normal file
@@ -0,0 +1,187 @@
|
||||
---
|
||||
Title: Content Metadata
|
||||
---
|
||||
|
||||
## Custom Content Metadata layout
|
||||
|
||||
In this tutorial, we are going to implement the following features:
|
||||
|
||||
- [MetadataLayout oriented config](#metadata-layout-oriented-config)
|
||||
|
||||
### Metadata Layout oriented config
|
||||
|
||||
Update `your-app.extensions.json` file, and insert a new entry to the `features.content-metadata-presets.custom`section:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
......
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you need to configure the groups and properties in a more detailed way. With this type of configuration any property
|
||||
of any aspect/type can be "cherry picked" and grouped into an accordion drawer, along with a translatable title defined
|
||||
in the preset configuration.
|
||||
|
||||
In the example below we are going to display in a new group all the properties of the ```cm:versionable``` aspect
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
{
|
||||
"id": "custom.features",
|
||||
"title": "MY_CUSTOM_TITLE",
|
||||
"items": [
|
||||
{
|
||||
"id": "cm:versionable",
|
||||
"aspect": "cm:versionable",
|
||||
"properties": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example below we are going to display in a new group some of the ```cm:dublincore``` aspect:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
{
|
||||
"id": "custom.features.two",
|
||||
"title": "MY_CUSTOM_TITLE_TWO",
|
||||
"items": [
|
||||
{
|
||||
"id": "cm:dublincore",
|
||||
"aspect": "cm:dublincore",
|
||||
"properties": [
|
||||
"cm:rights",
|
||||
"cm:title"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
In the example below we are going to display in the same group a mix of ```cm:dublincore``` and ```cm:versionable```
|
||||
aspect:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
{
|
||||
"id": "custom.features.two",
|
||||
"title": "MY_CUSTOM_TITLE_TWO",
|
||||
"items": [
|
||||
{
|
||||
"id": "cm:dublincore",
|
||||
"aspect": "cm:dublincore",
|
||||
"properties": [
|
||||
"cm:rights",
|
||||
"cm:title"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "cm:versionable",
|
||||
"aspect": "cm:versionable",
|
||||
"properties": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
Note: empty aspect or aspect not associated to the node will not be displayed
|
||||
|
||||
# Exclude aspects or properties
|
||||
|
||||
|
||||
You can also exclude specific aspects by adding the exclude property. It can be either a string if it's only one aspect or an array if you want to exclude multiple aspects at once:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
{
|
||||
"id": "app.content.metadata.customSetting",
|
||||
"includeAll": true,
|
||||
"exclude": ["exif:exif", "owner:parameters"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
When using this configuration you can still whitelist aspects and properties as you desire. The example below shows this with an aspect-oriented config:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"content-metadata-presets": [
|
||||
{
|
||||
"custom": [
|
||||
{
|
||||
"id": "app.content.metadata.customSetting",
|
||||
"includeAll": true,
|
||||
"exclude": ["cm:dublincore", "owner:parameters"]
|
||||
},
|
||||
{
|
||||
"id": "custom.features.two",
|
||||
"title": "MY_CUSTOM_TITLE_TWO",
|
||||
"items": [
|
||||
{
|
||||
"id": "cm:dublincore",
|
||||
"aspect": "cm:dublincore",
|
||||
"properties": [
|
||||
"cm:rights",
|
||||
"cm:title"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "cm:versionable",
|
||||
"aspect": "cm:versionable",
|
||||
"properties": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
169
docs/tutorials/file-lists.md
Normal file
169
docs/tutorials/file-lists.md
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
Title: File Lists
|
||||
---
|
||||
|
||||
## Custom File lists layout
|
||||
|
||||
In this tutorial, we are going to implement the following features:
|
||||
|
||||
- [Add a column in the Files list using a Node property](#add-a-column-in-the-files-list-using-a-node-property)
|
||||
- [Replace a column in the Files list](#replace-a-column-in-the-files-list)
|
||||
- [Add a Column in the Files list using a custom template](#add-a-column-in-the-files-list-using-a-node-property)
|
||||
|
||||
## File lists layout
|
||||
|
||||
The file list layout of:
|
||||
- files
|
||||
- libraries
|
||||
- favoriteLibraries
|
||||
- shared
|
||||
- recent
|
||||
- favorites
|
||||
- trashcan
|
||||
- searchLibraries
|
||||
|
||||
are all defined in the `/src/assets/app.extensions.json` of the content-app.
|
||||
All the possible properties customizable in the column are:
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| id | `string` | | Unique identifier of the column |
|
||||
| key | `string` | | Data source key. Can be either a column/property key like `title` or a property path like `createdBy.name`. |
|
||||
| title | `string` | "" | Display title of the column, typically used for column headers. You can use the i18n resource key to get it translated automatically. |
|
||||
| type | `string` | "text" | Value type for the column. Possible settings are 'text', 'image', 'date', 'fileSize', 'location', and 'json'. |
|
||||
| class | `string` | | Additional CSS class to be applied to column (header and cells). |
|
||||
| sortable | `boolean` | true | Toggles ability to sort by this column, for example by clicking the column header. |
|
||||
| template | `string` | optional |Custom layout template ID |
|
||||
| desktopOnly | `string` | | Show the column only in bigger viewport |
|
||||
| order | `string` | | Visualization order of the column |
|
||||
|
||||
|
||||
#### Type
|
||||
|
||||
- **text** this will show the property as a plain text
|
||||
- **fileSize** will convert the text into kb/mb/gb as needed.
|
||||
- **json** Shows a JSON-formatted value
|
||||
- **date** For the `date` column type, the Angular [DatePipe](https://angular.io/docs/ts/latest/api/common/DatePipe-class.html) formatting is used.
|
||||
- **Location** this displays a clickable location link pointing to the parent path of the node.
|
||||
|
||||
### Add a column in the Files list using a Node property
|
||||
|
||||
Update the `your-app.extensions.json` file, and insert a new entry to the `features.documentList` section:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"documentList": {
|
||||
"files": [
|
||||
{
|
||||
"id": "app.files.type",
|
||||
"key": "nodeType",
|
||||
"title": "APP.DOCUMENT_LIST.COLUMNS.TYPE",
|
||||
"type": "text",
|
||||
"class": "adf-ellipsis-cell adf-expand-cell-5",
|
||||
"sortable": true,
|
||||
"desktopOnly": false,
|
||||
"order": 102
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now, once you run the application, you should see an extra column that contain the code of your custom component
|
||||
|
||||
### Replace a column in the Files list
|
||||
|
||||
In order to replace a column in the list you need to use the same `id` in your extension file. For example to replace the modifedOn column add the following JSON in `your-app.extensions.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"documentList": {
|
||||
"files": [
|
||||
{
|
||||
"id": "app.files.modifiedOn",
|
||||
"key": "modifiedByUser.displayName",
|
||||
"title": "APP.DOCUMENT_LIST.COLUMNS.MODIFIED_FROM",
|
||||
"type": "text",
|
||||
"class": "adf-ellipsis-cell",
|
||||
"sortable": true,
|
||||
"desktopOnly": true,
|
||||
"order": 40
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add a Column in the Files list using a custom component template
|
||||
|
||||
As first step we can create our custom component in our extension:
|
||||
```typescript
|
||||
import { NameColumnComponent } from '@alfresco/adf-content-services';
|
||||
import { Component, ChangeDetectionStrategy, ViewEncapsulation, ElementRef, OnInit, OnDestroy } from '@angular/core';
|
||||
import { AlfrescoApiService } from '@alfresco/adf-core';
|
||||
|
||||
@Component({
|
||||
selector: 'custom-template-column',
|
||||
template: `<div *ngIf="isFile()">
|
||||
This is a custom Template For File
|
||||
</div>
|
||||
<div *ngIf="!isFile()">
|
||||
This is a custom Template For Folders
|
||||
</div>
|
||||
`,
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
encapsulation: ViewEncapsulation.None,
|
||||
host: { class: 'adf-datatable-content-cell adf-name-column' },
|
||||
})
|
||||
export class CustomTemplateComponent extends NameColumnComponent implements OnInit, OnDestroy {
|
||||
|
||||
constructor(public elementRef: ElementRef, private apiService: AlfrescoApiService) {
|
||||
super(elementRef, apiService);
|
||||
}
|
||||
|
||||
isFile(){
|
||||
return this.node.entry.isFile;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
In order to understand how to register a custom component refer to the [Registration](/extending/registration) documentation
|
||||
Once your component is registered.
|
||||
Register your new template component:
|
||||
|
||||
```typescript
|
||||
extensions.setComponents({
|
||||
'app.columns.custom': CustomTemplateComponent,
|
||||
});
|
||||
```
|
||||
|
||||
Add your new Column in `your-app.extensions.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"documentList": {
|
||||
"files": [
|
||||
{
|
||||
"id": "app.files.custom",
|
||||
"key": "name",
|
||||
"title": "APP.DOCUMENT_LIST.COLUMNS.CUSTOM",
|
||||
"type": "text",
|
||||
"class": "adf-ellipsis-cell adf-expand-cell-5",
|
||||
"sortable": true,
|
||||
"template": "app.columns.custom",
|
||||
"desktopOnly": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
65
docs/tutorials/file-preview.md
Normal file
65
docs/tutorials/file-preview.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
Title: File preview
|
||||
---
|
||||
|
||||
### File preview from a plugin with custom route
|
||||
|
||||
There might be scenarios where you build a plugin with a custom route, and from that route you might want to preview a file within an overlay.
|
||||
When having a plugin's entry point in a custom route, using the `/view` root-level application routes for previewing a file might be contradictory, since hitting any of these urls results a navigation away from the original route implying a reload of the original route's entry component when closing the preview panel (navigating back).
|
||||
|
||||
#### Example
|
||||
|
||||
Let's say you have a custom plugin with which you can start a process with any of your files. The plugin registers a custom route (`start-process`) with its entry component, where the user can start a process.
|
||||
In this component the user can fill in a form with different values for text fields and selectboxes and select a file. But for file selection, we would like to provide a preview functionality (with the `PreviewComponent` provided by the core application) to let the user be sure that the right file was selected. Obviously having a form filled in values (but not saved) means, that we don't want to loose our filled in data just because we are previewing a file. Because of this we would like the file preview to be opened in an overlay mode. The core application has one overlay region already defined for this reason, called `viewer`. This is the named router outlet we need to target without route change.
|
||||
|
||||
#### Solution
|
||||
|
||||
In our plugin we need to do the following steps:
|
||||
|
||||
##### Registering the custom route in the plugin.json
|
||||
|
||||
We need to add the custom route with our entry component and its child route for the preview:
|
||||
|
||||
```json
|
||||
{
|
||||
"routes": [
|
||||
{
|
||||
"id": "start-process",
|
||||
"path": "start-process",
|
||||
"parentRoute": "",
|
||||
"layout": "app.layout.main",
|
||||
// The component we register to be our entry point for this particular route
|
||||
"component": "myplugin.components.start-process",
|
||||
"children": [
|
||||
{
|
||||
"id": "start-process-preview",
|
||||
// It can be accessed on the "/start-process(viewer:preview/nodeId)" route
|
||||
"path": "preview/:nodeId",
|
||||
"component": "app.components.preview",
|
||||
"data": {
|
||||
// Using history.back() when closing the preview
|
||||
"navigateBackAsClose": true,
|
||||
// Disabling complex action and buttons for the preview
|
||||
"simplestMode": true
|
||||
},
|
||||
// We would like to target that named router outlet which is used for the viewer overlay
|
||||
"outlet": "viewer"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Dispatching the right action within our component to open the file preview
|
||||
|
||||
```ts
|
||||
import { PluginPreviewAction } from '@alfresco/aca-shared/store';
|
||||
|
||||
@Component({...})
|
||||
export class StartProcessComponent {
|
||||
onFilePreview({ nodeId }) {
|
||||
this.store.dispatch(new PluginPreviewAction('start-process-cloud', nodeId));
|
||||
}
|
||||
}
|
||||
```
|
||||
82
docs/tutorials/search-form.md
Normal file
82
docs/tutorials/search-form.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
Title: Search Form
|
||||
---
|
||||
|
||||
## Custom search form
|
||||
|
||||
From version 2.5.0 ACA search support multiple search configurations.
|
||||
In this tutorial, we are going to implement the following features:
|
||||
|
||||
- [Add a new search form](#add-a-new-search-form)
|
||||
- [Replace a search form](#replace-a-search-form)
|
||||
- [Replace default search](#replace-default-search)
|
||||
|
||||
### Extension Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| id | `string` | | Unique identifier of the search |
|
||||
| name | `string` | "" | Display title of the form |
|
||||
| order | `string` | | Visualization order in the dropdown |
|
||||
| default | `boolean` | | if the search has to be used as default search |
|
||||
| aca:fields| `string[]`| | list of aspects property to add in the query and search in the value for the given text. The property will be concatenated in AND|
|
||||
|
||||
### Search configuration properties
|
||||
|
||||
In order to learn more about :
|
||||
-The search UI configuration possibilities refer to the [ADF Search configuration documentation](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/user-guide/search-configuration-guide.md)
|
||||
-The search Query configuration possibilities refer to the [Full text search reference documentation](https://docs.alfresco.com/search-services/latest/using/)
|
||||
|
||||
### Add a new search form
|
||||
|
||||
Update `your-app.extensions.json` file, and insert a new entry to the `features.search` section:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"search": [
|
||||
{
|
||||
"id": "app.search.custom_search",
|
||||
"order": 200,
|
||||
"name": "APP.SEARCH.MY_CUSTOM_SEARCH",
|
||||
"default": false,
|
||||
"aca:fields": [ "cm:name", "cm:title", "cm:description", "TEXT", "TAG"],
|
||||
"filterQueries": [
|
||||
{
|
||||
"query": "+ASPECT: 'cm:person'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
Note that the entries of the filterQueries array are joined using the AND operator.
|
||||
|
||||
### Replace a search form
|
||||
To replace an already present search form you need to add a new search configuration with the same `id` of an already present configuration
|
||||
|
||||
|
||||
### Replace default search
|
||||
To replace the default search with your configuration set to true the default field
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"search": [
|
||||
{
|
||||
"id": "app.search.custom_search",
|
||||
"order": 200,
|
||||
"name": "APP.SEARCH.MY_CUSTOM_SEARCH",
|
||||
"default": true,
|
||||
"aca:fields": [ "cm:name", "cm:title", "cm:description", "TEXT", "TAG"],
|
||||
"filterQueries": [
|
||||
{
|
||||
"query": "+ASPECT: 'cm:person'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user