Otter Framework

Description

The Otter Project has the goal to provide a common platform to accelerate and facilitate the development on web application based on Angular. Otter is a very module framework split in several unit working together on a common base allowing CMS customization.

Note: The full documentation is available here.

Built With

• Angular
• Typescript
• RxJs
• Redux
• Sass
• Nx

Get Started

A new application can be with the simple commands:

# Starting a new angular application
npm install -g @angular/cli
ng new my-app

# Add Otter framework
ng add @o3r/core

Note: Please refer to Otter Get Started and Angular Get Started documentations for complete documentation

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

Please refer to Security file.

License

Please refer to the License file.

Acknowledgments

The Otter Team is responsible for the review of the code of this repository. Any bug of feature request can be addressed via issue report.

Developer

Building and Testing library

This document describes how to set up your development environment to build and test library. It also explains the basic mechanics of using git, node, and npm.

• Description
• Built With
• Get Started
• Contributing
• Versioning
• License
• Acknowledgments
• Developer
  • Building and Testing library
    • Prerequisite Software
    • Getting the Sources
    • Installing NPM Modules
    • Build command
    • Running tests locally
    • Manage task cache
    • Debugging with Visual Studio Code
    • Link local packages

See the contribution guidelines if you'd like to contribute to framework.

Prerequisite Software

Before you can build and test Otter modules, you must install and configure the following products on your development machine:

• Git and/or the GitHub app (for Mac or Windows); GitHub's Guide to Installing Git is a good source of information.

• Node.js, (version >=10.0.0) which is used to run tests, and generate distributable files. We also use Node's Package Manager, npm (version >3.8.x), which comes with Node. Depending on your system, you can install Node either from source or as a pre-packaged bundle.

• Yarn, a Node's Package Manager. You can install yarn using NPM manager (coming with Node.js). The version of Yarn currently used is embedded in the repository. In case you need to link this library with your project, you can check the section "Link local packages"

• Chrome, we use Chrome to run our tests.

Getting the Sources

Clone the Otter repository:

1. Login to Github enterprise using your P-Account.
2. Clone the project using the button Code or using the following git command

git clone https://github.com/AmadeusITGroup/otter.git

Installing NPM Modules

Next, install the JavaScript modules needed to build:

# Install library project dependencies (package.json)
yarn install

Build command

To build the modules, run:

yarn run build

Each module can be built independently thanks to Nx commands:

# ex: Build Core package only
yarn nx build core

Notes: Results are put in the dist of each modules (packages/@<scope>/<module>/dist).

Running tests locally

Check the formatting :

yarn run lint

Check Unit Test :

yarn run test

Each module can be test independently thanks to Nx commands:

# ex: Test Core package only
yarn nx test core

# ex: Lint Core package only
yarn nx lint core

Manage task cache

When running the Build, Lint or Test commands, Nx can use its cache mechanism. For some reason, it can be useful to clean the cache to investigate issue, this can be done via the following command:

yarn nx reset

Debugging with Visual Studio Code

The repository embedded the mandatory configuration and recommended VSCode plugging to be the most comfortable possible to develop on the Otter Framework.

The default configuration of the repository provide a way to run Unit Test one per one and to define, within VSCode, break points using the vscode-jest-tests debugger task.

The Otter Demo Application, included in the folder apps/@o3r/demo can be run by the following command:

yarn start

Link local packages

With Yarn v1, in the main package.json, add a resolutions property with the relative path to the dist of the local package, the protocol link: can be used. NOTE: It will not bring dependencies of the linked package.

Example:

{
  "resolutions": {
    "@o3r/localization": "./relative/path/to/otter/packages/@o3r/localization/dist",
    "@o3r/core": "link:./relative/path/to/otter/packages/@o3r/core/dist",
  }
}

With Yarn v2+, the protocol portal: can also be used NOTE: With the portal protocol it will bring all the dependencies of the linked package. Some issues can happen because of the mismatch version of these dependencies.

Example:

{
  "resolutions": {
    "@o3r/localization": "./relative/path/to/otter/library/@o3r/localization/dist",
    "@o3r/core": "link:./relative/path/to/otter/library/@o3r/core/dist",
    "@o3r/rules-engine": "portal:./relative/path/to/otter/library/@o3r/rules-engine/dist",
  }
}