diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 908382dee..886b6d1c5 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -90,7 +90,7 @@ jobs: changelog-types: '[{"type": "feat", "section": "Enhancements", "hidden": false }, {"type": "fix", "section": "Bug Fixes", "hidden": false }, {"type": "chore", "section": "Maintenance", "hidden": false }, {"type": "docs", "section": "Documentation", "hidden": false }]' publish: - name: Publish to npm + name: Publish to npm (on release only) needs: [build-test, e2e-test] runs-on: ubuntu-latest env: @@ -127,3 +127,53 @@ jobs: uses: lakto/google-chat-action@main with: url: ${{ secrets.GOOGLE_CHAT_DSP_RELEASES_WEBHOOK_URL }} + + # build documentation + docs-build-test: + name: Docs Build Test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 1 + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + - name: Disk Free + run: | + df -h + docker system df + docker system prune --all --force --volumes + df -h + - name: run docs build + run: make docs-build + - name: Disk Free After + run: | + df -h + docker system df + + # deploy documentation only on release + deploy-docs: + name: Deploy docs (on release only) + needs: [ + docs-build-test + ] + runs-on: ubuntu-latest + if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags') + steps: + - name: Checkout main + uses: actions/checkout@v2 + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} + REQUIREMENTS: docs/requirements.txt + - name: Disk Free After + run: | + df -h + docker system df diff --git a/.gitignore b/.gitignore index 140282d03..333f18008 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ /dist /tmp /out-tsc +/site # Only exists if Bazel was run /bazel-out diff --git a/Makefile b/Makefile index 2141f3a95..72bb12496 100755 --- a/Makefile +++ b/Makefile @@ -8,9 +8,36 @@ include vars.mk .PHONY: clean -# Clones the knora-api git repository +################################# +# Documentation targets +################################# + +.PHONY: docs-publish +docs-publish: ## build and publish docs to github Pages + mkdocs gh-deploy + +.PHONY: docs-build +docs-build: ## build docs into the local 'site' folder + mkdocs build + +.PHONY: docs-serve +docs-serve: ## serve docs for local viewing + mkdocs serve + +.PHONY: docs-install-requirements +docs-install-requirements: ## install requirements + pip3 install -r docs/requirements.txt + +.PHONY: docs-clean +docs-clean: ## cleans the project directory + @rm -rf site/ + +################################# +# Knora stack (DSP-API) targets +################################# + .PHONY: clone-knora-stack -clone-knora-stack: +clone-knora-stack: # Clones the knora-api git repository @rm -rf $(CURRENT_DIR)/.tmp/knora-stack @git clone --branch $(API_VERSION) --single-branch --depth 1 https://github.com/dasch-swiss/dsp-api.git $(CURRENT_DIR)/.tmp/knora-stack diff --git a/README.md b/README.md index 5e89be05a..30da38086 100644 --- a/README.md +++ b/README.md @@ -1,193 +1,46 @@ -# DSP-UI-LIB — A library to easily create Knora/DSP Apps +# DSP-UI — A library to easily create DSP Apps [![npm version](https://badge.fury.io/js/%40dasch-swiss%2Fdsp-ui.svg)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) -[![CI](https://github.com/dasch-swiss/knora-ui-ng-lib/workflows/CI/badge.svg)](https://github.com/dasch-swiss/knora-ui-ng-lib/actions?query=workflow%3ACI) +[![CI](https://github.com/dasch-swiss/dsp-ui-lib/workflows/CI/badge.svg)](https://github.com/dasch-swiss/dsp-ui-lib/actions?query=workflow%3ACI) [![npm downloads](https://img.shields.io/npm/dt/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) [![minzipped size](https://img.shields.io/bundlephobia/minzip/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) [![license](https://img.shields.io/npm/l/@dasch-swiss/dsp-ui.svg?style=flat)](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/LICENSE) -## Introduction + -This is the demo and developing environment for the NPM package [DSP-UI-LIB (@dasch-swiss/dsp-ui)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui). +DSP-UI is a library of angular modules enabling users to interact with [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/) to create a web application in a quick and simple way. These modules, comprised of components and directives, are written in Typescript and rely on [Angular material](https://material.angular.io). -The modules contained in DSP-UI-LIB help create an [Angular](https://angular.io) application to allow the user to connect to [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/) -in a quick and simple way. -Components and directives rely on [Angular Material](https://material.angular.io). - -DSP-UI-LIB is [free software](http://www.gnu.org/philosophy/free-sw.en.html), +DSP-UI is developed by the [Data and Service Center for the Humanities](https://dasch.swiss) as [free software](http://www.gnu.org/philosophy/free-sw.en.html), released under [GNU Affero General Public](http://www.gnu.org/licenses/agpl-3.0.en.html) license. -## Structure of This Project - -This project consists of two main parts: -1. The Angular library `DSP-UI-LIB (@dasch-swiss/dsp-ui)` in `project/dsp-ui`. -1. The demo Angular Application (Playground) in `src/app`. - -The Angular library contains the code that is published on NPM. -The demo Angular application's purpose is to demonstrate the library's functionality. -The library needs to be built first in order to use it withing the demo application. - -The demo application uses the **locally built version** of `@dasch-swiss/dsp-ui` -which is configured in [tsconfig.json](tsconfig.json) (`compilerOptions.paths`), -see [Angular docs](https://angular.io/guide/creating-libraries#building-and-rebuilding-your-library). - -## Prerequisites - -### Node.js - -Angular requires a [current, active LTS, or maintenance LTS](https://angular.io/guide/setup-local#prerequisites) version of Node.js. - -We recommend using [n](https://www.npmjs.com/package/n), -a tool that installs and manages Node.js versions on your local system. - -### NPM package manager - -Angular requires the [npm package manager](https://angular.io/guide/setup-local#prerequisites). - -### DSP-API - -The demo application requires a running instance of [DSP-API (Knora)](https://docs.knora.org/04-publishing-deployment/getting-started/) -compatible with the version defined in [vars.mk](vars.mk). - -## First steps - -Clone this repository: - -```bash -git clone https://github.com/dasch-swiss/dsp-ui-lib/ -``` - -Install the dependencies with: - -```bash -npm install -``` - -Build the library with: - -```bash -npm run build-lib -``` - -Run the demo application: - -```bash -npm run ng s -``` - -And access `http://localhost:4200` in your browser. - -**When you are developing the library -you always have to rebuild the library before using it from the demo application.** +## Documentation -## Scripts For Development +### ➡ [Getting started](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/getting-started/) -The following scripts can be used for development: +### Library modules -### Testing -- `npm test`: runs the unit tests of the demo application and the lib's unit tests. -- `npm test-lib`: runs the lib's unit tests in headless mode (no browser UI). -- `npm test-lib-local`: runs the lib's unit test with the browser UI (for local development of the lib). -- `npm run webdriver-update`: installs Chrome webdriver in the required version for the E2E tests. -- `npm run e2e`: runs the E2E tests from the demo application, see section [E2E Tests](README.md#Unit and E2E Tests). +The library consists of four Angular modules that are briefly described below. -### Building -- `npm run build`: builds the lib in productive mode, see section [Building the Library](README.md#Building the Library). -- `npm run build-dev`: builds the lib in development mode, see section [Building the Library](README.md#Building the Library). -- `npm build-app`: builds the demo application in productive mode, see also section [Run the application in productive mode](README.md#Run the application in productive mode) -- `npm run yalc-publish-lib`: builds the lib and publishes it locally using `yalc`. +### ➡ [DspCoreModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/core/) -## Library Build Options +*Services for API requests* +> DspCoreModule is a configuration handler for [`@dasch-swiss/dsp-js`](https://www.npmjs.com/package/@dasch-swiss/dsp-js) which offers all the services to make [DSP-API requests](https://docs.dasch.swiss/developers/knora/api-reference/queries/). -The library is built in productive mode for publication, using [tsconfig.lib.prod.json](projects/dsp-ui/tsconfig.lib.prod.json). +### ➡ [DspViewerModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/viewer/) -To perform additional checks during development, the library can be built in development mode, -using [tsconfig.lib.json](projects/dsp-ui/tsconfig.lib.json). Development builds use Ivy and perform [strict template checks](https://angular.io/guide/template-typecheck#template-type-checking). +*Resources, Properties, Lists, Value components* +> DspViewerModule contains object components to show a resource class representation, the property gui-elements and various view frameworks. -## Unit Tests and E2E Tests +### ➡ [DspSearchModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/search/) -There are unit tests for the lib (`projects/dsp-ui/src`) -and some basic unit tests for the demo application playground components (`src/app`). +*Search panel for all kind of search queries* +> DspSearchModule allows to make full text or extended searches in DSP-API. Filter by resource class and its properties related to an ontology. -The E2E tests have to be run from the demo application. -Unlike the unit tests, they require a running instance of DSP-API compatible with the release specified in [vars.mk](vars.mk). -Before running the E2E tests, reload the data in DSP-API's db. -The E2E tests can be run as follows: -- `npm run webdriver-update` -- `npm run e2e` +### ➡ [DspActionModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/action/) -## Demo Application (Playground) - -### Add a New Component to the Demo Application - -The demo app demonstrates the functionality of dsp-ui-lib's modules. -By default, the demo app's main component routes to the page demonstrating the resource viewer in read mode. - -Before adding a new component to the demo app, -check if the desired demo could be added to an existing component of the demo app. - -Follow these steps to add a new component to the demo app: -- create a new component in the demo app: - - create a new component using Angular CLI in `src/app` - - demonstrate a part of dsp-ui-lib (component, service etc.) in the new component of the demo app -- in `AppRoutingModule` and `AppComponent`'s template, set up the routing for your new component in the demo app. - -### Run the Application Locally in Dev Mode With Live Reloading - -To make changes to the DSP-UI and have your changes reflected immediately upon saving, follow these steps: - -- run `npm run build-watchful-lib-dev` from the project root directory -- open a new tab and run `npm run start` from the project root directory -- now, anytime you make a change to DSP-UI and save, the library will be re-built and the webpage will refresh and you will see the changes - -### Run the Application in Productive Mode - -To simulate a production environment, the application should be built with optimization and served locally -(not in dev mode, but from a local web server). - -- Install `nginx` on your system, e.g. `brew install nginx` for mac OS. Check the [documentation](https://linux.die.net/man/8/nginx) for more information. -- Create a configuration file for the test application. - The example defines a configuration file `/usr/local/etc/nginx/servers/dspuiapp.conf` for macOS. - Substitute `$abs_path_to_lib` with the actual absolute path on your system pointing to the project root. - Substitute `$dsp-ui_folder_name` with the folder name of the app build in `dist`. - -```nginx - server { - listen 8090; - server_name dspuiapp.local; - root /$abs_path_to_lib/dist/$dsp-ui_folder_name; - - location / { - try_files $uri $uri/ /index.html; - } - - access_log /usr/local/etc/nginx/logs/dspuiapp.local.access.log; - } -``` - -- Add an entry to your `/etc/hosts`: `127.0.0.1 dspuiapp.local` -- Create an empty file `dspuiapp.local.access.log` in `/usr/local/etc/nginx/logs` - (you might have to create the folder `logs` first) -- Start `nginx` (if `nginx` is already running, stop it first: `nginx`: `nginx -s stop`) -- Build the library: `npm run build-lib` -- Build the test app with optimization: `npm run build-app` -- Access it via - -### Build and Run the Application in Docker - -To build and run the application in Docker, do the following: - -1. `docker build --tag app:0.1 .` (you can use any tag name you want) -2. `docker run -v ~/localdir/config.prod.json:/public/config/config.prod.json --publish 4200:4200 --detach --name myname app:0.1` - -The first step builds the lib and app in Docker. Make sure to delete the contents of the `dist` folder on your local system first. - -The second step runs a container based on the image built in the previous step: - -- `-v` mounts a config file from your local file system in the Docker container, so you can set the config. -- `--publish` maps the port on your local machine to the port in the Docker container. - -You can now access the app on your local machine under . +*Special pipes and buttons* +> DspActionModule contains special pipes to sort lists or to get the index key in arrays, but also directives and components for images, sort buttons and s.o. ## Contribution -See our [contribution guidelines](projects/dsp-ui/Contribution.md). + +If you would like to contribute to the development of the DSP-UI modules alongside us, please consult the [general DSP contribution guidelines](https://docs.dasch.swiss/developers/dsp/contribution/) or the [DSP-UI specific contribution guidelines](https://dasch-swiss.github.io/dsp-ui-lib/how-to-contribute/) and the [design documentation](https://dasch-swiss.github.io/dsp-ui-lib/how-to-contribute/design-documentation/). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..dd4faf83b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,91 @@ +# DSP-UI Documentation + +This is the DSP-UI library documentation, based on [MkDocs](https://www.mkdocs.org) and published +under [http://dasch-swiss.github.io/dsp-ui-lib](http://dasch-swiss.github.io/dsp-ui-lib). + +## Contribute + +If you would like to add your own contributions to the docs, please read the following information regarding the file structure to ensure you follow the same structure. + +### File structure + +The documentation consists of three main topics with subordinate themes: + +1. **index** contains all information about the DSP-UI +1. **how-to-use** contains all about the usage of the DSP-UI modules + - Getting Started = All about the installation and init configuration + - Core = Documentation for the core module content + - Viewer = Documentation for the viewer module content + - Search = Documentation for the search module content + - Action = Documentation for the action module content +1. **how-to-contribute** contains all information for people who wants to contribute to DSP-UI + - Contribution = How to contribute incl. link to the general DSP contribution guidelines () + - Design Documentation = Structure conventions + - Docs Documentation = This document + - Release Notes = Contains the CHANGELOG file of DSP-UI + +Images like screenshots and so on have to be stored in `assets/images`. + +The `mkdocs.yml` file is present in the top-level directory of the repo and the source files are in the `docs/` folder. + +Plugins have to be defined in `requirements.txt` and in the github actions workflow `deploy-docs` step under `EXTRA_PACKAGES`. + +## Getting Started + +To run the documentation locally you'll need [Python](https://www.python.org/) installed, as well as the Python package manager [pip](http://pip.readthedocs.io/en/stable/installing/). You can check if you already have these installed by running the following commands from the command line: + +```shell +$ python --version +Python 3.8.2 +$ pip --version +pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) +``` + +MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3. + +### Installing dependencies + +Install the required packages by running the following command: + +```shell +make install-requirements +``` + +### Running the documentation locally + +MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` (repository's root folder) configuration file, and then start the server by running the following command: + +```shell +$ make docs-serve +INFO - Building documentation... +INFO - Cleaning site directory +[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 +[I 160402 15:50:43 handlers:58] Start watching changes +[I 160402 15:50:43 handlers:60] Start detecting changes +``` + +Open up in your browser, and you'll see the documentation start page being. + +In case you need to clean the project directory, run: + +```shell +make docs-clean +``` + +To get some help about the `make` commands, run: + +```shell +make help +``` + +### Building the documentation + +To build the documentation, run: + +```shell +make docs-build +``` + +### Deploying github page + +On each release of DSP-UI, a github action script will build and deploy the documentation on [dasch-swiss.github.io/dsp-ui-lib](https://dasch-swiss.github.io/dsp-ui-lib). Behind the scenes, MkDocs builds the documentation and uses the [mkdocs-deploy-gh-pages](https://github.com/marketplace/actions/deploy-mkdocs) actions script to deploy them to the gh-pages. That's it! diff --git a/docs/assets/fonts/roboto-v19-latin-300.eot b/docs/assets/fonts/roboto-v19-latin-300.eot new file mode 100644 index 000000000..574375d40 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.svg b/docs/assets/fonts/roboto-v19-latin-300.svg new file mode 100644 index 000000000..4ded944a8 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-300.svg @@ -0,0 +1,312 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-300.ttf b/docs/assets/fonts/roboto-v19-latin-300.ttf new file mode 100644 index 000000000..57a24e82f Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.woff b/docs/assets/fonts/roboto-v19-latin-300.woff new file mode 100644 index 000000000..2f6bdb5e7 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.woff2 b/docs/assets/fonts/roboto-v19-latin-300.woff2 new file mode 100644 index 000000000..ef8c8836b Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.eot b/docs/assets/fonts/roboto-v19-latin-500.eot new file mode 100644 index 000000000..2ec7bdd75 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.svg b/docs/assets/fonts/roboto-v19-latin-500.svg new file mode 100644 index 000000000..67eecf442 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-500.svg @@ -0,0 +1,305 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-500.ttf b/docs/assets/fonts/roboto-v19-latin-500.ttf new file mode 100644 index 000000000..dd04ff19d Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.woff b/docs/assets/fonts/roboto-v19-latin-500.woff new file mode 100644 index 000000000..869925869 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.woff2 b/docs/assets/fonts/roboto-v19-latin-500.woff2 new file mode 100644 index 000000000..6362d7f64 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.eot b/docs/assets/fonts/roboto-v19-latin-700.eot new file mode 100644 index 000000000..0168f09bc Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.svg b/docs/assets/fonts/roboto-v19-latin-700.svg new file mode 100644 index 000000000..11db87dd0 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-700.svg @@ -0,0 +1,309 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-700.ttf b/docs/assets/fonts/roboto-v19-latin-700.ttf new file mode 100644 index 000000000..ea06a634f Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.woff b/docs/assets/fonts/roboto-v19-latin-700.woff new file mode 100644 index 000000000..0f14effba Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.woff2 b/docs/assets/fonts/roboto-v19-latin-700.woff2 new file mode 100644 index 000000000..32b25eee7 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.eot b/docs/assets/fonts/roboto-v19-latin-italic.eot new file mode 100644 index 000000000..0753b8839 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.svg b/docs/assets/fonts/roboto-v19-latin-italic.svg new file mode 100644 index 000000000..4d5979710 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-italic.svg @@ -0,0 +1,323 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-italic.ttf b/docs/assets/fonts/roboto-v19-latin-italic.ttf new file mode 100644 index 000000000..bdbb10850 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.woff b/docs/assets/fonts/roboto-v19-latin-italic.woff new file mode 100644 index 000000000..b940dbcb7 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.woff2 b/docs/assets/fonts/roboto-v19-latin-italic.woff2 new file mode 100644 index 000000000..2741d4f08 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.eot b/docs/assets/fonts/roboto-v19-latin-regular.eot new file mode 100644 index 000000000..4f3480091 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.svg b/docs/assets/fonts/roboto-v19-latin-regular.svg new file mode 100644 index 000000000..627f5a368 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-regular.svg @@ -0,0 +1,308 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-regular.ttf b/docs/assets/fonts/roboto-v19-latin-regular.ttf new file mode 100644 index 000000000..a97385dfd Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.woff b/docs/assets/fonts/roboto-v19-latin-regular.woff new file mode 100644 index 000000000..69c882540 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.woff2 b/docs/assets/fonts/roboto-v19-latin-regular.woff2 new file mode 100644 index 000000000..1a5370151 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.woff2 differ diff --git a/docs/assets/icons/dasch-favicon.ico b/docs/assets/icons/dasch-favicon.ico new file mode 100644 index 000000000..0d9a7751e Binary files /dev/null and b/docs/assets/icons/dasch-favicon.ico differ diff --git a/docs/assets/icons/dasch-icon-white.svg b/docs/assets/icons/dasch-icon-white.svg new file mode 100644 index 000000000..396dd5358 --- /dev/null +++ b/docs/assets/icons/dasch-icon-white.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/assets/icons/favicon.png b/docs/assets/icons/favicon.png new file mode 100644 index 000000000..858b838fb Binary files /dev/null and b/docs/assets/icons/favicon.png differ diff --git a/docs/assets/images/admin-image1.png b/docs/assets/images/admin-image1.png new file mode 100644 index 000000000..e3bcc9009 Binary files /dev/null and b/docs/assets/images/admin-image1.png differ diff --git a/docs/assets/images/admin-image2.png b/docs/assets/images/admin-image2.png new file mode 100644 index 000000000..1d3dc92a3 Binary files /dev/null and b/docs/assets/images/admin-image2.png differ diff --git a/docs/assets/images/expert-search.png b/docs/assets/images/expert-search.png new file mode 100644 index 000000000..a01dd6599 Binary files /dev/null and b/docs/assets/images/expert-search.png differ diff --git a/docs/assets/images/extended-search.png b/docs/assets/images/extended-search.png new file mode 100644 index 000000000..65ee714a3 Binary files /dev/null and b/docs/assets/images/extended-search.png differ diff --git a/docs/assets/images/fulltext-search-simple.png b/docs/assets/images/fulltext-search-simple.png new file mode 100644 index 000000000..b0427ba85 Binary files /dev/null and b/docs/assets/images/fulltext-search-simple.png differ diff --git a/docs/assets/images/fulltext-search-with-project-filter.png b/docs/assets/images/fulltext-search-with-project-filter.png new file mode 100644 index 000000000..1612f0b78 Binary files /dev/null and b/docs/assets/images/fulltext-search-with-project-filter.png differ diff --git a/docs/assets/images/loader-after-submit-status.png b/docs/assets/images/loader-after-submit-status.png new file mode 100644 index 000000000..13fae9358 Binary files /dev/null and b/docs/assets/images/loader-after-submit-status.png differ diff --git a/docs/assets/images/loader-before-submit-status.png b/docs/assets/images/loader-before-submit-status.png new file mode 100644 index 000000000..73c01ef12 Binary files /dev/null and b/docs/assets/images/loader-before-submit-status.png differ diff --git a/docs/assets/images/loader-submitting-status.png b/docs/assets/images/loader-submitting-status.png new file mode 100644 index 000000000..e13042a57 Binary files /dev/null and b/docs/assets/images/loader-submitting-status.png differ diff --git a/docs/assets/images/login-form.png b/docs/assets/images/login-form.png new file mode 100644 index 000000000..23a604e96 Binary files /dev/null and b/docs/assets/images/login-form.png differ diff --git a/docs/assets/images/message-error.png b/docs/assets/images/message-error.png new file mode 100644 index 000000000..f9383ffa4 Binary files /dev/null and b/docs/assets/images/message-error.png differ diff --git a/docs/assets/images/message-short.png b/docs/assets/images/message-short.png new file mode 100644 index 000000000..b139f797c Binary files /dev/null and b/docs/assets/images/message-short.png differ diff --git a/docs/assets/images/search-panel.png b/docs/assets/images/search-panel.png new file mode 100644 index 000000000..c720c34ea Binary files /dev/null and b/docs/assets/images/search-panel.png differ diff --git a/docs/assets/images/search-results-filter.png b/docs/assets/images/search-results-filter.png new file mode 100644 index 000000000..d298b78c8 Binary files /dev/null and b/docs/assets/images/search-results-filter.png differ diff --git a/docs/assets/images/search-results-simple.png b/docs/assets/images/search-results-simple.png new file mode 100644 index 000000000..2973ba8ad Binary files /dev/null and b/docs/assets/images/search-results-simple.png differ diff --git a/docs/assets/images/submit-form-data-loader.png b/docs/assets/images/submit-form-data-loader.png new file mode 100644 index 000000000..186272133 Binary files /dev/null and b/docs/assets/images/submit-form-data-loader.png differ diff --git a/docs/assets/style/theme.css b/docs/assets/style/theme.css new file mode 100644 index 000000000..5fddd47a9 --- /dev/null +++ b/docs/assets/style/theme.css @@ -0,0 +1,21 @@ +/* Overwrite the default color with DaSCH's purple. */ +.md-header, +.md-tabs { + background-color: rgb(89, 73, 167) !important; +} + +.md-nav--primary .md-nav__item--active > .md-nav__link { + color: rgb(89, 73, 167) !important; +} + +/* Overwrite the default color in sidebar's header on mobile devices. */ +@media screen and (max-width: 76.1875em) { + .md-sidebar .md-nav__title, + .md-nav__source { + background-color: rgb(89, 73, 167) !important; + } + + .md-sidebar .md-nav__title { + color: white !important; + } +} diff --git a/projects/dsp-ui/design-documentation.md b/docs/how-to-contribute/design-documentation.md similarity index 87% rename from projects/dsp-ui/design-documentation.md rename to docs/how-to-contribute/design-documentation.md index 1e1304c53..740ed914a 100644 --- a/projects/dsp-ui/design-documentation.md +++ b/docs/how-to-contribute/design-documentation.md @@ -23,7 +23,7 @@ Any pipe relating to the transformation of strings must be placed in the folder ### Resource View Component The `ResourceViewComponent` initially gets a resource and passes the retrieved information to its child components to deal with the values. -As the user adds more values, edits existing ones etc., these changes are reflected in `ResourceViewComponent.resPropInfoVals`. +As the user adds more values, edits existing ones etc., these changes are reflected in `ResourceViewComponent.resPropInfoVals`. *This means the `ResourceViewComponent.resource` that was initially retrieved still represents the state of the past since its values are not updated.* Therefore, `ResourceViewComponent.resPropInfoVals` is used solely to represent a resource's values in the template. @@ -32,35 +32,36 @@ which are then updated in `ResourceViewComponent.resPropInfoVals`. ### CRUD UI Components -The viewer module provides components to perform CRUD operations. +The viewer module provides components to perform CRUD operations. These are split into two groups called **value** and **operation** components. -The value components deal with the specifics of each value type supported by Knora, +The value components deal with the specifics of each value type supported by DSP-API, the operation components deal with the actual CRUD operations. With the current design, an operation component can be written in a generic way so that it supports all value types. Therefore, there is no need to write value specific operation components. - + #### Value Components ##### Abstract Base Class -An Angular component per value type has been created. Each of these components is a subclass of the abstract class `BaseValueComponent`. +An Angular component per value type has been created. Each of these components is a subclass of the abstract class `BaseValueComponent`. A value component knows how to display a value of a given type in the UI and how to update it or create a new value interacting with a user in the UI. -The base class defines the following members +The base class defines the following members (some of them are declared as abstract and have to be implemented in the value components.): + - `@Input abstract displayValue?: ReadValue`: value to be displayed and/or updated, if any. The value has to be a subclass of `ReadValue`. - `@Input` `mode: 'read' | 'update' | 'create' | 'search'`: sets the mode of the value component. - `@Input() valueRequiredValidator?`: controls if the value should be required. Defaults to true. -- members ` abstract valueFormControl: FormControl` for the value and `abstract commentFormControl: FormControl` its comment. +- members `abstract valueFormControl: FormControl` for the value and `abstract commentFormControl: FormControl` its comment. - `abstract getInitValue(): any`: gets the value from the displayValue, if any. - `getInitComment: : string | null` gets the comment from displayValue, if any. -- `standardValidatorFunc(val: any, comment: string, commentCtrl: FormControl): ValidatorFn`: +- `standardValidatorFunc(val: any, comment: string, commentCtrl: FormControl): ValidatorFn`: generates a validator that checks if the value changed by the user is different from the existing version (in update mode): the comment has to at least be different from the previous version for the value to be valid. - `standardValueComparisonFunc(initValue: any, curValue: any): boolean`: method called by `standardValidatorFunc` that checks two given values for equality. This method has to be overridden for complex types (e.g., an interval, which is represented as an object). - `abstract customValidators: ValidatorFn[]`: contains validators for type checking (e.g, to check that a number is an integer). -- `resetFormControl(): void ` resets the values in the `FormControl`s and the validators for the given `mode` and `displayValue`. +- `resetFormControl(): void` resets the values in the `FormControl`s and the validators for the given `mode` and `displayValue`. - `abstract getNewValue(): CreateValue | false` gets a new value from the form. - `abstract getUpdatedValue(): UpdateValue | false` gets an updated value from the form. - `isEmptyVal(): boolean`: checks if the value is empty. @@ -83,7 +84,7 @@ This is used in the event that a user should be able to submit a form without fi ##### Simple and Complex Values `BaseValueComponent` handles most of the logic needed for simple values such as an integer or a URI value. -A value is considered simple if it can be represented with a primitive type in the `FormControl`. +A value is considered simple if it can be represented with a primitive type in the `FormControl`. An integer value, for instance, can simply be represented as a number in TypeScript. Complex types, however, have to be represented as an object in the `FormControl`. An interval, for example, is an object with a start and end that is set in the `FormControl`. @@ -126,7 +127,7 @@ In the case of an interval, the value component delegates the complex value to a } ``` -`IntervalInputComponent` defines its own `FormControl`s for the interval's start and end. +`IntervalInputComponent` defines its own `FormControl`s for the interval's start and end. Since these are primitive values (numbers), they can be handled directly in the template. In some cases, primitive values also need to be handled using `ControlValueAccessor`. @@ -135,7 +136,7 @@ This is [necessary](https://indepth.dev/never-again-be-confused-when-implementin #### Operation Components Operation components work with any value. They control the value components' inputs `displayValue` and `mode`. -They are responsible for the communication with the Knora API using `@dasch-swiss/dsp-js` when updating or creating a value. +They are responsible for the communication with the DSP-API using `@dasch-swiss/dsp-js` when updating or creating a value. `DisplayEditComponent` is an operation component that displays an existing value and makes it editable if the user has the necessary permissions. @@ -198,7 +199,7 @@ The expert search is a textarea which allows you to manually write Gravsearch qu ### Advanced search -The advanced search is a search form that allows for the specification of a resource class and and the values of its properties +The advanced search is a search form that allows for the specification of a resource class and and the values of its properties to create a Gravsearch query. #### Structure @@ -206,46 +207,46 @@ to create a Gravsearch query. The advanced search consists of the following components: - `AdvancedSearchComponent`: Main form: Reset and submit buttons, buttons to add and remove properties. - - `SelectOntologyComponent`: Select an ontology from a list. - - `SelectResourceClassComponent`: Select a resource class from a list. - - `SelectPropertyComponent`: Select a property from a list. - - `SpecifyPropertyValueComponent`: Specify a comparison operator and a value for a chosen property. - - `SearchBooleanValueComponent`: Specify a Boolean value. - - `SearchDateValueComponent`: Specify a date value. - - `SearchDecimalValueComponent`: Specify a decimal value. - - `SearchIntegerValueComponent`: Specify an integer value. - - `SearchLinkValueComponent`: Specify the target of a link property. - - `SearchListValueComponent`: Specify a list value. - - `SearchDisplayListComponent`: Displays the children of a list node recursively. - - `TextValueComponent`: Specify a text value. - - `UriValueComponent`: Specify a URI value. + - `SelectOntologyComponent`: Select an ontology from a list. + - `SelectResourceClassComponent`: Select a resource class from a list. + - `SelectPropertyComponent`: Select a property from a list. + - `SpecifyPropertyValueComponent`: Specify a comparison operator and a value for a chosen property. + - `SearchBooleanValueComponent`: Specify a Boolean value. + - `SearchDateValueComponent`: Specify a date value. + - `SearchDecimalValueComponent`: Specify a decimal value. + - `SearchIntegerValueComponent`: Specify an integer value. + - `SearchLinkValueComponent`: Specify the target of a link property. + - `SearchListValueComponent`: Specify a list value. + - `SearchDisplayListComponent`: Displays the children of a list node recursively. + - `TextValueComponent`: Specify a text value. + - `UriValueComponent`: Specify a URI value. #### Component Interaction The `AdvancedSearchComponent`' reacts to the selection of an ontology via the `@Output` of `SelectOntologyComponent`. -When an ontology is selected, `AdvancedSearchComponent` initialises the resource classes and properties of the selected ontology. +When an ontology is selected, `AdvancedSearchComponent` initialises the resource classes and properties of the selected ontology. These are then displayed with `SelectResourceClassComponent` and `SelectPropertyComponent` respectively. When initialised, `AdvancedSearchComponent` only shows the ontology selection. The choice of a resource class is optional. When a resource class is chosen, `AdvancedSearchComponent` reacts to this via the `@Output` of `SelectResourceClassComponent`. The properties of the chosen resource class are then displayed in `SelectPropertyComponent`. The selection of a resource class can be undone ("no selection"). -When a property is chosen, a comparison operator can be specified. +When a property is chosen, a comparison operator can be specified. Once a comparison operator is specified other than "EXISTS", a value can be specified using `SpecifyPropertyValueComponent`. Depending on the value type of the property, `SpecifyPropertyValueComponent` chooses the apt component to let the user enter a value. #### Form Validation -`AdvancedSearchComponent` creates the main form that is then passed down to the child components. +`AdvancedSearchComponent` creates the main form that is then passed down to the child components. Each child component that requires form validation creates an own form which is attached to the main form using `addControl` on the main `FormGroup`. -When a component is destroyed or reinitialised, the component's form is removed using `removeControl` on the main `FormGroup`. -**Both adding and removing to and from the main `FormGroup` have to be performed as async tasks +When a component is destroyed or reinitialised, the component's form is removed using `removeControl` on the main `FormGroup`. +**Both adding and removing to and from the main `FormGroup` have to be performed as async tasks to avoid [check detection errors](https://indepth.dev/everything-you-need-to-know-about-the-expressionchangedafterithasbeencheckederror-error/)**. The query can only be submitted if the main form is valid. Some additional logic is handled in `AdvancedSearchComponent`'s method `validateForm`. #### Query Generation -`AdvancedSearchComponent` gets the IRI of the specified resource class, if any. +`AdvancedSearchComponent` gets the IRI of the specified resource class, if any. It also gets an array of properties with their values (`PropertyWithValue[]`) to search for. These are then converted to a Gravsearch query using a service. diff --git a/docs/how-to-contribute/docs-documentation.md b/docs/how-to-contribute/docs-documentation.md new file mode 100644 index 000000000..4129e67ee --- /dev/null +++ b/docs/how-to-contribute/docs-documentation.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/how-to-contribute/index.md b/docs/how-to-contribute/index.md new file mode 100644 index 000000000..2b2a1bc89 --- /dev/null +++ b/docs/how-to-contribute/index.md @@ -0,0 +1,265 @@ +# How to Contribute to this Project + +If you are interested in contributing to this project, +please read our [general DSP contribution guidelines](https://docs.dasch.swiss/developers/dsp/contribution/) first. + +## Structure of this Project + +This project consists of two main parts: + +1. The Angular library `DSP-UI (@dasch-swiss/dsp-ui)` in `project/dsp-ui`. +1. The demo Angular Application (Playground) in `src/app`. + +The Angular library contains the code that is published on NPM. +The demo Angular application's purpose is to demonstrate the library's functionality. +The library needs to be built first in order to use it within the demo application. + +The demo application uses the **locally built version** of `@dasch-swiss/dsp-ui` +which is configured in [tsconfig.json](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/tsconfig.json) (`compilerOptions.paths`), +see [Angular docs](https://angular.io/guide/creating-libraries#building-and-rebuilding-your-library). + +## Prerequisites + +### Node.js + +Angular requires a [current, active LTS, or maintenance LTS](https://angular.io/guide/setup-local#prerequisites) version of Node.js. + +We recommend using [n](https://www.npmjs.com/package/n), +a tool that installs and manages Node.js versions on your local system. + +### NPM package manager + +Angular requires the [npm package manager](https://angular.io/guide/setup-local#prerequisites). + +### DSP-API + +The demo application requires a running instance of +[DSP-API (Knora)](https://docs.knora.org/04-publishing-deployment/getting-started/) +compatible with the version defined in [vars.mk](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/vars.mk): {% include-markdown "../../vars.mk" %} + +## First Steps + +Clone this repository: + +```shell +git clone https://github.com/dasch-swiss/dsp-ui-lib/ +``` + +Install the dependencies with: + +```shell +npm install +``` + +Build the library with: + +```shell +npm run build-lib +``` + +Run the demo application: + +```shell +ng s +``` + +And access `http://localhost:4200` in your browser. + +## Scripts For Development + +The following scripts can be used for development: + +### Testing + +- `npm test`: runs the unit tests of the demo application and the lib's unit tests. +- `npm test-lib`: runs the lib's unit tests in headless mode (no browser UI). +- `npm test-lib-local`: runs the lib's unit test with the browser UI (for local development of the lib). +- `npm run webdriver-update`: installs Chrome webdriver in the required version for the E2E tests. +- `npm run e2e`: runs the E2E tests from the demo application, see section [Unit Tests and E2E Tests](#unit-tests-and-e2e-tests). + +### Building + +- `npm run build-lib`: builds the lib in productive mode +- `npm run build-lib-dev`: builds the lib in development mode +- `npm build-app`: builds the demo application in productive mode +- `npm run yalc-publish-lib`: builds the lib and publishes it locally using [yalc](https://www.npmjs.com/package/yalc). + +## Library Build Options + +The library is built in productive mode for publication, using [tsconfig.lib.prod.json](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/projects/dsp-ui/tsconfig.lib.prod.json). + +To perform additional checks during development, the library can be built in development mode, +using [tsconfig.lib.json](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/projects/dsp-ui/tsconfig.lib.json). Development builds use Ivy and perform [strict template checks](https://angular.io/guide/template-typecheck#template-type-checking). + +## Unit Tests and E2E Tests + +There are unit tests for the lib (`projects/dsp-ui/src`) +and some basic unit tests for the demo application playground components (`src/app`). + +The E2E tests have to be run from the demo application. +Unlike the unit tests, they require a running instance of DSP-API compatible with the release specified in [vars.mk](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/vars.mk): {% include-markdown "../../vars.mk" %} +Before running the E2E tests, reload the data in DSP-API's db. +The E2E tests can be run as follows: + +- `npm run webdriver-update` +- `npm run e2e` + +## DSP-UI Library Developement + +### Adding New Components etc. to the Library + +Install [Angular CLI](https://angular.io/cli) globally: + +```shell + npm install -g @angular/cli +``` + +To add additional components etc. to a module of the library, run: + +```shell +ng generate component [path/in/the/module/][name-of-component] --project @dasch-swiss/dsp-ui +``` + +For example, to create a new component `test` in the action module, run: + +```shell +ng generate component action/test --project @dasch-swiss/dsp-ui +``` + +This command will create a folder called `test` inside of `projects/dsp-ui/src/lib/action/` containing the component's class, template, style, and spec files. + +Before testing the new component inside of the demo app, you have to rebuild it after each change: + +```shell +npm run build-lib +``` + +Alternatively, you can use [Live Reloading](#run-the-application-locally-in-dev-mode-with-live-reloading). + +## Demo Application (Playground) + +### Adding New Component to the Demo Application + +The demo app demonstrates the functionality of dsp-ui-lib's modules. +By default, the demo app's main component routes to the page demonstrating the resource viewer in read mode. + +Before adding a new component to the demo app, +check if the desired demo could be added to an existing component of the demo app. + +Follow these steps to add a new component to the demo app: + +- create a new component in the demo app: + - create a new component using Angular CLI in `src/app` + - demonstrate a part of dsp-ui-lib (component, service etc.) in the new component of the demo app +- in `AppRoutingModule` and `AppComponent`'s template, set up the routing for your new component in the demo app. + +### Run the Application Locally in Dev Mode With Live Reloading + +To make changes to the DSP-UI and have your changes reflected immediately upon saving, follow these steps: + +- run `npm run build-watchful-lib-dev` from the project root directory +- open a new tab and run `npm run start` from the project root directory +- now, anytime you make a change to DSP-UI and save, the library will be re-built and the webpage will refresh and you will see the changes + +### Run the Application in Productive Mode + +To simulate a production environment, the application should be built with optimization and served locally +(not in dev mode, but from a local web server). + +- Install `nginx` on your system, e.g. `brew install nginx` for mac OS. Check the [documentation](https://linux.die.net/man/8/nginx) for more information. +- Create a configuration file for the test application. + The example defines a configuration file `/usr/local/etc/nginx/servers/dspuiapp.conf` for macOS. + Substitute `$abs_path_to_lib` with the actual absolute path on your system pointing to the project root. + Substitute `$dsp-ui_folder_name` with the folder name of the app build in `dist`. + +```nginx + server { + listen 8090; + server_name dspuiapp.local; + root /$abs_path_to_lib/dist/$dsp-ui_folder_name; + + location / { + try_files $uri $uri/ /index.html; + } + + access_log /usr/local/etc/nginx/logs/dspuiapp.local.access.log; + } +``` + +- Add an entry to your `/etc/hosts`: `127.0.0.1 dspuiapp.local` +- Create an empty file `dspuiapp.local.access.log` in `/usr/local/etc/nginx/logs` + (you might have to create the folder `logs` first) +- Start `nginx` (if `nginx` is already running, stop it first: `nginx`: `nginx -s stop`) +- Build the library: `npm run build-lib` +- Build the test app with optimization: `npm run build-app` +- Access it via + +### Build and Run the Application in Docker + +To build and run the application in Docker, do the following: + +1. `docker build --tag app:0.1 .` (you can use any tag name you want) +2. `docker run -v ~/localdir/config.prod.json:/public/config/config.prod.json --publish 4200:4200 --detach --name myname app:0.1` + +The first step builds the lib and app in Docker. Make sure to delete the contents of the `dist` folder on your local system first. + +The second step runs a container based on the image built in the previous step: + +- `-v` mounts a config file from your local file system in the Docker container, so you can set the config. +- `--publish` maps the port on your local machine to the port in the Docker container. + +You can now access the app on your local machine under . + +## Architecture of the Library + +See [design documentation](./design-documentation.md). + +## Local Publishing of DSP-UI + +The demo application uses the locally built version of DSP-UI, see the repository's [structure](#structure-of-this-project). + +If you want to install an unpublished version of DSP-UI in your Angular application, you can use [yalc](https://www.npmjs.com/package/yalc). +`yalc` publishes DSP-UI to a local store. + +Install `yalc`: + +```shell +npm install yalc -g +``` + +Build the library and publish it to the local store: + +```shell +npm run build-app +npm run yalc-publish-lib +``` + +Add the local build your Angular application: + +```shell +yalc add @dasch-swiss/dsp-ui +npm install +``` + +To remove it from your project and restore `package.json`, run: + +```shell +yalc remove --all +``` + +## Publish a New Version of the Library to NPM + +Please follow the general DSP documentation about the release process: [prepare](https://docs.dasch.swiss/developers/dsp/contribution/#prepare-release) and [publish](https://docs.dasch.swiss/developers/dsp/contribution/#create-release). + +Before publishing: + +- Update documentation if necessary and commit the changes + +- Be sure that all dependencies to DSP-JS-LIB and DSP-API are set to the correct version: + - Update DSP-API version in `vars.mk` + - Update DSP-JS version in `package.json` and run `npm install` to update the `package-lock.json` + - Update DSP-JS version in section `peerDependencies` of `projects/dsp-ui/package.json` + +A new version will be published with each github release as it's part of github actions' workflow. To make a new release, you have to merge the open release PR as described [here](https://docs.dasch.swiss/developers/dsp/contribution/#create-release). + +The new package will be available on . diff --git a/docs/how-to-contribute/release-notes.md b/docs/how-to-contribute/release-notes.md new file mode 100644 index 000000000..b3767cbb1 --- /dev/null +++ b/docs/how-to-contribute/release-notes.md @@ -0,0 +1,3 @@ +{% + include-markdown "../../projects/dsp-ui/CHANGELOG.md" +%} diff --git a/docs/how-to-use/action/admin-image.md b/docs/how-to-use/action/admin-image.md new file mode 100644 index 000000000..f01bcf594 --- /dev/null +++ b/docs/how-to-use/action/admin-image.md @@ -0,0 +1,60 @@ +# AdminImage (Directive) + +You can use the admin image module for user avatar together with gravatar.com and for project logos. + +The feature of this module is the error handling: In case of a 404 error of the image source (img src) the module shows a default image-not-found image. Or a default user profile icon (type=user), or a default project icon (type=project). + +## Parameters + +Name | Type | Description +--- | --- | --- +image | string | source of the image:
- in case of user (gr)avatar it's the e-mail address,
- in case of project logo it's the image url +type | string | type of image; you can use it with:
- project
- user + +## Examples + +### User Avatar + +**HTML file** +```html +// Default user profile image + + +// Avatar example: 'salsah' user + + +// User image on error + + +// Default error image + +``` + +**Typescript file** +```ts +imgDefaultUser: string = 'root@example.com'; +imgSalsahUser: string = 'salsah@dasch.ch'; +``` + +![User avatars](../../assets/images/admin-image1.png) + +
+ +### Project Logo + +**HTML file** +```html +// Default project image + + +// Logo example: 'dasch' project + +``` + +**Typescript file** +```ts +imgDefaultProject: string = undefined; +imgDaschProject: string = 'http://dasch.swiss/content/images/2017/11/DaSCH_Logo_RGB.png'; +``` + +![Default project logos](../../assets/images/admin-image2.png) diff --git a/docs/how-to-use/action/existing-name.md b/docs/how-to-use/action/existing-name.md new file mode 100644 index 000000000..4e2488399 --- /dev/null +++ b/docs/how-to-use/action/existing-name.md @@ -0,0 +1,148 @@ +# ExistingName (Directive) + +With the ExistingNameDirective, we can prevent the usage of a name which should be unique but already exists. +e.g. It can be used to get a list of all project shortnames which can then be used as a list of existing names when checking the validity of a new project shortname. Alternatively, you can also use this as a blacklist for words you don't want the user to be able to enter. + +## Methods + +### existingNameValidator() +Validation of existing name value. String method (only one value); +Use it in a "formbuilder" group as a validator property. + +**Parameters** + +Name | Type | Description +--- | --- | --- +valRegexp | RegExp | Only one regular expression value + +**Returns** + + | +--- | +ValidatorFn | + +### existingNamesValidator() +Validation of existing name values. Array method (list of values) +Use it in a "formbuilder" group as a validator property. + +**Parameters** + +Name | Type | Description +--- | --- | --- +valArrayRegexp | RegExp | List of regular expression values + +**Returns** + + | +--- | +ValidatorFn | + +## Examples + +### Existing Name Validator + + + +**The following names already exists** +Try to use one of them in the form above and see what happens + +- Max +- Peter +- Paul +- John + +**HTML file** +```html +
+ + + + {{formErrors.name}} + + + + +
+``` + +**Typescript file** +```ts +dataMock: string[] = [ + 'Max', 'Peter', 'Paul', 'John' +]; + +// list of existing names +existingNames: [RegExp] = [ + new RegExp('user') +]; + +// define your form group +form: FormGroup; + +// error handling on the defined fields e.g. name +formErrors = { + 'name': '' +}; + +// error message on the defined fields in formErrors +validationMessages = { + 'name': { + 'required': 'A name is required', + 'existingName': 'This name exists already.' + } +}; + +constructor(private _formBuilder: FormBuilder) { + +} + +ngOnInit() { + // create a list of names, which already exists + for (const user of this.dataMock) { + this.existingNames.push( + new RegExp('(?:^|\W)' + user.toLowerCase() + '(?:$|\W)') + ); + } + + // build form + this.form = this._formBuilder.group({ + 'name': new FormControl({ + value: '', disabled: false + }, [ + Validators.required, + existingNamesValidator(this.existingNames) + ]) + }); + + // detect changes in the form + this.form.valueChanges.subscribe( + data => this.onValueChanged(data) + ); + + this.onValueChanged(); +} + + +onValueChanged(data?: any) { + + if (!this.form) { + return; + } + + // check if the form is valid + Object.keys(this.formErrors).map(field => { + this.formErrors[field] = ''; + const control = this.form.get(field); + if (control && control.dirty && !control.valid) { + const messages = this.validationMessages[field]; + Object.keys(control.errors).map(key => { + this.formErrors[field] += messages[key] + ' '; + }); + } + }); +} +``` diff --git a/docs/how-to-use/action/index.md b/docs/how-to-use/action/index.md new file mode 100644 index 000000000..7cbcf8fb5 --- /dev/null +++ b/docs/how-to-use/action/index.md @@ -0,0 +1,54 @@ +# DSP-UI ACTION module + +DspActionModule is like a tool box containing special pipes to sort lists or to get the index key in arrays, directives for images and sorting names, but also components to display progress indicator bars or customized dialog boxes for resources, etc... + +## Prerequisites + +For help getting started with a new Angular app, check the [Angular CLI](https://cli.angular.io/) documentation. + +For existing apps, follow these steps to begin using DSP-UI ACTION. + +## Installation + +DspActionModule is part of @dasch-swiss/dsp-ui, follow [the installation guide](/how-to-use/getting-started/). + +## Setup + + Import the action module in your app.module.ts and add it to the NgModules's imports: + +```javascript +import { AppComponent } from './app.component'; +import { DspCoreModule, DspActionModule } from '@dasch-swiss/dsp-ui'; + +@NgModule({ + declarations: [ + AppComponent + ], + imports: [ + DspCoreModule, // <- core module is required for some components and directives + DspActionModule // <- add action module in the imports + ], + providers: [ ... ] // <-- add providers if you use the core module as mentioned in the installation guide + bootstrap: [AppComponent] +}) +export class AppModule { +} +``` + +Some components need a global styling in the app to override some material styling rules. Please update your `angular.json` file as follow: + +```json +... + "styles": [ + "src/styles.scss", + "node_modules/@dasch-swiss/dsp-ui/action/assets/style/action.scss" // <- add this line + ], +... +``` + + + +## Components, Directives and Pipes + +This module contains various components like a progress indicator, sort button and sort-by pipe, but also directives for images (in the admin interface) and existing names. diff --git a/docs/how-to-use/action/key.md b/docs/how-to-use/action/key.md new file mode 100644 index 000000000..a192da50a --- /dev/null +++ b/docs/how-to-use/action/key.md @@ -0,0 +1,31 @@ +# Key (Pipe) + +This pipe can be used for "for loops", in the case of an array with non-numeric indexes. +It returns the key and the value(s). In the example below the `{{item.key}}` contains the index value +and the `{{item.value}}` contains the value(s). + +When the value is an object with name and label, you get them with `{{item.value.name}}` and `{{item.value.label}}`. + +## Examples + +### HTML file + +```html +
    +
  • + {{item.key}}: {{item.value}} +
    • +
