Salsah [Deprecated]

The System for Annotation and Linkage of Sources in Arts and Humanities (Salsah) is the generic user interface for Knora. This version of Salsah works fine with Knora v 2.4 and at the moment it will not support higher versions! Salsah was replaced by the simple user interface for DaSCH, which is called --> KUIRL.

---

Salsah is developed by the Digital Humanities Lab at the University of Basel, and is supported by the Swiss Academy of Humanities and Social Sciences.

Salsah is free software, released under the GNU Affero General Public License.

The project was generated with angular-cli.

You find more information about Salsah on:

https://dhlab-basel.github.io/Salsah/

Developer Environment

If you're a developer and you want to improve the app, please have a look at the developer guideline first:

https://dhlab-basel.github.io/Salsah/02-developer-hints/structure/

Prerequisites

We develop the Salsah app with Angular (v6), especially with Angular-cli, which requires the following tools:

Node

Install Node in version >=4 <=9. We recommend to use version 8.9.0.

The easiest way to install node in the correct version is to use 'n'.

Yarn (instead of npm)

By installing node, you get the node package manager (npm), which will be used for the app dependency management. But we recommend to use yarn instead of npm.

Install yarn by following the instructions on their website.

Angular-cli

To start the app or to create new components and services, you need angular-cli, which should be installed globally.

$ yarn global add @angular/cli

Getting started

Install the app dependencies

After cloning the Salsah code, install the needed node packages from the Salsah root directory:

$ cd /path/to/your/salsah/installation

$ yarn install --production=false

Start the Salsah app

Now you can start the app with

$ ng serve

which will run a server and the app in a developer mode on http://localhost:4200/.

By changing the code, the app will automatically compile and reload the page.

If you have any trouble to start the Salsah app with ng, you should have a look on the angular-cli documentation.

Developer hints

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive/pipe/service/class.

The SALSAH structure contents two main directories: model and view.

• The model directory contains angular services and everything else for API data requests. → At the moment, there are only a few services left. We moved all main services (Knora API request services) to the @knora/core module.

• The view directory contains all templates (angular components), pipes and directives. Pipes and directives are should be placed in view/modules/other/. → Here we also moving all generic components, pipes and directives to one of the Knora-ui modules.

Get more information about the status of the Knora-ui modules in this repo: https://github.com/dhlab-basel/Knora-ui

---

The command to create new component, e.g. a component to handle image objects, should look as follow:

ng g component view/object/image-object

"image-object" is the name for the new component.

Please read the Angular-cli documentation about the "generate" command.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the -prod flag for a production build.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor. Before running the tests make sure you are serving the app via ng serve.

Further help

To get more help on the angular-cli use ng --help or go check out the Angular-CLI README.

Code style

We develop Salsah with with angular-cli and the WebStorm editor by JetBrains. This editor (but also many others) is able to read the .editorconfig file in the Salsah root directory. It’s a configuration definition for the typescript- and the scss-lint tools. The following recommendations are important:

We use spaces instead of tabs (indent_style) with a size of 4 (indent_size).

There's one exception! For the styling we implemented Material and write own style with sass scss files, which has a indent size of 2.

For the typescript code styling, we’re following the TSLint recommendation. Please set your editor configuration as described there. It helps on reformat code (one cool function in WebStorm). One important point is to use single quotes always. Please set the TS punctuation settings to “use single quotes always”

Commit Message Schema

When writing commit messages, we stick to this schema:

type (scope): subject
body

Types:

• feature (new feature for the user)
• fix (bug fix for the user)
• docs (changes to the documentation)
• style (formatting, etc; no production code change)
• refactor (refactoring production code, eg. renaming a variable)
• test (adding missing tests, refactoring tests; no production code change)
• build (changes to node, node_modules, angular2, etc.; no production code changes)
• enhancement (residual category)

Example:

feature (resources route): add route for resource creation
- add path for multipart request
- adapt handling of resources responder