inteligr8/alfresco-content-app
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-content-app.git synced 2025-05-12 17:04:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
alfresco-content-app/docs/getting-started.md
Denys Vuika 160226094d
extensibility docs update (#571) 
* docs: custom sidebar tabs

* update docs

* docs update, simplify extension schema

* test fixes
2018-08-17 13:44:01 +01:00

15 KiB
Raw Blame History

title
title
Getting Started

Getting Started

Prerequisites

This application uses the latest releases from Alfresco:

You also need node.js (LTS) installed to build it locally from source code.

The latest version of the Alfresco Content platform is required due to the application using the latest REST APIs developments.

Building from source

The Content App is based on Angular CLI, and you can use all the commands, generators and blueprints supported by the CLI.

Prerequisites for building

Cloning and running

Use the following commands to clone the project, install dependencies and run it.

git clone https://github.com/Alfresco/alfresco-content-app.git
cd alfresco-content-app
npm install
npm start

The application runs at port 4200 by default, and should automatically open in the default browser once project compilation finishes.

Proxy settings

The Content App provides a proxy configuration for local development server that allows you to address specific scenarios with CORS and native authentication dialog.

You can find settings in the "proxy.conf.js" file in the project root directory.

The proxy settings get automatically applied every time you run the application with "npm start" script. You must restart the application every time you change the settings values.

Running unit tests

Run npm test to execute the unit tests via Karma.

Internationalization (i18n)

The Content Application provides support for the following languages:

  • German (de)
  • English (en)
  • Spanish (es)
  • French (fr)
  • Italian (it)
  • Japanese (ja)
  • Norwegian (nb)
  • Dutch (nl)
  • Brazilian Portuguese (pt-BR)
  • Russian (ru)
  • Simplified Chinese (zh-CN)

The fallback locale is the English one, however current browser language is taken as the default one automatically when the application starts.

User-defined language

You can allow users to set custom language that gets saved to user preferences. The main application menu already has the ADF Language Menu component integrated and pre-filled with the supported items.

To change the default language set edit the app.config.json file and add or remove items:

{
    ...,
    "languages": [
        {
            "key": "de",
            "label": "German"
        },
        {
            "key": "en",
            "label": "English"
        },
        {
            "key": "es",
            "label": "Spanish"
        },
        ...
    ]
}

The file is located at the following path: /src/app.config.json.

Custom languages

To add a custom language, add a new "JSON" file to the "/src/assets/i18n" folder with the name of the target locale, for instance, a "de.json" for the "German".

Translate the resource strings based on the default "en.json" file. You can copy the content over to your newly created file and replace English values with translated text.

{
  "APP": {
    "SIGN_IN": "Anmelden",
    "SIGN_OUT": "Abmelden",
    "NEW_MENU": {
      "LABEL": "Neu",
      "MENU_ITEMS": {
        "CREATE_FOLDER": "Ordner erstellen",
        "UPLOAD_FILE": "Datei hochladen",
        "UPLOAD_FOLDER": "Ordner hochladen"
      },
      ...
    }
  },
  ...
}

The Content Application automatically bundles your file upon project build. You can test your locale by changing the browser language settings and reloading the page.

Optionally, you can extend the ADF Language Menu component with the newly added language by updating the app.config.json file.

Customizing ADF translations

In addition to creating a custom language file for the Content Application, you can also provide translations for the ADF resources.

Your /src/assets/i18n/<lang>.json file can reflect the structure of one of the ADF language files:

At runtime, the application-level strings have the highest priority. That means you can replace the value of any ADF resource string if needed.

For example, let's change the title of the "Create Folder" dialog shipped with the ADF. Modify the /src/assets/i18n/en.json file and append the "CORE" section like in the example below:

{
    "APP": {
        ...
    },
    "CORE": {
        "FOLDER_DIALOG": {
            "CREATE_FOLDER_TITLE": "Custom title"
        }
    }
}

Now, if you run the application and click the "New → Create Folder" menu, the title of the dialog should look like the following:

Language picker

You can enable internal language picker in the app.config.json file:

{
    ...,

    "languagePicker": true,

    ...
}

CORS

The ACA already comes with the proxy configuration for Angular CLI to address CORS-related issues for development. Also, the docker images contain Nginx settings needed for CORS when developing and debugging application locally.

Chrome Workaround

For the Chrome browser, you can use the following plugin that allows you to toggle CORS: Allow-Control-Allow-Origin

Firefox Workaround

Firefox users can try the following plugin: CORS Everywhere

Safari Workaround

If you are developing or testing with Safari then you can use the "Develop" menu to toggle the CORS mode. Please note that the page must be reloaded every time you change CORS settings.

See also

Configuration

The Content Application provides support for a global settings file app.config.json that you can use to customize the behavior of ACA and ADF components.

Server settings

Once the Content Application starts, it needs to know where the Alfresco Content Services (either Community or Enterprise) server is. The "ecmHost" property allows you to set the address of the server using the dynamic or static format.

Dynamic address

The example below demonstrates the most common dynamic format for development environment:

{
    "ecmHost": "http://{hostname}{:port}",
    ...
}

The configuration above assumes you are running ACS and Content App on the same server and port and allows deploying to different servers having the same unified configuration file.

For example, a proxy server at localhost:4200 hosting the Content App as the root application, and localhost:4200/alfresco for the ACS repository.

At runtime, the application is going to automatically substitute the "{hostname}" value with the original hostname. Optionally it can also use the value of the original port if present, for example, "4200" at local machines, or skip the value for port 80.

Static address

Alternatively, you can provide a static address for the ACS server if necessary:

{
    "ecmHost": "http://localhost:4200",
    ...
}

Application settings

There are many settings you can change to alter the default behavior of the application.

Application Name

The following block allows you to change the name of the application.

{
    ...,
    "application": {
        "name": "Alfresco Example Content Application"
    }
}

The value of the application.name key gets appended to every browser tab title at runtime with the format [page title] - [application name], for example: "Personal Files - Alfresco Example Content Application".

The default logo displayed in the top left corner of the Alfresco Content Application can be easily changed:

  1. Place your custom logo image file in the [app-name]/src/assets/images folder. The displayed image will resize automatically, an image with extreme width/height might not retain its dimensions.

  2. In the app.config.json file, set the value of the application.logo to contain the name of the custom logo image: "logo": "/assets/images/[image-name].[extension]"

{
    ...,
    "application": {
        "logo": "/assets/images/alfresco-logo-white.svg"
    }
}

Header Background color

You can change the header background color by specifying color code for the "headerColor" key:

{
    ...,
    "headerColor": "#2196F3"
}

Restricted content

You can restrict users from uploading certain types of files and folders by setting or extending the list of rules at the "files.excluded" path.

By default, the application ships with the following rules already predefined:

{
    ...,
    "files": {
        "excluded": [
            ".DS_Store",
            "desktop.ini",
            "thumbs.db",
            ".git"
        ]
    },
    ...
}

You can get more details on the supported rules in the following article: Upload Service.

Pagination settings

You can change the default settings of the pagination that gets applied to all the document lists in the application.

{
    ...,
    "pagination": {
        "supportedPageSizes": [
            25,
            50,
            100
        ]
    },
    ...
}

Your custom settings

You can store any information in the application configuration file, and access it at runtime by using the AppConfigService service provided by ADF.

Please refer to the AppConfigService documentation to get more details on Application Configuration features and API available.

Navigation

The Alfresco Content Application provides the following navigation links:

  • Personal Files
  • File Libraries
  • Shared
  • Recent Files
  • Favorites
  • Trash

The side navigation provides support to customize the appearance of the links by editing the app.config.json.

Customization

Navigation configuration supports array and object like schema. Defining an object helps navigation to render visual delimiters between different groups of links.

{
  "navigation": {
     "main": [
      ...
     ],
   "secondary": [
     ...
    ]
  }
}


{
  "navigation": [
    { ... },
    { ... },
    ...
  ]
}

Customize icons and text

icon - supported value can be anything from Material Design icons library. If not defined, the link will render just the label value.

title - instructs the link to render a native browser tooltip with the given value. It can be a string or a i18n defined reference. If not defined, the link will not show a tooltip.

label - represents the visual name of the link. It can be a string or a i18n defined reference.

Changing ` "route": { "url": "/..." } ` value will affect the navigation since these are mapped to application routing system.

Custom text (i18n)

To change the title and label of navigation links edit the values under BROWSE entry found at /src/assets/i18n/en.json

"APP" : {
  ...
  "BROWSE": {
    "PERSONAL": {
    "TITLE": "Personal Files",
    "SIDENAV_LINK": {
        "LABEL": "Personal Files",
        "TOOLTIP": "View your Personal Files"
      }
    },
    ...
  }
}

For more information about internationalization see Internationalization (i18n) section.

User-defined navigation

To add custom navigation link for the application, first we need to create a component.

src/app/components/custom-page/custom-page.component.ts

import { Component } from '@angular/core';

@Component({
template: `
    <h4>{{ title }}</h4>
    `
})
export class CustomPage {
    title = 'My Custom Page'
}

Register the component in app.module.ts


  ...
  import { CustomPage } from './components/custom-page/custom-page.component';

  @NgModule({
    ...
    declarations: [
        ...,
        CustomPage
    ],
    ...
})

In the app.config.json define a link entry which will point to the custom page

{
  ...,
  "navigation": [
      "main": [ ... ],
      "secondary": [ ... ],
      "custom": [
        {
          "icon": "work",
          "label": "Link",
          "title": "My custom link",
          "route": {
              "url": "/custom-route"
          }
        }
      ]
  ]
}

Map the /custom-route in app.routes.ts as a child of LayoutComponent definition.


  import { CustomPage } from './components/custom-page/custom-page.component.ts';

  ...
  {
    path: '',
    component: LayoutComponent,
    children: [
     ...,
     {
        path: 'custom-route',
        component: CustomPage
      }
    ]
  }
  ...,

For more information about the content of a custom page see Document List Layout section.

Docker

The ACA comes with the ACS 6.0 Community Edition preconfigured. The application runs in to modes:

  • Development (runs latest source code, requires building application)
  • Preview (runs with latest published containers, master branch)

Development Mode

Run the local instance of the application packaged into the docker image together with the ACS images:

npm run build
npm run start:docker

The ACA runs on port 4000 when served from within container.

Use the following command to stop all the containers:

npm run stop:docker

Preview Mode

With this mode, you do not need building application from source code or installing dependencies.

To run the latest published container go to the docker-compose folder and start docker compose from there:

cd docker-compose
docker-compose up

The application is available at the http://localhost:3000 address.