+``` + +### Typescript file + +```ts +array = []; + +this.array['index-1'] = 'Value in index 1'; +this.array['index-2'] = 'Value in index 2'; +this.array['index-3'] = 'Value in index 3'; +``` + + diff --git a/docs/how-to-use/action/message.md b/docs/how-to-use/action/message.md new file mode 100644 index 000000000..c4c226134 --- /dev/null +++ b/docs/how-to-use/action/message.md @@ -0,0 +1,89 @@ +# Message (Component) - DEPRECATED + +Message component to handle notes, warning and error messages. +If you set the paramater `[short]="true"`, it shows a smaller message. +It can be used to give feedbacks in a form e.g. update process: show success or error message. + +## Parameters + +### Message type: DspMessageData or ApiServiceError + +Name | Type | Description +--- | --- | --- +message | DspMessageData, ApiServiceError | This type needs at least a status number (0-511). In this case, or if type is ApiServiceError, it takes the default status messages from the list of HTTP status codes
(https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) + +
+ +**Show short message only: it can be used in a form to show if a post was successfull or not.** + +Name | Type | Description +--- | --- | --- +short (optional) | boolean | + +
+ +**Show medium message: a message box without footnotes or links.** + +Name | Type | Description +--- | --- | --- +medium (optional) | boolean | + +## Examples + +### Success and error message, short version (= small size) + +#### HTML file + +```html + + +``` + +#### Typescript file + +```ts +// short message example +shortMessage: DspMessageData = { + status: 200, + statusMsg: 'Success', + statusText: 'You just update the user profile.', + type: 'Note', + footnote: 'Close it' +}; + +// error message example +errorMessage: ApiServiceError = { + status: 403, + errorInfo: + 'Http failure response for http://0.0.0.0:3333/admin/projects/shortcode/001/members: 400 Bad Request', + statusText: 'Bad Request', + url: 'http://0.0.0.0:3333/admin/projects/shortcode/001/members' +}; +``` + +![Message in short version](../../assets/images/message-short.png) + +
+ +### Error message, default size + +#### HTML file + +```html + +``` + +#### Typescript file + +```ts +// error message example +errorMessage: ApiServiceError = { + status: 403, + errorInfo: + 'Http failure response for http://0.0.0.0:3333/admin/projects/shortcode/001/members: 400 Bad Request', + statusText: 'Bad Request', + url: 'http://0.0.0.0:3333/admin/projects/shortcode/001/members' +}; +``` + +![Error message in default size version](../../assets/images/message-error.png) diff --git a/docs/how-to-use/action/progress-indicator.md b/docs/how-to-use/action/progress-indicator.md new file mode 100644 index 000000000..2fcfc7d95 --- /dev/null +++ b/docs/how-to-use/action/progress-indicator.md @@ -0,0 +1,47 @@ +# Progress Indicator (Component) + +The progress indicator can be used to show the status of loading something. +This can be the simple loader or in case of submitting data it can show the status (not ready, loading, done or error). + +## Parameters + +Name | Type | Description +--- | --- | --- +status (optional) | number | [status] is a number and can be used when submitting form data:
- not ready: -1
- loading: 0
- done: 1
- error: 400 +color=primary (optional) | string | Parameter to customize the appearance of the loader. Hexadecimal color value e.g. #00ff00 or similar color values 'red', 'green' etc. + +## Examples + +You can use the progress indicator in two ways: + +### Classic Loader + +#### HTML file + +```html + +``` + + + +
+ +### Submit-form-data loader + +e.g. as a list style type while submitting form data + +![Submit form data loader](../../assets/images/submit-form-data-loader.png) + +Angular Material Icons is required. You have to import the style file into your app and add the following line in your main styling file: + +`@import url('https://fonts.googleapis.com/icon?family=Material+Icons');` + +We recommend to host the Material Icons font in your app e.g. by using the [Material Icons package](https://www.npmjs.com/package/material-icons). + +
+ +### Dynamic example of Submit-form-data loader + +![Loader before submit stage](../../assets/images/loader-before-submit-status.png) +![Loader submitting stage](../../assets/images/loader-submitting-status.png) +![Loader after submit stage](../../assets/images/loader-after-submit-status.png) diff --git a/docs/how-to-use/action/sort-button.md b/docs/how-to-use/action/sort-button.md new file mode 100644 index 000000000..361cf6acb --- /dev/null +++ b/docs/how-to-use/action/sort-button.md @@ -0,0 +1,84 @@ +# SortButton (Component) + +A component with a list of properties to sort a list by. +It can be used together with the DspSortBy pipe. + +## Parameters + +{string} sortKeyChange
+EventEmitter when a user selected a sort property;
+This is the selected key. + +Name | Type | Description +--- | --- | --- +sortProps | Array | An array of SortProp objects for the selection menu:
SortProp: { key: string, label: string } +position='left' (optional) | string | Optional position of the sort menu: right or left +icon='sort' (optional) | string | Default icon is "sort" from material design. But you can replace it with another one e.g. sort_by_alpha +sortKey | string | Set and get (two-way data binding) of current sort key + +## Example - Simple Example + +### HTML file + +```html + + +
    +
  • + {{item.prename}} + {{item.lastname}} + by + {{item.creator}} +
    • +
+``` + +### Typescript file + +```ts +sortProps: any = [ + { + key: 'prename', + label: 'Prename' + }, + { + key: 'lastname', + label: 'Last name' + }, + { + key: 'creator', + label: 'Creator' + } +]; + +sortKey: string = 'creator'; + +list = [ + { + prename: 'Gaston', + lastname: 'Lagaffe', + creator: 'André Franquin' + }, + { + prename: 'Mickey', + lastname: 'Mouse', + creator: 'Walt Disney' + }, + { + prename: 'Donald', + lastname: 'Duck', + creator: 'Walt Disney' + }, + { + prename: 'Charlie', + lastname: 'Brown', + creator: 'Charles M. Schulz' + } +]; +``` + + + +### Optional + +It's possible to set the position of the sort button to the right or left side with the property `[position]`. diff --git a/docs/how-to-use/action/stringify-string-literal.md b/docs/how-to-use/action/stringify-string-literal.md new file mode 100644 index 000000000..dcdb3b76c --- /dev/null +++ b/docs/how-to-use/action/stringify-string-literal.md @@ -0,0 +1,29 @@ +# StringifyStringLiteral (Pipe) + +This pipe stringifies an array of StringLiterals. With the parameter `all`, the pipe concats all values and appends the corresponding language in brackets. + +Otherwise the pipe displays the value corresponding to the default language which comes from the user profile (if a user is logged-in) or from the browser. With the predefined language the pipe checks if a value exists in the array, otherwise it shows the first value. + +## Example - StringifyStringLiteral Pipe + +### HTML file + +```html +Show all values +

{{labels | dspStringifyStringLiteral:'all'}}

+ +Show only one value +

{{labels | dspStringifyStringLiteral}}

+``` + +### Typescript file + +```ts +labels: StringLiteral[] = '[{"value":"Welt","language":"de"},{"value":"World","language":"en"},{"value":"Monde","language":"fr"},{"value":"Mondo","language":"it"}]'; +``` + +**Show all values**
+Welt (de) / World (en) / Monde (fr) / Mondo (it) + +**Show only one value**
+World diff --git a/docs/how-to-use/action/truncate.md b/docs/how-to-use/action/truncate.md new file mode 100644 index 000000000..0e26320d0 --- /dev/null +++ b/docs/how-to-use/action/truncate.md @@ -0,0 +1,33 @@ +# Truncate (Pipe) + +This pipe can be used to shorten long text by a defined length. + +In markup: + +`{{ str | dspTruncate:[24] }}` + +or + +`{{ str | dspTruncate:[24, '...'] }}` + +The first parameter defines the length where to truncate the string. +Second optional parameter defines the characters to append to the shortened string. Default is `...`. + +The advantage of this pipe over the default Angular slice pipe is the simplicity of adding additional characters at the end of the shortened string. +The same construct with Angular slice pipe looks as follow: `{{ (str.length>24)? (str | slice:0:24)+'...':(str) }}`. + +## Example - Truncate Pipe + +### HTML file + +```html +

{{longText | dspTruncate:[24]}}

+``` + +### Typescript file + +```ts +longText: string = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vel pharetra vel turpis nunc eget lorem dolor. Euismod lacinia at quis risus sed vulputate. Ultrices gravida dictum fusce ut placerat orci nulla pellentesque. Tortor consequat id porta nibh venenatis cras. Turpis tincidunt id aliquet risus feugiat in ante metus. Dictum fusce ut placerat orci nulla pellentesque dignissim enim sit. Mattis vulputate enim nulla aliquet porttitor lacus luctus accumsan. Mauris sit amet massa vitae tortor condimentum lacinia quis vel. Dictum sit amet justo donec enim diam vulputate. Dignissim convallis aenean et tortor. Ut tellus elementum sagittis vitae et. Pretium viverra suspendisse potenti nullam ac tortor vitae purus faucibus. Eget mauris pharetra et ultrices neque ornare aenean. Diam in arcu cursus euismod. Odio ut enim blandit volutpat maecenas volutpat. Suspendisse interdum consectetur libero id faucibus nisl tincidunt eget. Risus commodo viverra maecenas accumsan.'; +``` + +Output: **Lorem ipsum dolor sit am...** diff --git a/docs/how-to-use/core/index.md b/docs/how-to-use/core/index.md new file mode 100644 index 000000000..008f372e2 --- /dev/null +++ b/docs/how-to-use/core/index.md @@ -0,0 +1,56 @@ +# DSP-UI CORE module + +DspCoreModule is a configuration handler for [`@dasch-swiss/dsp-js`](https://www.npmjs.com/package/@dasch-swiss/dsp-js) which offers all the services to make [DSP-API requests](https://docs.dasch.swiss/developers/knora/api-reference/queries/). + +## Prerequisites + +For help getting started with a new Angular app, check out the [Angular CLI](https://cli.angular.io/). + +For existing apps, follow these steps to begin using DSP-UI CORE. + +## Installation + +DspCoreModule is part of @dasch-swiss/dsp-ui, follow [the installation guide](/how-to-use/getting-started/). + +## Usage + + The following ProjectsComponent example shows how to implement the two libraries to get all projects from DSP-API: + +```typescript +import { Component, Inject, OnInit } from '@angular/core'; +import { DspApiConnectionToken } from '@dasch-swiss/dsp-ui'; +import { + ApiResponseData, + ApiResponseError, + KnoraApiConnection, + ProjectsResponse, + ReadProject +} from '@dasch-swiss/dsp-js'; + +@Component({ + selector: 'app-projects', + template: `
  • {{p.longname}} ({{p.shortname}} | {{p.shortcode}})
` +}) +export class ProjectsComponent implements OnInit { + projects: ReadProject[]; + + constructor( + @Inject(DspApiConnectionToken) private dspApiConnection: KnoraApiConnection + ) { } + + ngOnInit() { + this.getProjects(); + } + + getProjects() { + this.dspApiConnection.admin.projectsEndpoint.getProjects().subscribe( + (response: ApiResponseData) => { + this.projects = response.body.projects; + }, + (error: ApiResponseError) => { + console.error(error); + } + ); + } +} +``` diff --git a/docs/how-to-use/getting-started.md b/docs/how-to-use/getting-started.md new file mode 100644 index 000000000..5334927b2 --- /dev/null +++ b/docs/how-to-use/getting-started.md @@ -0,0 +1,167 @@ +# Getting started + +## Installation + +To use this library in your Angular app, install it from NPM: + +```bash +npm install @dasch-swiss/dsp-ui +``` + +## Dependencies + +This library has the following peer dependencies, which you also have to meet: + +- [@dasch-swiss/dsp-js](https://www.npmjs.com/package/@dasch-swiss/dsp-js) +- [jdnconvertiblecalendar](https://www.npmjs.com/package/jdnconvertiblecalendar) +- [jdnconvertiblecalendardateadapter](https://www.npmjs.com/package/jdnconvertiblecalendardateadapter) +- [ngx-color-picker](https://www.npmjs.com/package/ngx-color-picker) +- [openseadragon](https://openseadragon.github.io/#download) +- [svg-overlay](https://github.com/openseadragon/svg-overlay) +- [@ckeditor/ckeditor5-angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular) +- [ckeditor-build](http://github.com/dasch-swiss/ckeditor_custom_build) + +## Supported DSP-API Version + +The library is compatible with the DSP-API version defined in [vars.mk](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/vars.mk): {% include-markdown "../../vars.mk" %} + +The DSP-UI library supports runtime configuration. +The configuration is loaded when your Angular application starts. + +In your Angular project, create the file `config.dev.json` inside `src/config/`: + +```json +{ + "apiProtocol": "http", + "apiHost": "0.0.0.0", + "apiPort": 3333, + "apiPath": "", + "jsonWebToken": "", + "logErrors": true +} +``` + +Likewise, create a file `config.prod.json` with `logErrors` set to `false`. +The configuration files are needed to establish a connection to DSP-API. + +Create the property `name` in `src/environments/environment.ts` and set it to "dev": + +```typescript +export const environment = { + name: 'dev', // <-- this env. will load config.dev.json + production: false +}; +``` + +In `src/environments/environment.prod.ts`: + +```typescript +export const environment = { + name: 'prod', // <-- this env. will load config.prod.json + production: true +}; +``` + +Depending on the [build options](https://angular.io/guide/build#configuring-application-environments) (dev or prod), +the environment and configuration are chosen. + +The config files have to be integrated in `angular.json` in the "assets" section: + +```json +"assets": [ + "src/favicon.ico", + "src/assets", + "src/config" <-- add the config directory here +] +``` + +Define the following three [factory providers](https://angular.io/guide/dependency-injection-providers#using-factory-providers) in your application's `app.module.ts`: + + 1. Provide a function that calls `AppInitService`'s method `Init` and returns its return value which is a `Promise`. + Angular waits for this `Promise` to be resolved. + The `Promise` will be resolved once the configuration file has been fetched and its contents have been assigned. + 1. Get the [KnoraApiConfig](https://www.npmjs.com/package/@dasch-swiss/dsp-js) instance from the `AppInitService` instance and provide it as `DspApiConfigToken`. + 1. Create a [KnoraApiConnection](https://www.npmjs.com/package/@dasch-swiss/dsp-js) instance with the config and provide it as `DspApiConnectionToken`. + +Provide it in the main module and include the desired DSP-UI modules in the imports: + +```typescript +@NgModule({ + declarations: [ + AppComponent, + ProjectsComponent + ], + imports: [ + BrowserModule, + AppRoutingModule, + DspCoreModule, // <-- add the dsp-ui modules here + DspViewerModule + ], + providers: [ + // 1. + { + provide: APP_INITIALIZER, // see https://angular.io/api/core/APP_INITIALIZER + useFactory: (appInitService: AppInitService) => + (): Promise => { + return appInitService.Init('config', environment); + }, + deps: [AppInitService], // depends on AppInitService + multi: true + }, + // 2. + { + provide: DspApiConfigToken, + // return the instance of KnoraApiConfig provided by AppInitService + useFactory: (appInitService: AppInitService) => appInitService.dspApiConfig, + deps: [AppInitService] // depends on AppInitService + }, + // 3. + { + provide: DspApiConnectionToken, + // create and return an instance of KnoraApiConnection + useFactory: (appInitService: AppInitService) => new KnoraApiConnection(appInitService.dspApiConfig), + deps: [AppInitService] // depends on AppInitService + } + ], + bootstrap: [AppComponent] +}) +export class AppModule { } +``` + +The contents of the configuration can be accessed via `AppInitService`s member `config`. +Just inject `AppInitService` in your service's or component's constructor. + +The library needs a global styling in the app to override some material design rules. +If you're using Angular CLI, this is as simple as including one line in your `styles.scss` file: + +```css +@import '@dasch-swiss/dsp-ui/src/assets/style/dsp-ui.scss'; +``` + +Alternatively, you can just reference the file directly. This would look something like: + +```html + +``` + +## Usage + +Add the desired modules from DSP-UI to the `app.module.ts`. +Always import `DspCoreModule`. + +```typescript +@NgModule({ + declarations: [ + AppComponent, + ProjectsComponent + ], + imports: [ + BrowserModule, + AppRoutingModule, + DspCoreModule // <-- add the dsp-ui core module here + ], + providers: [ ... ] // <-- add providers as mentioned in section above + bootstrap: [AppComponent] +}) +export class AppModule { } +``` diff --git a/docs/how-to-use/search/expert-search.md b/docs/how-to-use/search/expert-search.md new file mode 100644 index 000000000..1186bd610 --- /dev/null +++ b/docs/how-to-use/search/expert-search.md @@ -0,0 +1,23 @@ +# Expert search (Component) + +The expert search is a textarea field in which Gravsearch queries can be written. Complex searches can be made this way but you must know the [Gravsearch language](https://docs.knora.org/paradox/03-apis/api-v2/query-language.html). + +## Parameters + +Name | Type | Description +--- | --- | --- +route (optionnal) | string | Route to navigate after search. This route path should contain a component for search results. +gravsearch | string | Send the gravsearch query back. +toggleExpertSearchForm | boolean | Trigger toggle for extended search form. + +## Examples + +Extended search panel + +```html + + + +``` + +![Expert search panel with a default Gravsearch query](../../assets/images/expert-search.png) diff --git a/docs/how-to-use/search/extended-search.md b/docs/how-to-use/search/extended-search.md new file mode 100644 index 000000000..34716505b --- /dev/null +++ b/docs/how-to-use/search/extended-search.md @@ -0,0 +1,25 @@ +# Extended search (Component) + +The extended search allows you to filter by project, by source type (resource class), or by the metadata (properties) of source types. Each filter can be standalone or combined. The metadata field can be precisely filtered with criteria such as "contains", "like", "equals to", "exists" or in case of a date value with "before" or "after". In addition, for a metadata field that is connected to another source type, it's possible to filter by this second source type. If you are looking for the source type "Photograph" with the metadata field "Photographer", which is connected to source type "Person", you can search for photograph(s) taken by person(s) who is born before February 1970. The result of this request will be an intersection of the two source types. + +## Parameters + +Name | Type | Description +--- | --- | --- +route | string | Route to navigate after search. This route path should contain a component for search results. +toggleExtendedSearchForm | boolean | Trigger toggle for extended search form. +gravsearch | string | Send the gravsearch query back. + +## Examples + +Extended search panel + +```html + + + + + +``` + +![Advanced search panel with a search example](../../assets/images/extended-search.png) diff --git a/docs/how-to-use/search/fulltext-search.md b/docs/how-to-use/search/fulltext-search.md new file mode 100644 index 000000000..2c1fbc5ff --- /dev/null +++ b/docs/how-to-use/search/fulltext-search.md @@ -0,0 +1,35 @@ +# Full-text search (Component) - DEPRECATED + +Input field to perform a full text search. + +## Parameters + +Name | Type | Description +--- | --- | --- +route | string | Route to navigate after search. This route path should contain a component for search results. +projectfilter (optional) | boolean | If true it shows the selection of projects to filter by. +filterbyproject (optional) | string | If the full-text search should be filtered by one project, you can define it with project iri. + +## Examples + +### Simple full-text search + +```html + + + + +``` + +![Simple full-text search](../../assets/images/fulltext-search-simple.png) + +### Full-text search with project filter + +```html + + + + +``` + +![Full-text search with project filter](../../assets/images/fulltext-search-with-project-filter.png) diff --git a/docs/how-to-use/search/index.md b/docs/how-to-use/search/index.md new file mode 100644 index 000000000..13fd3e457 --- /dev/null +++ b/docs/how-to-use/search/index.md @@ -0,0 +1,110 @@ +# DSP-UI SEARCH module + +DspSearchModule allows to make simple searches or extended searches in DSP-API. In extended search, resource class and its properties related to one specific ontology are selected to create your query. It is also possible to write Gravsearch queries to target specific data with the expert search form. + +## Prerequisites + +For help getting started with a new Angular app, check out the [Angular CLI](https://cli.angular.io/). + +For existing apps, follow these steps to begin using DSP-UI SEARCH. + +## Installation + +DspSearchModule is part of @dasch-swiss/dsp-ui, follow [the installation guide](/how-to-use/getting-started/). + +## Components + +This module contains various components to search. The main component is the dsp-search-panel, which contains the dsp-fulltext-search, dsp-extended-search and dsp-expert-search. All of them can be used standalone or in combination in dsp-search-panel. + +### [Search panel](/developers/dsp-ui/documentation/search/search-panel) + +Fully customizable panel. You can set the following parameters in dsp-search-panel: + +- route: string; url-route for search results +- filterbyproject: string; project iri to limit search results by project +- projectfilter: boolean; selection of all projects to filter by +- advanced: boolean; additional menu with advanced / extended search +- expert: boolean; additional menu with expert search / gravsearch "editor" + +If everything is set to false or undefined the search-panel is a simple full-text search. [Read more](modules/search/search-panel) + +### [Full-text search (Deprecated)](/developers/dsp-ui/documentation/search/fulltext-search) + +`` + +The parameter `route` defines the route where the search-results-component of the app is defined. + +We suggest to define a route for the search-results in the app.routing + +```typescript + path: 'search', + component: SearchComponent, // --> Component with the search panel + children: [ + { + path: ':mode/:q/:project', + component: SearchResultsComponent // --> search results, in case of paramter filterByProject and/or projectFilter + }, + { + path: ':mode/:q', + component: SearchResultsComponent + } + ] +``` + +### [Extended / advanced search](/developers/dsp-ui/documentation/search/extended-search) + +Generic search filter tool to limit search results to ontology and resource class and / or properties. + +If you want to use this search, you have to add the following css style to your main app stylesheet to style the date picker properly. + +```css +.mat-datepicker-content { + .mat-calendar { + height: auto !important; + } +} +``` + +### [Expert search](/developers/dsp-ui/documentation/search/expert-search) + +Expert search is a textarea input field in which you can create Gravsearch queries. +The expert search can be more powerful than the advanced search, but requires knowing how to use the query language Gravsearch (based on SparQL and developed by the DaSCH team). With Gravsearch, expert users can build searches by combining text-related criteria with any other criteria. + +Check the [Gravsearch learning guide](https://docs.knora.org/paradox/03-apis/api-v2/query-language.html) on DSP-API documentation. + +## Setup + +Import the search module in your app.module.ts and add it to the NgModules's imports: + +```javascript +import { AppComponent } from './app.component'; +import { DspCoreModule, DspSearchModule } from '@dasch-swiss/dsp-ui'; + +@NgModule({ + declarations: [ + AppComponent + ], + imports: [ + DspCoreModule, // <- core module is required for some components and directives + DspSearchModule // <- add search module in the imports + ], + providers: [ ... ] // <-- add providers as mentioned in the installation guide + bootstrap: [AppComponent] +}) +export class AppModule { +} +``` + +The search components need a global styling in the app to override some material styling rules. Please update your `angular.json` file as follow: + +```json +... + "styles": [ + "src/styles.scss", + "node_modules/@dasch-swiss/dsp-ui/search/assets/style/search.scss" // <- add this line + ], +... +``` + + diff --git a/docs/how-to-use/search/search-panel.md b/docs/how-to-use/search/search-panel.md new file mode 100644 index 000000000..cb5925141 --- /dev/null +++ b/docs/how-to-use/search/search-panel.md @@ -0,0 +1,30 @@ +# Search panel (Component) + +The search-panel contains the list of projects to filter and dsp-fulltext-search and links to dsp-extended-search and dsp-expert-search. + +## Parameters + +Name | Type | Description +--- | --- | --- +route | string | Route to navigate after search. This route path should contain a component for search results. +projectfilter (optional) | boolean | If true it shows the selection of projects to filter by. +filterbyproject (optional) | string | If your full-text search should be filtered by one project, you can define it with project iri in the parameter filterbyproject +advanced (optional) | boolean | Adds the extended / advanced search to the panel +expert (optional) | boolean | Adds the expert search / gravsearch editor to the panel + +## Examples + +Implement the search panel in your HTML file: + +```html + + + + +``` + +![Full search panel](../../assets/images/search-panel.png) diff --git a/docs/how-to-use/viewer/index.md b/docs/how-to-use/viewer/index.md new file mode 100644 index 000000000..38862da14 --- /dev/null +++ b/docs/how-to-use/viewer/index.md @@ -0,0 +1,45 @@ +# DSP-UI VIEWER module + +DspViewerModule contains components to display resources; as a single item or as a list for search results. It is comprised of resource sub-components such as file representations components to display still images, video, audio or text only and also value components to use single property elements. + +## Prerequisites + +For help getting started with a new Angular app, check out the [Angular CLI](https://cli.angular.io/). + +For existing apps, follow these steps to begin using DSP-UI VIEWER. + +## Installation + +DspViewerModule is part of @dasch-swiss/dsp-ui, follow [the installation guide](/how-to-use/getting-started/). + +## Setup + +Import the viewer module in your app.module.ts and add it to the NgModules's imports: + +```javascript +import { AppComponent } from './app.component'; +import { DspCoreModule, DspViewerModule } from '@dasch-swiss/dsp-ui'; + +@NgModule({ + declarations: [ + AppComponent + ], + imports: [ + DspCoreModule, // <- core module is required for some components and directives + DspViewerModule // <- add viewer module in the imports + ], + providers: [ ... ] // <-- add providers as mentioned in the installation guide + bootstrap: [AppComponent] +}) +export class AppModule { +} +``` + +## Usage + + +Use DSP-UI VIEWER module in the component template as follows. The example shows how to display a resource by iri = 'http://rdfh.ch/0803/18a671b8a601'. + +```html + +``` diff --git a/docs/how-to-use/viewer/search-results.md b/docs/how-to-use/viewer/search-results.md new file mode 100644 index 000000000..8878217a6 --- /dev/null +++ b/docs/how-to-use/viewer/search-results.md @@ -0,0 +1,72 @@ +# Search results (Component) + +The search-results component gets the search mode and parameters from routes or inputs, and returns the corresponding resources that are displayed in a list or a grid. The results can be filtered by project. + +## List of parameters + +- complexView (optional) +- searchQuery (optional) +- searchMode (optional) +- projectIri (optional) + +*** + +## Simple search results example + +### HTML file + +```html + +``` + +![Simple search results example](../../assets/images/search-results-simple.png) + +## Search results filtered by project example + +### HTML file + +```html + +``` + +### Typescript file + +```ts +export class SearchResultsComponent { + + projectIri = 'http://rdfh.ch/projects/0001'; // project iri + + constructor() { } +} +``` + +![Search results filtered by project example](../../assets/images/search-results-filter.png) + +## Search results providing search mode and query parameters example + +### HTML file + +```html + + +``` + +### Typescript file + +```ts +export class SearchResultsComponent { + + gravsearch: string = `PREFIX knora-api: + CONSTRUCT { + ?mainRes knora-api:isMainResource true . + } WHERE { + ?mainRes a knora-api:Resource . + ?mainRes a . + } + OFFSET 0`; + + constructor() { } +} +``` + +![Search results providing search mode and query parameters example](../../assets/images/search-results-filter.png) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..4129e67ee --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..7d42063de --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +mkdocs==1.1.2 +mkdocs-material==6.0.1 +mkdocs-include-markdown-plugin==2.7.1 +mkdocs-git-revision-date-plugin==0.3.1 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..41950bb21 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,58 @@ +site_name: DSP-UI documentation + +repo_url: https://github.com/dasch-swiss/dsp-ui-lib +repo_name: dasch-swiss/dsp-ui-lib +edit_uri: blob/main/docs/ +copyright: "© 2017 - 2021 Data and Service Center for the Humanities (DaSCH)" + +nav: + - Introduction: index.md + - User Guide: + - Getting Started: how-to-use/getting-started.md + - Core module: + - Introduction Core: how-to-use/core/index.md + - Viewer module: + - Introduction Viewer: how-to-use/viewer/index.md + - Search-results: how-to-use/viewer/search-results.md + - Search module: + - Introduction Search: how-to-use/search/index.md + - Search-panel: how-to-use/search/search-panel.md + - Fulltext search: how-to-use/search/fulltext-search.md + - Extended search: how-to-use/search/extended-search.md + - Expert search: how-to-use/search/expert-search.md + - Action module: + - Introduction Action: how-to-use/action/index.md + - AdminImage: how-to-use/action/admin-image.md + - ExistingName: how-to-use/action/existing-name.md + - Key: how-to-use/action/key.md + - Message: how-to-use/action/message.md + - Progress indicator: how-to-use/action/progress-indicator.md + - SortButton: how-to-use/action/sort-button.md + - StringifyStringLiteral: how-to-use/action/stringify-string-literal.md + - Truncate: how-to-use/action/truncate.md + - Contribution: + - How to contribute: how-to-contribute/index.md + - Design Documentation: how-to-contribute/design-documentation.md + - Docs Documentation: how-to-contribute/docs-documentation.md + - Release Notes: how-to-contribute/release-notes.md + +plugins: + - include-markdown + - search + - git-revision-date + +theme: + name: material + logo: 'assets/icons/dasch-icon-white.svg' + favicon: 'assets/icons/dasch-favicon.ico' + icon: + repo: fontawesome/brands/github + palette: + primary: 'deep purple' + accent: 'deep purple' + features: + - navigation.tabs + - navigation.sections + +extra_css: + - 'assets/style/theme.css' diff --git a/package.json b/package.json index 89d91613a..774640467 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,7 @@ "test": "ng t --watch=false --browsers=ChromeHeadless", "test-lib": "ng t --watch=false --browsers=ChromeHeadless --project @dasch-swiss/dsp-ui", "test-lib-local": "ng t --project @dasch-swiss/dsp-ui", - "build-lib": "ng b --prod --project @dasch-swiss/dsp-ui", + "build-lib": "ng b --prod --project @dasch-swiss/dsp-ui && cp README.md dist/@dasch-swiss/dsp-ui/", "build-lib-dev": "ng b --project @dasch-swiss/dsp-ui", "build-watchful-lib-dev": "ng b --project @dasch-swiss/dsp-ui --watch=true", "yalc-publish-lib": "npm run build-lib && yalc publish dist/@dasch-swiss/dsp-ui", diff --git a/projects/dsp-ui/Contribution.md b/projects/dsp-ui/Contribution.md deleted file mode 100644 index 94bae1763..000000000 --- a/projects/dsp-ui/Contribution.md +++ /dev/null @@ -1,95 +0,0 @@ -# Contribution - -## How to Contribute to This Project - -If you are interested in contributing to this project, -please read our [general contribution guidelines](https://docs.dasch.swiss/developers/dsp/contribution/) first. - -## Adding New Components etc. to the Library - -Install [Angular CLI](https://angular.io/cli) globally: - -```bash - npm install -g @angular/cli -``` - -To add additional components etc. to a module of the library, run: - -```bash -ng generate component [path/in/the/module/][name-of-component] --project @dasch-swiss/dsp-ui -``` - -For example, to create a new component `test` in the action module, run: - -```bash -ng generate component action/test --project @dasch-swiss/dsp-ui -``` - -This command will create a folder called `test` inside of `projects/dsp-ui/src/lib/action/` -containing the component's class, template, style, and spec files. - -Before testing the new component inside of the demo app, you have to rebuild it after each change: - -```bash -npm run build-lib -``` - -Alternatively, you can use [Live Reloading](https://github.com/dasch-swiss/dsp-ui-lib/blob/wip/dsp-1104-docs/README.md#run-the-application-locally-in-dev-mode-with-live-reloading). - -See [repository README](../../README.md#add-a-new-component-to-the-demo-application) -for more information about how to add new components to the demo application. - -## Architecture of the Library -See [design documentation](design-documentation.md). - -## Local Publishing of DSP-UI-LIB -The demo application uses the locally built version of DSP-UI-LIB, see the repository's [README](../../README.md#structure-of-this-project). - -If you want to install an unpublished version of DSP-UI-LIB in your Angular application, you can use [yalc](https://www.npmjs.com/package/yalc). -`yalc` publishes DSP-UI-LIB to a local store. - -Install `yalc`: - -```bash -npm install yalc -g -``` - -Build the library and publish it to the local store: - -```bash -npm run build-app -npm run yalc-publish-lib -``` - -Add the local build your Angular application: - -```bash -yalc add @dasch-swiss/dsp-ui -npm install -``` - -To remove it from your project and restore `package.json`, run: - -```bash -yalc remove --all -``` - -## Publish a New Version of the Library to NPM - -Before publishing: - -- Update README if necessary and commit the changes - -- Be sure that all dependencies to DSP-JS-LIB and DSP-API are set to the correct version: - - Update DSP-API version in `vars.mk` - - Update DSP-JS version in `package.json` and run `npm install` to update the `package-lock.json` - - Update DSP-JS version in section `peerDependencies` of `projects/dsp-ui/package.json` - -A new version will be published with each Github release as it's part of Github actions' workflow. -To make a new release, go to and update the draft called "Next release" by changing: - -- The tag version and the release title (same name) with the version number, e.g. `v3.0.0` or `v3.0.0-rc.0` -- If this is a pre-release, check the box "This is a pre-release" - -The new package will be available on . - diff --git a/projects/dsp-ui/README.md b/projects/dsp-ui/README.md deleted file mode 100644 index 9280276b0..000000000 --- a/projects/dsp-ui/README.md +++ /dev/null @@ -1,310 +0,0 @@ -# DSP-UI-LIB — A library to easily create Knora/DSP Apps - -[![npm version](https://badge.fury.io/js/%40dasch-swiss%2Fdsp-ui.svg)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) -[![CI](https://github.com/dasch-swiss/knora-ui-ng-lib/workflows/CI/badge.svg)](https://github.com/dasch-swiss/knora-ui-ng-lib/actions?query=workflow%3ACI) -[![npm downloads](https://img.shields.io/npm/dt/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) -[![minzipped size](https://img.shields.io/bundlephobia/minzip/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) -[![license](https://img.shields.io/npm/l/@dasch-swiss/dsp-ui.svg?style=flat)](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/LICENSE) - -## Introduction -The modules contained in DSP-UI-LIB help create an [Angular](https://angular.io) application to allow the user to connect to [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/) -in a quick and simple way. -Components and directives rely on [Angular Material](https://material.angular.io). - -DSP-UI-LIB is [free software](http://www.gnu.org/philosophy/free-sw.en.html), -released under [GNU Affero General Public](http://www.gnu.org/licenses/agpl-3.0.en.html) license. - -## Library modules -This library consists of four Angular modules that are briefly described below. -See [design documentation](design-documentation.md) for more detailed information. - -### DspCoreModule -The core module contains configuration files and all injection tokens needed to connect to DSP-API. - -### DspViewerModule -The viewer module contains components to display resources of different types from DSP-API, -and CRUD components to display, edit, create, and delete values. - -### DspSearchModule -The search module allows the user to make fulltext and advanced searches in DSP-API, -using a graphical interface. - -### DspActionModule -The action module contains special buttons (e.g. to sort a list), pipes and directives. - -## Setup - -### Installation -To use this library in your Angular app, install it from NPM: - -```bash -npm install @dasch-swiss/dsp-ui -``` - -### Dependencies -This library has the following peer dependencies, which you also have to meet: - - -- [@dasch-swiss/dsp-js](https://www.npmjs.com/package/@dasch-swiss/dsp-js) -- [jdnconvertiblecalendar](https://www.npmjs.com/package/jdnconvertiblecalendar) -- [jdnconvertiblecalendardateadapter](https://www.npmjs.com/package/jdnconvertiblecalendardateadapter) -- [ngx-color-picker](https://www.npmjs.com/package/ngx-color-picker) -- [openseadragon](https://openseadragon.github.io/#download) -- [svg-overlay](https://github.com/openseadragon/svg-overlay) -- [@ckeditor/ckeditor5-angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular) -- [ckeditor-build](http://github.com/dasch-swiss/ckeditor_custom_build) - -### Supported DSP-API Version -Check [vars.mk](../../vars.mk) to see which version of DSP-API this library is compatible with. - -### Setup -DSP-UI-LIB supports runtime configuration. -The configuration is loaded when your Angular application starts. - -In your Angular project, create the file `config.dev.json` inside `src/config/`: - -```json -{ - "apiProtocol": "http", - "apiHost": "0.0.0.0", - "apiPort": 3333, - "apiPath": "", - "jsonWebToken": "", - "logErrors": true -} -``` - -Likewise, create a file `config.prod.json` with `logErrors` set to `false`. -The configuration files are needed to establish a connection to DSP-API. - -Create the property `name` in `src/environments/environment.ts` and set it to "dev": - -```typescript -export const environment = { - name: 'dev', // <-- this env. will load config.dev.json - production: false -}; -``` - -In `src/environments/environment.prod.ts`: - -```typescript -export const environment = { - name: 'prod', // <-- this env. will load config.prod.json - production: true -}; -``` - -Depending on the [build options](https://angular.io/guide/build#configuring-application-environments) (dev or prod), -the environment and configuration are chosen. - -The config files have to be integrated in `angular.json` in the "assets" section: - -```json -"assets": [ - "src/favicon.ico", - "src/assets", - "src/config" <-- add the config directory here -] -``` - -Define the following three [factory providers](https://angular.io/guide/dependency-injection-providers#using-factory-providers) in your application's `app.module.ts`: - - 1. Provide a function that calls `AppInitService`'s method `Init` and returns its return value which is a `Promise`. - Angular waits for this `Promise` to be resolved. - The `Promise` will be resolved once the configuration file has been fetched and its contents have been assigned. - 1. Get the [KnoraApiConfig](https://www.npmjs.com/package/@dasch-swiss/dsp-js) instance from the `AppInitService` instance and provide it as `DspApiConfigToken`. - 1. Create a [KnoraApiConnection](https://www.npmjs.com/package/@dasch-swiss/dsp-js) instance with the config and provide it as `DspApiConnectionToken`. - -Provide it in the main module and include the desired DSP-UI modules in the imports: - -```typescript -@NgModule({ - declarations: [ - AppComponent, - ProjectsComponent - ], - imports: [ - BrowserModule, - AppRoutingModule, - DspCoreModule, // <-- add the dsp-ui modules here - DspViewerModule - ], - providers: [ - // 1. - { - provide: APP_INITIALIZER, // see https://angular.io/api/core/APP_INITIALIZER - useFactory: (appInitService: AppInitService) => - (): Promise => { - return appInitService.Init('config', environment); - }, - deps: [AppInitService], // depends on AppInitService - multi: true - }, - // 2. - { - provide: DspApiConfigToken, - // return the instance of KnoraApiConfig provided by AppInitService - useFactory: (appInitService: AppInitService) => appInitService.dspApiConfig, - deps: [AppInitService] // depends on AppInitService - }, - // 3. - { - provide: DspApiConnectionToken, - // create and return an instance of KnoraApiConnection - useFactory: (appInitService: AppInitService) => new KnoraApiConnection(appInitService.dspApiConfig), - deps: [AppInitService] // depends on AppInitService - } - ], - bootstrap: [AppComponent] -}) -export class AppModule { } -``` - -The contents of the configuration can be accessed via `AppInitService`s member `config`. -Just inject `AppInitService` in your service's or component's constructor. - -The library needs a global styling in the app to override some material design rules. -If you're using Angular CLI, this is as simple as including one line in your `styles.scss` file: - -```css -@import '@dasch-swiss/dsp-ui/src/assets/style/dsp-ui.scss'; -``` - -Alternatively, you can just reference the file directly. This would look something like: - -```html - -``` - -## Usage - - -Add the desired modules from DSP-UI to the `app.module.ts`. -Always import `DspCoreModule`. - -```typescript -@NgModule({ - declarations: [ - AppComponent, - ProjectsComponent - ], - imports: [ - BrowserModule, - AppRoutingModule, - DspCoreModule // <-- add the dsp-ui core module here - ], - providers: [ ... ] // <-- add providers as mentioned in section above - bootstrap: [AppComponent] -}) -export class AppModule { } -``` - - -**DspCoreModule** implements the `InjectionToken` `DspApiConnectionToken`. -The token provides an instance of `KnoraApiConnection` from [`@dasch-swiss/dsp-js`](https://www.npmjs.com/package/@dasch-swiss/dsp-js) -which offers methods to make requests to [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/queries/). -The following `ProjectsComponent` example shows how to retrieve all projects from DSP-API: - -```typescript -import { Component, Inject, OnInit } from '@angular/core'; -import { DspApiConnectionToken } from '@dasch-swiss/dsp-ui'; -import { ApiResponseData, ApiResponseError, KnoraApiConnection, ProjectsResponse, ReadProject } from '@dasch-swiss/dsp-js'; - -@Component({ - selector: 'app-projects', - template: `
  • {{p.longname}} ({{p.shortname}} | {{p.shortcode}})
` -}) -export class ProjectsComponent implements OnInit { - projects: ReadProject[]; - - constructor( - @Inject(DspApiConnectionToken) private _dspApiConnection: KnoraApiConnection - ) { } - - ngOnInit() { - this.getProjects(); - } - - getProjects() { - this._dspApiConnection.admin.projectsEndpoint.getProjects().subscribe( - (response: ApiResponseData) => { - this.projects = response.body.projects; - }, - (error: ApiResponseError) => { - console.error(error); - } - ); - } -} -``` - -**DspViewerModule** contains components to display resources; as a single item or as a list for search results. -It is comprised of resource sub-components such as file representations components to display still image, video, audio or simply text. - -It also contains value components which provide the necessary tools to display, edit, create, and delete values. - -Import DspViewerModule in the `app.module.ts`: - -```typescript -@NgModule({ - declarations: [ - AppComponent, - ProjectsComponent - ], - imports: [ - BrowserModule, - AppRoutingModule, - DspCoreModule, - DspViewerModule // <-- add the dsp-ui viewer module here - ], - providers: [ ... ] // <-- add providers as mentioned in section above - bootstrap: [AppComponent] -}) -export class AppModule { } -``` - - -And use it in the component template as follows. The example shows how to display a resource by iri = 'http://rdfh.ch/0803/18a671b8a601'. - -```html - -``` - -**DspSearchModule** allows different ways of searching in order to make simple or complex searches in DSP-API. This module contains various components you can use to search and all of them can either be used individually or in combination with one another using the search panel. - -Import DspSearchModule in the `app.module.ts`: - -```typescript -@NgModule({ - declarations: [ - AppComponent, - ProjectsComponent - ], - imports: [ - BrowserModule, - AppRoutingModule, - DspCoreModule, - DspSearchModule // <-- add the dsp-ui search module here - ], - providers: [ ... ] // <-- add providers as mentioned in section above - bootstrap: [AppComponent] -}) -export class AppModule { } -``` - - -And use it in the component template as follows. -The example shows how to display the search panel that includes the full text search bar. It can be customized by setting the parameters with your configuration. - -```html - - -``` - -## Contribution -See our [contribution guidelines](Contribution.md). diff --git a/src/index.html b/src/index.html index 61b488cb1..f5867dff2 100644 --- a/src/index.html +++ b/src/index.html @@ -2,7 +2,7 @@ - DSP-UI-LIB | Test and Playground Environment + DSP-UI | Test and Playground Environment