The config is a json object containing information about how the user interface for a specific project is displayed.
+The config is stored in the database and can be updated for a user without changing the code base.
+The default config is part of the repository in the config-fix.json file.
+
Config data is loaded by the ConfigService and then distributed to the relevant modules.
+This document aims to explain how cofiguration defines the rest of the application and all options that can be changed through the config.
The ConfigService is an Angular service that you can inject anywhere in the code if you need to access configuration values.
+It loads the configuration from the database (or the default file if no entry is available) first thing when starting the application.
+
Some core services use the ConfigService to dynamically set up parts of the application on startup.
+For example the NavigationItemsService creates the menu items as configured
+and the RouterService sets up Angular routing defining what components users see.
+The config service provides a behavior subject which will notify all subscribers when a new configuration was uploaded.
+This can be used for core tasks like setting up the routes or creating the navigation bar.
+
Top-level "view" components (i.e. components that are used to define a whole page, not just some building block for a part or section)
+receive their config data automatically assigned as @Input() properties mapped from config object property name to an identical component class property.
+This is handled by the RoutedViewComponent internally.
+(If needed for special cases, you can also access it through the standard Angular router and can access it by injecting ActivatedRoute.)
+
Storing config in DB
+
Config is currently stored in the normal app database with the fixed _id "_id": "Config:CONFIG_ENTITY".
+This document in the database has to contain a single property data that holds the config object whose parts are described here.
Uploading and downloading the configuration can be done by admins inside the admin view.
+
+
Config File
+
The config file is a json object containing information about what and how things are displayed in the application.
+On the top level of the config file, there are four different kinds of entries:
+
+
The main navigation menu (navigationMenu)
+
Views defining the UI of each page (view:<path>)
+
Lists of select options for dropdown fields (enum:<category-id>, including available Note categories, etc.)
+
Entity configuration to define [schemas](./entity-schema.html (entity:<entity-id>)
The top level entry navigationMenu builds the visible and clickable items for the navigation menu on the left hand side of the app. Right now, the navigationMenu has the only subentry items. items contains an array of objects, each object representing one item within the navigation menu. The order of the entries reflects how the navigation menu items are shown in the app.
+
Each navigation menu item object has to have the three properties name, icon and link. name hold the inscription of the item in the navigation menu in the app, icon indicates the little icon picture that is shown before the textual inscription of the item in the navigation menu and link contains the URL or view that the user is directed to when clicking on the navigation menu item. For every link given, there necessarily has to be a corresponding view-entry on the top level of the config file.
The largest part of the config file are the views. Each view entry starts with view:.
+The part that comes after the colon is what comes after the top level / in the URL of the app.
+There has to be one view entry with nothing after the colon, thus directing to the root path that is used as a default one when the user opens the app.
+Paths can have multiple parts, e.g. view:admin/conflicts.
+If we append :id, then this is used as a parameter directly from the app, e.g. view:child/:id is the path for the child details view where the app provides the child entity id to be viewed to the component.
+
The only mandatory field for each view is "component": telling the app which component to use for the respective view.
+The component part has to refer to an existing angular component within the app. Components that are valid and may
+be used for the view have the @DynamicComponent decorator present
+
The two optional fields of each view are "config": and "permittedUserRoles":.
+"permittedUserRoles" expects an array of user role strings.
+If one or more roles are specified, only users with these roles are able to see this menu item and visit this page in the app.
+
What comes within the "config": object depends on the component being used.
+The Dashboard-Component for example takes as "widgets:" an array of subcomponents, where every entry has to have a "component:" and may have an own "config:" object.
+(This "config" is passed to the component, which receives and handles it by implementing the OnInitDynamicComponent interface)
List components showing data in a table (such as ChildrenList oder SchoolsList) usually have the four config objects "title", "columns", "columnGroup" (optional) and "filters" (optional).
+(These are implemented by the EntityListComponent.)
+
The "title" is the text shown in the heading of the component.
+
"columns" contains an array of the columns to be displayed.
+The configuration for the columns happens with the FormFieldConfiguration interface.
+If all the information is available on the schema or through the datatype of a property, it is sufficient to put a string with the name of the property into the columns array.
The "columnGroup" object holds the three properties "default", "mobile" and "groups".
+"default" and "mobile" hold the names of the group of columns being displayed by default or on a mobile device.
+If the "columnGroup" property is not defined, all columns will be displayed.
+If "default" or "mobile" is not defined, the first entry of "groups" will be used.
+"groups" consists of an array of groups of columns, where every entry has a "name" and an array of column ids within "columns".
+Properties that are listed in any of the groups arrays and don't require further configurations, can be omitted from the columns array, the EntityListComponent will automatically add them.
The object "filters" within the config of a list component can be used to create filter options for the list data.
+The type of filter will be automatically determined by the datatype of that property.
+The filters allow to filter the table by the possible values of a property.
+This will create a filter for boolean values with three buttons (all, true, false).
+The names of these buttons can be specified using the "true", "false" and "all" option.
+The prebuilt option is used to enable or disable filters that contain more logic and are implemented inside the component which is displayed.
+This option requires the fields "type" and "id", where "id" matched the id of a prebuilt filter inside a component.
Detail components can show data of a single entity presented in multiple sections and forms.
+(These are implemented by the EntityDetailsModule, in particular the EntityDetailsComponent.)
+
You can find details on the config format and its sub-sections from API reference section: EntityDetailsConfig
+
The detail component requires three attributes: "icon", "entity" and "panels".
+"icon" indicates a little icon that will be rendered on the top of the page.
+"entity" expects the name of an entity for which the details page should be created.
+This has to match exactly the name of the entity defined by the @DatabaseEntity() annotation.
+The entity will then be loaded using the entity name and the id which is read from the URL.
+The "panels" field expects an array of panel definitions.
+Each panel has a "title" and an array of "components".
+The component configuration requires another "title", the "component" that should be rendered (the component has to be defined here OnInitDynamicComponent) and a configuration ("config") which is passed to this component.
The form component is a flexible component that can be used inside the details component.
+It allows to dynamically create a form through configuration.
+The configuration for this component expects a single field, the "fieldGroups".
+
The fieldGroups should be an array of logically related fields and optionally a header displayed above the group of fields.
+Each field group is rendered next to each other (as columns).
+You can also define only a single field in each fieldGroups entry, to display them next to each other instead of one field taking up full width.
+The definitions for the fields is defined by the FormFieldConfiguration
+However, the schema definitions of the entity should be sufficient so that only the names of the properties which should be editable in the form have to be provided.
+This means instead of placing an object in the fields array, simple strings do the same job.
This component shows a list of ChildSchoolRelations of a child in table.
+It can be configured which attributes of the ChildSchoolRelation are shown in the table and how the columns are named.
+Possible configurations are single and columns which are both optional.
+single is a boolean and if is set to true the component will show which (if any) school the child is currently attending.
+This should only be set to true, when the use-case only allows one active school per child.
+columns is an object and determines which columns of the ChildSchoolRelation are shown.
+The configuration is according to the EntitySubrecordComponent;
The entity object within the config file can be used to extend and configure existing entities.
+The name of the entity to which this config refers comes after the colon in this case "child".
+
Attributes
+
The attribute field allows to add attributes to an entity:
+Configure this as a key-value object with the property name as key and the schema as value, which refers to the entity schemas.
It is possible to overwrite, how an entity is converted to a string using the optional toStringAttributes key.
+This expects an array of strings referring to properties of that child which should be printed out.
+The order of these strings is also the order in which the property values are printed.
+
E.g. while some projects use a name property on a child, others might use firstname and lastname.
+In this case they probably want to show both the first and the last name in the app.
+To achieve this, the configuration of the Child entity can be extended like this:
For different organisations, entities might refer to different real life objects.
+In other words, it is not always suitable to call the entities Child or School and the icon might also be
+misleading.
+Therefore, the names and icons of entities can be changed through the config.
+This allows to change a text like Participants with unhealthy BMI to Patients with unhealthy BMI.
+To achieve this a label and labelPlural can be defined in the entity config.
+Additionally, the icon property allows to exchange the icon to another one from
+the FontAwesome Icon Library.
+
This also has to be adjusted when configuring in a different language.
Option lists or ConfigurableEnumValues can provide a pre-set list of options for a field
+to allow users to easily select an option from a dropdown and ensure that users are not entering random, invalid values.
+
Config entries for this purpose have a prefix enum: followed by an id you can freely define (e.g. enum:project-status).
+
The value is an array of objects defining the options. Mandatory fields for each option are "id" and "label".
+"id" should be written in uppercase letters without spaces (user underscore _ instead).
+The "id" should always stay the same as it is written to the database and identifies the value even if you rename the label shown to users.
+"label" holds the human-readable text for the dropdown entry or wherever the value is shown to the user.
+This text may be changed without any negative effect to data consistency and the change will instantly be visible in all saved entries of this type.
+
Example:
+Example :
"enum:project-status": [
+ {
+ "id": "ACTIVE",
+ "label": "active"
+ },
+ {
+ "id": "COMPLETED",
+ "label": "completed the programme"
+ },
+ {
+ "id": "DROPPED",
+ "label": "dropped out of the programme"
+ }
+]
Defining configurable enum properties
+
In order to use such an "enum" in entity fields, you need to set the schema datatype and the form type in the according config objects:
+
In the entity, set the dataType to "configurable-enum" and the "additional" to the id of the enum config:
A property can also be defined in a way that multiple values can be selected.
+To allow multiple selection, additionally isArray should be true.
+The following example creates a property materials where multiple values from the materials configurable enum can be selected.
There are a few specially built-in types of enums.
+The interaction types available for Notes are configured as the enum:interaction-type.
+
In addition to id and label for the interaction types you can optionally also configure "color"and "isMeeting".
+"color"can contain a background color for the entry in the form of the hexadecimal code, e.g. #E1F5FE.
+"isMeeting" is of the type boolean and tells whether the interaction type refers to a meeting or not.
For us, an "Entity" is an object in the database (and a representation of something in the user's real world, e.g. a "Child" or "School").
+Entities are at the core of the Aam Digital platform and the primary way to customize the system is to adapt and add new entity types.
+
The Entity Schema defines the data structure as well as how it is displayed in the UI.
+Entity instances also have some generic functionality inherited from the Entity base class.
+
+
see the sub-pages here for details of the various concepts related to the Entity system
Any entity can be archived (i.e. marked as inactive and hidden from UI by default) or anonymized (i.e. discarding most data and keeping a few selected properties for statistical reports).
+This is often preferable to deleting a record completely. Deleting data also affects statistical reports, even for previous time periods.
+By anonymizing records, all personal identifiable data can be removed and the remaining stub record can be stored indefinitely, as it is not subject to data protection regulations like GDPR anymore.
+
Anonymization is configured as part of the entity schema.
+Data of fields that are not explicitly marked to be retained during anonymization is always deleted (anonymization by default).
+
To keep some data even after the user "anonymized" a record, configure the anonymize property of the @DatabaseField decorator:
+
+
anonymize: "retain" will keep this field unchanged and prevent it from being deleted
+
anonymize: "retain-anonymized" will trigger a special "partial" deletion that depends on the dataType (e.g. date types will be changed to 1st July of the given year, thereby largely removing details but keeping data to calculate a rough age)
+
+
Cascading anonymization / deletion
+
Relationships between entities are automatically handled when the user anonymizes or deletes an entity.
+Any related entities that reference the anonymized/deleted entity are checked
+and - depending on their configured role - may be updated or anonymized as well.
+
The logic follows the scenarios shown below:
+
+
Data Protection & GDPR regarding anonymization / pseudonomyzation
+
The "anonymize" function is implemented specifically for data protection rules requiring to delete personal data.
+According to the EU's "General Data Protection Regulation" (GDPR) "anonymous" data does not fall under its regulations:
+
+
GDPR is not applicable to anonymous data: "The principles of data protection should therefore not apply to [...] personal data rendered anonymous in such a manner that the data subject is not or no longer identifiable." GDPR Recital 26
+
"To determine whether a natural person is identifiable, account should be taken of all the means reasonably likely to be used, such as singling out, either by the controller or by another person to identify the natural person directly or indirectly."
+
"To ascertain whether means are reasonably likely to be used to identify the natural person, account should be taken of all objective factors, such as the costs of and the amount of time required for identification, taking into consideration the available technology at the time of the processing and technological developments."
+
+
+
"Pseudonymisation enables the personal data to become unidentifiable unless more information is available whereas anonymization allows the processing of personal data to irreversibly prevent re-identification." source
In the case of records being retained "anonymized" in Aam Digital, we provide a context that makes re-identification even harder:
+
+
only authorized users of the system can access even the anonymized record (where only a few properties have been retained). Unless the organisation actively shares the data, it remains as securely protected as the personal data managed in Aam Digital.
+
those authorized users with access to the anonymized records (and therefor a theoretical chance to attempt re-identification) are team members of an organization. They have been screened to be responsible persons and are usually legally bound to keep information confidential.
+
by default only a few, explicitly selected properties in anonymized records are retained (data minimization by default). As such, both re-identification likelihood and the impact in case of re-identification are reduced as far as possible.
+
+
--> If our anonymization process is configured thoughfully on a case by case basis to only retain a few data fields that are not easy indirect identifiers, it seems reasonably unlikely that the person can be identified after the anonymization process. Therefore, GDPR should not apply to these records and it is legitimate to retain these for statistical reporting.
The Entity Schema defines details of the properties of an entity type.
+We define an entity type and its schema in code through a plain TypeScript class and some custom annotations.
+Read more on the background and practical considerations in How to create a new Entity Type.
+
An example of a schema definition:
+Example :
@DatabaseEntity('Child') // configures the database prefix to be used by the Schema system
+class Note extends Entity {
+ @DatabaseField() children: Child[];
+ @DatabaseField() text: string = 'default text';
+ @DatabaseField() date: Date; // dataType is inferred from the Typescript type
+ @DatabaseField({dataType: 'month'}) reportingMonth: Date; // sets a specific dataType how this value will be written to the database
+}
+
The logical flow looks something like this:
+
+
Entities are requested through the EntityMapperService (entityMapper.load(...))
+
The EntitySchemaService functions as a helper to the EntityMapperService
+and takes care of data transformations based on the schema of that entity type.
+
Data from the database is "loaded" into an entity instance to combine the raw data
+with its entity class by the EntityMapperService together with the EntitySchemaService.
+
The entity classes themselves only define the schema through the @DatabaseEntity and @DatabaseField decorators
+and are otherwise simple Typescript objects.
+
+
The process of saving an entity to the database works similarly with EntitySchemaService
+supporting the EntityMapperService and transforming the entity object into the desired format to be persisted into the database.
+
+
EntitySchemaService manages a registry of "data types",
+i.e. transformation functions that will be called for a specific schema field's dataType.
+
Basic data transformations for string, number, date and month are supported by default.
+You can register your own types by implementing services extending DefaultDatatype and
+providing these through Angular dependency injection using multi: true.
The schema definitions contains information regarding the schema transformation as well as how a property can be displayed.
+The EntitySchemaField interface shows all configuration options.
+If the editComponent and the viewComponent are not set, the default components of this property's datatype will be used.
+The description field allows adding further explanation which will be displayed as a tooltip.
+
Generic Entity functionalities
+
Metadata (created, updated)
+
Each record automatically holds basic data of timestamp and user who created and last updated the record.
+(see Entity class)
Aam Digital is designed to be an extendable platform.
+We try to define core interfaces that can be implemented in additional feature modules
+to implement further functionality in a modular way.
+
The following aspects are specifically designed to be extended:
+
+
DataTypes
+
transformation functions how data is stored in / read from database
+
editComponent how data is displayed and edited in forms
+
viewComponent how data is displayed in tables
+
importValueMapping to support smart import into the data type
pre-define a data structure with various fields and custom logic that may be interconnected. This mostly is useful if you implement very specialized UI components for a specific data structure.
+
any entity type can be extended through config for individual clients (e.g. adding further properties at runtime)
+
demo data generator to automatically provide useful sample records
defining a screen completely, including data loaded, etc. and hook it into the platforms navigation and overall layout
+
+
+
Sub-Views
+
defining a screen to display custom details for the entity currently loaded in the active route. The core platform takes care of passing the current entity and config details to the view as inputs.
filling the given card template with custom data and visualization
+
+
+
Filters
+
specialized logic and UIs to filter list data
+
+
+
Technical "Backend" Implementations
+
less common to change, but possible to implement integrations with different technical systems are
+
Authentication Services (e.g. switch between native CouchDB users and more advance Keycloak)
+
Database / Local Storage (e.g. switch between PouchDB using IndexedDB and purely in-memory, discardable data storage - or possibly implement an integration with a different system)
+
+
+
+
+
+
The folder structure of the code base (while containing some intertwined legacy structures) also reflects this architecture:
+
+
src/app/core: generic structures and platform code
+
src/app/features: more specialized, modular features that plug into the core code (e.g. a location / map integration type)
Aam Digital is an Angular application and can be deployed on a simple webserver.
+To do so we are using Docker and some other tools.
+
The following diagram show the actions that are performed when new code changes are published.
+
+
Dockerfile
+
The Dockerfile can be found in /build/Dockerfile.
+It provides a stable environment where the application is build, tested and packaged.
+It consists of two stages.
+The first stage is build on top of a node image and builds the application for production usage and optionally runs tests and uploads the test coverage.
+The second stage is build on top of a nginx image and only copies the files from the previous stage, which are necessary for deploying the application.
+This process makes the final image as small as possible.
+nginx is used to run a lightweight webserver.
+The configuration for nginx can be found in /build/default.conf.
+
Pull Requests
+
Whenever a new pull request is created, GitHub creates a new app on Heroku and posts the link to this app in the PR.
+For each new commit of a PR, GitHub then builds the Docker image for this branch.
+This includes building the application in production mode, linting the sourcecode and running the tests.
+If all these stages pass, GitHub will upload the newly created image to Heroku.
+Once this is done, a version of Aam Digital with the new changes included can be visited through the posted link.
+
Master Updates
+
After approving a PR and merging it into the master, semantic release automatically creates a new tag for this change.
+For each new tag a tagged Docker image is uploaded to DockerHub.
+
Deploying Aam Digital
+
The Docker image from DockerHub can then be downloaded and run via Docker using the following command:
+
+
docker pull aamdigital/ndb-server && docker run -p=80:80 aamdigital/ndb-server
+
+
However, this will only run Aam Digital in demo-mode.
+To run Aam Digital with a real database, a new config.json file has to be mounted into the image.
+This should have a structure equal to config.default.json (/src/assets/config.default.json).
+It holds the information about where to find the remote database, what the name of the app is and in which mode the app is being run.
+
The ndb-setup project provides a clear workflow for how to deploy a new instance of Aam Digital and CouchDB.
+It extends the Docker image with a docker-compose.yml file which handles all the dependencies.
+For further information checkout the README.
This is a rough sketch of the architecture of the core system under discussion. The modules and classes shown here are included in the ndb-core repository.
+
+
An actual, specific software system to be used will be based on the core and extend it:
+
+
Folder Structure
+
The application code is split within the src/app/ directory into modules providing
+general features and abstract components (core) and
+concrete feature modules for users' use cases (currently only child-dev-project).
We have made both technical and design choices to develop a secure platform.
+The Angular framework itself has some in-built protection against common security issues like cross-site scripting attacks (see Angular > Security).
+Beyond this, the following measures are implemented:
+
+
If deployed including our "replication-backend", that server-side API also ensures authenticated users can only access and sync data their account has permissions for.
+
Password policy enforces users to set a strong password including special characters (either via Keycloak or the platforms user profile form)
+
Content Security Policy (CSP) headers restrict connections to and execution of code from sources that are not whitelisted.
+
+
Content Security Policy (CSP)
+
CSP headers are set in the nginx server being built from the code base to serve the Angular app.
+The whitelisted CSP sources can be overwritten and adapted using a docker environment variable CSP (the default whitelist is defined in the Dockerfile).
+
+
CSP is currently running in "report-only" mode for testing.
+Scripts and connections are not yet blocked by default.
+
+
Allowing PouchDB to function under CSP
+
The browser-side database system PouchDB uses map-reduce functions for indexing which are defined as strings.
+It is therefore requiring 'unsafe-eval' in the CSP.
+
Whitelisting the index.html
+
To whitelist a specific script section (currently only in the index.html) a CSP hash can be used.
+Updating the hash should be necessary only rarely, when that script section changes.
+
The easiest and most reliable way to get the correct hash is to deploy a production build image and check the browser console.
+It states something like "Refused to execute inline script because it violates the following Content Security Policy directive: "...". Either the 'unsafe-inline' keyword, a hash ('sha256-<RELEVANT HASH>')" or a nonce is required." from where you can copy the given hash and include/update it in the CSP headers.
+Generating the hash by pasting the script into an online generator does not seem to work, probably because code is minified during the build process.
Lets talk about state for a second. With an offline-first synced session, there is lots of state involved needing to be synced. The following enums are used to define the possible states.
+
+
LoginState At the beginning or after logout the state is LOGGED_OUT. After successful login, the state changes to LOGGED_IN. Entering wrong credentials will result in LOGIN_FAILED. If login is not possible at the moment (due to bad or no internet) the state is UNAVAILABLE.
+
SyncState At the beginning or without internet the state is UNSYNCED. Once the user logs in the state changes to STARTED. If no problems occur, the state will change to COMPLETED, once all data is synced. If an error occurs the state changes to FAILED.
+
+
Database User
+
The DatabaseUser interface mirrors parts of the user documents as it is used by CouchDB (see here).
+The most important properties are the name which is equivalent to the username and the roles which is an array of roles the user has.
+The name can be used to assign e.g. notes to a user or find the User entity in the database.
+The roles are used to check whether the user has permissions to visit certain pages or edit certain entities.
+
Local User
+
The LocalUser interface is used by the LocalSession to store user information in the local storage.
+Additionally to the fields of the DatabaseUser interface it holds the encrypted password together with information how the password is encrypted.
+This can be used to verify the password later on.
+
Session Services
+
The SessionService interface provides methods for login, logout and user access.
+These methods need to be implemented to create a working session.
+
Local Session
+
The LocalSession manages a session without internet. It can be used for demo purposes or when no network connection is available.
+The session loads LocalUser objects from the local storage and uses the encrypted password to validate login credentials.
+It provides an additional method to save DatabaseUser objects together with the password to the local storage.
+If the password matches, it returns LoginState.LOGGED_IN.
+If the username matches an existing username but the password is wrong, it returns LoginState.LOGIN_FAILED.
+If the username does not match any saved users, it returns LoginState.UNAVAILABLE.
+
Remote Session
+
The RemoteSession directly authenticates against a CouchDB instance.
+It uses the _session endpoint of the CouchDB API for cookie-authentication.
+Once successfully logged in, a cookie is stored and sent with any further request to CouchDB.
+This cookie is valid for 10 minutes and renewed by CouchDB if regular requests occur.
+If the password matches, it returns LoginState.LOGGED_IN.
+If CouchDB returns are 401 error (unauthorized), it returns LoginState.LOGIN_FAILED.
+If the requests fails with an error message other thatn 401, it returns LoginState.UNAVAILABLE.
+
Synced Session
+
The SyncedSession combines the LocalSession and the RemoteSession.
+It starts the login workflow of both the RemoteSession and the LocalSession at the same time.
+It first only waits for the LocalSession because this is faster and also works without internet.
+Only if the local login fails the SyncedSession waits for the remote login.
+If the remote login succeeds, the returned user object is saved through the LocalSession to allow a local login next time.
+
The following table shows all possible return values of the local and the remote session and the handling of the synced session.
+The error message is shown in the LoginComponent
+
+
+
+
Remote Login
+
Local Login
+
Synced Login
+
Error Message
+
+
+
+
+
LOGGED_IN
+
LOGGED_IN
+
login + sync
+
-
+
+
+
LOGGED_IN
+
LOGIN_FAILED
+
sync + login
+
-
+
+
+
LOGGED_IN
+
UNAVAILABLE
+
sync + login
+
-
+
+
+
LOGIN_FAILED
+
LOGGED_IN
+
login -> logout
+
-
+
+
+
LOGIN_FAILED
+
LOGIN_FAILED
+
LOGIN_FAILED
+
Username and/or password incorrect
+
+
+
LOGIN_FAILED
+
UNAVAILABLE
+
LOGIN_FAILED
+
Username and/or password incorrect
+
+
+
UNAVAILABLE
+
LOGGED_IN
+
login + retry
+
-
+
+
+
UNAVAILABLE
+
LOGIN_FAILED
+
LOGIN_FAILED
+
Username and/or password incorrect
+
+
+
UNAVAILABLE
+
UNAVAILABLE
+
UNAVAILABLE
+
Please connect to the internet and try again
+
+
+
+
To illustrate this table, the following flow-diagram shows what happens in the case RemoteLogin: LOGGED_IN and LocalLogin: LoginFailed.
+This case happens when the password of a user has been changed on the server, but not locally and the users logs in with the new password.
+
.
+
The flow starts by the user entering a username and a password in the LoginComponent.
+First the user credentials are validated against the local session.
+This fails possible because the saved password does not match the user-entered one.
+Then the synced session waits for the remote login to finish.
+In this case the remote login succeeds and the DatabaseUser object can be retrieved from the remote session.
+The synced session then stores the DatabaseUser in the local session and after that tries to log in against the local session.
+Now that the DatabaseUser has been saved with the new password the local log in succeeds and returns LoginState.LOGGED_IN.
User roles are used to restrict what components a user can see and what data a user can access and edit.
+These roles are stored in the backend and are available in the frontend after a successful login.
+At the moment there are two places, depending on your system setup, where the roles can be defined.
+
CouchDB
+
When using CouchDB as authenticator, then the roles are directly stored on the org.couchdb.user document of a user.
+A new role can be added to a user by simply adding the name of the role to the user document.
+After the next login, the role will be available in the frontend.
+
Keycloak
+
When using Keycloak as an authenticator, the roles are assigned through so called Role-Mappings.
+To assign a new role to a user, this role first has to be created in the realm.
+To do this go to the Keycloak admin console, select the realm for which you want to create a role and go to the Realm
+roles menu item.
+Here a new role can be created and also a description can be provided for it.
+This description should explain non-technical users, what this role is there for.
+Default roles that are always available are user_app, admin_app and account_manager.
+After a role has been created, the role can be assigned to a user.
+This can either be done in the frontend using the UserSecurityComponent or via the Keycloak admin console under _
+Users_
+-> <select user> -> Role mapping -> Assign role.
+
Permissions
+
Aam Digital allows to specify permissions to restrict access of certain user roles to the various entity types.
+Permissions are defined using the CASL JSON syntax
+.
+The permissions are stored in a config object which is persisted together with other
+entities in the database.
+
Permission structure
+
As an example, we will define a permission object which allows users with the role user_appnot to create, read
+, update and deleteHealthCheck entities and notcreate and deleteSchool and Child entities.
+Besides that, the role is allowed to do everything.
+A second role admin_app is allowed to do everything.
+Additionally, we add a default rule which allows each user (independent of role) to read the Config entities.
+Default rules are prepended to the rules of any user and allow to configure user-agnostic permissions.
+The default rules can be overwritten in the role-specific rules.
The _id property needs to be exactly as displayed here, as there is only one permission object allowed in a single
+database.
+In data, the permissions for each of the user role are defined.
+In this example we have permissions defined for two roles: user_app and admin_app.
+The permissions for a given role consist of an array of rules.
+
In case of the user_app, we first define that the user is allowed to do everything.
+subject refers to the type of entity and all is a wildcard, that matches any entity.
+action refers to the operation that is allowed or permitted on the given subject.
+In this case manage is also a wildcard which means any operation is allowed.
+So the first rule states any operation is allowed on any entity.
+
The second and third rule for user_app restrict this through the "inverted": true keyword.
+While the first rule defined what this role is allowed to do, when "inverted": true is specified, this rule
+defines what the role is not allowed to do.
+This allows us to easily take permissions away from a certain role.
+In this case we don't allow users with this role to perform any operation on the HealhCheck entity and no create
+and update on Child and School entities.
+Other possible actions are read and update following the CRUD concept.
+
The admin_app role simpy allows user with this role to do everything, without restrictions.
+
To learn more about how to define rules, have a look at
+the CASL documentation.
+
It is also possible to access information of the user sending the request. E.g.:
This allows users to update the password property of their own document in the _users database.
+Placeholders can currently access properties that the replication-backend explicitly adds to the auth user object.
+Other available values are ${user.roles} (array of roles of the user) and ${user.projects} (the "projects" attribute of the user's entity that is linked to the account through the "exact_username" in Keycloak).
+
For more information on how to write rules have a look at the CASL documentation.
+
Implementing components with permissions
+
This section is about code using permissions to read and edit entities.
+If you want to change the menu items which are shown in the navigation bar have a look at the views section in
+the Configuration Guide.
+
The permission object is automatically fetched whenever a user logs in.
+The permissions disable certain buttons based on the users overall permissions.
+This is done in the app through
+the DisableEntityOperationDirective, which connects certain
+buttons with their operation.
+
As an example lets say we have a class variable called note which holds an object of the Note entity.
+We want to create a button which allows to edit this note.
+In the HTML template we could write the following in order to automatically connect it to the permission system:
This will automatically disable the button if the user is not allowed to update this specific note.
+
To check permissions inside a *.ts file, you can inject the EntityAbility:
+Example :
import { Note } from "./note";
+import { Injectable } from "@angular/core";
+import { EntityAbility } from "./permission-types";
+
+@Injectable()
+export class SomeService {
+ constructor(private ability: EntityAbility) {
+ if (this.ability.can("create", Note)) {
+ // I have permissions to create notes
+ const note = new Note();
+ } else {
+ // I don't have permissions to create notes
+ throw Error("Missing permissions");
+ }
+ }
+}
In this example the EntityAbility service is used to check whether the currently logged in user is allowed to create
+new objects of the Note entity.
+In this case a constructor is provided to check for the permissions,
+in other cases it might make more sense to use an instance of an object like this.ability.can('read', new Note()).
+
Permissions in production
+
As permissions cannot directly be created and edited from within the app at the moment, you can use the following steps
+to define permissions for a deployed system:
+
+
using CouchDB Fauxton GUI to edit database documents directly:
+Look for or create the document with "_id": "Config:Permissions" and define the permissions as described above.
+
After saving the new permissions document, update the replication backend about the updated permissions:
+Visit https://<your-system-domain>/db/api/ to use the OpenAPI interface for this.
+
There in Servers select /db deployed.
+
Click on Authorize enter valid user credentials and click Login.
+
Make a request to the POST /rules/{db}/reload endpoint, where {db} is the active database, e.g. app. If
+successful, the response will show the newly fetched rules.
+
In case some users might have gained access to documents to which they did not have access before,
+also trigger the POST /{db}/clear_local endpoint, where {db} again is the active database.
+The /{db}/clear_local endpoint will ensure that each client re-checks whether new objects are available for
+synchronization.
+This should also be used in case an existing user has gotten a new, more powerful role.
+In case a user lost permissions for objects that were already synced, this users local DB will automatically be
+destroyed and the user has to synchronize all data again.
+
+
The roles assigned to users are specified in the user documents in the _users database of CouchDB.
+
Permissions in development
+
When trying to test out things with the permissions,
+the DemoPermissionGeneratorService can be modified to change the
+permission object which is created in the demo data.
+These changes should not be committed however, as this demo data is also used in the publicly available demo.
+
The demo data comes with two user: demo and demo-admin.
+The demo user has the role user_app, the demo-admin has the roles user_app and admin_app.
+The permissions of the latter overwrite the permissions of the former.
The user should have a consistent experience across all areas of the app
+(i.e. whether editing needs to be enabled, how changes can be undone, how and how long notifications are displayed).
+More and more these actions will be generalized by components and services that we will use for our implementation of a specific form or page.
+Until then, our UX "policy" is loosely documented below:
+
+
Deleting an entity is always possible to undo by a simple SnackBar Action in the related SnackBar notification, shown for 8 seconds.
+
Views/Forms are by default not editable and have to be enabled through an "Edit" button.
+
Changes in forms are not saved automatically and have to be confirmed through a "Save" button.
In your html-components, mark any text that should be translated
+using the i18n directive:
+Example :
<button i18n-title="<meaning>|<description>" title="I am a button" i18n="<meaning>|<description>">Click me!</button>
+
In your other components, mark strings that may be translated
+using the localize function:
+Example :
const notification = $localize`I have eaten all ${number} Muffins`;
+
+
Elaborate Answer
+
The i18n-directive
+
The i18n directive allows up to three optional arguments. The first two -
+meaning and description - are used to aid translators while analyzing the
+texts. The third one is an optional ID. This ID is generated by angular and
+does not have to be provided.
+
If different components have the same content and the same meaning, they will
+be merged automatically, it is therefore not required (and will, in fact,
+generate a warning) to assign a custom id to components that should be
+translated in the same way. To enable this behavior, the same content and
+meaning should be provided.
+
The meaning of a text message is important so that translators can understand
+what the text should represent, even without having to see the actual website.
+Take this example:
+Example :
<span i18n>Address of {{user}}: {{user.address}}</span>
Without further knowledge, what does address refer to? The physical address
+of the user, or his internet-address?
+It is therefore always good practice including a meaning and further description
+like so:
+Example :
<span i18n="Address field|The address that a user lives at"> Address of {{user}} </span>
The i18n directive can also be used to translate tooltips, titles and other
+attributes of the element. This is done by writing i18n-title,
+i18n-matTooltip, e.t.c. The rules are the same as for the regular directive.
+
The localize-function
+
While html-elements can be marked for translation using the i18n directive,
+the same is not true for strings in non-html components. To enable localization
+here, the function $localize() is used. It is comparable to the directive,
+however some small changes have to be taken into account:
+
+
Meaning and description of the string to translate are in front of the actual
+string and are marked using two colons (:).
+
The translate-function is special in that it conceptually does not have
+parameters. Instead, the string is directly written after the identifier
+
+
Example:
+Example :
alertService.warn($localize`:Illegal input warning:Please provide the correct input for ${field}`);
Variables inside the string can be of arbitrary complexity and are escaped using the
+${} syntax.
Once content with the process of marking fields as translatable and providing
+good and understandable meaning to these fields, translation-files can be
+generated. This is done using the extract-i18n-script (Can be found in the
+file package.json). This script will generate one
+"Base file" and will also generate and update existing translation files
+for all locales given in the script. These will be located in the
+locale directory.
+XLF files are standardized and can be read using standard tools such as
+the Online XLIFF Editor
+
The translation files are in xml-format. After some preambles, there are
+characteristic blocks that follow all the same schema; blocks like this:
The <source> section is this the original string that we defined in code or html.
+If you are not in the messages.xlf file but in any other messages.<locale>.xlf file,
+you can provide translations. for the locale. For a list of common and standardized locales,
+see the ISO-639-2 standard.
+
To provide a translation, add the <target> tag inside the <trans-unit>
+tag (assuming we are inside messages.de.xlf and therefore looking for a
+german translation):
at the end of "projects" --> "ndb-core" --> "architect" --> "build" before the "configuration"-section starts.
+
Since the build process is fairly complex, only one locale is allowed during
+development. The locale must be inside the locale-folder and be of type
+messages.<your locale>.xlf
+
Angular will not translate the components on the fly. Instead, it will
+generate a separate app for each and every component provided in the
+localize array.
+
Other types of localization
+
Texts are not the only thing characterizing an international app. Other data
+has a different expression in different cultures. To enable this, several pipes
+can be used to transform that data automatically. For example:
+Example :
<span>It's a nice day {{today | date}}</span>
Will transform the date to different locales.
+Pre-built pipes are
+
+
DatePipe: Formats a date
+
CurrencyPipe: Transforms a number to a currency string
+
DecimalPipe: Transforms a number into a decimal string with given accuracy
+
PercentPipe: Transforms a number to a percent-string
+
+
ICU-Components
+
ICU is another standard that Angular uses to localize strings. There
+are two ICU-standards of interest: Pluralization and Selection
+
Pluralization
+
Some phrases contain plurals, such as
+Example :
<span>The game starts in {{minutesTillStart}} minutes</span>
This can produce the incorrect result of "The game starts in 1 minutes". To
+improve this, one should use plural forms. These have the following syntax:
amount is the selector - how much actually exists. Following this,
+the plural selector follows, indicating that this is a pluralized form.
+Finally, the different values that one can pluralize are described. Legal
+values are
+
+
=x matches, when the amount is exactly that value
+
one
+
two
+
few
+
many
+
others
+
+
others matches all amounts that cannot be matched by anything else. So the
+text above could be pluralized like this:
+Example :
<span>The game starts { minutesTillStart, plural,
+ =0 {right now}
+ one {in one minute}
+ others {in {{minutesTillStart}} minutes} }
+</span>
Selection
+
Selection selects one option of a set of selections. A suitable example
+for this is the gender of a person:
+Example :
This is {{person}}. {gender, select, male {He} female {She}} is a nice person.
Can be translated to the variants "This is Tom. He is a nice person" as well as
+"This is Nancy. She is a nice person". The syntax is:
The variable's type is arbitrary, however the options have to make sense.
+Types that are known to work well are the standard types of strings, numbers
+and booleans.
+
Do's and dont's
+
+
Try to keep your translatable texts as simple as possible concerning the
+amount of string-interpolation or computation inside the {{}}-Blocks. This
+makes it easier for translators
+
+
It may be tempting sometimes to do a 'string-in string' interpolation like so:
This must not be done. It is hard for translators to understand what's
+going on inside the interpolation, and the translated text might not
+be accepted by Angular's localize-package. Instead, you could use a
+custom getter:
This guide depicts the workflow one needs to go through to add another language
+(such as hindi, bengali, french e.t.c.) to the project
+
1) Find the correct language code
+
You first need the correct ISO-639-2 Language-Code. To find this code for a given
+language, go to their website
+and find the code that corresponds to your language (look in the ISO 639-1 Code column).
+For example, for french, this would be fr, for hindi, this would be hi
+
In addition to a language code, you might consider specifying a country if the spoken language can
+differ based on where the app should be shipped to. For example, English is spoken differently
+in the US (en-US), Great-Britain (en-GB) or Australia (en-AU).
+A list of available country codes can be found here.
+Once you have the language and country code, the resulting code is language code-country code.
+
2) Let xliffmerge know about the new language
+
xliffmerge is a tool that helps in the translation process. Especially, it is needed to
+update the language files while retaining old translations.
+
Go to xliffmerge.json and add your language code to the languages section.
+Again, for french, this could look like this:
+Example :
{
+ ...
+ "languages": [
+ // other languages
+ "fr"
+ ]
+}
3) Create a localization-file
+
In order to allow the actual translation process to take place, you need to create a
+standardized file that translators can work with. The standard that we use is xlf.
+
To generate a file, simply use the script extract-i18n located inside the package.json
+file. This will automatically generate the needed file if none exists
+
4) Add language icon
+
Go to the LanguageService and add the language to the list of availableLocales.
+This allows the app to show the langauge icon in the language select component.
+
5) Include language in bundle
+
To reduce the bundle size, only supported languages are shipped with the production build.
+To support a language by Angular (dates, units etc.) add the language to the webpack include in the main.ts
+file:
+Example :
const localeModule = await import(
+ /* webpackInclude: /(fr|de)\.mjs/ <-- add language between the brackets sepreated by a pipe symbol */
+ `../node_modules/@angular/common/locales/${locale}`
+);
6) Test your build
+
Run the app.
+You can change the language in the top right corner.
+If you have not added translations, the app will be in english.
+Try to translate some units.
+
In order to do this, go to the newly created src/locale/messages.<locale>.xlf file.
+Inside this file, you will find a lot of"trans-units". These mark single texts that
+you can translate. Translate one or more of these units by replacing the content of
+the target. For example:
You can change the state to "translated" as shown in the picture (but this is not required).
+Leave everything else as it is and test the app again. Translations should appear for each
+trans-unit that you have translated.
You have now successfully added the capability to translate the app into the target
+language. You can now take the translation file ("src/locale/messages.<your locale>.xlf") and
+send it to a translator to have it translated. Once this process is done, replace the
+preliminary translation file with the one that comes back from a translator.
"xlf-files" are the files generated by the extract-i18n script. They conform to the
+XLIFF Standard (Version 1.2)
+
How to create XLF files
+
You create XLF files automatically when you specify a new language. For details on how
+this works, have a look at the Add another Language guide.
+
How to update XLF files
+
Angular does not natively support updating old files. To do this,
+xliffmerge is used. This process takes into account old translations and
+merges them with new translations so that the number of items to translate
+stays at a minimum. Various configuration-options can be found at
+xliffmerge.json with the most interesting being
+
+
allowIdChange - whether the tool is allowed to merge translation-units
+with different ID's. This can be desired if two units have the same meaning and
+text, but differ in - for example - the amount of leading whitespaces.
+
+
autotranslate - experimental feature, can automatically translate the english
+file using Google Translate
+
+
beautifyOutput - makes the output more human-readable
+
+
+
Updating language files has several implications:
+
+
When a message is obsolete (you deleted the message from the code) it gets removed
+
Multiple messages (messages with the same description and meaning) are merged
+automatically
+
New messages will be added to the list automatically. These will have the state new
+
+
+
Hint: If you added new texts to translate and used xliffmerge, you can find those by
+searching for the string "new"
+
+
Available Tools
+
There are several tools that can be used to translated in a graphically appealing way.
+This is an incomplete list of some of these tools:
PO Editor: A capable editor that you need an
+acount for but is limited to 1000 strings with a free account
+
Lokalize:
+A tool that highlights <x .../> tags which prevents a user to accidentally delete them
+but lacks other features. Limited free version
+
OmegaT: A free tool for Windows, Mac and Linux with limited
+capabilities
+
+
Manual Translation
+
You can also do this manually in the XLF Document. The process is as follows:
+
+
Find the file for your locale, named messages.<locale>.xlf. They can be found
+in the locale folder. This file consists of several 'trans-unit's.
+Each of them consists of several sections. Here is an example of such a trans unit for german (de)Example :
Inside the trans-unit we see the two tags id and datatype. The id is a unique id
+that belongs to this trans unit. It can also be a custom, more descriptive id. In most
+cases, this is a generated id that you should pay no attention to when translating.
+
The datatype is always html, disregarding regardless of whether this actually came
+from an html file.
+
The source is the text that should be translated. This may not be altered.
+
The target is the translation. Any special elements, such as <x ... /> must not be
+changed. The content of them can be ignored. Additionally, a state can be associated
+with a translation. There are two common states: new and translated indicating that
+a new message has been added and has not been translated resp. that a message has already
+been translated. Additional states can be found at the website of the standard.
+
The context-group contains information where the text got extracted from. It can be
+ignored and must not be changed.
+
Further notes are attached to trans units in order to ease the translation process.
+You should also not change them, but they will be helpful.
The platform allows very flexible customization of the user interface and data structures to different use cases.
+This is usually possible without changes to the code base, using the configuration system.
+
+
This guide is currently only a "stub".
+
For the time being, please refer to the documentation about the Configuration.
We aim to build flexible, reusable components.
+If you implement a custom component using the building blocks of Aam Digital's platform, this can seamlessly be displayed both in modal forms and as a fullscreen view.
+
Architecture & Generic wrapper components
+
The following architecture allows you to implement components that only have @Input properties
+and do not access either Route or Dialog data directly.
+Instead, the platform always uses RoutedViewComponent or DialogViewComponent to parse such context and pass it into your component as simple Angular @Inputs.
+
+
If you implement a special view to display a single entities' details, you should also extend AbstractEntityDetailsComponent with your component.
+This takes care of loading the entity from the database, in case it is passed in as an id from the URL.
+
Implementing a custom view Component
+
+
Create a new component class
+
Add any @Input() properties for values that are provided from the config.
+
For EntityDetails views, you get access to an @Input() entity and @Input() entityConstructor via the AbstractEntityDetailsComponent automatically. Otherwise, you do not have to extend from this.
+
Use <app-view-title> and <app-view-actions> in your template to wrap the elements (if any) that you want to display as a header and action buttons.
+These parts are automatically placed differently in the layout depending on whether your component is display as a fullscreen, routed view (actions displayed top right) or as a dialog/modal (actions displayed fixed at bottom).
+
Register your component under a name (string) with the ComponentRegistry (usually we do this in one of the modules), so that it can be referenced under this string form the config.
+
You can then use it in config, as shown below.
+
+
Example template for a custom view component:
+Example :
<app-view-title>
+ <!-- the title is specially fixed and receives a back button or dialog close -->
+ My Entity {{ entity.name }}
+</app-view-title>
+
+<!-- anything in the template not specially marked/wrapped is used as main content -->
+<div>My Custom View Content</div>
+
+<app-view-actions>
+ <!-- some action buttons, e.g. using the app-dialog-buttons or anything else -->
+ <app-dialog-buttons [form]="form" [entity]="entity"></app-dialog-buttons>
+</app-view-actions>
Use the ComponentRegistry to register your component,
+e.g. in its Module:
+Example :
export class MyModule {
+ constructor(components: ComponentRegistry) {
+ components.addAll([
+ [
+ "MyView", // this is the name to use in the config document
+ () => import("./my-view/my-view.component").then((c) => c.MyViewComponent),
+ ],
+ ]);
+ }
+}
"Datatypes" define how a single field (i.e. entity property) is stored and displayed.
+They are core building blocks for all entities and can enable advanced functionality, like displaying a streetmap for an address.
+
The Aam Digital core defines most commonly known datatypes already (see CoreModule).
+The architecture of datatypes is designed for extension however, so you can easily add further types.
+
The base: DefaultDatatype and Angular Service
+
DefaultDatatype is the base class for all implementations of custom datatypes.
+It implements default logic for all the required aspects so that you can override only those parts that are relevant for your new type.
+
Implementations of datatypes are normal Angular Services.
+This allows you to inject and use any other service that you may need to do sophisticated data transformations.
+
Defining a new Datatype
+
+
Create a new Angular Service class (according to our file name convention it should follow the pattern my-custom.datatype.ts)
+
Use inheritance to extend the DefaultDatatype class
+
Define your datatype identifier (which is used in @DatabaseField annotations in their EntitySchemaField definitions) by setting the static dataType = "my-custom" property of your class
+
Override any of the other aspects if you want to customize them
+
+
This could result in a Datatype class like this:
+Example :
@Injectable()
+export class MyCustomDatatype extends DefaultDatatype<SpecialObject, string> {
+ static dataType = "my-custom";
+
+ constructor() {
+ super();
+ // use constructor to simply inject other services you need
+ }
+
+ editComponent = "EditMyCustomFormField";
+ viewComponent = "DisplayText";
+ // make sure to register your new components in the ComponentRegistry
+
+ transformToDatabaseFormat(value: SpecialObject): string {
+ // storing as string in the database for whatever reason
+ return value.toString();
+ }
+
+ transformToObjectFormat(value: string): SpecialObject {
+ return transformToSpecialObject(value);
+ }
+
+ importConfigComponent = "SpecialImportValueMapping";
+
+ importMapFunction(value: any, schemaField: EntitySchemaField, additional?: any) {
+ return SpecialValueParserForDifferentImportFormats(value);
+ }
+}
Please also refer to the extensive JsDoc code comments in the DefaultDatatype class.
+
Registering the new Datatype
+
Provide your datatype service using Angular dependency injection:
+{ provide: DefaultDatatype, useClass: MyCustomDatatype, multi: true },
+
The EntitySchemaService, that handles all data transformations, and other platform modules automatically pick up your datatype
+and use it for any entity properties that use the dataType identifier of your implementation.
"Entities" are the objects around which our whole system is built.
+Entity types specify a data structure for records in the case management system,
+defining both the data object as well as some details how the records are displayed in the UI to users.
+There may for example be User, Child or School classes representing the types of objects the users can view in lists and detail forms and interact with.
+
To adapt the platform to a certain use case, you usually want to adapt entity types or create new ones.
+This defines what fields users can see and edit in forms, among other things.
Unless you have special requirements and write further code specifically for your entity type,
+you usually should rely on the more flexible and easy approach defining them in the config.
+
This guide talks about the advance topic of implementing an entity type via code.
+
+
Creating a custom Entity type in code
+
To extend the system with types, you can create a new module and extend the existing base class of the Entity system.
+This is something you would only do if you are also implementing special components or services in the code base to handle this entity type.
+Otherwise, it is easier and more flexible to define an entity type through the config system only, as shown above.
+
The EntityModule specifies the base class and generic features, specific entity types can extend upon it.
+For an example, have a look at the User class that extends Entity.
+
The Entity class
+
Entity and any class extending it are only plain TypeScript classes defining the attributes (and possibly some "business logic" methods).
+
The classes should never contain code for saving/deleting or other database related code because we are keeping this separate in an EntityMapper class (see Data Mapper Pattern).
+
To keep them easy to understand and extend the Entity (sub-)classes also shouldn't depend on other components or services - Entity classes are not by themselves part of the Angular system and do not have dependency injection!
+
The EntitySchema
+
The EntitySchema object is defining which attributes of the class will be saved to the database.
+Attributes not explicitly defined in the Entity sub-type's schema are ignored when an instance is saved.
+
You must annotate your Entity class with the @DatabaseEntity('ENTITY_TYPE') decorator
+thereby defining a database prefix for your Entity type.
+
Any properties that you want to be persisted in the database when saving entities of this type
+must have the @DatabaseField() decorator.
+Any other properties are ignored and will be lost after saving and loading an entity of this type.
+As an example look at this class' schema definition:
Only dummy.name, dummy.size and dummy.month of a Dummy class instance are saved to the database.
+The dummy.temp property is available for internal processing but will be ignored when saving the entity to the database.
+
You can also set additional options for DatabaseFields and implement your own data transformations.
+For more details see the concept of the EntitySchema System.
+
Other components to be implemented for a new sub-type
+
The following components are related to display an Entity sub-type and currently implemented for each new sub-type as Angular components:
+
+
EntityDetailsComponent: displays all attributes of one of the Entity's objects to the user
+
EntityListComponent: displays a list of all the Entity's objects
+
EntityBlockComponent: displays a small, inline representation of one of the Entity's objects for use in other components
+
+
Example: Creating a new Entity sub-type
+Example :
import { Entity } from '../entity/entity';
+import { Gender} from './Gender';
+
+@DatabaseEntity('Child')
+export class Child extends Entity {
+ @DatabaseField() name: string;
+ @DatabaseField({dataType: 'string'}) gender: Gender;
+ @DatabaseField() dateOfBirth: Date;
+ @DatabaseField() marks: [];
+
+ age(): number {
+ // calculate from this.dateOfBirth
+ }
+
+ // Override this to define a human-readable, textual summary of the instance
+ toString(): string {
+ return this.name + ' (' + this.age() + ')';
+ }
+}
The reporting module allows organizations to automatically create reports of aggregated data for a given timespan.
+This can be used to track indicators and export anonymous data.
+
There are currently two systems available to generate reports, both using the same config documents (ReportConfig:*):
+
+
SQL-based queries executed server-side using the SQS server
+
(legacy) client-side generator using the aggregation & query syntax below
+
+
SQL Reports
+
For this feature, we have integrated the (optional) structured-query-service (SQS)
+(this creates a read-only copy of the data in the CouchDB and allows to run Sqlite queries against it).
+SQS enables the possibility to create SQL based queries in reports.
+
The SQS image is not available as open source and needs a licence. It is pulled from a private container registry.
+
Deployment
+
To activate it for an application, simply activate "aam-backend-service" profile (COMPOSE_PROFILES=aam-backend-service) in the applications .env file and run docker compose up -d.
+
Configuration
+
The reports can be defined as ReportConfig:* entities.
+
There are different modes for ReportConfig:
+
sql
+
Requirements: SQS
+
Simple SQL Report
+Example :
// app/ReportConfig:test-report
+{
+ "_id": "ReportConfig:test-report",
+ "title": "Test Report",
+ "mode": "sql",
+ "aggregationDefinition": "SELECT c.name as name, c.dateOfBirth as dateOfBirth FROM Child c",
+ "neededArgs": []
+}
SQL Report With Arguments
+
Additional arguments for the query (like a from and to date parameter) can be used in the SQL query directly using "?". The "neededArgs" array defines what arguments are filled for the "?" placeholders in the given order.
+Example :
// app/ReportConfig:test-report
+{
+ "_id": "ReportConfig:test-report",
+ "title": "Test Report",
+ "mode": "sql",
+ "aggregationDefinition": "SELECT c.name as name, c.dateOfBirth as dateOfBirth FROM Child c WHERE created_at BETWEEN ? AND ?",
+ "neededArgs": [
+ "from",
+ "to"
+ ]
+}
JSON-Query Reports (legacy)
+
Aggregation structure
+
Inside the aggregationDefinitions an array of aggregations can be added.
+The following example shows the structure of an aggregation.
groupBy defines an array of properties by which the results of the query are grouped,
+these results will be nested in the top-level query.
+
The aggregations array can be filled with further aggregations with the same structure.
+They will be executed on the result of the query as well as on each groupBy result.
+
+
query syntax
+
A full documentation can be found here.
+The most top-level aggregation has to start with the entity which should be queried.
+This can be done by selecting the entity type and chaining it with :toArray: e.g. Child:toArray.
+Now the array of all children is ready to be aggregated.
+You could for example be interested in all the children older than 10: Child:toArray[* age > 10].
+The * tells the query language to select all the children and not just one.
+The simple age call refers to the get age() function of the child entity.
+If you are interested in all female children older than 10 the call would look like Child:toArray[* age>10 & gender=F].
+If you are only interested in the names of these children Child:toArray[* age>10 & gender=M].name will transform the
+array of children into an array of strings.
+
To navigate between different entities a set of functions extends the query syntax.
+The full documentation for all the available functions can be found and extended in the
+QueryService.
+The first function you already know :toArray which creates an object into an array of values of this object.
+The following functions also exist:
+
+
:unique removes all duplicates from an array
+
:addPrefix(<ENTITY_TYPE>) adds the prefix <ENTITY_TYPE> to all strings in the input array.
+This is necessary to use the :toEntities function.
+The prefix will only be added if it is not set yet.
+
:toEntities transforms an array of entity-ids into an array of entities.
+The IDs need to have the full format e.g. Child:1234-5678.
+Therefore :addPrefix should always be used to add the correct entity before calling :toEntities.
+
:getRelated(<ENTITY_TYPE>, <PROPERTY_NAME>) is used to get the entity or entities which are mentioned through ids
+on a property of another entity e.g., to get all children that are part of a set of notes write Note:toArray:getRelated(Child, children)
+
:getIds(<PROPERTY_NAME>) works similar to :getRelated but does not transform the ids into entities.
+
:filterByObjectAttribute(<PROPERTY_NAME>, <KEY>, <VALUE>) is used to filter by an attribute which is a complex
+object like a configurable-enum. <PROPERTY_NAME> refers to the name of the property of the parent attribute,
+<KEY> refers to a key of this property and <VALUE> refers to the value(s) for which should be filtered.
+<VALUE> can be a string of multiple matches which are separated by |.
+E.g., to get all notes which are home visits or guardian talks write:
+Note:toArray:filterByObjectAttribute(category, id, HOME_VISIT|GUARDIAN_TALK)
+
:getParticipantsWithAttendance(<ATTENDANCE_STATUS>) only returns the children with the given attendance for a set
+of notes. The attendance refers to the :countAs attribute. To get all present children write
+Note:toArray:getParticipantsWithAttendance(PRESENT)
+
:addEntities(<ENTITY_TYPE>) can be used to create an array holding multiple entity types.
+E.g., to create an array holding notes and event notes write Note:toArray:addEntities(EventNote).
Aam Digital as a platform takes care of loading the relevant entity and configs for an "Entity Details View",
+which displays the information about a single entity (e.g. one specific student).
+The EntityDetailsComponent handles this initialization from the route.
+To display some details in a customized way, you can create "panel components" that receive a reference to the current entity and their config parameters as @Input() automatically.
+
+The tabs (in the config called "panels") within the Entity Details view can display one or more "panel components", as shown above.
+
To make these components as re-usable and simple as possible, we do not load config from the route here.
+Instead, the components are initialized from config by the DynamicComponentDirective.
+This automatically sets @Input() properties to the value with the same name in the config object.
+
Those background details aside, what that means for your implementation is:
+
Implementing a new Panel Component
+
+
Create a new component class
+
Add an @Input() entity: Entity;. This will always contain the entity object, whose Details View is currently being displayed. You should not load this yourself from the database.
+
(If needed) Add more inputs for aspects that should be configurable about your component.
+(e.g. @Input() showDescription: boolean;, which you can use in your template or code to adapt the component.)
+These values are automatically set to whatever value is specified in the config object for your component at runtime in the database.
+
Register the new component in its parent module, so that it can be loaded under its name through the config.
+(for details see Create a custom View Component)
We are following the "GitHub Flow", using feature branches for development.
+Please read through the following short guide before you get started:
+Understanding the GitHub Flow.
+
In summary, this means each feature will be implemented on it's own branch, which will then merged back onto the master branch. If you participate in the development, either by fixing a bug or implementing a new feature, follow these steps:
+
+
Analyze the bug or feature in a GitHub issue.
+Discuss possible approaches to solve it in the issue.
+
Create a new branch (from the current master!) for each issue/feature you are working on. Use a descriptive branch name.
+
Make commits on this branch. Use descriptive commit messages. If things are complex make multiple, logical commits.
+Do not use the same branch for implementing multiple features or bug fixes
+(instead create a separate branch from the master branch for each).
+
Run ng test to see if all unit tests are passed.
+If possible/necessary add more unit tests related to your new code. All tests must be passed before your contribution can be accepted.
+
Run ng lint to see if your code passes our project's code formatting standards.
+All problems must be resolved before your contribution can be accepted.
+
Once you have finished your work or want some feedback/discussion about it, open a new pull request (PR) on GitHub.
+Any reviews, feedback and discussions about your code will take place in this PR on GitHub. Please follow it and explain or adapt your code if necessary.
+
A different developer will merge your PR back onto the master branch. This makes sure there was a code review and manual testing.
+
After merging, delete your feature branch and make sure the corresponding issue(s) and pull request are closed.
+
+
Remarks
+
+
Reference an issue on GitHub in your commits or comments by writing the issue number (e.g. #15 to reference issue #15)
+
Add [WIP] to the beginning of the PR title if this is still "work in progress" and should not be merged yet.
+
If you have a lot of trivial commits in your working feature branch (such as fixed typos, fixed codestyle warnings, ...) you may squash some commits for better readability of the git history.
+This can be done with a git rebase on your feature branch (please never rebase the master branch).
+Further information can be found in the Git Book.
+
The Angular Style Guide provides helpful principles for Angular development.
Our Developer Documentation (which you are also currently reading here) is generated using compodoc.
+
While the How-To Guides and Concepts are explicitly written
+the API Reference (what you see in the sections Modules, Classes etc.) is generated from JsDoc code comments.
+
Therefore, whenever you write new code, please also document it with appropriate code comments.
With every push to the master, travis generates this documentation of the project automatically.
+All you have to do is to Comment your code with basic JSDoc! * For the correct comment format read https://compodoc.app/guides/comments.html
+
New code should always be documented as soon as you write or edit it.
+Your Pull Request should include documentation.
+
If you want to add or edit separate additional documentation like this page, work on branch compodoc and edit the markdown files under doc/compodoc_sources.
+If you add a new markdown file you also have to add it to summary.json.
+
+
Additional Information
+
+
npm run compodoc (see package.json) is used by Travis CI to generate the documentation.
+
You can also run npm run compodoc manually. You should better use the documentation provided online, however.
Every regular team member is encouraged to review other pull requests (PRs).
+You don't have to be a senior programmer or an expert in that particular part of the code
+to help by reviewing PRs (and possibly learn something along the way).
+
To establish best practices for our project and make reviews easier for you
+we are documenting guidelines for reviews here.
+
Goals: Why do we have reviews?
+
Why do we bother to spend time on code reviews / PR reviews?
+The main goals are:
+
+
Prevent bugs from getting into the master branch - and thereby onto users' devices.
+
Improve code quality - especially ensuring that the code is easy to understand.
+
+
Everybody has blind spots
+and sometimes we are also tempted to take short cuts (and forget to clean them up later).
+So it's essential to have a second set of eyes looking at code
+regardless of whether it was written by a long contributing, experienced developer
+or someone submitting their first PR.
+
Reviews are not about criticizing someone.
+They are about jointly discussing how things can be improved
+or even just what parts have room for improvement.
+
Definition of Done: When to accept a PR?
+
As far as possible we try to automate the must-have criteria to accept and merge a PR
+with the help of GitHub and Travis CI tools.
+But one of these required steps is also that the PR must have an "approving" review of another developer.
+
The following aspects are required for a PR to be merged.
+These are our expectations of quality that we have set ourselves:
+
The PR's changes must be:
+
+
working for the user as expected
+
tested by automated unit tests
+
easy to understand in code
+
+
The following sections specify more details of these high-level aspects
+and give you concrete steps for how you can review them.
+
(1.) Is the app working?
+
The most essential thing about any change: It should work for users running the app.
+
As a reviewer that means for you:
+
+
Check out the branch of the PR on your machine.
+
Run npm install to make sure you have all the right dependencies installed.
+
Run the app locally.
+Put yourself in the shoes of a user and click around, testing the app: 1. Does the new feature / bugfix function as discussed and expected? 2. How are edge cases and errors handled?
+_ This depends on the kind of change. If you can't think of any, just go on. 3. Does the user get feedback about what is going on in a way that is understandable for people with no technical knowledge?
+(That is in case of success as well as failure.) 4. Do related features that might have been affected by the changes of this PR still work?
+_ Again, this depends on the kind of PR. If you don't see anything else to test, that's absolutely okay. 5. If the change affects UI elements: How do they look in a smaller browser window?
+
Write a comment in the PR on GitHub about what any problems or ideas you encountered.
+
+
(2.) Is the code tested with unit tests?
+
The unit testing is checked automatically and concerns two aspects:
+
+
Are all tests passing?
+
That is new tests for this PR as well as all other tests to ensure no previously working function was broken.
+
+
+
Are the changes of this PR covered by unit tests?
+
We aim for a "test coverage" of at least 80% and PRs should contain new unit tests for the changes they are making.
+
+
+
+
The CI system reports the status of these conditions automatically and displays them in the GitHub PR.
+
You don't have to do any specific reviewing regarding this.
+If some tests fail, you may want to wait with your review until the author has fixed them so that you can review a final, working state of the code.
+Also, if you notice some important edge cases that are not tested by unit tests yet, do suggest these to be added.
+
(3.) Is the code understandable and well structured?
+
Reviewing a PR means reviewing code.
+If you spot a logical error or have a suggestion how to rewrite some code to improve performance that's awesome.
+But even more important is asking the right questions and pointing out all the parts that are hard (or impossible) to understand.
+
Rather sooner than later even the author of the code will have forgotten the hidden logic of that super complex function.
+And she/he will thank your for requesting a simpler code structure or a better documentation during your review.
+
You can review the PR's code changes easily on GitHub:
+
+
In the GitHub PR switch to the "Files changed" tab.
+
Go through the code changes and comment on specific lines:
+
If you don't understand what a block of code does.
+It should be possible to understand everything.
+Be ruthless and ask about everything that's unclear -
+code structure and/or documentation should be improved for everybody in this case.
+
If you have a suggestion to improve the code.
+Whether you have an idea to structure things in a clearer way
+or to solve it differently - share your suggestions.
+
You can also suggest code changes from within the GitHub UI that can be merged - without having the checkout and commit to the branch on you local machine. See Suggesting Changes on GitHub
+
+
+
"Finish your review" in GitHub.
+If there are issues or questions remaining, set the review status "Comment" or "Request Changes" instead of "Approve".
+
+
Finish up
+
That's it - thank you for improving the project with your feedback through your PR review!
+
If you commented with questions or suggestions, please try to follow up quickly when you receive replies.
+Otherwise, finishing and merging the PR gets delayed.
Our project runs all existing tests whenever you create or update a PR on GitHub
+and checks test coverage (i.e. how much of your code is actually run by the tests you have written).
+
+
Tips & Guidelines
+
Mock all dependencies
+
Unit tests for a class should usually cover that "unit" of code,
+i.e. your implementation of that class but not of all the referenced other services.
+
Try to "mock" all services that your implementation depends on, e.g. using jasmine.createSpyObj.
All tests are located under ndb-core/e2e/integration directory.
+Create a file with the ending .spec.ts or just .ts
+
With command
+
Cypress offers a command line tool that automatically creates a test file with a minimal setup for you.
+In order to create a test called loging run:
+
+
ng generate @cypress/schematic:e2e --name=login --path=e2e/integration
+
+
Organizing tests
+
If you have tests that fit together, create a separate folder inside for them.
+This grouping will help you navigate through them better, e.g. /../integration/child-tests/
+
2. Gherkin Template
+
What is Gherkin and how does it help writing E2E tests
+
Gherkin is a formal language that primarily serves as a communication language in agile teams for describing system behaviour based on the concrete examples and thus supports the following goals:
+
+
Creation of understandable and executable specification for all stakeholders in agile teams.
Scenario: Linking a child to a school
+Given I am on the details page of a child
+When I add an entry in the 'Previous Schools' section with a specific school
+Then I can see that child in the 'Children Overview' of the details page of this school
Gherkin uses a set of special keywords to give structure and meaning to executable specifications.
describe("Scenario of the Test", () => {
+ before("Given I am at login page", function () {
+ // In the before() function we can describe our start Point and specific variables
+ //e.g.
+ cy.visit("http://localhost:4200");
+ cy.wrap("Something").as("VariableName");
+ ...
+ });
+
+ // In the it() function the single tests of the test scenario can be written
+ it("When I add an entry in the Previous School section", function () {
+ // get the specific button and click on it
+ cy.get("buttonElement")
+ .should("contain", "ButtonName")
+ .click();
+ // choose object from Dropdown menu type our Variable and click on it
+ cy.get('DropdownMenu')
+ .type(this.VariableName)
+ .click();
+ ...
+ });
+
+ //Write more test cases here by adding aditional it functions tags
+});
+
Make an assertion about the resulting application state.
+
+
+
What role does Gherkin play?
+
We take the previous Scenario as example:
+Example :
Scenario: Linking a child to a school
+Given I am on the details page of a child
+When I add an entry in the 'Previous Schools' section with a specific school
+Then I can see that child in the 'Children Overview' of the details page of this school
We can translate this into the following template:
+Example :
describe("Scenario: Linking a child to a school", () => {
+ before("Given I am on the details page of a child", function() {
+
+ });
+
+ it("When I add an entry in the 'Previous Schools' section with a specific school", function () {
+
+ });
+
+ it("Then I can see that child in the 'Children Overview' of the details page of this school", function () {
+
+ });
+
+});
Now the before(...) and it(...) blocks should be filled with the code that corresponds to the according description.
+
4. Run the E2E-Tests
+
To open Cypress in the "Open-Mode" run the following command from the project root.
+
+
npm run e2e-open
+
+
This will start the browser with the Cypress Interface.
+This Interface is called Test Runner where you can select the tests to be executed and interactively follow and debug the test execution.
+
The Selector Playground is also available in the interface, which is a useful tool to write new tests by selecting items in the DOM.
+
The tests are also executed in each pull-request.
+The check with the name Pipeline / run-e2e-tests (pull_request) indicates whether the E2E tests were successful.
+
Aam Digital specific best practices
+
TBD.
+
Outlook: Better Gherkin integration
+
The specification of the scenarios with Gherkin is normally stored in so-called Feature Files.
+These files are human-readable text files.
+It makes sense to use cypress-cucumber-preprocessor in the future.
+This or a similar framework can speed up test creation because it allows Feature Files to be interpreted into Cypress code
How to display dialogs, notifications and log errors
+
To give users a consistent look & feel and make things easier to implement
+we have generic services to help with these tasks.
+You should always inject and use these rather than implement your own variant of such functionalities.
+
Display a confirmation dialog
+
Before executing an action with far-reaching consequences (e.g. deleting an entity)
+you should request explicit confirmation from the user through a confirmation dialog box.
+To reduce boiler-plate code for this, you can use the ConfirmationDialogService:
The service is a wrapper for MatDialog.
+Use it to open a dialog box with your text:
+Example :
const confirmed = await this.confirmationDialog.getConfirmation("Delete?", "Are you sure you want to delete this Child?");
You can then react to the user action (whether "Yes" or "No" was clicked):
+Example :
if (confirmed) {
+ // do something
+}
You can also display dialogs with only one "OK" button rather than the yes/no option
+by setting the optional 'buttons' parameter:
+Example :
this.confirmationDialog.getConfirmation("Info", "No options here, just some text.", OkButton);
In this case also consider whether you really want to use a "blocking" dialog box
+or if a simple "alert" notification may be the better choice.
+
Check the definitions of those button presets in confirmation-dialog.component.ts to see
+how you can also create fully custom choices of buttons.
+
Display a notification
+
You can display a short notification text to the user in an non-disrupting way using the AlertService.
+This will show a small hovering notification box towards the bottom of the screen
+(through MatSnackBar):
The different alert levels result in different styling of the notification.
+More serious alert levels (warning and above) also require the user to actively dismiss the notification
+while other notifications disappear automatically after some time.
+
+
If you want to log errors or other events for developers analysis and monitoring, also read the Log Errors Guide.
A common recurring requirement is to display a list of entities that are related to the current context.
+For example displaying a table of all notes relating to the selected child in its detail view.
+You shouldn't have to implement almost the same components again and again for this,
+so we have a generic EntitySubrecordComponent for these use cases.
+
Creating a basic "subrecord" component
+
To keep code organized and separated you should create a new component that uses EntitySubrecordComponent
+rather than trying to put everything into a larger component that includes other information as well
+(e.g. create a ChildNotesComponent instead of putting your configuration for the EntitySubrecordComponent into the ChildDetailsComponent).
+
Best use the Angular CLI to generate a new component in the relevant module:
+Example :
ng generate component child-notes
The template remains very simple as you build on top of the generic EntitySubrecordComponent
+and pass your values and configurations into it:
You need to set these parameters in your component class of course.
+[records] simply takes an array of entities to be displayed,
+e.g. in a oversimplified example (usually you would do some filtering or use a query):
The [newRecordFactory] is used to create a new entity of the required entity type when the user clicks the "add" button.
+This has to be a function that returns a new entity instance:
+Example :
generateNewRecordFactory() {
+ // define values locally because "this" is a different scope after passing a function as input to another component
+ const childId = this.childId;
+
+ return () => {
+ const newNote = new Note(Date.now().toString());
+ newNote.date = new Date();
+ newNote.children = [childId];
+
+ return newNote;
+ };
+}
This gives you the power to already pre-fill certain values in the new entity
+like in this example linking the new note with the selected child automatically.
+Unfortunately the implementation has to be a little clumsy: A method that itself returns a function again.
+
Finally, the [columns] configuration allows you a lot of flexibility over
+which properties of the entities are shown and how they are formatted and edited.
+This takes an array of FormFieldConfigurations:
Only the properties that you set here will be displayed to the user.
+Use the parameters to configure transformations and form field types.
+When a entity is displayed, most of the properties can be omitted and will be fetched from the schema definition
+
+
To learn about the full range of column options check out the API Reference:
The EntitySubrecordComponent allows the user to edit an entity inline in the table.
+By default, clicking on a row will automatically open a form popup which shows all editable fields of the table.
+What happens when a row is clicked can be overwritten with the [showEntity] parameter.
+This parameter expects a function that gets the clicked entity as input.
The list views like /child, /school, /note ,... have a button to export data.
+Clicking this button will create a downloadable .csv file.
+The format of this file can be adjusted through the configuration for the list view.
+
Config Format
+
The configuration of the export format is part of the configuration of the EntityListComponent.
The label property is optional and provides a title for this column.
+If nothing is provided the query (without dots) is used (e.g. for "query": ".name" the label will be name).
+
The query has to be a valid JSON-Query.
+The query will be run on each entity of the list page that is visited (e.g. on each child).
+For further information about the query-syntax read the Reports Guide which uses the same query language.
+
The subQueries is optional and expects an array of ExportColumnConfigs.
+The queries of the subQueries will be run for each result of the parent query.
+In the example above, this would mean that for each ChildSchoolRelation the name of the school, the from- and the to-date will be exported.
+If subQueries is defined, each object of the parent query will lead to one row in the report.
+In the example above this would mean if there are n children and each of them has m child-school-relations then the final report will have n*m rows and the columns Child, School Name, From, To (Child from the first query and the others from the sub-queries).
+In case subQueries is defined, the result of the parent query will not be visible in the export.
+If the results of the parent query is wanted in the report, a simple sub-query can be added that returns all values of the parent query (query: "[*]").
+
Example Output
+
Using the config from above with the following data:
If the app is run in the "useTemporaryDatabase" mode, realistic demo data is generated on each startup.
+
This Guide walks you through the steps to add data to this demo mode for your own Entity type.
+
The Basics
+
+
Create a service that extends DemoDataGenerator.
+
Make sure you call super() in your constructor to execute the parent class' constructor.
+
Implement the generateEntities(): Entity[] method so that it returns an array of demo entities.
+
Try to create objects that are similar to real data. That will make it more useful during for testing and demo.
+
The most simple implementation could be to return an array of a few hard-coded instances.
+
+
+
To actually make the DemoDataModule generate your demo entities you need to add your service to its config.
+In the AppModule (or wherever you import the DemoDataModule) add your service provider:
+_ e.g. DemoDataModule.forRoot([{ provide: DemoUserGeneratorService, useClass: DemoUserGeneratorService }])
+_ When the DemoDataModule is loaded your generator is then also triggered.
+
Change your config.json and set demo_mode: true to start the app with in demo mode
+and get your data generated on startup.
+
+
Creating realistic, random data
+
Your generator service is a standard Angular Service that can become as complex as you need it to be.
+
+
You can import our (customized) faker.js
+to easily generate realistic property values like names or dates.
+_ import import {faker} from '../demo-data/faker'; (Faker is not an Angular service just a simple JavaScript module)
+_ use child.name = faker.name.firstName() + ' ' + faker.name.lastName() for example to generate realistic random names
+
+
You can use Angular's dependency injection to inject any other services that you may rely on to generate meaningful demo data.
+This way you can also inject other DemoDataGenerators if you need to generate entities related to other types of entities.
+_ inject demoChildren: DemoChildGenerator in your constructor
+_ use this.demoChildren.entities to access all demo child entities that have been generated by the DemoChildGenerator * generate your demo entities relating to the demo child entities as needed
+
+
+
Making the generator configurable
+
If you want to make your generator more flexible, an important step is to receive some configuration.
+This can be passed into your service through dependency injection as well.
+
(1.) Create a simple class to hold your config.
+For example:
+Example :
export class DemoChildConfig {
+ count: number;
+}
Use a real class and not an interface for this.
+Interfaces only exist in TypeScript before transpilation to Javascript and are not available during runtime,
+therefore an interface cannot be used as a provider key for Angular dependency injection.
+
(2.) Add your config class to the constructor of your service to make it available within your generator:
(3.) Add a static method called provider() to your service class.
+The provider method will accept an instance of your config class and return a array of Angular providers.
+This makes it much easier to register your service together with its config.
+(Our pattern for this is inspired by the forRoot() pattern of Angular Modules.)
+Example :
/**
+ * This function returns a provider object to be used in an Angular Module configuration:
+ * `providers: [DemoUserProvider.provider({count: 150})]`
+ * @param config The configuration specifying the number of entities the service should generate.
+ */
+ static provider(config: DemoChildConfig) {
+ return [
+ { provide: DemoChildGenerator, useClass: DemoChildGenerator },
+ { provide: DemoChildConfig, useValue: config },
+ ];
+ }
(4.) Use the provider() method when registering your service with the DemoDataModule
+and set your config there at the same time:
Note that the spread operator (the ... in front of the call to .provider()) is required.
+As the provider() method returns an array of providers, the ... "flattens" that array
+and simply makes all providers directly items of the primary array that is passed into DemoDataModule.forRoot().
One of the core actions you may need when developing new features is to interact with the database
+to load data, create new entities or update existing ones.
+We have a few generic services and concepts that help you do this without much overhead.
+
Understanding Database and Entities
+
Depending on the database the app is set up with, the lowest level of persisting data is the Database
+that interacts with the browser's storage systems and may also be synced with a remote database.
+
In our code we have an abstraction layer above the database interactions implemented in the EntityModule.
+You interact with a database record as an instance of the Entity class (or one of its sub types).
+This way, you can use methods on these entities and benefit from the EntitySchema System for transformations as a kind of ORM.
+
In you code you simply treat database records as simple TypeScript objects
+(instances of an Entity subclass)
+and use the EntityMapperService to load and save them.
+
+
Normally you should not use the Database class anywhere directly.
+Use the EntityMapperService instead, which is one abstraction layer above the specific database code.
+
+
Loading an entity
+
Use Angular's dependency injection to get the EntityMapperService in your code:
You can load an individual entity by its id.
+Due to restrictions of TypeScript you have to explicitly pass the Entity (sub)class as the first parameter
+so that the EntityMapperService can use it to properly cast the record to the correct Entity type:
IDs have to be unique for the Entity type,
+i.e. if you have a Child entity with ID "2" that is not be a problem
+but if there already is another User entity with this ID in the database save will fail.
+
To update an existing entity you can simply change the object and save it again:
In this case the loaded user contains an internal _rev property that allows the system to match it with the existing database record
+and avoid a conflict, so the updated entity is saved to the database.
+
You can also force the system to overwrite an existing conflicting database record
+(although you probably should only use that if you know what you are doing)
+by setting the optional second parameter of save to true (forceUpdate):
Deleting an entity is similar to saving
+(and the same rules about conflicts apply, so you should delete only entity instances that you actually loaded previously):
+Example :
const user = await this.entityMapper.load<User>(User, '1');
+await this.entityMapper.remove<User>(user);
This Guide considers logging of errors and information that is necessary for developers in debugging and monitoring.
+Refer to the Display Dialogs or Notifications Guide
+regarding ways to inform the user about errors or other events.
+
Logging things
+
Production code (whatever is merged into the master branch) should not contain any calls to console.log().
+If you need to output information for possible debugging that is not handled otherwise, use the AlertService from our AlertsModule.
+This way, all logging is done in a consistent manner and can possibly be transferred to the development team or saved in some other way.
+
To log information for analysis and debugging (without explicit notification to the user)
+use the Logging object:
Similar to the AlertService the LoggingService has multiple log levels
+that control whether log messages are sent to the remote monitoring and how they are treated there.
+
Remote Logging
+
The service side logging is performed via the sentry.io logging service.
+The credentials for the EWB-Account can be found in the podio workspace.
The application code is split within the src/app/ directory into modules providing
+general features and abstract components (core) and
+concrete feature modules for projects' use cases (child-dev-project).
+
Overall the following guidelines apply:
+
+
Different functionalities are usually split into separate Angular Modules each in its own folder.
+
At least all core features are well documented with JsDoc comments
+and therefore also have a complete API Reference here (see Modules).
+
If you have a certain challenge, browse the "How-To Guides" here in the documentation
+reusable features and approaches are documented there.
The EntityMapperService gives you an easy way to access
+all entities of an Entity type or an individual entity by its ID (see Load and Save Data for these basics).
+However, for more advance features this will not be enough and you may need more powerful ways to load certain data.
+This is where (persistent) queries come into play.
+
+
The easiest workaround to get a specific set of entities is to load all entities of that type using the EntityMapperService
+and then just use standard JavaScript/TypeScript to select the required entities.
+With larger databases this is hitting its limitations however.
+
+
PouchDB Queries
+
Our application is to some extent coupled with PouchDB/CouchDB.
+As queries and database indexing is closely related to the underlying database this feature (at the moment)
+directly refers to the underlying PouchDB feature.
This is one of the rare cases where you will need to inject Database directly rather than only interacting with EntityMapperService.
+
Beware, unfortunately the map: function has to be a string containing the javascript function (to prevent the build optimization from messing this up).
+
Loading data through a query
+
After following above steps to saveDatabaseIndex that query is now available in the database.
+
You can now use this query to load data through its query id,
+which is combined from the design document _id (without the "_design/" prefix) and the views key:
+Example :
const result = await this.db.query('my_index/by_child', {key: childId, include_docs: true});
Also note the additional options parameter with a key (the "search value") and include_docs set to true.
+The query function is a direct wrapper for PouchDB's query function, please refer to their docs for details.
+
As the query result is not automatically parsed by our EntityMapperService you have to map them manually:
This document collects all prerequisites that are necessary to run the application without problems. This can be complex settings or just simple value initialisations.
+
+
At least one user is in the database. Create a admin user that can not be deleted, if this is possible
+
password change is only possible with internet connection. Otherwise different passwords on local and remote database are possible.
This Tutorial is still work in progress and will be further extended & improved.
+
+
In this tutorial we will walk you through the first steps of getting the Aam Digital project up and running -
+and writing your first little extension to it.
+
We will focus on things specific to our project.
+But there will be links to other tutorials and resources about the basics of the technologies we use.
+
If anything is unclear or missing, please open an issue on GitHub.
+Your questions and feedback are very welcome!
TODO: this needs a more detailed explanation of the most basic aspects of the code base
+
+
Getting started with coding
+
+
Don't get overwhelmed by the mass of config files in the root directory.
+Jump directly to the subfolder src/app/ where the actually relevant code is located.
+
The project is structured into several Modules, each in its own folder under src/app/core (general features) or src/app/child-ded-project (special user-facing features)
+
To extend upon the existing system, don't worry about the lower layer modules.
+Focus on understanding the top level modules adding user features like the SchoolModule and the ChildrenModule.
In addition, we use Docker and nginx to deploy and run the application.
+
If you are not familiar with (some of) our tools and technologies yet,
+here are some useful resources to get started.
+You will need to have basic knowledge of these before you can properly start contributing to our project.
+
Git (and GitHub)
+
Git helps us track all changes to our project, allows us to revert things and is the basis for our code review process.
You can also check out the official git book (chapter 1-3 are most relevant).
+
TypeScript
+
TypeScript is our primary programming language.
+If you are familiar with JavaScript, learning TypeScript shouldn't be too hard for you.
+All JavaScript code is also valid TypeScript.
+TypeScript just adds some things on top to make development easier and less error-prone.
+
(If you don't know JavaScript yet, you can find an endless amount of online courses to learn it - go and do some of these before continuing here!)
+
If you have some experience with another "statically typed" language like Java, the additional concepts of TypeScript should feel familiar.
+A quick comparison like this may be enough to get you a basic understanding: TypeScript vs. JavaScript
+
Angular
+
Angular is a powerful web development framework and the basis for our project.
+It provides good structure to build complex enterprise-level web applications
+with its concepts of components, services and modules.
+
It does take a while to work through Angular's core concepts.
+But every minute you invest into understanding these basics now will make your development easier and cleaner forever after.
You will need a solid understanding of the Angular basics of components, services, dependency injection.
+The more advanced topics beyond that are things you can also learn while already working on our project.
+We'll be happy to guide you!
+
Angular Material
+
We are using some standard UI components following the Material Design as building blocks.
We have built an abstraction layer of the database access.
+Underneath our app is using PouchDB but you do not need any knowledge about this for most work on our project.
In order to work on our project you should first set up a local development environment.
+That way you can run the app on your own computer and immediately see and test changes you make.
Before changing things or implementing new features, you should get a basic idea of how Aam Digital currently works for our users.
+Feel free to reach out to someone from our team, if you haven't already. We'll be happy to give you a demo and talk about the needs and backgrounds of our users.
+
To get a true feeling for the app, work through the following short usage scenarios yourself:
+
Basic participants & notes
+
+
Register a new participant in the system. (Hint: Go through the "Children" list)
+
Add a note about your new participant. (Hint: Either expand the "Notes & Reports" section or use the blue "primary action" button on the bottom right)
+
Find your new note in the project-wide list of notes. (Hint: Navigate to the "Notes" list using the main menu on the left)
+
+
Recording attendance
+
+
Add your new participant to a "Recurring Activity". (Hint: open the details of one activity from the "Recurring Activities" list and add the name in the "Participants" section)
+
Record today's attendance for that activity. (Hint: Use "Record Attendance" and find the activity you have just added your participant to)
+
See your participant's attendance record. (Hint: Open the details view for your participant by clicking on the relevant row in the "Children" list and then expand the "Attendance" section)
+
+
Play around
+
Try some of the other features and get a feeling for Aam Digital.
Aggregate information about all events for a RecurringActivity within a given time period.
+
This object is not saved in the database but instead generated dynamically from stored Events
+to avoid problems keeping all information in sync in the database.
The entity's type.
+In classes extending Entity this is usually overridden by the class annotation @DatabaseEntity('NewEntity').
+The type needs to be used as routing path in lower case. The routing path can be defined in the configuration file.
whether this entity type can contain "personally identifiable information" (PII)
+and therefore should follow strict data protection requirements
+and offer a function to anonymize records.
The number of events that have at least one participant with an undefined status.
+This may occur when the user does not complete the full roll call or skips participants.
+The count of unknown status can indicate if manual checking and corrections are required.
Generate filter options dynamically from the given value to be matched.
+
This is a utility function to make it easier to generate FilterSelectionOptions for standard cases
+if you simply want each option to filter items having the given attribute matching different values.
+If you have more sophisticated filtering needs, use the constructor to set FilterSelectionOptions that
+you created yourself.
+Example :
A separate FilterSelectionOption is created for each value with a filter
+ that is true of a data item's property exactly matches that value.
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Description
+
+
+
+
+
valuesToMatchAsOptions
+
+ (string | number)[]
+
+
+
+ No
+
+
+
+
+
An array of values to be matched.
+A separate FilterSelectionOption is created for each value with a filter
+that is true of a data item's property exactly matches that value.
export class Changelog {
+ /** short title of the version */
+ name: string;
+
+ /** version tag, e.g. "2.1.7" */
+ tag_name: string;
+
+ /** description of changes included in this version */
+ body: string;
+
+ /** release date */
+ published_at: string;
+
+ /** whether it is a pre-release */
+ prerelease?: boolean;
+
+ /** whether it is a draft */
+ draft?: boolean;
+}
+
import { DatabaseEntity } from "../../../core/entity/database-entity.decorator";
+import { DatabaseField } from "../../../core/entity/database-field.decorator";
+import { TimePeriod } from "../../../core/entity-details/related-time-period-entities/time-period";
+
+/**
+ * Record of a school year that a Child attended a certain class in a School.
+ *
+ * This class remains as a stub and in the future will be further refactored
+ * TODO: refactor into generic time-period based relationship entity --> #2512
+ */
+@DatabaseEntity("ChildSchoolRelation")
+export class ChildSchoolRelation extends TimePeriod {
+ static override hasPII = true;
+
+ @DatabaseField({
+ dataType: "entity",
+ additional: "Child",
+ entityReferenceRole: "composite",
+ validators: {
+ required: true,
+ },
+ anonymize: "retain",
+ })
+ childId: string;
+
+ @DatabaseField({
+ dataType: "entity",
+ additional: "School",
+ entityReferenceRole: "aggregate",
+ validators: {
+ required: true,
+ },
+ anonymize: "retain",
+ })
+ schoolId: string;
+
+ @DatabaseField({
+ dataType: "date-only",
+ label: $localize`:Label for the start date of a relation:Start date`,
+ description: $localize`:Description of the start date of a relation:The date a child joins a school`,
+ anonymize: "retain",
+ })
+ declare start: Date;
+
+ @DatabaseField({
+ dataType: "date-only",
+ label: $localize`:Label for the end date of a relation:End date`,
+ description: $localize`:Description of the end date of a relation:The date of a child leaving the school`,
+ anonymize: "retain",
+ })
+ declare end: Date;
+}
+
Calling this will allow the same keys to be added multiple times without thrown errors.
+This is useful for storybook where live-updates re-trigger the decorator while the registry is cached.
import { Type } from "@angular/core";
+import { Registry } from "./core/config/registry/dynamic-registry";
+
+export type AsyncComponent = () => Promise<Type<any>>;
+
+/**
+ * This registry hold all the loading functions for components that can be used dynamically with lazy loading.
+ */
+export class ComponentRegistry extends Registry<AsyncComponent> {}
+
+// TODO make a build script that looks for annotations and creates this
+export const componentRegistry = new ComponentRegistry();
+
+export type ComponentTuple = [string, AsyncComponent];
+
import { Entity } from "../entity/model/entity";
+import { DatabaseField } from "../entity/database-field.decorator";
+import { DatabaseEntity } from "../entity/database-entity.decorator";
+
+/**
+ * The class which represents the config for the application.
+ */
+@DatabaseEntity("Config")
+export class Config<T = any> extends Entity {
+ /**
+ * The ID for the UI and data-model config
+ */
+ static readonly CONFIG_KEY = "CONFIG_ENTITY";
+
+ /**
+ * The ID for the permission configuration
+ */
+ static readonly PERMISSION_KEY = "Permissions";
+
+ /**
+ * This field contains all the configuration and does not have a predefined type.
+ */
+ @DatabaseField() data: T;
+
+ constructor(id = Config.CONFIG_KEY, configuration?: T) {
+ super(id);
+ this.data = configuration;
+ }
+
+ override copy(): this {
+ const newConfig = super.copy();
+ newConfig.data = JSON.parse(JSON.stringify(this.data));
+ return newConfig;
+ }
+}
+
Generate filter options dynamically from the given value to be matched.
+
This is a utility function to make it easier to generate FilterSelectionOptions for standard cases
+if you simply want each option to filter items having the given attribute matching different values.
+If you have more sophisticated filtering needs, use the constructor to set FilterSelectionOptions that
+you created yourself.
+Example :
A separate FilterSelectionOption is created for each value with a filter
+ that is true of a data item's property exactly matches that value.
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Description
+
+
+
+
+
valuesToMatchAsOptions
+
+ (string | number)[]
+
+
+
+ No
+
+
+
+
+
An array of values to be matched.
+A separate FilterSelectionOption is created for each value with a filter
+that is true of a data item's property exactly matches that value.
import { fakerEN_IN as originalFaker } from "@faker-js/faker";
+import { GeoResult } from "../../features/location/geo.service";
+/**
+ * Extension of faker.js implementing additional data generation methods.
+ */
+class CustomFaker {
+ /**
+ * Merge the created CustomFaker's implementation with a given faker's standard methods.
+ * @param baseFaker A standard faker.js
+ */
+ constructor(
+ // @ts-ignore
+ private baseFaker: Faker.FakerStatic,
+ ) {
+ // make baseFaker methods available from instances of this class
+ Object.assign(this, baseFaker);
+ }
+
+ /**
+ * Generate a date that works as a date of birth in the given age range.
+ * @param minAge The minimum age (today) of a person with the generated random birthdate.
+ * @param maxAge The maximum age (today) of a person with the generated random birthdate.
+ */
+ public dateOfBirth(minAge: number, maxAge: number): Date {
+ const currentYear = new Date().getFullYear();
+ const latest = new Date();
+ latest.setFullYear(currentYear - minAge);
+ const earliest = new Date();
+ earliest.setFullYear(currentYear - maxAge);
+ return this.baseFaker.date.between({ from: earliest, to: latest });
+ }
+
+ /**
+ * Return the given date if it is defined and earlier than today's date
+ * otherwise return a Date representing today.
+ * @param date The date to be compared
+ */
+ getEarlierDateOrToday(date: Date): Date {
+ const today = new Date();
+
+ if (!date || date > today) {
+ return today;
+ } else {
+ return date;
+ }
+ }
+
+ geoAddress(): GeoResult {
+ const coordinates = faker.location.nearbyGPSCoordinate({
+ origin: [52.4790412, 13.4319106],
+ });
+ return {
+ lat: Number.parseFloat(coordinates[0].toString()),
+ lon: Number.parseFloat(coordinates[1].toString()),
+ display_name: faker.location.streetAddress(true),
+ } as GeoResult;
+ }
+}
+
+/**
+ * Typing for faker including extended functionality.
+ */
+export type Faker = typeof originalFaker & CustomFaker;
+
+originalFaker.seed(1);
+
+/**
+ * (Extended) faker module
+ */
+export const faker = new CustomFaker(originalFaker) as Faker;
+
Implement this if the dashboard depends on the user having access to a certain entity.
+If an array of strings is returned, the dashboard is shown if the user has access to at least one of them.
same of the normal config that will later be passed to the inputs
+
+
+
+
+
+
+
+ Returns : string | []
+
+
+
+
ENTITY_TYPE which a user needs to have
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
export abstract class DashboardWidget {
+ /**
+ * Implement this if the dashboard depends on the user having access to a certain entity.
+ * If an array of strings is returned, the dashboard is shown if the user has access to at least one of them.
+ *
+ * @param config same of the normal config that will later be passed to the inputs
+ * @return ENTITY_TYPE which a user needs to have
+ */
+ static getRequiredEntities(config: any): string | string[] {
+ return;
+ }
+}
+
Load all documents (matching the given PouchDB options) from the database.
+
Normally you should rather use "getAll()" or another well typed method of this class
+instead of passing PouchDB specific options here
+because that will make your code tightly coupled with PouchDB rather than any other database provider.
The PouchDB style design document for the map/reduce query
+
+
+
+
+
+
+
+ Returns : Promise<any>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Observable } from "rxjs";
+
+/**
+ * An implementation of this abstract class provides functions for direct database access.
+ * This interface is an extension of the [PouchDB API](https://pouchdb.com/api.html).
+ */
+export abstract class Database {
+ /**
+ * Load a single document by id from the database.
+ * @param id The primary key of the document to be loaded
+ * @param options Optional options for the database engine (PouchDB)
+ */
+ abstract get(id: string, options?: GetOptions): Promise<any>;
+
+ /**
+ * Load all documents (matching the given PouchDB options) from the database.
+ *
+ * Normally you should rather use "getAll()" or another well typed method of this class
+ * instead of passing PouchDB specific options here
+ * because that will make your code tightly coupled with PouchDB rather than any other database provider.
+ *
+ * @param options PouchDB options object as in the normal PouchDB library
+ */
+ abstract allDocs(options?: GetAllOptions): Promise<any>;
+
+ /**
+ * Save a document to the database.
+ * @param object The document to be saved
+ * @param forceUpdate (Optional) Whether conflicts should be ignored and an existing conflicting document forcefully overwritten.
+ */
+ abstract put(object: any, forceUpdate?: boolean): Promise<any>;
+
+ /**
+ * Save a bunch of documents at once to the database
+ * @param objects The documents to be saved
+ * @param forceUpdate (Optional) Whether conflicts should be ignored and existing conflicting documents forcefully overwritten.
+ * @returns array holding success responses or errors depending on the success of the operation
+ */
+ abstract putAll(objects: any[], forceUpdate?: boolean): Promise<any[]>;
+
+ /**
+ * Delete a document from the database
+ * @param object The document to be deleted (usually this object must at least contain the _id and _rev)
+ */
+ abstract remove(object: any): Promise<any>;
+
+ /**
+ * Query data from the database based on a more complex, indexed request.
+ *
+ * This is directly calling the PouchDB implementation of this function.
+ * Also see the documentation there: {@link https://pouchdb.com/api.html#query_database}
+ *
+ * @param fun The name of a previously saved database index
+ * @param options Additional options for the query, like a `key`. See the PouchDB docs for details.
+ */
+ abstract query(fun: any, options?: QueryOptions): Promise<any>;
+
+ /**
+ * Create a database index to `query()` certain data more efficiently in the future.
+ *
+ * Also see the PouchDB documentation regarding indices and queries: {@link https://pouchdb.com/api.html#query_database}
+ *
+ * @param designDoc The PouchDB style design document for the map/reduce query
+ */
+ abstract saveDatabaseIndex(designDoc: any): Promise<any>;
+
+ /**
+ * Load all documents (with the given prefix) from the database.
+ * @param prefix The string prefix of document ids that should be retrieved
+ */
+ getAll(prefix = ""): Promise<Array<any>> {
+ return this.allDocs({
+ include_docs: true,
+ startkey: prefix,
+ endkey: prefix + "\ufff0",
+ });
+ }
+
+ /**
+ * @returns true if there are no documents in the database
+ */
+ abstract isEmpty(): Promise<boolean>;
+
+ /**
+ * Closes all open connections to the database base and destroys it (clearing all data)
+ */
+ abstract destroy(): Promise<any>;
+
+ abstract changes(prefix: string): Observable<any>;
+}
+
+/**
+ * Basic query options supported by {@link Database}.
+ *
+ * also see https://pouchdb.com/guides/queries.html
+ */
+export type QueryOptions = PouchDB.Query.Options<any, any>;
+
+/**
+ * Basic database read options supported by {@link Database}.
+ *
+ * also see https://pouchdb.com/api.html#fetch_document
+ */
+export type GetAllOptions =
+ | PouchDB.Core.AllDocsWithKeyOptions
+ | PouchDB.Core.AllDocsWithKeysOptions
+ | PouchDB.Core.AllDocsWithinRangeOptions
+ | PouchDB.Core.AllDocsOptions;
+
+/**
+ * Basic database read options supported by {@link Database}.
+ *
+ * also see https://pouchdb.com/api.html#fetch_document
+ */
+export type GetOptions = PouchDB.Core.GetOptions;
+
import { calculateAge } from "../../../utils/utils";
+
+/**
+ * Subclass of Date which provides the getter `age`.
+ * This age is calculated based on the date that this object represents.
+ */
+export class DateWithAge extends Date {
+ static DATA_TYPE = "date-with-age";
+
+ get age() {
+ return calculateAge(this);
+ }
+}
+
Extend this class to define new data types (i.e. for properties of entities)
+and provide your implementation using Angular DI:
+{ provide: DefaultDatatype, useClass: MyCustomDatatype, multi: true },
+
This class is also used as the default fallback Datatype for the EntitySchemaService that keeps values unchanged between database and entity instance.
+This type is automatically used whenever no fitting Datatype can be found for that config or TypeScript type.
Key for this datatype that must be specified in the DatabaseField annotation to use this transformation.
+
for example @DatabaseField({dataType: 'foo'}) myField will trigger the datatype implementation with name "foo".
+
If you set the name to a TypeScript type, class properties with this type will automatically use
+that EntitySchemaDatatype without the need to explicitly state the dataType config in the annotation
+(e.g. @DatabaseField() myField: string is triggering the EntitySchemaDatatype with name "string".
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
The EntitySchemaField configuration providing details of how the value should be transformed.
+This can be set as a parameter to the @DatabaseField() annotation in Entity classes.
The EntitySchemaField configuration providing details of how the value should be transformed.
+This can be set as a parameter to the @DatabaseField() annotation in Entity classes.
import { EntitySchemaField } from "../schema/entity-schema-field";
+import { Entity } from "../model/entity";
+import { ColumnMapping } from "../../import/column-mapping";
+import { asArray } from "../../../utils/utils";
+
+/**
+ * Extend this class to define new data types (i.e. for properties of entities)
+ * and provide your implementation using Angular DI:
+ * `{ provide: DefaultDatatype, useClass: MyCustomDatatype, multi: true },`
+ *
+ * This class is also used as the default fallback Datatype for the EntitySchemaService that keeps values unchanged between database and entity instance.
+ * This type is automatically used whenever no fitting Datatype can be found for that config or TypeScript type.
+ */
+export class DefaultDatatype<EntityType = any, DBType = any> {
+ /**
+ * Key for this datatype that must be specified in the DatabaseField annotation to use this transformation.
+ *
+ * for example `@DatabaseField({dataType: 'foo'}) myField` will trigger the datatype implementation with `name` "foo".
+ *
+ * If you set the name to a TypeScript type, class properties with this type will automatically use
+ * that EntitySchemaDatatype without the need to explicitly state the dataType config in the annotation
+ * (e.g. `@DatabaseField() myField: string` is triggering the EntitySchemaDatatype with `name` "string".
+ */
+ static dataType: string = "";
+ get dataType(): string {
+ return (this.constructor as typeof DefaultDatatype).dataType;
+ }
+
+ /**
+ * The human-readable name for this dataType, used in config UIs.
+ */
+ static label: string = $localize`:datatype-label:any`;
+ get label(): string {
+ return (this.constructor as typeof DefaultDatatype).label;
+ }
+
+ /**
+ * The default component how this datatype should be displayed in lists and forms.
+ *
+ * The edit component has to be a registered component. Components that are registered contain the `DynamicComponent`
+ * decorator
+ */
+ viewComponent = "DisplayText";
+ editComponent = "EditText";
+
+ /**
+ * Transformation function taking a value in the format that is used in entity instances and returning the value
+ * in the format used in database objects.
+ *
+ * @param value The value (in Entity format) to be transformed
+ * @param schemaField The EntitySchemaField configuration providing details of how the value should be transformed.
+ * This can be set as a parameter to the `@DatabaseField()` annotation in Entity classes.
+ * @param parent The full entity instance this value is part of (e.g. to allow cross-related transformations)
+ */
+ transformToDatabaseFormat(
+ value: EntityType,
+ schemaField?: EntitySchemaField,
+ parent?: Entity,
+ ): DBType {
+ return value as any;
+ }
+
+ /**
+ * Transformation function taking a value in the format that is used in database objects and returning the value
+ * in the format used in entity instances.
+ *
+ * @param value The value (in database format) to be transformed
+ * @param schemaField The EntitySchemaField configuration providing details of how the value should be transformed.
+ * This can be set as a parameter to the `@DatabaseField()` annotation in Entity classes.
+ * @param parent The full entity instance this value is part of (e.g. to allow cross-related transformations)
+ */
+ transformToObjectFormat(
+ value: DBType,
+ schemaField?: EntitySchemaField,
+ parent?: any,
+ ): EntityType {
+ return value as any;
+ }
+
+ /**
+ * The function used to map values from the import data to values in the entities to be created.
+ * @param val The value from an imported cell to be mapped
+ * @param schemaField The schema field definition for the target property into which the value is mapped
+ * @param additional config as returned by the configComponent
+ */
+ async importMapFunction(
+ val: any,
+ schemaField: EntitySchemaField,
+ additional?: any,
+ ): Promise<EntityType | EntityType[]> {
+ if (schemaField.isArray) {
+ return asArray(val).map((v) =>
+ this.transformToObjectFormat(v, schemaField),
+ );
+ } else {
+ return this.transformToObjectFormat(val, schemaField);
+ }
+ }
+
+ /**
+ * A component to be display as a dialog to configure the transformation function
+ * (e.g. defining a format or mapping)
+ */
+ importConfigComponent?: string;
+
+ /**
+ * Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+ * or has a valid, complete "additional" config.
+ * returns "undefined" if no user action is required.
+ * @param col
+ */
+ importIncompleteAdditionalConfigBadge(col: ColumnMapping): string {
+ return undefined;
+ }
+
+ /**
+ * (Partially) anonymize to "retain-anonymized" for reporting purposes without personal identifiable information.
+ * @param value The original value to be anonymized
+ */
+ async anonymize(
+ value: EntityType,
+ schemaField: EntitySchemaField,
+ parent: any,
+ ): Promise<any> {
+ return undefined;
+ }
+}
+
import { AbstractControl } from "@angular/forms";
+import { EntitySchemaField } from "../entity/schema/entity-schema-field";
+import { EntityForm } from "../common-components/entity-form/entity-form.service";
+import { DefaultValueConfig } from "../entity/schema/default-value-config";
+import { Entity } from "../entity/model/entity";
+
+/**
+ * A special strategy to define and set default values, which can be used by the DefaultValueService,
+ * e.g. dynamic placeholders or inherited values.
+ */
+export abstract class DefaultValueStrategy {
+ /**
+ * Calculate and set the default value for a form control, according to the custom strategy.
+ * @param targetFormControl The form control to set the default value for.
+ * @param fieldConfig The field configuration of this entity field.
+ * @param form The overall entity form, including all related fields to support complex, interrelated value calculations.
+ */
+ abstract setDefaultValue(
+ targetFormControl: AbstractControl<any, any>,
+ fieldConfig: EntitySchemaField,
+ form: EntityForm<any>,
+ ): void;
+
+ async onFormValueChanges<T extends Entity>(
+ form: EntityForm<T>,
+ ): Promise<void> {}
+
+ async initEntityForm<T extends Entity>(form: EntityForm<T>): Promise<void> {}
+}
+
+/**
+ * Get the default value configs filtered for the given mode.
+ * @param defaultValueConfigs
+ * @param mode
+ */
+export function getConfigsByMode(
+ defaultValueConfigs: Map<string, DefaultValueConfig>,
+ mode: ("inherited" | "static" | "dynamic")[],
+): Map<string, DefaultValueConfig> {
+ let configs: Map<string, DefaultValueConfig> = new Map();
+
+ for (const [key, defaultValueConfig] of defaultValueConfigs) {
+ if (mode.indexOf(defaultValueConfig.mode) !== -1) {
+ configs.set(key, defaultValueConfig);
+ }
+ }
+
+ return configs;
+}
+
Providers for DemoDataGenerator service implementations to be registered for data generation.
+
This may also include providers for services a DemoDataGenerator depends on.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import {
+ ClassProvider,
+ FactoryProvider,
+ Injectable,
+ Injector,
+ ValueProvider,
+} from "@angular/core";
+import { DemoDataGenerator } from "./demo-data-generator";
+import { EntityMapperService } from "../entity/entity-mapper/entity-mapper.service";
+import { Database } from "../database/database";
+
+/**
+ * General config object to pass all initially register DemoDataGenerators
+ * with `DemoDataModule.forRoot()`.
+ *
+ * see docs at {@link DemoDataModule}
+ */
+export class DemoDataServiceConfig {
+ /**
+ * Providers for DemoDataGenerator service implementations to be registered for data generation.
+ *
+ * This may also include providers for services a DemoDataGenerator depends on.
+ */
+ dataGeneratorProviders: (ValueProvider | ClassProvider | FactoryProvider)[] =
+ [];
+}
+
+/**
+ * The DemoDataService is the manager for all provided DemoDataGenerator implementations.
+ * It serves as the central service to trigger the demo data generation into the database.
+ *
+ * To add more demo data generators, refer the documentation
+ * [How to Generate Demo Data]{@link /additional-documentation/how-to-guides/generate-demo-data.html}
+ */
+@Injectable()
+export class DemoDataService {
+ /** All registered demo data generator services */
+ readonly dataGenerators: DemoDataGenerator<any>[] = [];
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private injector: Injector,
+ private config: DemoDataServiceConfig,
+ private database: Database,
+ ) {}
+
+ private registerAllProvidedDemoDataGenerators() {
+ for (const provider of this.config.dataGeneratorProviders) {
+ const service = this.injector.get<any>(provider.provide);
+ if (service && service instanceof DemoDataGenerator) {
+ this.dataGenerators.push(service);
+ }
+ }
+ }
+
+ /**
+ * Trigger all registered DemoDataGenerator implementations to generate demo entities
+ * and add all the generated entities to the Database.
+ */
+ async publishDemoData() {
+ if (!(await this.database.isEmpty())) {
+ return;
+ }
+ this.registerAllProvidedDemoDataGenerators();
+
+ // completely generate all data (i.e. call every generator) before starting to save the data
+ // to allow generators to delete unwanted entities of other generators before they are saved
+ // (e.g. the DropoutChildGenerator should be able to delete Attendance records of the Child after its dropout date)
+ this.dataGenerators.forEach((generator) => generator.entities);
+
+ // save the generated data
+ for (const generator of this.dataGenerators) {
+ await this.entityMapper.saveAll(generator.entities);
+ // Wait for other async tasks in the queue e.g. ConfigService setting up config after it has been saved
+ await new Promise((resolve) => setTimeout(resolve));
+ }
+ }
+}
+
Key for this datatype that must be specified in the DatabaseField annotation to use this transformation.
+
for example @DatabaseField({dataType: 'foo'}) myField will trigger the datatype implementation with name "foo".
+
If you set the name to a TypeScript type, class properties with this type will automatically use
+that EntitySchemaDatatype without the need to explicitly state the dataType config in the annotation
+(e.g. @DatabaseField() myField: string is triggering the EntitySchemaDatatype with name "string".
"Entity" is a base class for all domain model classes.
+It implements the basic general properties and methods that are required for all Entity types
+e.g. supporting the Entity Schema system or basic database logic.
+
Entity classes do not deal with database actions, use EntityMapperService with its find/save/delete functions.
+
Do not use the Entity class directly. Instead, implement your own Entity types, writing classes that extend "Entity".
+A How-To Guide on how to implement your own types is available:
The entity's type.
+In classes extending Entity this is usually overridden by the class annotation @DatabaseEntity('NewEntity').
+The type needs to be used as routing path in lower case. The routing path can be defined in the configuration file.
whether this entity type can contain "personally identifiable information" (PII)
+and therefore should follow strict data protection requirements
+and offer a function to anonymize records.
Override getWarningLevel() to define when the entity is in a critical condition and should be color-coded
+and highlighted in generic components of the UI.
Check, if this entity is considered active or archived.
+
This is taken from the property "inactive".
+If the property doesn't exist, the default is true.
+
Some subclasses overwrite this functionality, but this logic is considered deprecated (!) now
+and implementations have to make sure that "inactive" property takes precedence!
import { v4 as uuid } from "uuid";
+import { EntitySchema } from "../schema/entity-schema";
+import { DatabaseField } from "../database-field.decorator";
+import {
+ getWarningLevelColor,
+ WarningLevel,
+} from "../../../child-dev-project/warning-level";
+import { IconName } from "@fortawesome/fontawesome-svg-core";
+import { UpdateMetadata } from "./update-metadata";
+
+/**
+ * This represents a static class of type <T>.
+ * It can be used for passing a class from which new objects should be created.
+ * It can also be used to check the ENTITY_TYPE of a class
+ * For example usage check the {@link EntityMapperService}.
+ */
+export type EntityConstructor<T extends Entity = Entity> = (new (
+ id?: string,
+) => T) &
+ typeof Entity;
+
+/**
+ * "Entity" is a base class for all domain model classes.
+ * It implements the basic general properties and methods that are required for all Entity types
+ * e.g. supporting the Entity Schema system or basic database logic.
+ *
+ * Entity classes do not deal with database actions, use {@link EntityMapperService} with its find/save/delete functions.
+ *
+ * Do not use the Entity class directly. Instead, implement your own Entity types, writing classes that extend "Entity".
+ * A How-To Guide on how to implement your own types is available:
+ * - [How to Create a new Entity Type]{@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
+ */
+export class Entity {
+ /**
+ * The entity's type.
+ * In classes extending Entity this is usually overridden by the class annotation `@DatabaseEntity('NewEntity')`.
+ * The type needs to be used as routing path in lower case. The routing path can be defined in the configuration file.
+ */
+ static ENTITY_TYPE = "Entity";
+
+ /**
+ * EntitySchema defining property transformations from/to the database.
+ * This is auto-generated from the property annotations `@DatabaseField()`.
+ *
+ * see {@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
+ */
+ static schema: EntitySchema;
+
+ /**
+ * True if this type's schema has been customized dynamically from the config.
+ */
+ static _isCustomizedType?: boolean; // todo should be private or renamed to "isCustomizedType"
+
+ /**
+ * Defining which attribute values of an entity should be shown in the `.toString()` method.
+ *
+ * The default is the ID of the entity (`entityId`).
+ * This can be overwritten in subclasses or through the config.
+ */
+ static toStringAttributes = ["entityId"];
+
+ /**
+ * human-readable name/label of the entity in the UI
+ */
+ static get label(): string {
+ return this._label ?? this.ENTITY_TYPE;
+ }
+
+ static set label(value: string) {
+ this._label = value;
+ }
+
+ private static _label: string;
+
+ /**
+ * human-readable label for uses of plural of the entity in the UI
+ */
+ static get labelPlural(): string {
+ return this._labelPlural ?? this.label;
+ }
+
+ static set labelPlural(value: string) {
+ this._labelPlural = value;
+ }
+
+ private static _labelPlural: string;
+
+ /**
+ * icon id used for this entity
+ */
+ static icon: IconName;
+
+ /**
+ * color used for to highlight this entity type across the app
+ */
+ static color: string;
+
+ /**
+ * Base route of the entity (list/details) view for this entity type.
+ */
+ static get route(): string {
+ let route = this._route ?? this.ENTITY_TYPE.toLowerCase();
+ if (!route.startsWith("/")) {
+ route = "/" + route;
+ }
+ return route;
+ }
+
+ static set route(value: string) {
+ this._route = value;
+ }
+
+ private static _route: string;
+
+ /**
+ * Extract the ENTITY_TYPE from an id.
+ * @param id An entity's id including prefix.
+ */
+ static extractTypeFromId(id: string): string {
+ const split = id.indexOf(":");
+ return id.substring(0, split);
+ }
+
+ /**
+ * Extract entityId without prefix.
+ * @param id An entity's id including prefix.
+ */
+ static extractEntityIdFromId(id: string): string {
+ const split = id.indexOf(":");
+ return id.substring(split + 1);
+ }
+
+ /**
+ * Create a prefixed id by adding the type prefix if it isn't already part of the given id.
+ * @param type The type prefix to be added.
+ * @param id The id to be extended with a prefix.
+ */
+ static createPrefixedId(type: string, id: string): string {
+ id = String(id);
+ const prefix = type + ":";
+ if (!id.startsWith(prefix)) {
+ return prefix + id;
+ } else {
+ return id;
+ }
+ }
+
+ static blockComponent?: string;
+
+ /**
+ * whether this entity type can contain "personally identifiable information" (PII)
+ * and therefore should follow strict data protection requirements
+ * and offer a function to anonymize records.
+ */
+ static hasPII: boolean = false;
+
+ /**
+ * Internal database id.
+ * This is usually combined from the ENTITY_TYPE as a prefix with the entityId field `EntityType:entityId`
+ * @example "Entity:123"
+ */
+ @DatabaseField({ anonymize: "retain" }) private _id: string;
+
+ /** internal database doc revision, used to detect conflicts by PouchDB/CouchDB */
+ @DatabaseField({ anonymize: "retain" }) _rev: string;
+
+ @DatabaseField({
+ anonymize: "retain",
+ })
+ created: UpdateMetadata;
+
+ @DatabaseField({
+ anonymize: "retain",
+ })
+ updated: UpdateMetadata;
+
+ @DatabaseField({ anonymize: "retain" })
+ inactive: boolean;
+
+ /**
+ * Whether this entity has been anonymized and therefore cannot be re-activated.
+ */
+ @DatabaseField({ anonymize: "retain" })
+ anonymized: boolean;
+
+ /** whether this entity object is newly created and not yet saved to database */
+ get isNew(): boolean {
+ return !this._rev;
+ }
+
+ /** actual id without prefix */
+ private get entityId(): string {
+ return Entity.extractEntityIdFromId(this._id);
+ }
+
+ /**
+ * Set id without prefix.
+ * @param newEntityId The new id without prefix.
+ */
+ private set entityId(newEntityId: string) {
+ this._id = Entity.createPrefixedId(this.getType(), newEntityId);
+ }
+
+ /**
+ * Check, if this entity is considered active or archived.
+ *
+ * This is taken from the property "inactive".
+ * If the property doesn't exist, the default is `true`.
+ *
+ * Some subclasses overwrite this functionality, but this logic is considered deprecated (!) now
+ * and implementations have to make sure that "inactive" property takes precedence!
+ */
+ get isActive(): boolean {
+ if (this.inactive !== undefined) {
+ return !this.inactive;
+ }
+ if (this["active"] !== undefined) {
+ return this["active"];
+ }
+ return true;
+ }
+
+ /**
+ * If existing entities with `isActive: false` exist, then these values are assigned to the property "active".
+ * @param isActive
+ */
+ set isActive(isActive: boolean) {
+ this["active"] = isActive;
+ this.inactive = !isActive;
+ }
+
+ /**
+ * Creates an entity object with the given id. This id is final and won't be changeable after this object has been
+ * created.
+ *
+ * @param id a unique id for this entity; if no id is passed a uuid is generated automatically
+ */
+ constructor(id: string = uuid()) {
+ this.entityId = id;
+ }
+
+ /**
+ * Get the class (Entity or the actual subclass of the instance) to call static methods on the correct class considering inheritance
+ */
+ getConstructor(): EntityConstructor<this> {
+ return this.constructor as EntityConstructor<this>;
+ }
+
+ /**
+ * Get the entity schema of this class
+ */
+ getSchema(): EntitySchema {
+ return this.getConstructor().schema;
+ }
+
+ /**
+ * Returns the id of this entity.
+ *
+ * Note that an id is final and can't be changed after the object has been instantiated, hence there is no
+ * <code>setId()</code> method.
+ *
+ * @returns {string} the unique id of this entity
+ */
+ public getId(withoutPrefix = false): string {
+ return withoutPrefix ? this.entityId : this._id;
+ }
+
+ /**
+ * Returns the type which is used to categorize this entity in the database.
+ *
+ * <b>Important: Do not overwrite this method! Types are handled internally.</b>
+ *
+ * @returns {string} the entity's type (which is the class name).
+ */
+ public getType(): string {
+ return this.getConstructor().ENTITY_TYPE;
+ }
+
+ /**
+ * Returns a string representation or summary of the instance.
+ * This can be configured with the static `toStringAttributes` for each subclass.
+ *
+ * @returns {string} the instance's string representation.
+ */
+ public toString(): string {
+ if (
+ this.anonymized &&
+ this.getConstructor().toStringAttributes.every(
+ (attr) => this[attr] === undefined,
+ )
+ ) {
+ return $localize`:Entity.toString fallback for anonymized record:[anonymized ${
+ this.getConstructor().label
+ }]`;
+ }
+
+ return this.getConstructor()
+ .toStringAttributes.map((attr) => this[attr])
+ .join(" ");
+ }
+
+ /**
+ * Used by some generic UI components to set the color for the entity instance.
+ * Override this method as needed.
+ */
+ public getColor(): string {
+ return getWarningLevelColor(this.getWarningLevel());
+ }
+
+ /**
+ * Override getWarningLevel() to define when the entity is in a critical condition and should be color-coded
+ * and highlighted in generic components of the UI.
+ */
+ public getWarningLevel(): WarningLevel {
+ return WarningLevel.NONE;
+ }
+
+ /**
+ * Shallow copy of the entity.
+ * The resulting entity will be of the same type as this
+ * (taking into account subclassing)
+ */
+ public copy(generateNewId: boolean = false): this {
+ const other = new (this.getConstructor())(this._id);
+ Object.assign(other, this);
+
+ if (generateNewId) {
+ delete other._rev;
+ other.entityId = uuid();
+ }
+
+ return other;
+ }
+
+ /**
+ * Checks if the entity is valid and if the check fails, throws an error explaining the failed check.
+ */
+ assertValid(): void {
+ return;
+ }
+}
+
Generate filter options dynamically from the given value to be matched.
+
This is a utility function to make it easier to generate FilterSelectionOptions for standard cases
+if you simply want each option to filter items having the given attribute matching different values.
+If you have more sophisticated filtering needs, use the constructor to set FilterSelectionOptions that
+you created yourself.
+Example :
A separate FilterSelectionOption is created for each value with a filter
+ that is true of a data item's property exactly matches that value.
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Description
+
+
+
+
+
valuesToMatchAsOptions
+
+ (string | number)[]
+
+
+
+ No
+
+
+
+
+
An array of values to be matched.
+A separate FilterSelectionOption is created for each value with a filter
+that is true of a data item's property exactly matches that value.
Calling this will allow the same keys to be added multiple times without thrown errors.
+This is useful for storybook where live-updates re-trigger the decorator while the registry is cached.
import { Entity, EntityConstructor } from "./model/entity";
+import { Registry } from "../config/registry/dynamic-registry";
+import { getEntitySchema } from "./database-field.decorator";
+
+export class EntityRegistry extends Registry<EntityConstructor> {
+ /**
+ * Get an array of entity types, optionally filtered to exclude internal, administrative types.
+ * @param onlyUserFacing Whether to only include types that are explicitly defined and customized in the config, from which we infer they are user-facing.
+ */
+ getEntityTypes(
+ onlyUserFacing = false,
+ ): { key: string; value: EntityConstructor }[] {
+ let entities = Array.from(this.entries()).map(([key, value]) => ({
+ key,
+ value,
+ }));
+ if (onlyUserFacing) {
+ entities = entities.filter(({ key, value }) => value._isCustomizedType);
+ }
+ return entities;
+ }
+}
+
+export const entityRegistry = new EntityRegistry((key, constructor) => {
+ if (!(new constructor() instanceof Entity)) {
+ throw Error(
+ `Tried to register an entity-type that is not a subclass of Entity\n` +
+ `type: ${key}; constructor: ${constructor}`,
+ );
+ }
+});
+
+/**
+ * Decorator (Annotation `@DatabaseEntity()`) to set the string ENTITY_TYPE to an Entity Type.
+ * The entity should also be added to the {@link databaseEntities} array of the surrounding module.
+ *
+ * also see {@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
+ *
+ * @param entityType The string key for this Entity Type, used as id prefix.
+ */
+export function DatabaseEntity(entityType: string) {
+ return (constructor) => {
+ entityRegistry.add(entityType, constructor);
+ constructor.ENTITY_TYPE = entityType;
+
+ // append parent schema definitions
+ const parentConstructor = Object.getPrototypeOf(constructor);
+ const schema = getEntitySchema(constructor);
+ parentConstructor.schema.forEach((value, key) => schema.set(key, value));
+ };
+}
+
Simple relationship object to represent an individual child's status at an event including context information.
+TODO overwork this concept to either be a sublass of Entity or not (at the moment it uses a lot of casting, e.g. to be used in the entity subrecord)
import {
+ ATTENDANCE_STATUS_CONFIG_ID,
+ AttendanceStatusType,
+ NullAttendanceStatusType,
+} from "./attendance-status";
+import { DatabaseField } from "../../../core/entity/database-field.decorator";
+
+/**
+ * Simple relationship object to represent an individual child's status at an event including context information.
+ * TODO overwork this concept to either be a sublass of Entity or not (at the moment it uses a lot of casting, e.g. to be used in the entity subrecord)
+ */
+export class EventAttendance {
+ static DATA_TYPE = "event-attendance";
+
+ private _status: AttendanceStatusType;
+ @DatabaseField({
+ dataType: "configurable-enum",
+ additional: ATTENDANCE_STATUS_CONFIG_ID,
+ })
+ get status(): AttendanceStatusType {
+ return this._status;
+ }
+
+ set status(value) {
+ if (typeof value === "object") {
+ if (value.isInvalidOption) {
+ value.shortName = "?";
+ value.countAs = NullAttendanceStatusType.countAs;
+ }
+ this._status = value;
+ } else {
+ this._status = NullAttendanceStatusType;
+ }
+ }
+
+ @DatabaseField() remarks: string;
+
+ constructor(
+ status: AttendanceStatusType = NullAttendanceStatusType,
+ remarks: string = "",
+ ) {
+ this.status = status;
+ this.remarks = remarks;
+ }
+
+ public copy(): EventAttendance {
+ return Object.assign(new EventAttendance(), this);
+ }
+}
+
+/**
+ * A full registry of event-attendance entries for multiple participants.
+ *
+ * TODO: this class can become the basis for a more generic attendance data that is not hard-wired to Note entities.
+ */
+export class EventAttendanceMap extends Map<string, EventAttendance> {
+ static DATA_TYPE = "event-attendance-map";
+
+ constructor() {
+ super();
+ }
+}
+
import {
+ ATTENDANCE_STATUS_CONFIG_ID,
+ AttendanceStatusType,
+ NullAttendanceStatusType,
+} from "./attendance-status";
+import { DatabaseField } from "../../../core/entity/database-field.decorator";
+
+/**
+ * Simple relationship object to represent an individual child's status at an event including context information.
+ * TODO overwork this concept to either be a sublass of Entity or not (at the moment it uses a lot of casting, e.g. to be used in the entity subrecord)
+ */
+export class EventAttendance {
+ static DATA_TYPE = "event-attendance";
+
+ private _status: AttendanceStatusType;
+ @DatabaseField({
+ dataType: "configurable-enum",
+ additional: ATTENDANCE_STATUS_CONFIG_ID,
+ })
+ get status(): AttendanceStatusType {
+ return this._status;
+ }
+
+ set status(value) {
+ if (typeof value === "object") {
+ if (value.isInvalidOption) {
+ value.shortName = "?";
+ value.countAs = NullAttendanceStatusType.countAs;
+ }
+ this._status = value;
+ } else {
+ this._status = NullAttendanceStatusType;
+ }
+ }
+
+ @DatabaseField() remarks: string;
+
+ constructor(
+ status: AttendanceStatusType = NullAttendanceStatusType,
+ remarks: string = "",
+ ) {
+ this.status = status;
+ this.remarks = remarks;
+ }
+
+ public copy(): EventAttendance {
+ return Object.assign(new EventAttendance(), this);
+ }
+}
+
+/**
+ * A full registry of event-attendance entries for multiple participants.
+ *
+ * TODO: this class can become the basis for a more generic attendance data that is not hard-wired to Note entities.
+ */
+export class EventAttendanceMap extends Map<string, EventAttendance> {
+ static DATA_TYPE = "event-attendance-map";
+
+ constructor() {
+ super();
+ }
+}
+
import { Entity } from "../../entity/model/entity";
+import { MongoQuery } from "@casl/ability";
+import { ListFilterComponent } from "../list-filter/list-filter.component";
+import { EventEmitter, Type } from "@angular/core";
+
+/**
+ * This filter can be used to filter an array of entities.
+ * It has to follow the MongoDB Query Syntax {@link https://www.mongodb.com/docs/manual/reference/operator/query/}.
+ *
+ * The filter is parsed using ucast {@link https://github.com/stalniy/ucast/tree/master/packages/mongo2js}
+ */
+export type DataFilter<T> = MongoQuery<T> | {};
+
+export abstract class Filter<T extends Entity> {
+ /**
+ * The component used to display filter option to the user.
+ */
+ component: Type<any> = ListFilterComponent;
+
+ public selectedOptionValues: string[] = [];
+
+ /**
+ * Triggered when this filter changes value
+ * (e.g. when the user selects a new value in a FilterComponent).
+ *
+ * This is part of the filter object because dynamic filter components can't expose @Outputs
+ */
+ selectedOptionChange = new EventEmitter<string[]>();
+
+ protected constructor(
+ public name: string,
+ public label: string = name,
+ ) {}
+
+ abstract getFilter(): DataFilter<T>;
+}
+
+/**
+ * Generic configuration for a filter with different selectable {@link FilterSelectionOption} options.
+ *
+ * This is a reusable format for any kind of dropdown or selection component that offers the user a choice
+ * to narrow down a list of data items.
+ * As the filter function is provided as part of each {@link FilterSelectionOption}
+ * an instance of this FilterSelection class can manage all filter selection logic.
+ */
+export class SelectableFilter<T extends Entity> extends Filter<T> {
+ /**
+ * Generate filter options dynamically from the given value to be matched.
+ *
+ * This is a utility function to make it easier to generate {@link FilterSelectionOption}s for standard cases
+ * if you simply want each option to filter items having the given attribute matching different values.
+ * If you have more sophisticated filtering needs, use the constructor to set {@link FilterSelectionOption}s that
+ * you created yourself.
+ *
+ * @param valuesToMatchAsOptions An array of values to be matched.
+ * A separate FilterSelectionOption is created for each value with a filter
+ * that is true of a data item's property exactly matches that value.
+ * @param attributeName The name of the property of a data item that is compared to the value in the filter function.
+ */
+ public static generateOptions<T extends Entity>(
+ valuesToMatchAsOptions: (string | number)[],
+ attributeName: string,
+ ): FilterSelectionOption<T>[] {
+ return valuesToMatchAsOptions
+ .filter((k) => !!k)
+ .map((k) => ({
+ key: k.toString().toLowerCase(),
+ label: k.toString(),
+ filter: { [attributeName]: k } as DataFilter<T>,
+ }));
+ }
+
+ /**
+ * Create a FilterSelection with different options to be selected.
+ * @param name The name or id describing this filter
+ * @param options An array of different filtering variants to chose between
+ * @param label The user-friendly label describing this filter-selection
+ * (optional, defaults to the name of the selection)
+ */
+ constructor(
+ public override name: string,
+ public options: FilterSelectionOption<T>[],
+ public override label: string = name,
+ ) {
+ super(name, label);
+ this.selectedOptionValues = [];
+ }
+
+ /**
+ * Get the full filter option by its key.
+ * @param key The identifier of the requested option
+ */
+ getOption(key: string): FilterSelectionOption<T> | undefined {
+ return this.options.find((option: FilterSelectionOption<T>): boolean => {
+ return option.key === key;
+ });
+ }
+
+ /**
+ * Get the filter query for the given option.
+ * If the given key is undefined or invalid, the returned filter matches any elements.
+ */
+ public getFilter(): DataFilter<T> {
+ const filters: DataFilter<T>[] = this.selectedOptionValues
+ .map((value: string) => this.getOption(value))
+ .filter((value: FilterSelectionOption<T>) => value !== undefined)
+ .map((previousValue: FilterSelectionOption<T>) => {
+ return previousValue.filter as DataFilter<T>;
+ });
+
+ if (filters.length === 0) {
+ return {} as DataFilter<T>;
+ }
+ return {
+ $or: [...filters],
+ } as unknown as DataFilter<T>;
+ }
+}
+
+/**
+ * Represents one specific option to filter data in a certain way.
+ * used by {@link SelectableFilter}
+ */
+export interface FilterSelectionOption<T> {
+ /** identifier for this option in the parent FilterSelection instance */
+ key: string;
+
+ /** label displayed for this option to the user in the UI */
+ label: string;
+
+ /** Optional color */
+ color?: string;
+
+ /**
+ * The filter query which should be used if this filter is selected
+ */
+ filter: DataFilter<T>;
+}
+
Implement an Angular Service extending this base class
+when you need to work with continuous updates of a specific entity from the database.
+(e.g. SiteSettings & SiteSettingsService)
Centrally managed logging to allow log messages to be filtered by level and even sent to a remote logging service
+that allows developers to monitor and analyse problems.
+
Logging to the remote monitoring server is set only for warnings and errors.
+
To allow remote logging, call Sentry.init during bootstrap in your AppModule or somewhere early on during startup.
+
Import the constant Logging to use this from anywhere (without Angular DI).
Mocked entity mapper. Can/should only be used whenever some data should be saved
+and loaded. This is not to be used to mock database/anything related to the Schema-service.
Custom error indicating that some functionality (like file access) is not at the moment because the app is offline
+and that feature is not supported in offline mode.
The functionality that was attempted but is not available offline.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
export class NotAvailableOfflineError extends Error {
+ /**
+ * @param feature The functionality that was attempted but is not available offline.
+ */
+ constructor(feature: string) {
+ super("Functionality not available offline: " + feature);
+ }
+}
+
other records (e.g. a recurring activity, group membership, ...) to which this note is related in some way,
+so that notes can be displayed linked to these entities.
+
This property saves ids including their entity type prefix.
Counts how many children have the given attendance status.
+The status is counted based on the AttendanceLogicalStatus and the AttendanceStatusType.countAs attribute
Returns the event attendance details for the given child.
+
This method returns a default object that can be used and updated even if no attendance has been recorded yet.
+Returns undefined if the child is not added to this event/note instance.
import { DatabaseEntity } from "../../../core/entity/database-entity.decorator";
+import { Entity } from "../../../core/entity/model/entity";
+import { DatabaseField } from "../../../core/entity/database-field.decorator";
+import {
+ INTERACTION_TYPE_CONFIG_ID,
+ InteractionType,
+} from "./interaction-type.interface";
+import {
+ EventAttendance,
+ EventAttendanceMap,
+} from "../../attendance/model/event-attendance";
+import {
+ AttendanceLogicalStatus,
+ NullAttendanceStatusType,
+} from "../../attendance/model/attendance-status";
+import { getWarningLevelColor, WarningLevel } from "../../warning-level";
+import { Ordering } from "../../../core/basic-datatypes/configurable-enum/configurable-enum-ordering";
+import { PLACEHOLDERS } from "../../../core/entity/schema/entity-schema-field";
+
+@DatabaseEntity("Note")
+export class Note extends Entity {
+ static override toStringAttributes = ["subject"];
+ static override hasPII = true;
+
+ static create(
+ date: Date,
+ subject: string = "",
+ children: string[] = [],
+ ): Note {
+ const instance = new Note();
+ instance.date = date;
+ instance.subject = subject;
+ for (const child of children) {
+ instance.addChild(child);
+ }
+ return instance;
+ }
+
+ /**
+ * Returns the name of the Note property where entities of the given entity type are stored
+ * @param entityType
+ */
+ static getPropertyFor(entityType: string) {
+ switch (entityType) {
+ case "Child":
+ return "children";
+ case "School":
+ return "schools";
+ case "User":
+ return "authors";
+ default:
+ return "relatedEntities";
+ }
+ }
+
+ // TODO: remove these special properties (children, schools) and use relatedEntities instead once the attendance system is generalized (#1364)
+ /** IDs of Child entities linked with this note */
+ @DatabaseField({
+ dataType: "entity",
+ isArray: true,
+ additional: "Child",
+ entityReferenceRole: "composite",
+ editComponent: "EditAttendance",
+ anonymize: "retain",
+ })
+ children: string[] = [];
+
+ /**
+ * optional additional information about attendance at this event for each of the linked children
+ *
+ * No direct access to change this property. Use the `.getAttendance()` method to have safe access.
+ */
+ @DatabaseField({ anonymize: "retain" })
+ private childrenAttendance: EventAttendanceMap = new EventAttendanceMap();
+
+ @DatabaseField({
+ dataType: "date-only",
+ defaultValue: {
+ mode: "dynamic",
+ value: PLACEHOLDERS.NOW,
+ },
+ anonymize: "retain",
+ })
+ date: Date;
+
+ @DatabaseField()
+ subject: string;
+
+ @DatabaseField({ dataType: "long-text" })
+ text: string;
+
+ /** IDs of users that authored this note */
+ @DatabaseField({
+ dataType: "entity",
+ isArray: true,
+ additional: "User",
+ defaultValue: {
+ mode: "dynamic",
+ value: PLACEHOLDERS.CURRENT_USER,
+ },
+ anonymize: "retain",
+ })
+ authors: string[] = [];
+
+ @DatabaseField({
+ dataType: "configurable-enum",
+ additional: INTERACTION_TYPE_CONFIG_ID,
+ anonymize: "retain",
+ })
+ category: InteractionType;
+
+ @DatabaseField({
+ dataType: "file",
+ })
+ attachment: string;
+
+ /**
+ * id referencing a different entity (e.g. a recurring activity) this note is related to
+ */
+ @DatabaseField({
+ anonymize: "retain",
+ })
+ relatesTo: string;
+
+ /**
+ * other records (e.g. a recurring activity, group membership, ...) to which this note is related in some way,
+ * so that notes can be displayed linked to these entities.
+ *
+ * This property saves ids including their entity type prefix.
+ */
+ @DatabaseField({
+ dataType: "entity",
+ isArray: true,
+ // by default no additional relatedEntities can be linked apart from children and schools, overwrite this in config to display (e.g. additional: "ChildSchoolRelation")
+ additional: undefined,
+ anonymize: "retain",
+ })
+ relatedEntities: string[] = [];
+
+ /**
+ * related school ids (e.g. to infer participants for event roll calls)
+ */
+ @DatabaseField({
+ dataType: "entity",
+ isArray: true,
+ additional: "School",
+ entityReferenceRole: "composite",
+ anonymize: "retain",
+ })
+ schools: string[] = [];
+
+ @DatabaseField({
+ dataType: "configurable-enum",
+ additional: "warning-levels",
+ anonymize: "retain",
+ })
+ warningLevel: Ordering.EnumValue;
+
+ override getWarningLevel(): WarningLevel {
+ if (this.warningLevel) {
+ return WarningLevel[this.warningLevel.id];
+ } else {
+ return WarningLevel.NONE;
+ }
+ }
+
+ public override getColor() {
+ const actualLevel = this.getWarningLevel();
+ if (actualLevel === WarningLevel.OK || actualLevel === WarningLevel.NONE) {
+ return this.category?.color;
+ } else {
+ return super.getColor();
+ }
+ }
+
+ public getColorForId(childId: string): string {
+ if (
+ this.category?.isMeeting &&
+ this.childrenAttendance.get(childId)?.status.countAs ===
+ AttendanceLogicalStatus.ABSENT
+ ) {
+ // child is absent, highlight the entry
+ return getWarningLevelColor(WarningLevel.URGENT);
+ }
+ return this.getColor();
+ }
+
+ /**
+ * removes a specific child from this note
+ * @param childId The id of the child to exclude from the notes
+ */
+ removeChild(childId: string) {
+ this.children = this.children.filter((c) => c !== childId);
+ this.childrenAttendance.delete(childId);
+ }
+
+ /**
+ * adds a new child to this note
+ * @param child The child or the id of the child to add to the notes
+ */
+ addChild(child: Entity | string) {
+ const childId = typeof child === "string" ? child : child?.getId();
+ if (!childId || this.children.includes(childId)) {
+ return;
+ }
+
+ this.children = this.children.concat(childId);
+ }
+
+ /**
+ * adds a new school to this note
+ * @param school The school or its id to be added to the note
+ */
+ addSchool(school: Entity | string) {
+ const schoolId = typeof school === "string" ? school : school.getId();
+ if (this.schools.includes(schoolId)) {
+ return;
+ }
+
+ this.schools = this.schools.concat(schoolId);
+ }
+
+ /**
+ * Returns the event attendance details for the given child.
+ *
+ * This method returns a default object that can be used and updated even if no attendance has been recorded yet.
+ * Returns undefined if the child is not added to this event/note instance.
+ *
+ * @param child: The child or the id of the child to look for
+ */
+ getAttendance(child: string | Entity): EventAttendance {
+ const childId = typeof child === "string" ? child : child.getId();
+ if (!this.children.includes(childId)) {
+ return undefined;
+ }
+
+ let attendance = this.childrenAttendance.get(childId);
+ if (!attendance) {
+ attendance = new EventAttendance();
+ this.childrenAttendance.set(childId, attendance);
+ }
+ if (!(attendance instanceof EventAttendance)) {
+ attendance = Object.assign(new EventAttendance(), attendance);
+ }
+ return attendance;
+ }
+
+ /**
+ * Whether the attendance context information available through `getAttendance` is missing data for some children.
+ *
+ * While getAttendance will always set and return at least a default value `hasUnknownAttendances` can be used
+ * to flag events with incomplete data.
+ */
+ hasUnknownAttendances(childId?: string): boolean {
+ if (childId) {
+ return (
+ this.getAttendance(childId).status.id === NullAttendanceStatusType.id
+ );
+ }
+
+ if (this.childrenAttendance.size < this.children.length) {
+ return true;
+ } else {
+ for (const v of this.childrenAttendance.values()) {
+ if (v.status.id === NullAttendanceStatusType.id) {
+ return true;
+ }
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Counts how many children have the given attendance status.
+ * The status is counted based on the AttendanceLogicalStatus and the `AttendanceStatusType.countAs` attribute
+ * @param status which should be counted
+ * @returns number of children with this status
+ */
+ countWithStatus(status: AttendanceLogicalStatus): number {
+ const attendanceValues = this.childrenAttendance.values();
+ return [...attendanceValues].filter(
+ (attendance) => attendance.status.countAs === status,
+ ).length;
+ }
+
+ /**
+ * Performs a deep copy of the note copying all simple data
+ * (such as the date, author, e.t.c.) as well as copying the
+ * child-array
+ */
+ override copy(): this {
+ const note = super.copy();
+ note.children = [...this.children];
+ note.schools = [...this.schools];
+ note.relatedEntities = [...this.relatedEntities];
+ note.authors = [...this.authors];
+ note.childrenAttendance = new EventAttendanceMap();
+ this.childrenAttendance.forEach((value, key) => {
+ note.childrenAttendance.set(key, value.copy());
+ });
+ return note;
+ }
+}
+
Implementation of a datasource that directly queries an index on the Database
+supporting optional pagination to only load a subset of the data as required by a paginator.
+
An instance of QueryDataSource can be created and used as source for a mat-table component.
import { CollectionViewer, DataSource } from "@angular/cdk/collections";
+import { BehaviorSubject, Observable } from "rxjs";
+import { MatPaginator } from "@angular/material/paginator";
+import { Entity } from "../entity/model/entity";
+import { Database } from "./database";
+
+/**
+ * Implementation of a datasource that directly queries an index on the {@link Database}
+ * supporting optional pagination to only load a subset of the data as required by a paginator.
+ *
+ * An instance of QueryDataSource can be created and used as source for a mat-table component.
+ *
+ * also see https://material.angular.io/cdk/table/overview#connecting-the-table-to-a-data-source
+ * and https://medium.com/angular-in-depth/angular-material-pagination-datasource-73080d3457fe
+ */
+export class QueryDataSource<T extends Entity> implements DataSource<T> {
+ /** internal observable to emit new result data. This is provided to users calling .connect() */
+ private dataSubject = new BehaviorSubject<T[]>([]);
+
+ /** internal observable to emit new loading status. This is provided to users through the public .loading$ */
+ private loadingSubject = new BehaviorSubject<boolean>(false);
+
+ /** Indicates whether the datasource is currently loading new data */
+ public loading$ = this.loadingSubject.asObservable();
+
+ private _paginator: MatPaginator | null;
+ get paginator(): MatPaginator | null {
+ return this._paginator;
+ }
+ set paginator(value: MatPaginator | null) {
+ this._paginator = value;
+
+ if (this.paginator) {
+ this.paginator.page.subscribe(() => this.loadData());
+ this.loadData();
+ }
+ }
+
+ constructor(
+ private database: Database,
+ private queryName: string,
+ ) {}
+
+ /**
+ * Connect to the datasource and receive an observable to subscribe to loaded data.
+ * Whenever pagination is changed this will emit new datasets.
+ * @param collectionViewer (not necessary)
+ */
+ connect(collectionViewer: CollectionViewer): Observable<T[]> {
+ this.loadData();
+ return this.dataSubject.asObservable();
+ }
+
+ /**
+ * Disconnect and discard open observables for this datasource.
+ * @param collectionViewer (not necessary)
+ */
+ disconnect(collectionViewer: CollectionViewer): void {
+ this.dataSubject.complete();
+ this.loadingSubject.complete();
+ }
+
+ /**
+ * (re)load data from the database for the given query and (if set) to current pagination values.
+ */
+ async loadData() {
+ this.loadingSubject.next(true);
+
+ const options: any = {
+ include_docs: true,
+ };
+ if (this.paginator) {
+ options.limit = this.paginator.pageSize;
+ options.skip = this.paginator.pageIndex * this.paginator.pageSize;
+ }
+
+ const results = await this.database.query(this.queryName, options);
+
+ this.paginator.length = results.total_rows;
+ this.dataSubject.next(results.rows);
+
+ this.loadingSubject.next(false);
+ }
+}
+
A registry is an affordance to register dynamic objects to strings.
+It is commonly used to dynamically load entities, views or routes from the config
+
A registry cannot be instantiated directly. Instead, you should subclass from the registry
+and register it in the AppModule
+See EntityRegistry for an example
Calling this will allow the same keys to be added multiple times without thrown errors.
+This is useful for storybook where live-updates re-trigger the decorator while the registry is cached.
export abstract class Registry<T> extends Map<string, T> {
+ // This controls whether the registry will throw an error when a key is added multiple times
+ private failOnDuplicate = true;
+
+ constructor(private beforeAddCheck?: (key: string, mapping: T) => void) {
+ super();
+ }
+
+ public add(key: string, mapping: T) {
+ this.beforeAddCheck?.(key, mapping);
+ if (this.has(key) && this.failOnDuplicate) {
+ throw Error(
+ `${
+ this.constructor.name
+ }: Duplicate entity definition: ${key} is already registered with element ${this.get(
+ key,
+ )}`,
+ );
+ }
+ this.set(key, mapping);
+ }
+
+ public addAll(tuples: [string, T][]) {
+ tuples.forEach(([name, value]) => this.add(name, value));
+ }
+
+ public override get(key: string): T {
+ if (!this.has(key)) {
+ throw Error(
+ `${this.constructor.name}: Requested item "${key}" is not registered. See dynamic-registry.ts for more details.`,
+ );
+ // To register a component, add @DynamicComponent("COMPONENTNAME") to the components .ts-file and implement the onInitFromDynamicConfig method, e.g. onInitFromDynamicConfig(config: any) {}
+ }
+ return super.get(key);
+ }
+
+ /**
+ * Calling this will allow the same keys to be added multiple times without thrown errors.
+ * This is useful for storybook where live-updates re-trigger the decorator while the registry is cached.
+ */
+ public allowDuplicates() {
+ this.failOnDuplicate = false;
+ }
+}
+
A report can be accessed by users to generate aggregated statistics or customized exports calculated from available data.
+"read" permission for a ReportConfig entity is also used to control which users can generate the report's results.
+
This is the class which is saved to the database.
+However, when using this in code, use the ReportEntity instead which provides better type safety.
import { Entity, EntityConstructor } from "../../core/entity/model/entity";
+import { DatabaseEntity } from "../../core/entity/database-entity.decorator";
+import { Aggregation } from "./data-aggregation.service";
+import { ExportColumnConfig } from "../../core/export/data-transformation-service/export-column-config";
+import { DatabaseField } from "../../core/entity/database-field.decorator";
+
+/**
+ * A report can be accessed by users to generate aggregated statistics or customized exports calculated from available data.
+ * "read" permission for a ReportConfig entity is also used to control which users can generate the report's results.
+ *
+ * This is the class which is saved to the database.
+ * However, when using this in code, use the {@link ReportEntity} instead which provides better type safety.
+ */
+@DatabaseEntity("ReportConfig")
+class ReportConfig extends Entity {
+ /** human-readable title of the report */
+ @DatabaseField() title: string;
+
+ /**
+ * (optional) mode of export.
+ * The {@link ReportEntity} holds the restriction on valid report modes.
+ * Default is "reporting"
+ */
+ @DatabaseField() mode?: string;
+
+ /**
+ * (sql only) list of arguments needed for the sql query. Placeholder "?" will be replaced.
+ */
+ @DatabaseField() neededArgs?: string[] = [];
+
+ /** the definitions to calculate the report's aggregations */
+ @DatabaseField() aggregationDefinitions: any[] = [];
+
+ /** (sql only) the definition to calculate the report */
+ @DatabaseField() aggregationDefinition: string | undefined = undefined;
+}
+
+/**
+ * Union type to enable type safety for report configs.
+ * Use this instead of the {@class ReportConfig}
+ */
+export type ReportEntity = AggregationReport | ExportingReport | SqlReport;
+/**
+ * This allows the `ReportEntity` to also be used as a constructor or in the `EntityMapper`
+ */
+export const ReportEntity = ReportConfig as EntityConstructor<ReportEntity>;
+
+/**
+ * Reports handles by the {@class DataAggregationService}
+ */
+export interface AggregationReport extends ReportConfig {
+ mode: "reporting";
+ aggregationDefinitions: Aggregation[];
+}
+
+/**
+ * Reports handles by the {@class DataTransformationService}
+ */
+export interface ExportingReport extends ReportConfig {
+ /**
+ * If no mode is set, it will default to 'exporting'
+ */
+ mode?: "exporting";
+ aggregationDefinitions: ExportColumnConfig[];
+}
+
+/**
+ * Reports handles by the {@class SqlReportService}
+ */
+export interface SqlReport extends ReportConfig {
+ mode: "sql";
+ /**
+ * a valid SQL SELECT statements, can contain "?" placeholder for arguments
+ */
+ aggregationDefinition: string;
+
+ /**
+ * a list of arguments, passed into the sql statement
+ */
+ neededArgs: string[];
+}
+
Datatype for the EntitySchemaService transforming values of complex objects recursively.
+
(De)serialize instances of any class recognizing the normal @DatabaseField() annotations within that referenced class.
+This is useful if your Entity type is complex and has properties that are instances of other classes
+rather just basic value types like string or number.
+You can then annotate some properties of that referenced class so they will be saved to the database while ignoring other properties.
+The referenced class instance will be saved embedded into the entity's object and not as an own "stand-alone" entity.
+
see the unit tests in entity-schema.service.spec.ts for an example
+
implement this as its own datatype for a specific class functioning as "embedded" schema.
Key for this datatype that must be specified in the DatabaseField annotation to use this transformation.
+
for example @DatabaseField({dataType: 'foo'}) myField will trigger the datatype implementation with name "foo".
+
If you set the name to a TypeScript type, class properties with this type will automatically use
+that EntitySchemaDatatype without the need to explicitly state the dataType config in the annotation
+(e.g. @DatabaseField() myField: string is triggering the EntitySchemaDatatype with name "string".
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
import { DefaultDatatype } from "../../entity/default-datatype/default.datatype";
+import { EntitySchemaService } from "../../entity/schema/entity-schema.service";
+import { EntityConstructor } from "../../entity/model/entity";
+
+/**
+ * Datatype for the EntitySchemaService transforming values of complex objects recursively.
+ *
+ * (De)serialize instances of any class recognizing the normal @DatabaseField() annotations within that referenced class.
+ * This is useful if your Entity type is complex and has properties that are instances of other classes
+ * rather just basic value types like string or number.
+ * You can then annotate some properties of that referenced class so they will be saved to the database while ignoring other properties.
+ * The referenced class instance will be saved embedded into the entity's object and not as an own "stand-alone" entity.
+ *
+ * see the unit tests in entity-schema.service.spec.ts for an example
+ *
+ * implement this as its own datatype for a specific class functioning as "embedded" schema.
+ */
+export abstract class SchemaEmbedDatatype extends DefaultDatatype {
+ abstract embeddedType: EntityConstructor;
+
+ constructor(private schemaService: EntitySchemaService) {
+ super();
+ }
+
+ override transformToDatabaseFormat(value: any) {
+ return this.schemaService.transformEntityToDatabaseFormat(
+ value,
+ this.embeddedType.schema,
+ );
+ }
+
+ override transformToObjectFormat(value: any) {
+ const instance = new this.embeddedType();
+ this.schemaService.loadDataIntoEntity(instance, value);
+ return instance;
+ }
+}
+
Generic configuration for a filter with different selectable FilterSelectionOption options.
+
This is a reusable format for any kind of dropdown or selection component that offers the user a choice
+to narrow down a list of data items.
+As the filter function is provided as part of each FilterSelectionOption
+an instance of this FilterSelection class can manage all filter selection logic.
Generate filter options dynamically from the given value to be matched.
+
This is a utility function to make it easier to generate FilterSelectionOptions for standard cases
+if you simply want each option to filter items having the given attribute matching different values.
+If you have more sophisticated filtering needs, use the constructor to set FilterSelectionOptions that
+you created yourself.
+Example :
A separate FilterSelectionOption is created for each value with a filter
+ that is true of a data item's property exactly matches that value.
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Description
+
+
+
+
+
valuesToMatchAsOptions
+
+ (string | number)[]
+
+
+
+ No
+
+
+
+
+
An array of values to be matched.
+A separate FilterSelectionOption is created for each value with a filter
+that is true of a data item's property exactly matches that value.
import { Entity } from "../../entity/model/entity";
+import { MongoQuery } from "@casl/ability";
+import { ListFilterComponent } from "../list-filter/list-filter.component";
+import { EventEmitter, Type } from "@angular/core";
+
+/**
+ * This filter can be used to filter an array of entities.
+ * It has to follow the MongoDB Query Syntax {@link https://www.mongodb.com/docs/manual/reference/operator/query/}.
+ *
+ * The filter is parsed using ucast {@link https://github.com/stalniy/ucast/tree/master/packages/mongo2js}
+ */
+export type DataFilter<T> = MongoQuery<T> | {};
+
+export abstract class Filter<T extends Entity> {
+ /**
+ * The component used to display filter option to the user.
+ */
+ component: Type<any> = ListFilterComponent;
+
+ public selectedOptionValues: string[] = [];
+
+ /**
+ * Triggered when this filter changes value
+ * (e.g. when the user selects a new value in a FilterComponent).
+ *
+ * This is part of the filter object because dynamic filter components can't expose @Outputs
+ */
+ selectedOptionChange = new EventEmitter<string[]>();
+
+ protected constructor(
+ public name: string,
+ public label: string = name,
+ ) {}
+
+ abstract getFilter(): DataFilter<T>;
+}
+
+/**
+ * Generic configuration for a filter with different selectable {@link FilterSelectionOption} options.
+ *
+ * This is a reusable format for any kind of dropdown or selection component that offers the user a choice
+ * to narrow down a list of data items.
+ * As the filter function is provided as part of each {@link FilterSelectionOption}
+ * an instance of this FilterSelection class can manage all filter selection logic.
+ */
+export class SelectableFilter<T extends Entity> extends Filter<T> {
+ /**
+ * Generate filter options dynamically from the given value to be matched.
+ *
+ * This is a utility function to make it easier to generate {@link FilterSelectionOption}s for standard cases
+ * if you simply want each option to filter items having the given attribute matching different values.
+ * If you have more sophisticated filtering needs, use the constructor to set {@link FilterSelectionOption}s that
+ * you created yourself.
+ *
+ * @param valuesToMatchAsOptions An array of values to be matched.
+ * A separate FilterSelectionOption is created for each value with a filter
+ * that is true of a data item's property exactly matches that value.
+ * @param attributeName The name of the property of a data item that is compared to the value in the filter function.
+ */
+ public static generateOptions<T extends Entity>(
+ valuesToMatchAsOptions: (string | number)[],
+ attributeName: string,
+ ): FilterSelectionOption<T>[] {
+ return valuesToMatchAsOptions
+ .filter((k) => !!k)
+ .map((k) => ({
+ key: k.toString().toLowerCase(),
+ label: k.toString(),
+ filter: { [attributeName]: k } as DataFilter<T>,
+ }));
+ }
+
+ /**
+ * Create a FilterSelection with different options to be selected.
+ * @param name The name or id describing this filter
+ * @param options An array of different filtering variants to chose between
+ * @param label The user-friendly label describing this filter-selection
+ * (optional, defaults to the name of the selection)
+ */
+ constructor(
+ public override name: string,
+ public options: FilterSelectionOption<T>[],
+ public override label: string = name,
+ ) {
+ super(name, label);
+ this.selectedOptionValues = [];
+ }
+
+ /**
+ * Get the full filter option by its key.
+ * @param key The identifier of the requested option
+ */
+ getOption(key: string): FilterSelectionOption<T> | undefined {
+ return this.options.find((option: FilterSelectionOption<T>): boolean => {
+ return option.key === key;
+ });
+ }
+
+ /**
+ * Get the filter query for the given option.
+ * If the given key is undefined or invalid, the returned filter matches any elements.
+ */
+ public getFilter(): DataFilter<T> {
+ const filters: DataFilter<T>[] = this.selectedOptionValues
+ .map((value: string) => this.getOption(value))
+ .filter((value: FilterSelectionOption<T>) => value !== undefined)
+ .map((previousValue: FilterSelectionOption<T>) => {
+ return previousValue.filter as DataFilter<T>;
+ });
+
+ if (filters.length === 0) {
+ return {} as DataFilter<T>;
+ }
+ return {
+ $or: [...filters],
+ } as unknown as DataFilter<T>;
+ }
+}
+
+/**
+ * Represents one specific option to filter data in a certain way.
+ * used by {@link SelectableFilter}
+ */
+export interface FilterSelectionOption<T> {
+ /** identifier for this option in the parent FilterSelection instance */
+ key: string;
+
+ /** label displayed for this option to the user in the UI */
+ label: string;
+
+ /** Optional color */
+ color?: string;
+
+ /**
+ * The filter query which should be used if this filter is selected
+ */
+ filter: DataFilter<T>;
+}
+
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
The EntitySchemaField configuration providing details of how the value should be transformed.
+This can be set as a parameter to the @DatabaseField() annotation in Entity classes.
The EntitySchemaField configuration providing details of how the value should be transformed.
+This can be set as a parameter to the @DatabaseField() annotation in Entity classes.
import { Entity } from "../../entity/model/entity";
+import { DatabaseEntity } from "../../entity/database-entity.decorator";
+import { DatabaseField } from "../../entity/database-field.decorator";
+import moment from "moment";
+
+/**
+ * Record that is only active for a given time period.
+ */
+@DatabaseEntity("TimePeriod")
+export class TimePeriod extends Entity {
+ @DatabaseField({
+ dataType: "date-only",
+ label: $localize`:Label for the start date of a relation:Start date`,
+ description: $localize`:Description of the start date of a relation:The date from when this is active.`,
+ })
+ start: Date;
+
+ @DatabaseField({
+ dataType: "date-only",
+ label: $localize`:Label for the end date of a relation:End date`,
+ description: $localize`:Description of the end date of a relation:The date after which this is inactive.`,
+ })
+ end: Date;
+
+ /**
+ * Returns true if this relation is currently active
+ */
+ override get isActive(): boolean {
+ if (this.inactive) {
+ // manual archiving of records takes precendence
+ return false;
+ }
+
+ return this.isActiveAt(new Date());
+ }
+
+ /**
+ * Checks whether this relation was active on a specific date
+ * @param date on which the active status should be checked
+ */
+ isActiveAt(date: Date): boolean {
+ return (
+ (!this.start || moment(this.start).isSameOrBefore(date, "day")) &&
+ (!this.end || moment(this.end).isSameOrAfter(date, "day"))
+ );
+ }
+
+ override getColor(): string {
+ return this.isActive ? "#90ee9040" : "";
+ }
+
+ override assertValid() {
+ super.assertValid();
+
+ this.checkValidDateRange();
+ }
+
+ private checkValidDateRange() {
+ if (!this.end) {
+ // without end date, any range is valid
+ return;
+ }
+
+ const startLabel = this.getSchema().get("start").label;
+ const endLabel = this.getSchema().get("end").label;
+ if (this.end && !this.start) {
+ throw new Error(
+ $localize`:Error assertValid failed:No "${startLabel}" date is set`,
+ );
+ } else if (moment(this.start).isAfter(this.end, "days")) {
+ throw new Error(
+ $localize`:Error assertValid failed:The "${startLabel}" date is after the "${endLabel}" date`,
+ );
+ }
+ }
+}
+
All fields are defined in config (in the database) and customized there,
+this class only serves as an interface for required fields upon which core functionalities are built.
import { DatabaseEntity } from "../../../core/entity/database-entity.decorator";
+import { Entity } from "../../../core/entity/model/entity";
+import { TimeInterval } from "../recurring-interval/time-interval";
+import { TodoCompletion } from "./todo-completion";
+import { WarningLevel } from "../../../child-dev-project/warning-level";
+import { DatabaseField } from "../../../core/entity/database-field.decorator";
+
+/**
+ * Base Entity Type for the Todo Feature.
+ *
+ * All fields are defined in config (in the database) and customized there,
+ * this class only serves as an interface for required fields upon which core functionalities are built.
+ */
+@DatabaseEntity("Todo")
+export class Todo extends Entity {
+ static create(properties: Partial<Todo>): Todo {
+ const instance = new Todo();
+ Object.assign(instance, properties);
+ return instance;
+ }
+
+ @DatabaseField()
+ subject: string = "";
+
+ @DatabaseField()
+ description: string = "";
+
+ @DatabaseField({ dataType: "date-only" })
+ deadline: Date;
+
+ /**
+ * Optional field to specify a point in time from when the task can be started.
+ */
+ @DatabaseField({ dataType: "date-only" })
+ startDate?: Date;
+
+ @DatabaseField({ dataType: "entity", isArray: true })
+ assignedTo: string[] = [];
+
+ /**
+ * other records (e.g. a recurring activity, group membership, ...) to which this task is related in some way.
+ *
+ * This property saves ids including their entity type prefix.
+ */
+ @DatabaseField({ dataType: "entity", isArray: true })
+ relatedEntities: string[] = [];
+
+ @DatabaseField()
+ repetitionInterval: TimeInterval;
+
+ @DatabaseField()
+ completed?: TodoCompletion;
+
+ override get isActive(): boolean {
+ if (this.inactive) {
+ // manual archiving of records takes precedence
+ return false;
+ }
+
+ return !this.completed;
+ }
+
+ get isOverdue(): boolean {
+ return !!(
+ !this.completed &&
+ this.deadline &&
+ this.deadline.getTime() < new Date().getTime()
+ );
+ }
+
+ override getWarningLevel(): WarningLevel {
+ if (this.isOverdue) {
+ return WarningLevel.URGENT;
+ }
+ if (this.completed) {
+ return WarningLevel.OK;
+ }
+ return WarningLevel.NONE;
+ }
+}
+
import { DatabaseField } from "../database-field.decorator";
+
+/**
+ * Object to store metadata about a "revision" of a document including date and author of the change.
+ */
+export class UpdateMetadata {
+ static DATA_TYPE = "update-metadata";
+
+ /** when the update was saved to db */
+ @DatabaseField() at: Date;
+
+ /** username who saved the update */
+ @DatabaseField() by: string;
+
+ constructor(by: string = undefined, at: Date = new Date()) {
+ this.by = by;
+ this.at = at;
+ }
+}
+
Service to share context for components that can be used both
+in dialogs (wrapped by DialogViewComponent) and
+in full screen (wrapped by RoutedViewComponent).
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
<div *ngIf="loading">
+ <mat-progress-bar mode="indeterminate"></mat-progress-bar>
+</div>
+
+<div class="flex-row flex-wrap gap-large" *ngIf="!loading">
+ <app-attendance-calendar
+ class="flex-grow"
+ [records]="combinedAttendance?.events || []"
+ [highlightForChild]="forChild"
+ [activity]="entity"
+ ></app-attendance-calendar>
+ <app-attendance-summary
+ [attendance]="combinedAttendance"
+ [forChild]="forChild"
+ [columns]="columns"
+ class="margin-top-regular flex-grow"
+ ></app-attendance-summary>
+</div>
+
+<app-entities-table
+ [entityType]="entityCtr"
+ [records]="records"
+ [customColumns]="columns"
+ clickMode="none"
+ (entityClick)="showDetails($event)"
+ [getBackgroundColor]="getBackgroundColor"
+ [editable]="false"
+>
+</app-entities-table>
+
+<div class="margin-top-regular">
+ <mat-slide-toggle
+ i18n="
+ slider|show unrelated attendance-entries for an activity that are not
+ linked to the child of interest
+ "
+ (change)="updateDisplayedRecords($event.checked)"
+ i18n-matTooltip="
+ Show unrelated tooltip|Tooltip that will appear when hovered over the
+ show-unrelated button
+ "
+ matTooltip="Activate to also show entries for the activity that do not have any events with actual participation of this person"
+ >
+ Also show unrelated
+ </mat-slide-toggle>
+
+ <button
+ i18n="
+ load-all button|load all records, not only the ones from the last 6 months
+ "
+ mat-stroked-button
+ (click)="init(true)"
+ >
+ Load all records
+ </button>
+</div>
+
+ Default value : [
+ $localize`:One of the stages while recording child-attendances:Select Event`,
+ $localize`:One of the stages while recording child-attendances:Record Attendance`,
+ ]
+
/* Moves the component 12 pixels to the left so that the "go back" button is aligned with the left border */
+.relative-left {
+ position: relative;
+ left: -12px;
+}
+
+:host {
+ display: flex;
+ flex-direction: column;
+}
+
<h2 mat-dialog-title i18n>Configure Text Block</h2>
+<app-dialog-close mat-dialog-close></app-dialog-close>
+
+<mat-dialog-content>
+ <p i18n>
+ This text is displayed as part of the form to provide additional information
+ without any input options for the user:
+ </p>
+
+ <form [formGroup]="schemaFieldsForm">
+ <div class="entity-form-cell">
+ <mat-form-field>
+ <textarea formControlName="label" matInput rows="3"></textarea>
+ </mat-form-field>
+ </div>
+ </form>
+</mat-dialog-content>
+
+<mat-dialog-actions>
+ <button mat-button (click)="save()" i18n="Button label">Save</button>
+ <button mat-button mat-dialog-close i18n="Button label">Cancel</button>
+</mat-dialog-actions>
+
<div class="hint-banner" i18n>
+ You can edit how users will see the details of a single record of this type.
+ Drag and drop fields and sections in this preview of a profile view and group
+ them as appropriate. The editor below closely resembles how the form will look
+ for users later.
+ <br />
+ We recommend to keep things simple: Only add fields that you really need for
+ your work.
+</div>
+
+<app-view-title [disableBackButton]="true" [displayInPlace]="true">
+ <Name of displayed {{ this.entityConstructor?.label }}>
+</app-view-title>
+
+<app-admin-tabs [tabs]="config?.panels" [newTabFactory]="newPanelFactory">
+ <ng-template [appAdminTabTemplate]="config?.panels" let-item>
+ <div class="flex-column gap-large padding-top-large">
+ <div
+ *ngFor="let componentConfig of item.components; let j = index"
+ class="section-wrapper"
+ >
+ <app-admin-section-header
+ [(title)]="componentConfig.title"
+ (remove)="item.components.splice(j, 1)"
+ ></app-admin-section-header>
+
+ <app-admin-entity-form
+ *ngIf="componentConfig.component === 'Form'; else otherComponent"
+ [config]="componentConfig.config"
+ [entityType]="entityConstructor"
+ >
+ </app-admin-entity-form>
+
+ <ng-template #otherComponent>
+ <app-admin-entity-panel-component
+ [config]="componentConfig"
+ [entityType]="entityConstructor"
+ ></app-admin-entity-panel-component>
+ </ng-template>
+ </div>
+
+ <button
+ mat-stroked-button
+ color="accent"
+ class="section-add-button"
+ (click)="addComponent(item)"
+ i18n
+ >
+ <fa-icon
+ aria-label="add element"
+ icon="plus-circle"
+ class="standard-icon-with-text"
+ ></fa-icon>
+ Add Section
+ </button>
+ </div>
+ </ng-template>
+</app-admin-tabs>
+
+
+
+
+
+ ./admin-entity-details.component.scss
+
+
@use "@angular/material/core/style/elevation" as mat-elevation;
+@use "variables/sizes";
+
+.admin-ui-title {
+ font-style: italic;
+}
+
+.save-buttons {
+ margin: auto 0;
+}
+
+.section-wrapper {
+ @include mat-elevation.elevation(1);
+ margin: sizes.$small;
+ padding: sizes.$small;
+}
+/* TODO: making direct child of app-admin-section-header somehow breaks this
+ although `:has(> app-admin-section-header .group-remove-button` (without :hover) does work ... */
+.section-wrapper:has(> app-admin-section-header .group-remove-button:hover) {
+ border-color: rgb(255, 0, 0);
+ background-color: rgba(255, 0, 0, 0.1);
+}
+
+.section-add-button {
+ padding: sizes.$large;
+ margin: sizes.$small;
+}
+
@use "mixins/grid-layout";
+@use "variables/sizes";
+
+.grid-layout {
+ @include grid-layout.adaptive(
+ $min-block-width: sizes.$form-group-min-width,
+ $max-screen-width: 414px
+ );
+}
+
+.entity-form-cell {
+ display: flex;
+ flex-direction: column;
+
+ /* set the width of each form field to 100% in every form component that is a descendent
+ of the columns-wrapper class */
+ mat-form-field {
+ width: 100%;
+ }
+
+ /* We align the photo (and only tht photo) to the center of the cell if there is one.
+ This looks better on desktop and mobile compared to an alignment to the start of the cell
+ which is the default for all other elements */
+ > app-edit-photo {
+ align-self: center;
+ }
+}
+
Opens the configuration settings for a field.
+If the field has an editComponent defined in the schema, it opens the text configuration.
+Otherwise, it opens the field configuration.
import { Component, Input, OnChanges, SimpleChanges } from "@angular/core";
+import { Entity, EntityConstructor } from "../../../entity/model/entity";
+import {
+ EntityForm,
+ EntityFormService,
+} from "../../../common-components/entity-form/entity-form.service";
+import { FormControl } from "@angular/forms";
+import { MatDialog } from "@angular/material/dialog";
+import { AdminEntityFieldComponent } from "../admin-entity-field/admin-entity-field.component";
+import {
+ CdkDragDrop,
+ DragDropModule,
+ moveItemInArray,
+ transferArrayItem,
+} from "@angular/cdk/drag-drop";
+import {
+ ColumnConfig,
+ FormFieldConfig,
+ toFormFieldConfig,
+} from "../../../common-components/entity-form/FormConfig";
+import { AdminEntityService } from "../../admin-entity.service";
+import { lastValueFrom } from "rxjs";
+import { NgForOf, NgIf } from "@angular/common";
+import { FaIconComponent } from "@fortawesome/angular-fontawesome";
+import { MatButtonModule } from "@angular/material/button";
+import { MatTooltipModule } from "@angular/material/tooltip";
+import { MatCardModule } from "@angular/material/card";
+import { EntityFieldLabelComponent } from "../../../common-components/entity-field-label/entity-field-label.component";
+import { EntityFieldEditComponent } from "../../../common-components/entity-field-edit/entity-field-edit.component";
+import { AdminSectionHeaderComponent } from "../../building-blocks/admin-section-header/admin-section-header.component";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { FormConfig } from "../../../entity-details/form/form.component";
+import { AdminEditDescriptionOnlyFieldComponent } from "../admin-entity-field/admin-edit-description-only-field/admin-edit-description-only-field.component";
+import { FieldGroup } from "app/core/entity-details/form/field-group";
+
+@UntilDestroy()
+@Component({
+ selector: "app-admin-entity-form",
+ templateUrl: "./admin-entity-form.component.html",
+ styleUrls: [
+ "./admin-entity-form.component.scss",
+ "../../building-blocks/admin-section-header/admin-section-header.component.scss",
+ "../../../common-components/entity-form/entity-form/entity-form.component.scss",
+ ],
+ standalone: true,
+ imports: [
+ DragDropModule,
+ NgForOf,
+ FaIconComponent,
+ MatButtonModule,
+ MatTooltipModule,
+ MatCardModule,
+ EntityFieldLabelComponent,
+ EntityFieldEditComponent,
+ AdminSectionHeaderComponent,
+ NgIf,
+ ],
+})
+export class AdminEntityFormComponent implements OnChanges {
+ @Input() entityType: EntityConstructor;
+
+ @Input() config: FormConfig;
+
+ dummyEntity: Entity;
+ dummyForm: EntityForm<any>;
+
+ availableFields: ColumnConfig[] = [];
+ readonly createNewFieldPlaceholder: FormFieldConfig = {
+ id: null,
+ label: $localize`:Label drag and drop item:Create New Field`,
+ };
+
+ readonly createNewTextPlaceholder: FormFieldConfig = {
+ id: null,
+ label: $localize`:Label drag and drop item:Create Text Block`,
+ };
+
+ constructor(
+ private entityFormService: EntityFormService,
+ private matDialog: MatDialog,
+ adminEntityService: AdminEntityService,
+ ) {
+ adminEntityService.entitySchemaUpdated
+ .pipe(untilDestroyed(this))
+ .subscribe(() => {
+ this.availableFields = []; // force re-init of the label components that otherwise do not detect the change
+ setTimeout(() => this.initForm());
+ });
+ }
+
+ async ngOnChanges(changes: SimpleChanges): Promise<void> {
+ if (changes.config) {
+ await this.initForm();
+ }
+ }
+
+ private async initForm() {
+ this.initAvailableFields();
+
+ this.dummyEntity = new this.entityType();
+ this.dummyForm = await this.entityFormService.createEntityForm(
+ [...this.getUsedFields(this.config), ...this.availableFields],
+ this.dummyEntity,
+ );
+ this.dummyForm.formGroup.disable();
+ }
+
+ private getUsedFields(config: FormConfig): ColumnConfig[] {
+ return config.fieldGroups.reduce((p, c) => p.concat(c.fields), []);
+ }
+
+ /**
+ * Load any fields from schema that are not already in the form, so that the user can drag them into the form.
+ * @param config
+ * @private
+ */
+ private initAvailableFields() {
+ const usedFields = this.getUsedFields(this.config);
+ const unusedFields = Array.from(this.entityType.schema.entries())
+ .filter(
+ ([key]) =>
+ !usedFields.some(
+ (x) => x === key || (x as FormFieldConfig).id === key,
+ ),
+ )
+ .filter(([key, value]) => value.label) // no technical, internal fields
+ .sort(([aId, a], [bId, b]) => a.label.localeCompare(b.label))
+ .map(([key]) => key);
+
+ this.availableFields = [
+ this.createNewFieldPlaceholder,
+ this.createNewTextPlaceholder,
+ ...unusedFields,
+ ];
+ }
+
+ /**
+ * Open the form to edit details of a single field's schema.
+ *
+ * @param field field to edit or { id: null } to create a new field
+ * @returns the id of the field that was edited or created (which is newly defined in the dialog for new fields)
+ */
+ async openFieldConfig(field: ColumnConfig): Promise<string> {
+ let fieldIdToEdit = toFormFieldConfig(field).id;
+ const dialogRef = this.matDialog.open(AdminEntityFieldComponent, {
+ width: "99%",
+ maxHeight: "90vh",
+ data: {
+ fieldId: fieldIdToEdit,
+ entityType: this.entityType,
+ },
+ });
+ return lastValueFrom(dialogRef.afterClosed());
+ }
+
+ /**
+ * Open the form to edit details of a single text's schema.
+ *
+ * @param textField text to edit or { id: null } to create a new text
+ * @returns the id of the text that was edited or created (which is newly defined in the dialog for new fields)
+ */
+ async openTextConfig(textField: FormFieldConfig): Promise<FormFieldConfig> {
+ const dialogRef = this.matDialog.open(
+ AdminEditDescriptionOnlyFieldComponent,
+ {
+ data: textField,
+ },
+ );
+
+ const result = await lastValueFrom(dialogRef.afterClosed());
+ return result;
+ }
+
+ drop(event: CdkDragDrop<ColumnConfig[], ColumnConfig[]>) {
+ const prevFieldsArray = event.previousContainer.data;
+ const newFieldsArray = event.container.data;
+
+ if (
+ prevFieldsArray[event.previousIndex] === this.createNewFieldPlaceholder
+ ) {
+ this.dropNewField(event);
+ return;
+ }
+
+ if (
+ prevFieldsArray[event.previousIndex] === this.createNewTextPlaceholder
+ ) {
+ this.dropNewText(event);
+ return;
+ }
+
+ if (event.previousContainer === event.container) {
+ moveItemInArray(newFieldsArray, event.previousIndex, event.currentIndex);
+ } else {
+ transferArrayItem(
+ prevFieldsArray,
+ newFieldsArray,
+ event.previousIndex,
+ event.currentIndex,
+ );
+ }
+
+ if (newFieldsArray === this.availableFields) {
+ // ensure available fields have consistent order
+ this.initAvailableFields();
+ }
+ }
+
+ /**
+ * Opens the configuration settings for a field.
+ * If the field has an editComponent defined in the schema, it opens the text configuration.
+ * Otherwise, it opens the field configuration.
+ * @param field The field to open the configuration settings for.
+ */
+ async openConfigDetails(field: ColumnConfig) {
+ let fieldIdToEdit = toFormFieldConfig(field).id;
+ const configDetails = Object.assign(
+ {},
+ this.entityType.schema.get(fieldIdToEdit) ?? {},
+ field,
+ ) as FormFieldConfig;
+
+ if (configDetails.editComponent == "EditDescriptionOnly") {
+ const updatedField = await this.openTextConfig(configDetails);
+ Object.assign(field, updatedField);
+ await this.initForm();
+ } else {
+ await this.openFieldConfig(field);
+ }
+ }
+
+ /**
+ * drop handler specifically for the "create new field" item
+ * @param event
+ * @private
+ */
+ private async dropNewField(
+ event: CdkDragDrop<ColumnConfig[], ColumnConfig[]>,
+ ) {
+ if (event.container.data === this.availableFields) {
+ // don't add new field to the available fields that are not in the form yet
+ return;
+ }
+
+ const newFieldId = await this.openFieldConfig({ id: null });
+ if (!newFieldId) {
+ return;
+ }
+
+ this.dummyForm.formGroup.addControl(newFieldId, new FormControl());
+ this.dummyForm.formGroup.disable();
+ event.container.data.splice(event.currentIndex, 0, newFieldId);
+
+ // the schema update has added the new field to the available fields already, remove it from there
+ this.availableFields.splice(this.availableFields.indexOf(newFieldId), 1);
+ }
+ /**
+ * drop handler specifically for the "create new Text field" item
+ * @param event
+ * @private
+ */
+ private async dropNewText(
+ event: CdkDragDrop<ColumnConfig[], ColumnConfig[]>,
+ ) {
+ if (event.container.data === this.availableFields) {
+ // don't add new Text field to the available fields that are not in the form yet
+ return;
+ }
+
+ const newTextField = await this.openTextConfig({ id: null });
+ if (!newTextField) {
+ return;
+ }
+
+ this.dummyForm.formGroup.addControl(newTextField.id, new FormControl());
+ this.dummyForm.formGroup.disable();
+ event.container.data.splice(event.currentIndex, 0, newTextField);
+
+ // the schema update has added the new Text field to the available fields already, remove it from there
+ this.availableFields.splice(this.availableFields.indexOf(newTextField), 1);
+ }
+
+ dropNewGroup(event: CdkDragDrop<any, any>) {
+ const newCol = { fields: [] };
+ this.config.fieldGroups.push(newCol);
+ event.container.data = newCol.fields;
+ this.drop(event);
+ }
+
+ removeGroup(i: number) {
+ const [removedFieldGroup] = this.config.fieldGroups.splice(i, 1);
+ this.initAvailableFields();
+ }
+
+ hideField(field: ColumnConfig, group: FieldGroup) {
+ const fieldIndex = group.fields.indexOf(field);
+ group.fields.splice(fieldIndex, 1);
+ this.initAvailableFields();
+ }
+}
+
+
+
+
+
<div cdkDropListGroup class="overall-container flex-row">
+ <!-- FORM PREVIEW -->
+ <div class="flex-grow admin-grid-layout padding-right-regular">
+ <!-- FIELD GROUPS -->
+ <div
+ *ngFor="let group of config.fieldGroups; let i = index"
+ class="entity-form-cell admin-form-column section-container"
+ >
+ <!-- GROUP HEADER -->
+ <app-admin-section-header
+ [(title)]="group.header"
+ (remove)="removeGroup(i)"
+ ></app-admin-section-header>
+
+ <div
+ cdkDropList
+ [cdkDropListData]="group.fields"
+ (cdkDropListDropped)="drop($event)"
+ class="fields-group-list drop-list"
+ >
+ <!-- FIELD [start] -->
+ <div
+ *ngFor="let field of group.fields"
+ class="admin-form-field flex-row align-center"
+ cdkDrag
+ cdkDragBoundary=".overall-container"
+ >
+ <fa-icon icon="grip-vertical" size="xl" class="drag-handle"></fa-icon>
+
+ <div class="field-hover-buttons flex-row align-center gap-small">
+ <button
+ class="field-edit-button"
+ mat-stroked-button
+ color="accent"
+ (click)="openConfigDetails(field)"
+ i18n="Button label"
+ >
+ Edit Field
+ </button>
+
+ <button
+ mat-icon-button
+ color="black"
+ (click)="hideField(field, group)"
+ aria-label="Hide Field"
+ matTooltip="remove (i.e. hide) this field from the form"
+ i18n-matTooltip
+ >
+ <fa-icon icon="times"></fa-icon>
+ </button>
+ </div>
+
+ <div class="dummy-form-field">
+ <app-entity-field-edit
+ [field]="field"
+ [entity]="dummyEntity"
+ [form]="dummyForm"
+ ></app-entity-field-edit>
+ </div>
+ </div>
+ <!-- FIELD [end]-->
+ </div>
+ </div>
+
+ <!-- DROP AREA: NEW FIELD GROUP -->
+ <div class="entity-form-cell admin-form-column">
+ <div
+ cdkDropList
+ (cdkDropListDropped)="dropNewGroup($event)"
+ class="fields-group-list drop-list drop-area-hint"
+ i18n="Header of drag and drop box"
+ >
+ drop here to create new field group
+ <fa-icon
+ icon="question-circle"
+ matTooltip="You can group fields so that they will always appear next to each other while the layout is automatically adjusted to different screen sizes. Such field groups can also have a title displayed to users."
+ i18n-matTooltip
+ ></fa-icon>
+ </div>
+ </div>
+ </div>
+
+ <!-- TOOLBAR -->
+ <mat-card class="toolbar">
+ <mat-card-content
+ cdkDropList
+ (cdkDropListDropped)="drop($event)"
+ [cdkDropListData]="availableFields"
+ class="drop-list"
+ >
+ <div class="drop-area-hint">
+ <em i18n="title for drag and drop section">hidden fields</em><br />
+ <span i18n="subtitle for drag and drop section">
+ drag & drop to / from here
+ </span>
+ <fa-icon
+ icon="question-circle"
+ matTooltip="You can remove fields from this form without deleting them completely. The fields here will not be visible or editable for users but you can display them in other views or keep them archived to not lose previously collected data. Drag a field back into the form preview to display it."
+ i18n-matTooltip
+ ></fa-icon>
+ </div>
+
+ <div
+ *ngFor="let field of availableFields"
+ class="admin-form-field flex-row align-center"
+ [class.admin-form-field-new]="
+ field === createNewFieldPlaceholder ||
+ field === createNewTextPlaceholder
+ "
+ cdkDrag
+ cdkDragBoundary="mat-drawer-container"
+ >
+ <fa-icon icon="grip-vertical" size="xl" class="drag-handle"></fa-icon>
+
+ <div>
+ <app-entity-field-label
+ [field]="field"
+ [entityType]="entityType"
+ ></app-entity-field-label>
+
+ <button
+ *ngIf="
+ field !== createNewFieldPlaceholder &&
+ field !== createNewTextPlaceholder
+ "
+ mat-stroked-button
+ color="accent"
+ class="field-hover-buttons field-edit-button-small"
+ (click)="openFieldConfig(field)"
+ >
+ Edit
+ </button>
+ </div>
+ </div>
+ </mat-card-content>
+ </mat-card>
+</div>
+
@use "mixins/grid-layout";
+@use "variables/sizes";
+
+.grid-layout {
+ @include grid-layout.adaptive(
+ $min-block-width: sizes.$form-group-min-width,
+ $max-screen-width: 414px
+ );
+}
+
+.entity-form-cell {
+ display: flex;
+ flex-direction: column;
+
+ /* set the width of each form field to 100% in every form component that is a descendent
+ of the columns-wrapper class */
+ mat-form-field {
+ width: 100%;
+ }
+
+ /* We align the photo (and only tht photo) to the center of the cell if there is one.
+ This looks better on desktop and mobile compared to an alignment to the start of the cell
+ which is the default for all other elements */
+ > app-edit-photo {
+ align-self: center;
+ }
+}
+
<div class="hint-banner" i18n>
+ The settings here apply to the entity type overall and take effect everywhere
+ the entity is displayed, including lists, forms and other views.
+</div>
+
+<h2 i18n>General Settings of "{{ entityConstructor.label }}" Records</h2>
+
+<form [formGroup]="basicSettingsForm">
+ <mat-tab-group>
+ <mat-tab label="Basics" i18n-label>
+ <div class="grid-layout flex-grow margin-top-regular">
+ <div class="entity-form-cell">
+ <mat-form-field>
+ <mat-label i18n>Label</mat-label>
+ <input formControlName="label" matInput #formLabel />
+ </mat-form-field>
+
+ <mat-form-field floatLabel="always">
+ <mat-label>
+ <span i18n>Label (Plural)</span>
+
+ <fa-icon
+ icon="question-circle"
+ matTooltip="Optionally you can define how multiple records of this entity should be called, e.g. in lists."
+ i18n-matTooltip
+ ></fa-icon>
+ </mat-label>
+ <input
+ formControlName="labelPlural"
+ matInput
+ [placeholder]="formLabel.value"
+ />
+ </mat-form-field>
+
+ <mat-form-field floatLabel="always">
+ <mat-label>
+ <span i18n>Icon</span>
+
+ <fa-icon
+ icon="question-circle"
+ matTooltip="The icon to represent this entity type, e.g. when displaying records as a small preview block."
+ i18n-matTooltip
+ ></fa-icon>
+ </mat-label>
+ <input formControlName="icon" matInput />
+
+ <mat-hint i18n>
+ Find available icon names at
+ <a
+ href="https://fontawesome.com/v6/search?o=r&m=free"
+ target="_blank"
+ >fontawesome.com</a
+ >
+ </mat-hint>
+ </mat-form-field>
+ </div>
+
+ <div class="entity-form-cell">
+ <mat-form-field>
+ <mat-label>
+ <span i18n>Generated Title of Record</span>
+
+ <fa-icon
+ icon="question-circle"
+ matTooltip="Select the fields that should be used (in that order) to generate a simple name/title for a record. This generated title is used in previews, search and for form fields that allow to select a record of this type. (Only text fields can be used here)"
+ i18n-matTooltip
+ ></fa-icon>
+ </mat-label>
+ <app-basic-autocomplete
+ formControlName="toStringAttributes"
+ #formDataType
+ [options]="toStringAttributesOptions"
+ [optionToString]="objectToLabel"
+ [valueMapper]="objectToValue"
+ [multi]="true"
+ [reorder]="true"
+ ></app-basic-autocomplete>
+ </mat-form-field>
+ </div>
+ </div>
+ </mat-tab>
+
+ <!--
+ ADVANCED SETTINGS
+ -->
+ <mat-tab
+ label="Configure PII / Anonymization"
+ i18n-label
+ [disabled]="false"
+ >
+ <div class="margin-top-regular overflow-table">
+ <div class="flex-row align-center">
+ <mat-checkbox
+ [checked]="showPIIDetails"
+ (change)="toggleAnonymizationTable($event)"
+ i18n
+ >Has personal information (PII)</mat-checkbox
+ >
+ <app-help-button
+ text="If the fields of this record type contain personal, sensitive information you can mark this here. Checking this box enables the 'anonymization' feature. This allows users to anonymize records of this type instead of just archiving or deleting them."
+ i18n-text
+ ></app-help-button>
+ </div>
+
+ <div *ngIf="showPIIDetails">
+ <p i18n>
+ Configure how records of this type can be anonymized. Users can
+ "anonymize" a record as an alternative to just archiving it (keeping
+ all personal details) or deleting it (losing any trace of the
+ record, even in reports). Select below which fields can be
+ "retained" to keep some limited data for statistical reporting and
+ which fields have to be removed because they contain personal
+ details.
+ </p>
+
+ <mat-table [dataSource]="fieldAnonymizationDataSource">
+ <ng-container matColumnDef="label">
+ <mat-cell *matCellDef="let anonymizeData">
+ {{ anonymizeData.label }}
+ </mat-cell>
+ </ng-container>
+
+ <ng-container matColumnDef="field">
+ <mat-cell *matCellDef="let anonymizeData">
+ <app-anonymize-options
+ [value]="anonymizeData.field.anonymize"
+ (valueChange)="
+ changeFieldAnonymization(anonymizeData.field, $event)
+ "
+ ></app-anonymize-options>
+ </mat-cell>
+ </ng-container>
+
+ <mat-row
+ *matRowDef="let row; columns: ['label', 'field']"
+ ></mat-row>
+ </mat-table>
+ </div>
+ </div>
+ </mat-tab>
+ </mat-tab-group>
+</form>
+
@use "mixins/grid-layout";
+
+.grid-layout {
+ @include grid-layout.adaptive(
+ $min-block-width: 250px,
+ $max-screen-width: 414px
+ );
+}
+.entity-form-cell {
+ display: flex;
+ flex-direction: column;
+ /* set the width of each form field to 100% in every form component that is a descendent of the columns-wrapper class */
+ mat-form-field {
+ width: 100%;
+ }
+}
+.overflow-table {
+ max-height: calc(100vh - 250px);
+ overflow: auto;
+}
+
Simple building block for UI Builder for a section title including button to remove the section.
+
Supports two-way binding for the title.
+
add css class "section-container" and import this component's scss in the parent's styleUrl
+to get visual highlighting on hovering over the remove button,
+or copy the style from there.
+LIMITATION: multiple hierarchies each using this have to define seperate container classes, otherwise styles will leak
import { Component, EventEmitter, Input, OnInit, Output } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { MatOptionModule } from "@angular/material/core";
+import { MatSelectModule } from "@angular/material/select";
+import { MatTooltipModule } from "@angular/material/tooltip";
+
+/**
+ * Simple form field for admins to select the "anonymize" mode for an entity field.
+ * Displays tooltips as descriptions also.
+ */
+@Component({
+ selector: "app-anonymize-options",
+ standalone: true,
+ imports: [CommonModule, MatOptionModule, MatSelectModule, MatTooltipModule],
+ templateUrl: "./anonymize-options.component.html",
+ styleUrl: "./anonymize-options.component.scss",
+})
+export class AnonymizeOptionsComponent implements OnInit {
+ @Input() value: string;
+ @Output() valueChange = new EventEmitter<string>();
+
+ ngOnInit(): void {
+ if (!this.value) {
+ this.value = "";
+ }
+ }
+}
+
+
+
+
+
<mat-form-field appearance="fill">
+ <mat-label>
+ <ng-content></ng-content>
+ </mat-label>
+
+ <mat-select
+ [(value)]="value"
+ (selectionChange)="valueChange.emit($event.value)"
+ >
+ <mat-option
+ value=""
+ matTooltip="Completely remove the value from the record during anonymization."
+ i18n-matTooltip
+ matTooltipPosition="before"
+ i18n
+ >Remove</mat-option
+ >
+ <mat-option
+ value="retain"
+ matTooltip="Keep the original value without any anonymization."
+ i18n-matTooltip
+ matTooltipPosition="before"
+ i18n
+ >Retain</mat-option
+ >
+ <mat-option
+ value="retain-anonymized"
+ matTooltip="Anonymize the value, but retain some generalized information. For dates, this removes the day and only keeps the year for statistical reporting. If a datatype (like the simple text field) does not support partial anonymization, the value will instead be removed completely."
+ i18n-matTooltip
+ matTooltipPosition="before"
+ i18n
+ >Partially Anonymize</mat-option
+ >
+ </mat-select>
+</mat-form-field>
+
Simple component displaying the current app version
+including functionality to open an info dialog showing the latest change when the user clicks on it.
import { ChangeDetectionStrategy, Component, OnInit } from "@angular/core";
+import { LatestChangesDialogService } from "../latest-changes-dialog.service";
+
+/**
+ * Simple component displaying the current app version
+ * including functionality to open an info dialog showing the latest change when the user clicks on it.
+ */
+@Component({
+ selector: "app-version",
+ templateUrl: "./app-version.component.html",
+ standalone: true,
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AppVersionComponent implements OnInit {
+ /** the current app version */
+ currentVersion: string;
+
+ constructor(private changelogDialog: LatestChangesDialogService) {}
+
+ ngOnInit(): void {
+ this.currentVersion = this.changelogDialog.getCurrentVersion();
+ }
+
+ /**
+ * Open dialog box to display changelog information about the latest version to the user.
+ */
+ public showLatestChanges(): void {
+ this.changelogDialog.showLatestChanges();
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<small>
+ {{ currentVersion }}
+</small>
+
<h1 i18n="Sync notification line 1">Building application</h1>
+<p i18n="Sync notification line 2">The application will be ready in a moment</p>
+<mat-progress-bar mode="indeterminate"></mat-progress-bar>
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<h1 mat-dialog-title>
+ <app-dialog-close mat-dialog-close></app-dialog-close>
+ {{ entity?.activity?.title }}: {{ entity.periodFrom | date: "shortDate" }} -
+ {{ entity.periodTo | date: "shortDate" }}
+</h1>
+<div mat-dialog-content>
+ <div
+ class="summary w-{{ entity.getWarningLevel() }}"
+ i18n="
+ Attendance|Attendance of a child (in percent) or the average of the event
+ (in percent)
+ "
+ >
+ Attendance:
+ {{
+ (forChild
+ ? entity?.getAttendancePercentage(forChild)
+ : entity?.getAttendancePercentageAverage()
+ ) | percent: "1.0-0"
+ }}
+ </div>
+
+ <div class="flex-row flex-wrap gap-regular" *ngIf="forChild">
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="days present|How many days a child was present"
+ placeholder="days present"
+ [value]="entity.countEventsPresent(forChild)"
+ readonly
+ />
+ </mat-form-field>
+
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="days absent|How many days a child was absent"
+ placeholder="days absent"
+ [value]="entity.countEventsAbsent(forChild)"
+ readonly
+ />
+ </mat-form-field>
+
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="
+ days absent|How many days the presence or absence of a child is
+ unknown
+ "
+ placeholder="unknown status"
+ [value]="entity.countEventsWithUnknownStatus(forChild)"
+ readonly
+ />
+ </mat-form-field>
+ </div>
+
+ <div class="flex-row flex-wrap gap-regular" *ngIf="!forChild">
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="Total present|How many children were present"
+ placeholder="Total present"
+ [value]="entity.countTotalPresent()"
+ readonly
+ />
+ </mat-form-field>
+
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="Total absent|How many children were absent"
+ placeholder="Total absent"
+ [value]="entity.countTotalAbsent()"
+ readonly
+ />
+ </mat-form-field>
+
+ <mat-form-field>
+ <input
+ matInput
+ type="number"
+ i18n-placeholder="
+ Total unknown|How many children have an unknown presence or absence
+ status
+ "
+ placeholder="Total unknown"
+ [value]="entity.countEventsWithUnknownStatus()"
+ readonly
+ />
+ </mat-form-field>
+ </div>
+
+ <app-entities-table
+ [entityType]="EventNote"
+ [records]="entity.events"
+ [customColumns]="eventsColumns"
+ clickMode="none"
+ (entityClick)="showEventDetails($event)"
+ [editable]="false"
+ >
+ </app-entities-table>
+
+ <app-attendance-calendar
+ [records]="entity.events"
+ [highlightForChild]="forChild"
+ [activity]="entity.activity"
+ ></app-attendance-calendar>
+</div>
+
@use "variables/sizes";
+
+/* The indicator is a round, colored shape with a small margin on the right
+it is used as prefix in the form field and for the individual options */
+.indicator {
+ width: sizes.$regular;
+ height: sizes.$regular;
+ border-radius: 50%;
+
+ margin-right: sizes.$small;
+ margin-left: sizes.$small;
+
+ /* when the indicator is used as prefix in a form field
+ it should be center-aligned with the content, but is baseline-aligned
+ without this small margin */
+ &__prefix {
+ margin-bottom: 0.15em;
+ }
+
+ /* when the indicator is used inside the option-field it has `display: inline`
+ which causes the field not to draw correctly */
+ &__option {
+ display: inline-block;
+ vertical-align: middle;
+ margin-bottom: 0.225em;
+ }
+}
+
Only participants who were absent more than this threshold are counted and shown in the dashboard.
+
The default is 1.
+That means if someone was absent two or more days within a specific activity in the given week
+the person will be counted and displayed as a critical case in this dashboard widget.
The offset from the default time period, which is the last complete week.
+
For example:
+If you set the offset of 0, the widget displays attendance for the last completed week (i.e. ending last Saturday).
+If you set the offset to 7 and today is Thursday, the widget displays attendance from the Monday 3 days ago
+(i.e. the current running week).
import { Component, Input, OnInit } from "@angular/core";
+import { Router } from "@angular/router";
+import { AttendanceLogicalStatus } from "../../model/attendance-status";
+import { AttendanceService } from "../../attendance.service";
+import { EventAttendance } from "../../model/event-attendance";
+import { ActivityAttendance } from "../../model/activity-attendance";
+import { RecurringActivity } from "../../model/recurring-activity";
+import moment, { Moment } from "moment";
+import { groupBy } from "../../../../utils/utils";
+import { MatTableModule } from "@angular/material/table";
+import { DynamicComponent } from "../../../../core/config/dynamic-components/dynamic-component.decorator";
+import { NgForOf, NgIf } from "@angular/common";
+import { EntityBlockComponent } from "../../../../core/basic-datatypes/entity/entity-block/entity-block.component";
+import { AttendanceDayBlockComponent } from "./attendance-day-block/attendance-day-block.component";
+import { DashboardWidget } from "../../../../core/dashboard/dashboard-widget/dashboard-widget";
+import { EventNote } from "../../model/event-note";
+import { DashboardListWidgetComponent } from "../../../../core/dashboard/dashboard-list-widget/dashboard-list-widget.component";
+import { EntityRegistry } from "../../../../core/entity/database-entity.decorator";
+
+interface AttendanceWeekRow {
+ childId: string;
+ activity: RecurringActivity;
+ attendanceDays: (EventAttendance | undefined)[];
+}
+
+@DynamicComponent("AttendanceWeekDashboard")
+@Component({
+ selector: "app-attendance-week-dashboard",
+ templateUrl: "./attendance-week-dashboard.component.html",
+ styleUrls: ["./attendance-week-dashboard.component.scss"],
+ standalone: true,
+ imports: [
+ NgIf,
+ MatTableModule,
+ NgForOf,
+ EntityBlockComponent,
+ AttendanceDayBlockComponent,
+ DashboardListWidgetComponent,
+ ],
+})
+export class AttendanceWeekDashboardComponent
+ extends DashboardWidget
+ implements OnInit
+{
+ static override getRequiredEntities() {
+ return EventNote.ENTITY_TYPE;
+ }
+
+ /**
+ * The offset from the default time period, which is the last complete week.
+ *
+ * For example:
+ * If you set the offset of 0, the widget displays attendance for the last completed week (i.e. ending last Saturday).
+ * If you set the offset to 7 and today is Thursday, the widget displays attendance from the Monday 3 days ago
+ * (i.e. the current running week).
+ */
+ @Input() daysOffset = 0;
+
+ /**
+ * description displayed to users for what this widget is analysing
+ * e.g. "Absences this week"
+ */
+ @Input() label: string;
+
+ @Input() periodLabel: string;
+
+ /**
+ * Only participants who were absent more than this threshold are counted and shown in the dashboard.
+ *
+ * The default is 1.
+ * That means if someone was absent two or more days within a specific activity in the given week
+ * the person will be counted and displayed as a critical case in this dashboard widget.
+ */
+ @Input() absentWarningThreshold: number = 1;
+
+ /**
+ * The special attendance status type for which this widget should filter.
+ *
+ * (Optional) If this is not set, all status types that are counted as logically "ABSENT" are considered.
+ */
+ @Input() attendanceStatusType: string;
+
+ entries: AttendanceWeekRow[][];
+
+ constructor(
+ private attendanceService: AttendanceService,
+ private router: Router,
+ private entityRegistry: EntityRegistry,
+ ) {
+ super();
+ }
+
+ ngOnInit() {
+ if (this.periodLabel && !this.label) {
+ this.label = $localize`:Dashboard attendance component subtitle:Absences ${this.periodLabel}`;
+ }
+ return this.loadAttendanceOfAbsentees();
+ }
+
+ private async loadAttendanceOfAbsentees() {
+ const previousMonday = moment()
+ .startOf("isoWeek")
+ .subtract(1, "week")
+ .add(this.daysOffset, "days");
+ const previousSaturday = moment(previousMonday).add(5, "days");
+
+ const activityAttendances =
+ await this.attendanceService.getAllActivityAttendancesForPeriod(
+ previousMonday.toDate(),
+ previousSaturday.toDate(),
+ );
+ const lowAttendanceCases = new Set<string>();
+ const records: AttendanceWeekRow[] = [];
+ for (const att of activityAttendances) {
+ const rows = this.generateRowsFromActivityAttendance(
+ att,
+ moment(previousMonday),
+ moment(previousSaturday),
+ );
+ records.push(...rows);
+
+ rows
+ .filter((r) => this.filterLowAttendance(r))
+ .forEach((r) => lowAttendanceCases.add(r.childId));
+ }
+
+ const groups = groupBy(records, "childId");
+ this.entries = groups
+ .filter(([childId]) => lowAttendanceCases.has(childId))
+ .map(([_, attendance]) => attendance);
+ }
+
+ private generateRowsFromActivityAttendance(
+ att: ActivityAttendance,
+ from: Moment,
+ to: Moment,
+ ): AttendanceWeekRow[] {
+ if (!att.activity) {
+ return [];
+ }
+
+ const results: AttendanceWeekRow[] = [];
+ for (const participant of att.activity.participants) {
+ const eventAttendances = [];
+
+ let day = moment(from);
+ while (day.isSameOrBefore(to, "day")) {
+ const event = att.events.find((e) => day.isSame(e.date, "day"));
+ if (event) {
+ eventAttendances.push(event.getAttendance(participant));
+ } else {
+ // put a "placeholder" into the array for the current day
+ eventAttendances.push(undefined);
+ }
+ day = day.add(1, "day");
+ }
+
+ results.push({
+ childId: participant,
+ activity: att.activity,
+ attendanceDays: eventAttendances,
+ });
+ }
+
+ return results;
+ }
+
+ private filterLowAttendance(row: AttendanceWeekRow): boolean {
+ let countAbsences = 0;
+ if (!this.attendanceStatusType) {
+ countAbsences = row.attendanceDays.filter(
+ (e) => e?.status?.countAs === AttendanceLogicalStatus.ABSENT,
+ ).length;
+ } else {
+ countAbsences = row.attendanceDays.filter(
+ (e) => e?.status?.id === this.attendanceStatusType,
+ ).length;
+ }
+
+ return countAbsences > this.absentWarningThreshold;
+ }
+
+ goToChild(childId: string) {
+ const Child = this.entityRegistry.get("Child");
+ this.router.navigate([Child.route, childId]);
+ }
+}
+
+
+
+
+
<app-dashboard-list-widget
+ icon="exclamation-triangle"
+ theme="attendance"
+ [subtitle]="label"
+ explanation="Cases absent multiple times in the given week"
+ i18n-explanation="Dashboard attendance component explanation tooltip"
+ [entries]="entries"
+>
+ <div class="table-wrapper">
+ <table mat-table i18n-aria-label aria-label="cases absent multiple times">
+ <!-- Table header only for assistive technologies like screen readers -->
+ <tr hidden="true">
+ <th scope="col" i18n="The participant of a group, e.g. a school">
+ Participant
+ </th>
+ <th scope="col" i18n="The attendance of a participant, e.g. a student">
+ Attendance
+ </th>
+ </tr>
+ <ng-container matColumnDef="child">
+ <td
+ *matCellDef="let rowGroup"
+ (click)="goToChild(rowGroup[0].childId)"
+ class="pointer"
+ >
+ <app-entity-block
+ [entityId]="rowGroup[0].childId"
+ entityType="Child"
+ ></app-entity-block>
+ </td>
+ </ng-container>
+
+ <ng-container matColumnDef="attendance">
+ <td *matCellDef="let rowGroup">
+ <div
+ *ngFor="let activityRecord of rowGroup"
+ class="activities-record"
+ >
+ <ng-container *ngFor="let day of activityRecord.attendanceDays">
+ <app-attendance-day-block
+ [attendance]="day"
+ ></app-attendance-day-block>
+ </ng-container>
+ </div>
+ </td>
+ </ng-container>
+
+ <tr mat-row *matRowDef="let row; columns: ['child', 'attendance']"></tr>
+ </table>
+
+ <div
+ *ngIf="entries?.length === 0"
+ i18n="Placeholder if no absences are visible in dashboar"
+ class="headline"
+ >
+ no absences recorded
+ </div>
+ </div>
+</app-dashboard-list-widget>
+
+
+
+
+
+ ./attendance-week-dashboard.component.scss
+
+
@use "../../../../core/dashboard/dashboard-widget-base";
+
+/* Lays out the single day components */
+.activities-record {
+ display: flex;
+ flex-direction: row;
+ gap: 3px;
+ /* puts the whole component to the end */
+ justify-content: flex-end;
+}
+
A dumb component handling presentation of the sync indicator icon
+and an additional details dropdown listing all currently running background processes.
Simple banner to mark a feature as "beta" and inform users of possibly limited functionality.
+
+
+
+
+
+
+
+
Metadata
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
selector
+
app-beta-feature
+
+
+
+
standalone
+
true
+
+
+
+
imports
+
+ MatTooltip
+ MatCard
+ FaIconComponent
+
+
+
+
+
+
+
+
templateUrl
+
./beta-feature.component.html
+
+
+
+
+
+
styleUrl
+
./beta-feature.component.scss
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Component } from "@angular/core";
+import { MatTooltip } from "@angular/material/tooltip";
+import { MatCard } from "@angular/material/card";
+import { FaIconComponent } from "@fortawesome/angular-fontawesome";
+
+/**
+ * Simple banner to mark a feature as "beta" and inform users of possibly limited functionality.
+ */
+@Component({
+ selector: "app-beta-feature",
+ standalone: true,
+ imports: [MatTooltip, MatCard, FaIconComponent],
+ templateUrl: "./beta-feature.component.html",
+ styleUrl: "./beta-feature.component.scss",
+})
+export class BetaFeatureComponent {}
+
+
+
+
+
<mat-card
+ class="banner-container"
+ matTooltip="This feature is overall still under development. You might experience some issues or limited functionality. We appreciate your feedback, please contact our User Support with your problems and suggestions."
+ i18n-matTooltip
+>
+ <fa-icon icon="person-digging"></fa-icon>
+ <span i18n>Beta Feature</span>
+</mat-card>
+
import {
+ Component,
+ ElementRef,
+ Inject,
+ OnInit,
+ ViewChild,
+} from "@angular/core";
+import { Changelog } from "../changelog";
+import { MAT_DIALOG_DATA } from "@angular/material/dialog";
+import { isObservable, Observable } from "rxjs";
+import { LatestChangesService } from "../latest-changes.service";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { MarkdownService } from "ngx-markdown";
+import { MarkedRendererCustom } from "./MarkedRendererCustom";
+
+/**
+ * Display information from the changelog for the latest version.
+ *
+ * This component is used as content of a dialog.
+ */
+@UntilDestroy()
+@Component({
+ templateUrl: "./changelog.component.html",
+ styleUrls: ["./changelog.component.scss"],
+})
+export class ChangelogComponent implements OnInit {
+ /** The array of relevant changelog entries to be displayed */
+ changelogs: Changelog[];
+
+ /** Display advanced information that may not be useful to normal users */
+ showAdvancedDetails = false;
+
+ @ViewChild("changelogContainer") contentContainer: ElementRef;
+
+ /**
+ * This component is to be created through a MatDialog that should pass in the relevant data.
+ *
+ * @example
+ * dialog.open(ChangelogComponent, { data: { changelogData: latestChangesService.getChangelogs() } });
+ */
+ constructor(
+ @Inject(MAT_DIALOG_DATA) public data: Observable<Changelog[]>,
+ private latestChangesService: LatestChangesService,
+ private markdownService: MarkdownService,
+ ) {}
+
+ ngOnInit(): void {
+ if (isObservable(this.data)) {
+ this.data
+ .pipe(untilDestroyed(this))
+ .subscribe((changelog) => (this.changelogs = changelog));
+ }
+
+ this.customizeMarkdownRenderer();
+ }
+
+ get noChangelogAvailable(): string {
+ return $localize`No Changelog Available`;
+ }
+
+ /**
+ * Add one more previous release card to the end of the currently displayed list of changelogs.
+ */
+ loadPreviousRelease() {
+ if (!this.changelogs) {
+ return;
+ }
+
+ const lastDisplayedVersion =
+ this.changelogs[this.changelogs.length - 1]?.tag_name;
+ this.latestChangesService
+ .getChangelogsBeforeVersion(lastDisplayedVersion, 1)
+ .pipe(untilDestroyed(this))
+ .subscribe((additionalChangelog) => {
+ this.changelogs.push(...additionalChangelog);
+
+ setTimeout(() => this.scrollToBottomOfReleases());
+ });
+ }
+
+ private scrollToBottomOfReleases() {
+ this.contentContainer.nativeElement.scrollTop =
+ this.contentContainer.nativeElement.scrollHeight;
+ }
+
+ private customizeMarkdownRenderer() {
+ const customRenderer = new MarkedRendererCustom();
+ this.markdownService.renderer.heading = customRenderer.heading;
+ this.markdownService.renderer.list = customRenderer.list;
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<h1 mat-dialog-title>Latest Changes</h1>
+
+<mat-dialog-content #changelogContainer>
+ <div *ngFor="let changelog of changelogs" class="changelog-entry-container">
+ <h2>{{ changelog?.name || noChangelogAvailable }}</h2>
+ <div class="padding-bottom-regular">
+ <span
+ ><fa-icon icon="calendar-alt"></fa-icon>
+ {{ changelog?.published_at | date }}</span
+ >
+ <span class="padding-left-small"
+ ><fa-icon icon="tag"></fa-icon> {{ changelog?.tag_name }}</span
+ >
+ </div>
+ <markdown [data]="changelog?.body"></markdown>
+ <a
+ *ngIf="showAdvancedDetails"
+ mat-stroked-button
+ [href]="'https://www.github.com'"
+ target="_blank"
+ i18n="Show more information about a change that was made to the app"
+ >
+ More Information
+ </a>
+ </div>
+</mat-dialog-content>
+
+<mat-dialog-actions class="flex-row gap-regular flex-wrap">
+ <button mat-stroked-button (click)="loadPreviousRelease()" i18n>
+ Show previous changes
+ </button>
+ <button
+ mat-raised-button
+ [mat-dialog-close]="true"
+ i18n="Generic close button"
+ class="remove-margin-left"
+ >
+ Close
+ </button>
+</mat-dialog-actions>
+
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
An array of featureIds that the user has already requested during the current session.
+
Users cannot request the same feature twice and see that they have already requested the feature.
+This information is not persisted across sessions however. So after reloading the page this history is gone.
import { Component, Inject, Input, OnInit, Optional } from "@angular/core";
+import { AlertService } from "../../../core/alerts/alert.service";
+import { ActivatedRoute } from "@angular/router";
+import { AnalyticsService } from "../../../core/analytics/analytics.service";
+import { MAT_DIALOG_DATA, MatDialogModule } from "@angular/material/dialog";
+import { DialogCloseComponent } from "../../../core/common-components/dialog-close/dialog-close.component";
+import { MatButtonModule } from "@angular/material/button";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { NgIf } from "@angular/common";
+
+import { RouteTarget } from "../../../route-target";
+
+/**
+ * Placeholder page to announce that a feature is not available yet.
+ *
+ * This integrates with analytics and allows user to explicitly request the feature.
+ */
+@RouteTarget("ComingSoon")
+@Component({
+ selector: "app-coming-soon",
+ templateUrl: "./coming-soon.component.html",
+ styleUrls: ["./coming-soon.component.scss"],
+ imports: [
+ DialogCloseComponent,
+ MatDialogModule,
+ MatButtonModule,
+ FontAwesomeModule,
+ NgIf,
+ ],
+ standalone: true,
+})
+export class ComingSoonComponent implements OnInit {
+ /**
+ * An array of featureIds that the user has already requested during the current session.
+ *
+ * Users cannot request the same feature twice and see that they have already requested the feature.
+ * This information is not persisted across sessions however. So after reloading the page this history is gone.
+ */
+ static featuresRequested = [];
+
+ /**
+ * the identifier for the specific feature this page serves as a placeholder for
+ */
+ @Input() featureId: string;
+
+ /**
+ * whether user has already requested the feature
+ */
+ requested: boolean;
+
+ constructor(
+ private alertService: AlertService,
+ private analyticsService: AnalyticsService,
+ private activatedRoute: ActivatedRoute,
+ @Optional() @Inject(MAT_DIALOG_DATA) dialogData: { featureId: string },
+ ) {
+ if (dialogData) {
+ this.init(dialogData.featureId);
+ }
+ this.activatedRoute.paramMap.subscribe((params) => {
+ if (params.has("feature")) {
+ this.init(params.get("feature"));
+ }
+ });
+ }
+
+ ngOnInit(): void {
+ if (this.featureId) {
+ this.init(this.featureId);
+ }
+ }
+
+ private init(newFeatureId: string) {
+ this.featureId = newFeatureId;
+ this.requested =
+ ComingSoonComponent.featuresRequested.includes(newFeatureId);
+
+ this.track("visit");
+ }
+
+ private track(action: string) {
+ this.analyticsService.eventTrack(this.featureId, {
+ category: "feature_request",
+ label: action,
+ });
+ }
+
+ /**
+ * Report an explicit user request for the feature through the analytics plugin.
+ */
+ reportFeatureRequest() {
+ this.track("request");
+
+ this.requested = true;
+ ComingSoonComponent.featuresRequested.push(this.featureId);
+ this.alertService.addInfo(
+ $localize`:Sent after the user has sent a feature-request:Thank you for letting us know.`,
+ );
+ }
+}
+
+
+
+
+
<app-dialog-close mat-dialog-close></app-dialog-close>
+<mat-dialog-content>
+ <h1 i18n="Coming Soon header">Coming Soon</h1>
+ <h3 i18n="Coming Soon description">
+ Sorry, this feature isn't quite ready yet. We are working hard to make this
+ available for you. Let us know below if you need this functionality.
+ </h3>
+
+ <div class="feedback-section margin-bottom-regular">
+ <button
+ mat-raised-button
+ color="primary"
+ class="full-width"
+ (click)="reportFeatureRequest()"
+ [disabled]="requested"
+ i18n="
+ Feature Button|Indicates that the user needs this feature and can send a
+ feature-request
+ "
+ >
+ <fa-icon *ngIf="requested" aria-label="requested" icon="check"></fa-icon>
+ I need this feature
+ </button>
+
+ <a
+ i18n
+ mat-stroked-button
+ class="full-width"
+ target="_blank"
+ rel="noopener"
+ href="mailto:info@aam-digital.com?subject=Feature-Request%20{{
+ featureId
+ }}"
+ >
+ I can tell you about my use case
+ </a>
+ </div>
+
+ <img src="../../../../assets/canvas-stand.png" alt="" class="illustration" />
+</mat-dialog-content>
+
Apply the given diff, save the resulting new document to the database
+and remove the conflicting document, thereby resolving the conflict.
+
This method is also used to resolve the conflict to keep the conflicting version instead of the current doc.
+Then this simply applies the diff of the existing conflicting version instead of a user-edited diff.
changes the current doc has compared to the conflicting doc.
+
This mirrors diffs but shows the things that would be added if the current doc would
+overwrite the conflicting version instead of the other way round.
import { Component, EventEmitter, Input, OnInit, Output } from "@angular/core";
+import { MatInputModule } from "@angular/material/input";
+import {
+ FormBuilder,
+ FormGroup,
+ FormsModule,
+ ReactiveFormsModule,
+} from "@angular/forms";
+import { MatCheckboxModule } from "@angular/material/checkbox";
+import { EntitySchemaField } from "app/core/entity/schema/entity-schema-field";
+import { FormValidatorConfig } from "app/core/common-components/entity-form/dynamic-form-validators/form-validator-config";
+import { CommonModule } from "@angular/common";
+import { HelpButtonComponent } from "../../../../common-components/help-button/help-button.component";
+
+@Component({
+ selector: "app-configure-entity-field-validator",
+ standalone: true,
+ imports: [
+ MatInputModule,
+ FormsModule,
+ MatCheckboxModule,
+ CommonModule,
+ ReactiveFormsModule,
+ HelpButtonComponent,
+ ],
+ templateUrl: "./configure-entity-field-validator.component.html",
+ styleUrl: "./configure-entity-field-validator.component.scss",
+})
+export class ConfigureEntityFieldValidatorComponent implements OnInit {
+ validatorForm: FormGroup;
+
+ /**
+ * the field definition with the currently existing validator settings to be edited
+ */
+ @Input() entitySchemaField: EntitySchemaField;
+
+ /**
+ * Emit the latest state of the validators config whenever the user changed it in the displayed form.
+ */
+ @Output() entityValidatorChanges = new EventEmitter<FormValidatorConfig>();
+
+ constructor(private fb: FormBuilder) {}
+
+ ngOnInit() {
+ this.init();
+ }
+
+ private init() {
+ if (this.entitySchemaField.validators) {
+ this.validatorForm = this.fb.group({
+ required: [this.entitySchemaField.validators.required],
+ min: [this.entitySchemaField.validators.min],
+ max: [this.entitySchemaField.validators.max],
+ regex: [this.entitySchemaField.validators.pattern],
+ validEmail: [this.entitySchemaField.validators.validEmail],
+ uniqueId: [this.entitySchemaField.validators.uniqueId],
+ });
+ } else {
+ this.validatorForm = this.fb.group({
+ required: [false],
+ min: [null],
+ max: [null],
+ regex: [""],
+ validEmail: [false],
+ uniqueId: [""],
+ });
+ }
+
+ this.validatorForm.valueChanges.subscribe((value) => {
+ const rawValues = this.validatorForm.getRawValue();
+ const cleanedValues =
+ this.removeDefaultValuesFromValidatorConfig(rawValues);
+
+ this.entityValidatorChanges.emit(cleanedValues);
+ });
+ }
+
+ /**
+ * Removes default fields and returns a validator config that only contains explicitly activated validators.
+ * @param validators form values including default values that are unchanged
+ */
+ removeDefaultValuesFromValidatorConfig(
+ validators: FormValidatorConfig,
+ ): FormValidatorConfig {
+ for (let key of Object.keys(validators)) {
+ if (isDefaultValue(validators[key])) {
+ delete validators[key];
+ }
+ }
+
+ function isDefaultValue(value): boolean {
+ return value === false || value === "" || value === null;
+ }
+
+ return validators;
+ }
+}
+
+
+
+
+
<form class="validator-form-cell flex-column" [formGroup]="validatorForm">
+ <ng-container *ngIf="entitySchemaField.dataType === 'number'">
+ <mat-form-field class="number-field">
+ <mat-label i18n>Minimum Value</mat-label>
+ <input formControlName="min" matInput type="number" />
+ </mat-form-field>
+
+ <mat-form-field class="number-field">
+ <mat-label i18n>Maximum Value</mat-label>
+ <input formControlName="max" matInput type="number" />
+ </mat-form-field>
+ </ng-container>
+
+ <!-- TODO: requires transformation of value to { pattern: string, message: string } before saving
+ <mat-form-field *ngIf="entitySchemaField.dataType === 'string'">
+ <mat-label i18n>Pattern (Regex)</mat-label>
+ <input formControlName="regex" matInput />
+ <app-help-button
+ matSuffix
+ text="Define a format (-> regular expression) that text values have to match to be valid."
+ i18n-text
+ ></app-help-button>
+ </mat-form-field>
+ -->
+
+ <div>
+ <mat-checkbox i18n formControlName="required">
+ Required Field
+ </mat-checkbox>
+ <app-help-button
+ text="Users always must provide a value in this field"
+ i18n-text
+ ></app-help-button>
+ </div>
+
+ <div>
+ <mat-checkbox i18n formControlName="uniqueId">
+ Unique ID [experimental]</mat-checkbox
+ >
+ <app-help-button
+ text="Ensures the value is not used as an ID for another existing record already. (Experimental Feature: Does not support advanced edge cases)"
+ i18n-text
+ ></app-help-button>
+ </div>
+
+ <div *ngIf="entitySchemaField.dataType === 'string'">
+ <mat-checkbox i18n formControlName="validEmail">
+ Valid Email Format
+ </mat-checkbox>
+ <app-help-button
+ text="Users must enter a text that can be used as an email."
+ i18n-text
+ ></app-help-button>
+ </div>
+</form>
+
The reference to the dialog this component is displayed within
+
+
+
+
+
+
+
+
+
+
+
+
import { Component, Inject } from "@angular/core";
+import {
+ MAT_DIALOG_DATA,
+ MatDialogModule,
+ MatDialogRef,
+} from "@angular/material/dialog";
+import { DialogCloseComponent } from "../../dialog-close/dialog-close.component";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatButtonModule } from "@angular/material/button";
+
+/**
+ * A configurable confirmation dialog box
+ * used by the {@link ConfirmationDialogService}.
+ */
+@Component({
+ selector: "app-confirmation-dialog",
+ templateUrl: "./confirmation-dialog.component.html",
+ imports: [
+ DialogCloseComponent,
+ NgIf,
+ MatDialogModule,
+ MatButtonModule,
+ NgForOf,
+ ],
+ standalone: true,
+})
+export class ConfirmationDialogComponent {
+ /**
+ * This component is used as a template for MatDialog, created with the required dependencies through that service.
+ * @param dialogRef The reference to the dialog this component is displayed within
+ * @param data The configuration defining what text and buttons will be displayed
+ */
+ constructor(
+ public dialogRef: MatDialogRef<ConfirmationDialogComponent>,
+ @Inject(MAT_DIALOG_DATA) public data: ConfirmationDialogConfig,
+ ) {}
+}
+
+/**
+ * Options to configure the {@link ConfirmationDialogComponent}.
+ */
+export interface ConfirmationDialogConfig {
+ /** title of the dialog box */
+ title: string;
+
+ /** description text in the dialog box */
+ text: string;
+
+ /** The buttons that should be displayed */
+ buttons: ConfirmationDialogButton[];
+
+ /** Whether or not to specify a 'close' icon-button.
+ * This button is on the top-right of the dialog and closes it with no result
+ */
+ closeButton?: boolean;
+}
+
+export interface ConfirmationDialogButton {
+ text: string;
+ dialogResult?: boolean | undefined;
+ click();
+}
+
+export const OkButton: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog OK:OK`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+];
+
+export const YesNoButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+];
+
+export const YesNoCancelButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+ {
+ text: $localize`:Confirmation dialog Cancel:Cancel`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: undefined,
+ },
+];
+
@use "mixins/grid-layout";
+@use "variables/sizes";
+
+/* The minimum size of a widget for big screens */
+/* The minimum size on small screens is whatever size is available */
+$min-widget-width: 330px;
+/* There will only be one column below this screen width, as defined by the media query */
+$max-screen-width: $min-widget-width + sizes.$margin-main-view-right +
+ sizes.$margin-main-view-left;
+$widget-height: 430px;
+
+:host {
+ @include grid-layout.adaptive($min-widget-width, $max-screen-width);
+ /* Make all rows be equal in height */
+ grid-auto-rows: $widget-height;
+}
+
+.grid-item {
+ transition: all 1s;
+}
+
Base dashboard widget to build widgets that display a number of entries as a table.
+
This widget automatically handles loading animation and pagination.
+Define a mat-table with your desired layout for displaying the entries through content-projection
+and provide the data array as an input using async pipe.
array of items to be displayed in paginated widget table.
+you can use an observable with async pipe here to let the component automatically handle "loading" indicator:
+[entries]="myDataObservable | async"
+
Alternatively define an entityType and dataPipe to let the component load data itself.
import { Component, Inject } from "@angular/core";
+import {
+ MAT_DIALOG_DATA,
+ MatDialogModule,
+ MatDialogRef,
+} from "@angular/material/dialog";
+import moment from "moment/moment";
+import { FormControl, ReactiveFormsModule } from "@angular/forms";
+import { ConfirmationDialogService } from "../../../common-components/confirmation-dialog/confirmation-dialog.service";
+import { MappingDialogData } from "../../../import/import-column-mapping/import-column-mapping.component";
+import { MatInputModule } from "@angular/material/input";
+import { DatePipe, NgClass, NgForOf, NgIf } from "@angular/common";
+import { MatListModule } from "@angular/material/list";
+import { MatButtonModule } from "@angular/material/button";
+import { HelpButtonComponent } from "../../../common-components/help-button/help-button.component";
+import { DynamicComponent } from "../../../config/dynamic-components/dynamic-component.decorator";
+
+/**
+ * Configuration dialog for parsing date value of data imported from a file.
+ */
+@DynamicComponent("DateImportConfig")
+@Component({
+ selector: "app-date-import-config",
+ templateUrl: "./date-import-config.component.html",
+ styleUrls: ["./date-import-config.component.scss"],
+ standalone: true,
+ imports: [
+ MatDialogModule,
+ MatInputModule,
+ ReactiveFormsModule,
+ NgIf,
+ MatListModule,
+ NgForOf,
+ NgClass,
+ DatePipe,
+ MatButtonModule,
+ HelpButtonComponent,
+ ],
+})
+export class DateImportConfigComponent {
+ format = new FormControl("");
+ valid = false;
+ values: { value: string; parsed?: Date }[] = [];
+
+ constructor(
+ @Inject(MAT_DIALOG_DATA) public data: MappingDialogData,
+ private confirmation: ConfirmationDialogService,
+ private dialog: MatDialogRef<any>,
+ ) {
+ this.values = this.data.values
+ .filter((val) => !!val)
+ .map((value) => ({ value }));
+ this.format.valueChanges.subscribe(() => this.checkDateValues());
+ this.format.setValue(this.data.col.additional);
+ }
+
+ checkDateValues() {
+ this.format.setErrors(undefined);
+ this.values.forEach((val) => {
+ // TODO: check and improve the date parsing. Tests fail with moment.js > 2.29
+ const date = moment(val.value, this.format.value?.toUpperCase(), true);
+ if (date.isValid()) {
+ val.parsed = date.toDate();
+ } else {
+ delete val.parsed;
+ this.format.setErrors({ parsingError: true });
+ }
+ });
+ // Sort unparsed dates to front
+ this.values.sort((v1, v2) =>
+ v1.parsed && !v2.parsed ? 1 : !v1.parsed && v2.parsed ? -1 : 0,
+ );
+ }
+
+ async save() {
+ const confirmed =
+ !this.format.errors ||
+ (await this.confirmation.getConfirmation(
+ $localize`Ignore values?`,
+ $localize`Some values don't have a mapping and will not be imported. Are you sure you want to keep it like this?`,
+ ));
+ if (confirmed) {
+ this.data.col.additional = this.format.value?.toUpperCase();
+ this.dialog.close();
+ }
+ }
+}
+
+
+
+
+
<mat-dialog-content>
+ <mat-form-field>
+ <mat-label i18n>Date format</mat-label>
+ <input [formControl]="format" matInput />
+ <mat-hint i18n>
+ e.g. YYYY-MM-DD
+ <a
+ href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format"
+ target="_blank"
+ rel="noopener"
+ >(help)</a
+ >
+ </mat-hint>
+ <mat-error *ngIf="format.errors" i18n>
+ Format cannot parse all dates
+ </mat-error>
+ </mat-form-field>
+
+ <app-help-button
+ text="Define how date values in your imported data are formatted, so that the system correctly understands them. Values that do not match the given format will be ignored (remain empty) during import."
+ i18n-text="import - value mapping (date) - help text"
+ ></app-help-button>
+
+ <mat-list>
+ <mat-list-item
+ *ngFor="let val of values"
+ [ngClass]="{ invalid: !val.parsed }"
+ >
+ {{ val.value }} -> {{ val.parsed | date }}
+ </mat-list-item>
+ </mat-list>
+</mat-dialog-content>
+
+<mat-dialog-actions>
+ <button mat-raised-button color="accent" (click)="save()" i18n>
+ Save & Close
+ </button>
+ <button mat-stroked-button matDialogClose i18n>Cancel</button>
+</mat-dialog-actions>
+
<mat-dialog-content>
+ <p i18n>Generating sample data for this demo ...</p>
+ <mat-progress-bar mode="indeterminate"></mat-progress-bar>
+</mat-dialog-content>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Component } from "@angular/core";
+
+/**
+ * Loading box during demo data generation.
+ *
+ * see {@link DemoDataModule}
+ */
+@Component({
+ template: `
+ <mat-dialog-content>
+ <p i18n>Generating sample data for this demo ...</p>
+ <mat-progress-bar mode="indeterminate"></mat-progress-bar>
+ </mat-dialog-content>
+ `,
+})
+export class DemoDataGeneratingProgressDialogComponent {}
+
Wrapper component for a modal/dialog view
+that takes parameters from the dialog data and passes these on to normal @Input properties.
+
This allows to develop functional feature components in a way to easily reuse them for display
+as a full page view or in a modal dialog.
+(also see RoutedViewComponent)
This component is used to display a tooltip when a element is elementDisabled.
+Normally, tooltips are not shown on elementDisabled elements, therefore this component creates the tooltip on a wrapping
+div.
A component which displays the age of an entity with a DateOfBirth property.
+The name of the property where the DateOfBirth is defined has to be passed as config.
+e.g. show age of a child
indicating that the value is not in its original state, so that components can explain this to the user
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Component, OnInit } from "@angular/core";
+import { ViewDirective } from "../../../entity/default-datatype/view.directive";
+import { DynamicComponent } from "../../../config/dynamic-components/dynamic-component.decorator";
+import { DateWithAge } from "../dateWithAge";
+
+/**
+ * A component which displays the age of an entity with a DateOfBirth property.
+ * The name of the property where the DateOfBirth is defined has to be passed as config.
+ * e.g. show age of a child
+ * ```json
+ * {
+ * "id": "age",
+ * "label": "Age",
+ * "viewComponent": "DisplayAge",
+ * "config": "dateOfBirth"
+ * }
+ * ```
+ */
+@DynamicComponent("DisplayAge")
+@Component({
+ selector: "app-display-age",
+ template: "{{ date?.age }}",
+ standalone: true,
+})
+export class DisplayAgeComponent
+ extends ViewDirective<any, string>
+ implements OnInit
+{
+ date: DateWithAge;
+
+ ngOnInit() {
+ this.date = this.entity[this.config];
+ }
+}
+
dynamically calculate the value based on configured entity fields.
+This is defined as a function to re-calculate on every change detection cycle as the value remains outdated otherwise.
indicating that the value is not in its original state, so that components can explain this to the user
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Component } from "@angular/core";
+import { ViewDirective } from "../../../entity/default-datatype/view.directive";
+import { DynamicComponent } from "../../../config/dynamic-components/dynamic-component.decorator";
+
+/**
+ * This component allows to display a boolean attribute of an entity.
+ * It will display a checkmark when the attribute is true.
+ */
+@DynamicComponent("DisplayCheckmark")
+@Component({
+ selector: "app-display-tick",
+ template: `{{ value ? "✓" : "" }}`,
+ standalone: true,
+})
+export class DisplayCheckmarkComponent extends ViewDirective<boolean> {}
+
/* Inherit the styles from the surrounding component. Otherwise the img is overflowing.
+Remove padding and margin so they are not applied a second time. */
+img {
+ all: inherit;
+ padding: 0;
+ margin: 0;
+}
+
indicating that the value is not in its original state, so that components can explain this to the user
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Component, HostBinding, OnInit } from "@angular/core";
+import { ViewDirective } from "../../../entity/default-datatype/view.directive";
+import { DynamicComponent } from "../../../config/dynamic-components/dynamic-component.decorator";
+import { CommonModule } from "@angular/common";
+
+@DynamicComponent("DisplayPercentage")
+@Component({
+ selector: "app-display-percentage",
+ template:
+ "{{ value !== undefined ? (value | number : numberFormat) + '%' : '-' }}",
+ standalone: true,
+ imports: [CommonModule],
+})
+export class DisplayPercentageComponent
+ extends ViewDirective<number, { decimalPlaces?: number }>
+ implements OnInit
+{
+ @HostBinding("style") style = {};
+ numberFormat: string;
+
+ /**
+ * returns a css-compatible color value from green to red using the given
+ * input value
+ * @param percent The percentage from 0-100 (both inclusive). 0 will be completely red, 100 will be completely green
+ * Everything between will have suitable colors (orange, yellow,...)
+ * If the color is NaN, the color will be a light grey
+ */
+ private static fromPercent(percent: number): string {
+ if (Number.isNaN(percent)) {
+ return "rgba(130,130,130,0.4)";
+ }
+ // the hsv color-value is to be between 0 (red) and 120 (green)
+ // percent is between 0-100, so we have to normalize it first
+ const color = (percent / 100) * 120;
+ return "hsl(" + color + ", 100%, 85%)";
+ }
+
+ ngOnInit() {
+ this.numberFormat =
+ "1." +
+ (this.config && this.config.decimalPlaces
+ ? this.config.decimalPlaces + "-" + this.config.decimalPlaces
+ : "0-0");
+ this.style = {
+ "background-color": DisplayPercentageComponent.fromPercent(this.value),
+ "border-radius": "5%",
+ padding: "5px",
+ width: "min-content",
+ };
+ }
+}
+
Wrapper of LocationInput for use as an EditComponent.
+(this should become obsolete after we refactor all EditComponents to be implemented as FormControls)
<div mat-dialog-title style="display: flex">
+ <mat-form-field class="title-field margin-top-small">
+ <input
+ [formControl]="title"
+ matInput
+ type="text"
+ i18n-placeholder="
+ Title Progress|Edit the progress of one or multiple tasks
+ "
+ placeholder="Title"
+ />
+ <mat-error *ngIf="title.hasError('required')" i18n>
+ This field is required
+ </mat-error>
+ </mat-form-field>
+
+ <app-dialog-close mat-dialog-close></app-dialog-close>
+</div>
+
+<mat-dialog-content class="dialog-content">
+ <div
+ *ngFor="let control of parts.controls; let index = index"
+ class="entry-wrapper mat-elevation-z1"
+ [formGroup]="$any(control)"
+ >
+ <mat-form-field class="header-field">
+ <input
+ formControlName="label"
+ matInput
+ type="text"
+ i18n-placeholder="Process Label|The label of a process or task"
+ placeholder="Task"
+ />
+ <mat-error *ngIf="control.hasError('required', 'label')" i18n>
+ This field is required
+ </mat-error>
+ </mat-form-field>
+
+ <button mat-icon-button color="accent" (click)="removePart(index)">
+ <fa-icon
+ class="button-icon"
+ aria-label="remove element"
+ icon="trash"
+ ></fa-icon>
+ </button>
+
+ <mat-form-field class="current-field">
+ <input
+ formControlName="currentValue"
+ matInput
+ type="number"
+ i18n-placeholder="
+ Current process|The Current value of a process or task
+ "
+ placeholder="Current"
+ [errorStateMatcher]="currentErrorStateMatcher"
+ />
+ <mat-error *ngIf="control.hasError('required', 'currentValue')" i18n>
+ This field is required
+ </mat-error>
+ <mat-error *ngIf="control.hasError('min', 'currentValue')" i18n>
+ Must be greater than 0
+ </mat-error>
+ <mat-error
+ *ngIf="control.hasError('currentGtTarget')"
+ i18n="
+ The number entered in this form is less than another field but should
+ not be
+ "
+ >
+ Must not be greater than target
+ </mat-error>
+ </mat-form-field>
+
+ <mat-form-field class="target-field">
+ <input
+ formControlName="targetValue"
+ matInput
+ type="number"
+ i18n-placeholder="Target process|The target amount of a process"
+ placeholder="Target"
+ />
+ <mat-error
+ *ngIf="control.hasError('required', 'targetValue')"
+ i18n="A field entered in a form is required and wasn't provided"
+ >
+ This field is required
+ </mat-error>
+ <mat-error
+ *ngIf="control.hasError('min', 'targetValue')"
+ i18n="A field entered in a form must be greater than 0"
+ >
+ Must be greater than 0
+ </mat-error>
+ </mat-form-field>
+ </div>
+
+ <div>
+ <button mat-button color="accent" (click)="addPart()">
+ <fa-icon
+ class="button-icon margin-sides-small"
+ aria-label="add element"
+ icon="plus-circle"
+ ></fa-icon>
+ <span i18n="Add a task to the progress dashboard list">
+ Add New Task
+ </span>
+ </button>
+ </div>
+</mat-dialog-content>
+<mat-dialog-actions>
+ <button
+ mat-raised-button
+ color="accent"
+ [mat-dialog-close]="outputData.value"
+ [disabled]="outputData.invalid"
+ >
+ <span
+ matTooltip="Fix the errors to save the form"
+ [matTooltipDisabled]="outputData.valid"
+ i18n-matTooltip="Shown when there are errors that prevent saving"
+ i18n
+ >Save</span
+ >
+ </button>
+ <button mat-stroked-button mat-dialog-close i18n>Cancel</button>
+</mat-dialog-actions>
+
This component creates a normal text input with autocomplete.
+Compared to the EditEntityComponent this does not just assign the ID to the form control
+but instead completely overwrites the form with the values taken from the selected entity.
+This is especially useful when instead of creating a new entity, an existing one can also be selected (and extended).
+
When a value is already present the autocomplete is disabled, and it works like a normal text input.
outputs an event containing an array of currently selected records (checkmarked by the user)
+Checkboxes to select rows are only displayed if you set "selectable" also.
whether the "delete" action will trigger a navigation back to the parent list.
+This is useful when the entity is deleted from a fullscreen detail view but not for an overlay.
import { Component, Input } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { MatCardModule } from "@angular/material/card";
+import { MatButtonModule } from "@angular/material/button";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { Entity } from "../../entity/model/entity";
+import { EntityActionsService } from "../../entity/entity-actions/entity-actions.service";
+
+/**
+ * Informs users that the entity is inactive (or anonymized) and provides options to change the status.
+ */
+@Component({
+ selector: "app-entity-archived-info",
+ standalone: true,
+ imports: [CommonModule, MatCardModule, MatButtonModule, FontAwesomeModule],
+ templateUrl: "./entity-archived-info.component.html",
+ styleUrls: ["./entity-archived-info.component.scss"],
+})
+export class EntityArchivedInfoComponent {
+ @Input() entity: Entity;
+
+ constructor(public entityActionsService: EntityActionsService) {}
+}
+
+
+
+
+
<mat-card appearance="outlined" class="card" *ngIf="entity && !entity.isActive">
+ <mat-card-header class="card-header">
+ <div mat-card-avatar class="card-icon">
+ <fa-icon icon="info-circle" size="lg"></fa-icon>
+ </div>
+ <mat-card-title *ngIf="!entity.anonymized" i18n>Archived</mat-card-title>
+ <mat-card-title *ngIf="entity.anonymized" i18n
+ >Anonymized & Archived</mat-card-title
+ >
+ </mat-card-header>
+
+ <mat-card-content>
+ <p *ngIf="entity.anonymized" i18n>
+ This record has been anonymized. Details containing personal information
+ have been deleted and cannot be restored. For statistical reporting, this
+ basic record has been kept.
+ </p>
+
+ <p i18n>
+ This record is archived and will be hidden from lists and select options
+ by default.
+ </p>
+ </mat-card-content>
+
+ <mat-card-actions *ngIf="!entity.anonymized">
+ <button
+ mat-stroked-button
+ color="accent"
+ (click)="entityActionsService.undoArchive(entity)"
+ >
+ Reactivate
+ </button>
+ </mat-card-actions>
+</mat-card>
+
if the groupBy field is an entity reference this holds the related entity type,
+so that the entity block will be displayed instead of an id string,
+otherwise undefined, to display simply the group label.
import { Component, EventEmitter, Input, Output } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { DisableEntityOperationDirective } from "../../permissions/permission-directive/disable-entity-operation.directive";
+import { FaIconComponent } from "@fortawesome/angular-fontawesome";
+import { MatButtonModule } from "@angular/material/button";
+import { MatTableModule } from "@angular/material/table";
+import { Entity, EntityConstructor } from "../../entity/model/entity";
+import { Angulartics2OnModule } from "angulartics2";
+import { MatTooltipModule } from "@angular/material/tooltip";
+
+@Component({
+ selector: "app-entity-create-button",
+ standalone: true,
+ imports: [
+ CommonModule,
+ DisableEntityOperationDirective,
+ FaIconComponent,
+ MatButtonModule,
+ MatTableModule,
+ Angulartics2OnModule,
+ MatTooltipModule,
+ ],
+ templateUrl: "./entity-create-button.component.html",
+ styleUrl: "./entity-create-button.component.scss",
+})
+export class EntityCreateButtonComponent<T extends Entity = Entity> {
+ @Input() entityType: EntityConstructor<T>;
+
+ /**
+ * Optional factory method to create a new entity instance with some default values.
+ * If not provided, the simple entityType constructor is used.
+ */
+ @Input() newRecordFactory?: () => T;
+
+ /**
+ * Emits a new entity instance when the user clicks the button.
+ */
+ @Output() entityCreate = new EventEmitter<T>();
+
+ /**
+ * Whether only an icon button without text should be displayed.
+ * Default is false
+ */
+ @Input() iconOnly: boolean = false;
+
+ /**
+ * Create a new entity.
+ * The entity is only written to the database when the user saves this record which is newly added in edit mode.
+ */
+ create() {
+ const newRecord = this.newRecordFactory
+ ? this.newRecordFactory()
+ : new this.entityType();
+ this.entityCreate.emit(newRecord);
+ }
+}
+
This component can be used to display an entity in more detail.
+It groups subcomponents in panels.
+Any component that is registered (has the DynamicComponent decorator) can be used as a subcomponent.
+The subcomponents will be provided with the Entity object and the creating new status, as well as its static config.
Generic component to display the label of one form field of an entity
+without having to handle overwriting the field config with potentially missing schema field details.
A general purpose form component for displaying and editing entities.
+It uses the FormFieldConfig interface for building the form fields but missing information are also fetched from
+the entity's schema definitions. Properties with sufficient schema information can be displayed by only providing
+the name of this property (and not an FormFieldConfig object).
+
This component can be used directly or in a popup.
+Inside the entity details component use the FormComponent which is registered as dynamic component.
Whether the component should use a grid layout or just rows
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import {
+ Component,
+ Input,
+ OnChanges,
+ SimpleChanges,
+ ViewEncapsulation,
+} from "@angular/core";
+import { Entity } from "../../../entity/model/entity";
+import { EntityForm } from "../entity-form.service";
+import { EntityMapperService } from "../../../entity/entity-mapper/entity-mapper.service";
+import { filter } from "rxjs/operators";
+import { ConfirmationDialogService } from "../../confirmation-dialog/confirmation-dialog.service";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { NgClass, NgForOf, NgIf } from "@angular/common";
+import { Subscription } from "rxjs";
+import moment from "moment";
+import { EntityFieldEditComponent } from "../../entity-field-edit/entity-field-edit.component";
+import { FieldGroup } from "../../../entity-details/form/field-group";
+import { EntityAbility } from "../../../permissions/ability/entity-ability";
+
+/**
+ * A general purpose form component for displaying and editing entities.
+ * It uses the FormFieldConfig interface for building the form fields but missing information are also fetched from
+ * the entity's schema definitions. Properties with sufficient schema information can be displayed by only providing
+ * the name of this property (and not an FormFieldConfig object).
+ *
+ * This component can be used directly or in a popup.
+ * Inside the entity details component use the FormComponent which is registered as dynamic component.
+ */
+@UntilDestroy()
+@Component({
+ selector: "app-entity-form",
+ templateUrl: "./entity-form.component.html",
+ styleUrls: ["./entity-form.component.scss"],
+ // Use no encapsulation because we want to change the value of children (the mat-form-fields that are
+ // dynamically created)
+ encapsulation: ViewEncapsulation.None,
+ imports: [NgForOf, NgIf, NgClass, EntityFieldEditComponent],
+ standalone: true,
+})
+export class EntityFormComponent<T extends Entity = Entity>
+ implements OnChanges
+{
+ /**
+ * The entity which should be displayed and edited
+ */
+ @Input() entity: T;
+
+ @Input() fieldGroups: FieldGroup[];
+
+ @Input() form: EntityForm<T>;
+
+ /**
+ * Whether the component should use a grid layout or just rows
+ */
+ @Input() gridLayout = true;
+
+ private initialFormValues: any;
+ private changesSubscription: Subscription;
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private confirmationDialog: ConfirmationDialogService,
+ private ability: EntityAbility,
+ ) {}
+
+ ngOnChanges(changes: SimpleChanges) {
+ if (this.fieldGroups) {
+ this.fieldGroups = this.filterFieldGroupsByPermissions(
+ this.fieldGroups,
+ this.entity,
+ );
+ }
+
+ if (changes.entity && this.entity) {
+ this.changesSubscription?.unsubscribe();
+ this.changesSubscription = this.entityMapper
+ .receiveUpdates(this.entity.getConstructor())
+ .pipe(
+ filter(({ entity }) => entity.getId() === this.entity.getId()),
+ filter(({ type }) => type !== "remove"),
+ untilDestroyed(this),
+ )
+ .subscribe(({ entity }) => this.applyChanges(entity));
+ }
+
+ if (changes.form && this.form) {
+ this.initialFormValues = this.form.formGroup.getRawValue();
+ this.disableForLockedEntity();
+ }
+ }
+
+ private async applyChanges(externallyUpdatedEntity: T) {
+ if (this.formIsUpToDate(externallyUpdatedEntity)) {
+ Object.assign(this.entity, externallyUpdatedEntity);
+ return;
+ }
+
+ const userEditedFields = Object.entries(
+ this.form.formGroup.getRawValue(),
+ ).filter(([key]) => this.form.formGroup.controls[key].dirty);
+ let userEditsWithoutConflicts = userEditedFields.filter(([key]) =>
+ // no conflict with updated values
+ this.entityEqualsFormValue(
+ externallyUpdatedEntity[key],
+ this.initialFormValues[key],
+ ),
+ );
+ if (
+ userEditsWithoutConflicts.length !== userEditedFields.length &&
+ !(await this.confirmationDialog.getConfirmation(
+ $localize`Load changes?`,
+ $localize`Local changes are in conflict with updated values synced from the server. Do you want the local changes to be overwritten with the latest values?`,
+ ))
+ ) {
+ // user "resolved" conflicts by confirming to overwrite
+ userEditsWithoutConflicts = userEditedFields;
+ }
+
+ // apply update to all pristine (not user-edited) fields and update base entity (to avoid conflicts when saving)
+ Object.assign(this.entity, externallyUpdatedEntity);
+ Object.assign(this.initialFormValues, externallyUpdatedEntity);
+ this.form.formGroup.reset(externallyUpdatedEntity as any);
+
+ // re-apply user-edited fields
+ userEditsWithoutConflicts.forEach(([key, value]) => {
+ this.form.formGroup.get(key).setValue(value);
+ this.form.formGroup.get(key).markAsDirty();
+ });
+ }
+
+ private formIsUpToDate(entity: T): boolean {
+ return Object.entries(this.form.formGroup.getRawValue()).every(
+ ([key, value]) => this.entityEqualsFormValue(entity[key], value),
+ );
+ }
+
+ private filterFieldGroupsByPermissions<T extends Entity = Entity>(
+ fieldGroups: FieldGroup[],
+ entity: Entity,
+ ): FieldGroup[] {
+ const action = entity.isNew ? "create" : "read";
+
+ return fieldGroups
+ .map((group) => {
+ group.fields = group.fields.filter((field) =>
+ this.ability.can(
+ action,
+ entity,
+ typeof field === "string" ? field : field.id,
+ ),
+ );
+ return group;
+ })
+ .filter((group) => group.fields.length > 0);
+ }
+
+ private entityEqualsFormValue(entityValue, formValue) {
+ return (
+ (entityValue instanceof Date &&
+ moment(entityValue).isSame(formValue, "day")) ||
+ (entityValue === undefined && formValue === null) ||
+ entityValue === formValue ||
+ JSON.stringify(entityValue) === JSON.stringify(formValue)
+ );
+ }
+
+ /**
+ * Disable the form for certain states of the entity, like it being already anonymized.
+ * @private
+ */
+ private disableForLockedEntity() {
+ if (this.entity?.anonymized) {
+ this.form.formGroup.disable();
+ }
+ }
+}
+
+
+
+
+
<form [ngClass]="{ 'grid-layout': gridLayout }">
+ <div *ngFor="let group of fieldGroups" class="entity-form-cell">
+ <h2 *ngIf="group.header">{{ group.header }}</h2>
+ <div *ngFor="let field of group.fields">
+ <app-entity-field-edit
+ [field]="field"
+ [entity]="entity"
+ [form]="form"
+ ></app-entity-field-edit>
+ </div>
+ </div>
+</form>
+
+
+
+
+
+ ./entity-form.component.scss
+
+
@use "mixins/grid-layout";
+@use "variables/sizes";
+
+.grid-layout {
+ @include grid-layout.adaptive(
+ $min-block-width: sizes.$form-group-min-width,
+ $max-screen-width: 414px
+ );
+}
+
+.entity-form-cell {
+ display: flex;
+ flex-direction: column;
+
+ /* set the width of each form field to 100% in every form component that is a descendent
+ of the columns-wrapper class */
+ mat-form-field {
+ width: 100%;
+ }
+
+ /* We align the photo (and only tht photo) to the center of the cell if there is one.
+ This looks better on desktop and mobile compared to an alignment to the start of the cell
+ which is the default for all other elements */
+ > app-edit-photo {
+ align-self: center;
+ }
+}
+
This component allows to create a full-blown table with pagination, filtering, searching and grouping.
+The filter and grouping settings are written into the URL params to allow going back to the previous view.
+The pagination settings are stored for each user.
+The columns can be any kind of component.
+The column components will be provided with the Entity object, the id for this column, as well as its static config.
+
The component can be either used inside a template, or directly in a route through the config object.
defines the bottom margin of the topmost row in the
+desktop version. This has to be bigger when there are
+several column groups since there are
+tabs with zero top-padding in this case
@use "../../../../styles/variables/breakpoints";
+@use "variables/sizes";
+@use "variables/colors";
+
+/**
+ * Aligns the baseline of the filter-field with the baseline
+ * of the other controls.
+ * This only has to be done on the desktop
+ */
+.filter-field {
+ @media screen and (min-width: breakpoints.$md) {
+ /* restricts the width so that the field does not feel too big */
+ max-width: 412px;
+ }
+}
+
+.bulk-action-button {
+ right: sizes.$large;
+
+ padding: sizes.$regular;
+ background-color: colors.$background;
+}
+
The accessor used for filtering and when selecting a new
+entity.
+ Per default, this filters for the name. If the entity
+has no name, this filters for the entity's id.
The placeholder is what is seen when someone clicks into the input-
+field and adds new entities.
+In the note-details-view, this is "Add children..."
+The placeholder is only displayed if loading === false
Whether to show entities in the list.
+Entities can still be selected using the autocomplete,
+and selection as well as selectionChange will
+still work as expected
Recalculates the number of inactive entities that match the current filter,
+and optionally updates the current filter function (otherwise reuses the filter previously set)
true when this is loading and false when it's ready.
+This subject's state reflects the actual loading resp. the 'readiness'-
+state of this component. Will trigger once loading is done
+
+
+
+
+
+
+
+
+
+
+
+
+ Readonly
+ loadingPlaceholder
+
+
+
+
+
+
+ Default value : $localize`:A placeholder for the input element when select options are not loaded yet:loading...`
+
The entity-type (e.g. 'Child', 'School', e.t.c.) to set.
+ that displays the entities. Can be an array giving multiple types.
+
+
+
+ Parameters :
+
+
+
+
Name
+
Type
+
Optional
+
Description
+
+
+
+
+
type
+
+
+ string | string[]
+
+
+
+ No
+
+
+
+
The ENTITY_TYPE of a Entity. This affects the entities which will be loaded and the component
+that displays the entities. Can be an array giving multiple types.
This component can be used to display dynamic Font-Awesome icons.
+The term 'dynamic icons' refers to icons that are injected at runtime,
+for example through the config.
Sets the dynamic icon by name.
+You should make sure that the icon is registered inside the iconAliases-map,
+or put it into this map if it isn't there.
+
+If for some reason the icon is not inside the map or cannot be inserted into the map,
+the icon name has to match the exact icon name as provided by font-awesome.
+A prefix can be specified using the syntax "", for example
+"far address-book". The default prefix, if not specified, is "fas"
+(font-awesome solid icons)
+
+In case the provided icon still doesn't exist, a question-mark-icon with circle
+(see fallbackIcon) will be shown.
+
+Note that there is no getter, and you should not attempt to get the icon name, for example via
+_icon#iconName since it is not guaranteed to be the same as the provided name
Sets the dynamic icon by name.
+You should make sure that the icon is registered inside the iconAliases-map,
+or put it into this map if it isn't there.
+
+If for some reason the icon is not inside the map or cannot be inserted into the map,
+the icon name has to match the exact icon name as provided by font-awesome.
+A prefix can be specified using the syntax "", for example
+"far address-book". The default prefix, if not specified, is "fas"
+(font-awesome solid icons)
+
+In case the provided icon still doesn't exist, a question-mark-icon with circle
+(see fallbackIcon) will be shown.
+
+Note that there is no getter, and you should not attempt to get the icon name, for example via
+_icon#iconName since it is not guaranteed to be the same as the provided name
import { ChangeDetectionStrategy, Component, Input } from "@angular/core";
+import { IconName, IconPrefix } from "@fortawesome/fontawesome-svg-core";
+import {
+ faCalendarAlt,
+ faCalendarCheck,
+ faChartLine,
+ faFileAlt,
+ faQuestionCircle,
+ faUsers,
+} from "@fortawesome/free-solid-svg-icons";
+import {
+ FaIconLibrary,
+ FontAwesomeModule,
+ IconDefinition,
+} from "@fortawesome/angular-fontawesome";
+import { Logging } from "../../logging/logging.service";
+import { NgIf } from "@angular/common";
+
+/**
+ * A map to prevent old configs to be broken
+ */
+const iconAliases = new Map<string, IconDefinition>([
+ ["calendar-check-o", faCalendarCheck],
+ ["file-text", faFileAlt],
+ ["question", faQuestionCircle],
+ ["line-chart", faChartLine],
+ ["calendar", faCalendarAlt],
+ ["users", faUsers],
+]);
+
+/**
+ * This component can be used to display dynamic Font-Awesome icons.
+ * The term 'dynamic icons' refers to icons that are injected at runtime,
+ * for example through the config.
+ */
+@Component({
+ selector: "app-fa-dynamic-icon",
+ template: ` <fa-icon *ngIf="_icon" [icon]="_icon"></fa-icon>`,
+ imports: [FontAwesomeModule, NgIf],
+ standalone: true,
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class FaDynamicIconComponent {
+ /** The fallback icon if the given icon is neither known (inside the internal map)
+ * nor registered as a font-awesome icon
+ */
+ static fallbackIcon = faQuestionCircle;
+
+ /**
+ * Sets the dynamic icon by name.
+ * You should make sure that the icon is registered inside the {@link iconAliases}-map,
+ * or put it into this map if it isn't there.
+ * <br>
+ * If for some reason the icon is not inside the map or cannot be inserted into the map,
+ * the icon name has to match the <em>exact</em> icon name as provided by font-awesome.
+ * A prefix can be specified using the syntax "<prefix> <icon-name>", for example
+ * "far address-book". The default prefix, if not specified, is "fas"
+ * (font-awesome solid icons)
+ * <br>
+ * In case the provided icon still doesn't exist, a question-mark-icon with circle
+ * (see {@link fallbackIcon}) will be shown.
+ * <br>
+ * Note that there is no getter, and you should not attempt to get the icon name, for example via
+ * {@link _icon#iconName} since it is not guaranteed to be the same as the provided name
+ * @param icon the icon name
+ */
+ @Input() set icon(icon: string) {
+ if (!icon) {
+ this._icon = undefined;
+ return;
+ }
+ let definition = iconAliases.get(icon);
+ if (!definition && icon) {
+ const iconAndDef = icon.split(" ");
+ if (iconAndDef.length === 1) {
+ definition = this.iconLibrary.getIconDefinition(
+ "fas",
+ icon as IconName,
+ );
+ } else {
+ definition = this.iconLibrary.getIconDefinition(
+ iconAndDef[0] as IconPrefix,
+ iconAndDef[1] as IconName,
+ );
+ }
+ // Fallback if the icon is not available: search through the icon definitions
+ }
+ if (!definition) {
+ // Fallback if the icon is neither in the map nor a registered icon
+ definition = FaDynamicIconComponent.fallbackIcon;
+ Logging.warn(
+ `Tried to set icon "${icon}" but it does not exist as a font awesome regular item nor is it registered as an alias.`,
+ );
+ }
+ this._icon = definition;
+ }
+
+ /**
+ * The font-awesome internal icon definition
+ */
+ _icon: IconDefinition;
+
+ constructor(private iconLibrary: FaIconLibrary) {}
+}
+
import { Component, Input } from "@angular/core";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { MatButtonModule } from "@angular/material/button";
+import { NgIf } from "@angular/common";
+import { MatTooltipModule } from "@angular/material/tooltip";
+
+/**
+ * Display a help button that shows the user additional guidance and explanations when necessary
+ * as the user clicks on it.
+ */
+@Component({
+ selector: "app-help-button",
+ templateUrl: "./help-button.component.html",
+ styleUrls: ["./help-button.component.scss"],
+ standalone: true,
+ imports: [FontAwesomeModule, MatButtonModule, NgIf, MatTooltipModule],
+})
+export class HelpButtonComponent {
+ /**
+ * Help text to be displayed
+ */
+ @Input() text: string;
+}
+
import {
+ Component,
+ EventEmitter,
+ Input,
+ OnChanges,
+ Output,
+ SimpleChanges,
+} from "@angular/core";
+import { ColumnMapping } from "../column-mapping";
+import { EntityRegistry } from "../../entity/database-entity.decorator";
+import { EntityConstructor } from "../../entity/model/entity";
+import { MatDialog } from "@angular/material/dialog";
+import { HelpButtonComponent } from "../../common-components/help-button/help-button.component";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatInputModule } from "@angular/material/input";
+import { BasicAutocompleteComponent } from "../../common-components/basic-autocomplete/basic-autocomplete.component";
+import { FormsModule } from "@angular/forms";
+import { MatButtonModule } from "@angular/material/button";
+import { MatBadgeModule } from "@angular/material/badge";
+import { EntitySchemaService } from "../../entity/schema/entity-schema.service";
+import { ComponentRegistry } from "../../../dynamic-components";
+import { DefaultDatatype } from "../../entity/default-datatype/default.datatype";
+import { ImportColumnMappingService } from "./import-column-mapping.service";
+
+/**
+ * Import sub-step: Let user map columns from import data to entity properties
+ * and define value matching and transformations.
+ */
+@Component({
+ selector: "app-import-column-mapping",
+ templateUrl: "./import-column-mapping.component.html",
+ styleUrls: ["./import-column-mapping.component.scss"],
+ standalone: true,
+ imports: [
+ HelpButtonComponent,
+ NgForOf,
+ MatInputModule,
+ BasicAutocompleteComponent,
+ FormsModule,
+ MatButtonModule,
+ NgIf,
+ MatBadgeModule,
+ ],
+})
+export class ImportColumnMappingComponent implements OnChanges {
+ @Input() rawData: any[] = [];
+ @Input() columnMapping: ColumnMapping[] = [];
+ @Output() columnMappingChange = new EventEmitter<ColumnMapping[]>();
+
+ @Input() set entityType(value: string) {
+ if (!value) {
+ return;
+ }
+
+ this.entityCtor = this.entities.get(value);
+ this.dataTypeMap = {};
+ this.allProps = [...this.entityCtor.schema.entries()]
+ .filter(([_, schema]) => schema.label)
+ .map(([name, schema]) => {
+ this.dataTypeMap[name] = this.schemaService.getDatatypeOrDefault(
+ schema.dataType,
+ );
+ return name;
+ });
+ }
+
+ private entityCtor: EntityConstructor;
+
+ /** entity properties that have a label */
+ allProps: string[] = [];
+
+ /** properties that need further adjustments through a component */
+ dataTypeMap: { [name: string]: DefaultDatatype };
+
+ /** warning label badges for a mapped column that requires user configuration for the "additional" details */
+ mappingAdditionalWarning: { [key: string]: string } = {};
+
+ labelMapper = (name: string) => this.entityCtor.schema.get(name).label;
+ isUsed = (option: string) =>
+ this.columnMapping.some(({ propertyName }) => propertyName === option);
+
+ constructor(
+ private entities: EntityRegistry,
+ private schemaService: EntitySchemaService,
+ private componentRegistry: ComponentRegistry,
+ private dialog: MatDialog,
+ private importColumnMappingService: ImportColumnMappingService,
+ ) {}
+
+ ngOnChanges(changes: SimpleChanges): void {
+ if (changes.columnMapping) {
+ this.importColumnMappingService.automaticallySelectMappings(
+ this.columnMapping,
+ this.entityCtor.schema,
+ );
+ }
+ }
+
+ async openMappingComponent(col: ColumnMapping) {
+ const uniqueValues = new Set<any>();
+ this.rawData.forEach((obj) => uniqueValues.add(obj[col.column]));
+ const configComponent = await this.componentRegistry.get(
+ this.dataTypeMap[col.propertyName].importConfigComponent,
+ )();
+
+ this.dialog
+ .open<any, MappingDialogData>(configComponent, {
+ data: {
+ col: col,
+ values: [...uniqueValues],
+ entityType: this.entityCtor,
+ },
+ width: "80vw",
+ disableClose: true,
+ })
+ .afterClosed()
+ .subscribe(() => this.updateMapping(col, true));
+ }
+
+ updateMapping(col: ColumnMapping, settingAdditional: boolean = false) {
+ if (!settingAdditional) {
+ // reset additional, because mapping changed
+ delete col.additional;
+ }
+
+ this.mappingAdditionalWarning[col.column] =
+ this.dataTypeMap[
+ col.propertyName
+ ]?.importIncompleteAdditionalConfigBadge?.(col);
+
+ // Emitting copy of array to trigger change detection; values have been updated in place through data binding
+ this.columnMappingChange.emit([...this.columnMapping]);
+ }
+
+ // TODO: infer column mapping from data. The following is from old DataImportModule (#1942)
+ /**
+ * Try to guess mappings of import file columns to entity properties.
+ * (e.g. based on column headers)
+ * @private
+ */
+ private inferColumnPropertyMapping() {
+ //const columnMap: ImportColumnMap = {};
+ // for (const p of this.properties) {
+ // const match = this.importData?.fields.find(
+ // (f) => f === p.label || f === p.key
+ // );
+ // if (match) {
+ // columnMap[match] = p;
+ // }
+ // }
+ //
+ // this.loadColumnMapping(columnMap);
+ }
+}
+
+export interface MappingDialogData {
+ col: ColumnMapping;
+ values: any[];
+ entityType: EntityConstructor;
+}
+
+
+
+
+
<div>
+ <span i18n>Define which columns / fields will be imported:</span>
+
+ <app-help-button
+ style="float: right"
+ text="The form below lists all columns from your imported file.
+ Select a property of the record type in the system, into which you want to import each column.
+ You can also omit some columns. If you do not select anything for a column, that column will be ignored during the import.
+ For advanced types, use the button next to the field to configure how values are transformed."
+ i18n-text="import - column mapping - help text"
+ >
+ </app-help-button>
+</div>
+
+<div>
+ <div *ngFor="let col of columnMapping">
+ <mat-form-field>
+ <mat-label>{{ col.column }}</mat-label>
+ <app-basic-autocomplete
+ [options]="allProps"
+ [(ngModel)]="col.propertyName"
+ (ngModelChange)="updateMapping(col)"
+ [optionToString]="labelMapper"
+ [hideOption]="isUsed"
+ />
+ </mat-form-field>
+
+ <button
+ class="margin-left-small"
+ mat-stroked-button
+ *ngIf="dataTypeMap[col.propertyName]?.importConfigComponent"
+ (click)="openMappingComponent(col)"
+ i18n="
+ import - column mapping - configure additional transformation button
+ "
+ [matBadge]="mappingAdditionalWarning?.[col.column]"
+ [matBadgeHidden]="!mappingAdditionalWarning?.[col.column]"
+ matBadgeColor="warn"
+ >
+ Configure value mapping
+ </button>
+ </div>
+</div>
+
<p i18n>Select a .csv file with data to import:</p>
+
+<app-input-file (fileLoad)="onFileLoad($event)" fileType="csv"></app-input-file>
+
+<div *ngIf="data" i18n>{{ data.data?.length }} rows detected for import</div>
+
@if (isLoading) {
+ <div>
+ <div i18n>Preparing data for preview and import ...</div>
+ <mat-progress-bar mode="indeterminate"></mat-progress-bar>
+ </div>
+} @else {
+ <div class="flex-row gap-regular align-center">
+ <span class="flex-grow" i18n>Review your mapped data to be imported:</span>
+
+ <button (click)="startImport()" mat-raised-button color="accent" i18n>
+ Start Import
+ </button>
+
+ <app-help-button
+ text="The data previewed here is mapped and transformed according to the 'Column Mapping' you defined in the previous step.
+ Only columns for which you selected a field there will be imported and appears here in this preview.
+ If necessary, you can go back to the previous step and make changes to the mapping."
+ i18n-text="import - review data - help text"
+ >
+ </app-help-button>
+ </div>
+
+ <app-entities-table
+ [entityType]="entityConstructor"
+ [customColumns]="displayColumns"
+ [columnsToDisplay]="displayColumns"
+ [records]="mappedEntities"
+ clickMode="none"
+ [editable]="false"
+ />
+}
+
Display an indicator for form fields explaining the status of the inherited-value config of that field
+and allowing users to re-sync the inherited value manually.
import { Component, OnInit } from "@angular/core";
+import { MatCardModule } from "@angular/material/card";
+import { MatButtonModule } from "@angular/material/button";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { ActivatedRoute, Router } from "@angular/router";
+import { LoginState } from "../session-states/login-state.enum";
+import { LoginStateSubject } from "../session-type";
+import { AsyncPipe, NgForOf, NgIf } from "@angular/common";
+import { SessionManagerService } from "../session-service/session-manager.service";
+import { MatProgressBarModule } from "@angular/material/progress-bar";
+import { SessionInfo } from "../auth/session-info";
+import { SiteSettingsService } from "../../site-settings/site-settings.service";
+import { MatTooltipModule } from "@angular/material/tooltip";
+import { MatListModule } from "@angular/material/list";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { waitForChangeTo } from "../session-states/session-utils";
+import { race, timer } from "rxjs";
+
+/**
+ * Allows the user to login online or offline depending on the connection status
+ */
+@UntilDestroy()
+@Component({
+ selector: "app-login",
+ templateUrl: "./login.component.html",
+ styleUrls: ["./login.component.scss"],
+ imports: [
+ MatCardModule,
+ MatButtonModule,
+ NgIf,
+ MatProgressBarModule,
+ AsyncPipe,
+ MatTooltipModule,
+ MatListModule,
+ NgForOf,
+ FontAwesomeModule,
+ ],
+ standalone: true,
+})
+export class LoginComponent implements OnInit {
+ offlineUsers: SessionInfo[] = [];
+ enableOfflineLogin: boolean;
+ loginInProgress = false;
+
+ constructor(
+ private router: Router,
+ private route: ActivatedRoute,
+ public sessionManager: SessionManagerService,
+ public loginState: LoginStateSubject,
+ public siteSettingsService: SiteSettingsService,
+ ) {
+ this.enableOfflineLogin = !this.sessionManager.remoteLoginAvailable();
+
+ sessionManager
+ .remoteLogin()
+ .then(() => sessionManager.clearRemoteSessionIfNecessary());
+ }
+
+ ngOnInit() {
+ this.loginState.pipe(untilDestroyed(this)).subscribe((state) => {
+ this.loginInProgress = state === LoginState.IN_PROGRESS;
+ if (state === LoginState.LOGGED_IN) {
+ this.routeAfterLogin();
+ }
+ });
+
+ this.offlineUsers = this.sessionManager.getOfflineUsers();
+ race(
+ this.loginState.pipe(waitForChangeTo(LoginState.LOGIN_FAILED)),
+ timer(10000),
+ ).subscribe(() => {
+ this.enableOfflineLogin = true;
+ });
+ }
+
+ private routeAfterLogin() {
+ const redirectUri = this.route.snapshot.queryParams["redirect_uri"] || "";
+ this.router.navigateByUrl(decodeURIComponent(redirectUri));
+ }
+
+ tryLogin() {
+ return this.sessionManager.remoteLogin();
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<mat-card appearance="raised" class="full-width border-box-sizing">
+ <mat-card-header class="header">
+ <mat-card-title style="text-align: center" i18n="Sign in title">
+ Welcome
+ </mat-card-title>
+ <mat-card-subtitle i18n="Sign in subtitle">
+ to your system
+ <em>{{ siteSettingsService.siteName | async }}</em>
+ </mat-card-subtitle>
+ </mat-card-header>
+
+ <mat-card-content>
+ <div class="gap-regular flex-column">
+ <!-- ONLINE -->
+ <div
+ matTooltip="It is necessary to log in to the server so that your data can be synchronized with other team members. We are checking whether you are still logged in or otherwise forward you to provide your credentials. You can still use the application offline, if you currently have no internet connection."
+ i18n-matTooltip="online login tooltip"
+ >
+ <div *ngIf="loginInProgress">
+ <em i18n="login progess bar title">Checking online login ...</em>
+ <mat-progress-bar
+ mode="indeterminate"
+ class="login-check-progressbar"
+ ></mat-progress-bar>
+ </div>
+
+ <div *ngIf="!loginInProgress">
+ <div
+ i18n="online login failed text"
+ class="online-error margin-bottom-small"
+ >
+ We couldn't connect to the server currently. You can still use the
+ application offline, if you have logged in on this device
+ previously.
+ </div>
+ <button
+ mat-stroked-button
+ type="button"
+ (click)="tryLogin()"
+ i18n="Login button"
+ style="width: 100%"
+ >
+ Retry online login
+ </button>
+ </div>
+ </div>
+
+ <!-- OFFLINE -->
+ <mat-card
+ *ngIf="offlineUsers.length > 0"
+ class="margin-top-large"
+ appearance="outlined"
+ >
+ <mat-card-header
+ matTooltip="You can use the application completely offline. However, your changes cannot be synchronized with other team members in this mode. When available, you should always use the online login."
+ i18n-matTooltip="offline login tooltip"
+ >
+ <h3 mat-card-title class="offline-title" i18n="offline section title">
+ Offline Login
+ </h3>
+ <mat-card-subtitle i18n="Select user for offline login title"
+ >Log in as user ...</mat-card-subtitle
+ >
+ </mat-card-header>
+
+ <mat-card-content>
+ <mat-action-list>
+ <button
+ mat-list-item
+ *ngFor="let user of offlineUsers"
+ (click)="sessionManager.offlineLogin(user)"
+ [disabled]="!enableOfflineLogin"
+ >
+ <fa-icon matListItemIcon icon="user"></fa-icon>
+ {{ user.email ?? user.name }}
+ </button>
+ </mat-action-list>
+ </mat-card-content>
+ </mat-card>
+ </div>
+ </mat-card-content>
+</mat-card>
+
import { Component } from "@angular/core";
+import { MenuItem, NavigationMenuConfig } from "../menu-item";
+import { ConfigService } from "../../../config/config.service";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { NavigationEnd, Router, RouterLink } from "@angular/router";
+import { filter, startWith } from "rxjs/operators";
+import { MatListModule } from "@angular/material/list";
+import { NgForOf } from "@angular/common";
+import { Angulartics2Module } from "angulartics2";
+import { FaDynamicIconComponent } from "../../../common-components/fa-dynamic-icon/fa-dynamic-icon.component";
+import { RoutePermissionsService } from "../../../config/dynamic-routing/route-permissions.service";
+
+/**
+ * Main app menu listing.
+ */
+@UntilDestroy()
+@Component({
+ selector: "app-navigation",
+ templateUrl: "./navigation.component.html",
+ styleUrls: ["./navigation.component.scss"],
+ imports: [
+ MatListModule,
+ NgForOf,
+ Angulartics2Module,
+ RouterLink,
+ FaDynamicIconComponent,
+ ],
+ standalone: true,
+})
+export class NavigationComponent {
+ /** The menu-item link (not the actual router link) that is currently active */
+ activeLink: string;
+
+ /** name of config array in the config json file */
+ private readonly CONFIG_ID = "navigationMenu";
+
+ /** all menu items to be displayed */
+ public menuItems: MenuItem[] = [];
+
+ constructor(
+ private configService: ConfigService,
+ private router: Router,
+ private routePermissionService: RoutePermissionsService,
+ ) {
+ this.configService.configUpdates
+ .pipe(untilDestroyed(this))
+ .subscribe(() => this.initMenuItemsFromConfig());
+ this.router.events
+ .pipe(
+ startWith(new NavigationEnd(0, this.router.url, "")),
+ filter((event) => event instanceof NavigationEnd),
+ )
+ .subscribe((event: NavigationEnd) => {
+ this.activeLink = this.computeActiveLink(event.url);
+ });
+ }
+
+ /**
+ * Computes the active link from a set of MenuItems.
+ * The active link is the link with the most "overlap", i.e.
+ * the most specific link that can be found given the array.
+ * @param newUrl The new url for which the navigation item should be highlighted
+ * @return the most specific link
+ * @private
+ */
+ private computeActiveLink(newUrl: string): string {
+ // conservative filter matching all items that could fit to the given url
+ const items: MenuItem[] = this.menuItems.filter((item) =>
+ newUrl.startsWith(item.link),
+ );
+ switch (items.length) {
+ case 0:
+ return "";
+ case 1:
+ const link = items[0].link;
+ // for root "/" only return on exact match to avoid confusing highlighting of unrelated items
+ return newUrl === link || link.length > 1 ? link : "";
+ default:
+ // If there are multiple matches (A user navigates with a URL that starts with
+ // multiple links from a MenuItem), use the element where the length is bigger.
+ //
+ // For example: Let there be two possible routes: '/attendance' and '/attendance/add/day'.
+ // When a user navigates to the URL '/attendance', only '/attendance' is
+ // a prefix of the possible '/attendance'. The potential other candidate '/attendance/add/day'
+ // is not a prefix of '/attendance' and there is no ambiguity.
+ //
+ // Vice Versa, when navigated to '/attendance/add/day',
+ // both '/attendance' and '/attendance/add/day' are a prefix of '/attendance/add/day'.
+ // In the latter case, the one with the longer URL should match.
+ return items.reduce((i1, i2) =>
+ i1.link.length > i2.link.length ? i1 : i2,
+ ).link;
+ }
+ }
+
+ /**
+ * Load menu items from config file
+ */
+ private async initMenuItemsFromConfig() {
+ const config = this.configService.getConfig<NavigationMenuConfig>(
+ this.CONFIG_ID,
+ );
+
+ this.menuItems = await this.routePermissionService.filterPermittedRoutes(
+ config.items,
+ );
+
+ // re-select active menu item after menu has been fully initialized
+ this.activeLink = this.computeActiveLink(location.pathname);
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<mat-nav-list>
+ <ng-container *ngFor="let item of menuItems">
+ <mat-list-item
+ angulartics2On="click"
+ angularticsCategory="Navigation"
+ angularticsAction="app_navigation_link_click"
+ [angularticsLabel]="item.label"
+ [routerLink]="[item.link]"
+ [class.matched-background]="item.link === activeLink"
+ onclick="this.blur();"
+ >
+ <a class="flex-row gap-small">
+ <app-fa-dynamic-icon
+ class="nav-icon"
+ [icon]="item.icon"
+ ></app-fa-dynamic-icon>
+ <div>{{ item.label }}</div>
+ </a>
+ </mat-list-item>
+ <mat-divider></mat-divider>
+ </ng-container>
+</mat-nav-list>
+
+
+
+
+
+ ./navigation.component.scss
+
+
@use "variables/sizes";
+@use "variables/colors";
+
+/* ensures that all icons have the same width */
+.nav-icon {
+ min-width: sizes.$max-icon-width;
+}
+
+.matched-background {
+ background-color: colors.$background !important;
+}
+
<div class="flex-column place-center">
+ <h1 i18n>Page Not Found</h1>
+ <h2 class="error-code">404</h2>
+ <p i18n>
+ Either the page has been removed or you don't have the required permissions
+ to view this page.
+ </p>
+ <button mat-stroked-button routerLink="" i18n>Go to Dashboard</button>
+</div>
+
import { Component, Input, OnInit } from "@angular/core";
+import { Note } from "../model/note";
+import { AttendanceLogicalStatus } from "../../attendance/model/attendance-status";
+import { DynamicComponent } from "../../../core/config/dynamic-components/dynamic-component.decorator";
+
+/**
+ * Displays the amount of children with a given attendance status at a given note.
+ */
+@DynamicComponent("NoteAttendanceCountBlock")
+@Component({
+ selector: "app-note-attendance-count-block",
+ template: `{{ participantsWithStatus }}`,
+ standalone: true,
+})
+export class NoteAttendanceCountBlockComponent implements OnInit {
+ /**
+ * The note on which the attendance should be counted.
+ */
+ @Input() entity: Note;
+
+ /**
+ * The logical attendance status for which the attendance should be counted.
+ */
+ @Input() config: { status: AttendanceLogicalStatus };
+
+ participantsWithStatus: number;
+
+ ngOnInit() {
+ this.participantsWithStatus = this.entity.countWithStatus(
+ this.config.status,
+ );
+ }
+}
+
import { Component, Input, OnInit } from "@angular/core";
+import { ChildrenService } from "../../../children/children.service";
+import moment from "moment";
+import { MatTableModule } from "@angular/material/table";
+import { DynamicComponent } from "../../../../core/config/dynamic-components/dynamic-component.decorator";
+import { EntityRegistry } from "../../../../core/entity/database-entity.decorator";
+import { EntityConstructor } from "../../../../core/entity/model/entity";
+import { DecimalPipe, NgIf } from "@angular/common";
+import { EntityBlockComponent } from "../../../../core/basic-datatypes/entity/entity-block/entity-block.component";
+import { DashboardWidget } from "../../../../core/dashboard/dashboard-widget/dashboard-widget";
+import { Note } from "../../model/note";
+import { DashboardListWidgetComponent } from "../../../../core/dashboard/dashboard-list-widget/dashboard-list-widget.component";
+
+interface NotesDashboardConfig {
+ entity?: string;
+ sinceDays?: number;
+ fromBeginningOfWeek?: boolean;
+ mode?: "with-recent-notes" | "without-recent-notes";
+}
+
+/**
+ * Dashboard Widget displaying entities that do not have a recently added Note.
+ *
+ * If you do not set "sinceDays" of "fromBeginningOfWeek" inputs
+ * by default notes since beginning of the current week are considered.
+ */
+@DynamicComponent("NotesDashboard")
+@Component({
+ selector: "app-no-recent-notes-dashboard",
+ templateUrl: "./notes-dashboard.component.html",
+ styleUrls: ["./notes-dashboard.component.scss"],
+ standalone: true,
+ imports: [
+ NgIf,
+ MatTableModule,
+ EntityBlockComponent,
+ DecimalPipe,
+ DashboardListWidgetComponent,
+ ],
+})
+export class NotesDashboardComponent
+ extends DashboardWidget
+ implements OnInit, NotesDashboardConfig
+{
+ static override getRequiredEntities(config: NotesDashboardConfig) {
+ return config?.entity || Note.ENTITY_TYPE;
+ }
+
+ /**
+ * Entity for which the recent notes should be counted.
+ */
+ @Input() set entity(value: string) {
+ this._entity = this.entities.get(value);
+ }
+
+ _entity: EntityConstructor;
+ /**
+ * number of days since last note that entities should be considered having a "recent" note.
+ */
+ @Input() sinceDays = 0;
+
+ /** Whether an additional offset should be automatically added to include notes from the beginning of the week */
+ @Input() fromBeginningOfWeek = true;
+
+ @Input() mode: "with-recent-notes" | "without-recent-notes";
+
+ /**
+ * Entities displayed in the template with additional "daysSinceLastNote" field
+ */
+ entries: EntityWithRecentNoteInfo[];
+
+ subtitle: string;
+
+ constructor(
+ private childrenService: ChildrenService,
+ private entities: EntityRegistry,
+ ) {
+ super();
+ }
+
+ ngOnInit() {
+ if (!this._entity) {
+ this.entity = "Child";
+ }
+
+ let dayRangeBoundary = this.sinceDays;
+ if (this.fromBeginningOfWeek) {
+ dayRangeBoundary += moment().diff(moment().startOf("week"), "days");
+ }
+ switch (this.mode) {
+ case "with-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] <= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities with recent reports:${this._entity.labelPlural} with recent report`;
+ break;
+ case "without-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] >= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities without recent reports:${this._entity.labelPlural} having no recent reports`;
+ break;
+ }
+ }
+
+ private async loadConcernedEntities(
+ filter: (stat: [string, number]) => boolean,
+ dayRangeBoundary: number,
+ ) {
+ const queryRange = Math.round((dayRangeBoundary * 3) / 10) * 10; // query longer range to be able to display exact date of last note for recent
+
+ // recent notes are sorted ascending, without recent notes descending
+ const order = this.mode === "with-recent-notes" ? -1 : 1;
+ const recentNotesMap =
+ await this.childrenService.getDaysSinceLastNoteOfEachEntity(
+ this._entity.ENTITY_TYPE,
+ queryRange,
+ );
+ this.entries = Array.from(recentNotesMap)
+ .filter(filter)
+ .map((stat) => statsToEntityWithRecentNoteInfo(stat, queryRange))
+ .sort((a, b) => order * (b.daysSinceLastNote - a.daysSinceLastNote));
+ }
+
+ get tooltip(): string {
+ switch (this.mode) {
+ case "with-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases with a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ case "without-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases without a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ }
+ }
+
+ get sinceBeginningOfTheWeek(): string {
+ if (this.fromBeginningOfWeek) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note since the beginning of the week':since the beginning of the week`
+ );
+ }
+ }
+
+ get withinTheLastNDays(): string {
+ if (this.sinceDays > 0) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note within the last x days':without a note within the last ${this.sinceDays} days`
+ );
+ }
+ }
+}
+
+/**
+ * details on entity stats to be displayed
+ */
+interface EntityWithRecentNoteInfo {
+ entityId: string;
+ daysSinceLastNote: number;
+ /** true when the daysSinceLastNote is not accurate but was cut off for performance optimization */
+ moreThanDaysSince: boolean;
+}
+
+/**
+ * Map a result entry from getDaysSinceLastNoteOfEachEntity to the EntityWithRecentNoteInfo interface
+ * @param stat Array of [entityId, daysSinceLastNote]
+ * @param queryRange The query range (the maximum of days that exactly calculated)
+ */
+function statsToEntityWithRecentNoteInfo(
+ stat: [string, number],
+ queryRange: number,
+): EntityWithRecentNoteInfo {
+ if (stat[1] < Number.POSITIVE_INFINITY) {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: stat[1],
+ moreThanDaysSince: false,
+ };
+ } else {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: queryRange,
+ moreThanDaysSince: true,
+ };
+ }
+}
+
+
+
+
+
<app-dashboard-list-widget
+ icon="file-alt"
+ theme="note"
+ [subtitle]="subtitle"
+ [explanation]="tooltip"
+ [entries]="entries"
+>
+ <div class="table-wrapper">
+ <table mat-table [attr.aria-label]="subtitle">
+ <!-- Table header only for assistive technologies like screen readers -->
+ <tr hidden="true">
+ <th scope="col">{{ _entity.label }}</th>
+ <th scope="col">Days since last note</th>
+ </tr>
+ <ng-container matColumnDef="entity">
+ <td *matCellDef="let entityNoteInfo">
+ <app-entity-block
+ [entityId]="entityNoteInfo.entityId"
+ ></app-entity-block>
+ </td>
+ </ng-container>
+
+ <ng-container
+ matColumnDef="daysSinceLastNote"
+ i18n="Amount of days back|Format like 'Days passed > 5 days'"
+ >
+ <td *matCellDef="let entityNoteInfo" class="text-align-end">
+ <ng-container *ngIf="entityNoteInfo.moreThanDaysSince">
+ >
+ </ng-container>
+ {{ entityNoteInfo.daysSinceLastNote | number: "1.0-0" }} days
+ </td>
+ </ng-container>
+
+ <tr
+ mat-row
+ *matRowDef="let row; columns: ['entity', 'daysSinceLastNote']"
+ ></tr>
+ </table>
+
+ <div *ngIf="entries?.length === 0">
+ <ng-container
+ *ngIf="mode === 'without-recent-notes'"
+ i18n="
+ There are no participants that don't have a recent report to be shown
+ here
+ "
+ >
+ no records without recent report
+ </ng-container>
+ <ng-container
+ *ngIf="mode === 'with-recent-notes'"
+ i18n="
+ There are no participants that have a recent report to be shown here
+ "
+ >
+ no records with recent report
+ </ng-container>
+ </div>
+ </div>
+</app-dashboard-list-widget>
+
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
This component lists attendance blocks for a child for recent months filtered by institutions.
+The child object the institution needs to be provided.
+It also implements a flexible layout to display less attendance blocks on a smaller layout.
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
Display a list of entity subrecords (entities related to the current entity details view)
+which can be active or past/inactive.
+
This component is similar to RelatedEntities but provides some additional UI to help users
+create a new entry if no currently active entry exists and
+show/hide inactive entries from the list.
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
import { Component, Input, OnInit } from "@angular/core";
+import { FormFieldConfig } from "../../common-components/entity-form/FormConfig";
+import moment from "moment";
+import { DynamicComponent } from "../../config/dynamic-components/dynamic-component.decorator";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { MatSlideToggleModule } from "@angular/material/slide-toggle";
+import { FormsModule } from "@angular/forms";
+import { MatTooltipModule } from "@angular/material/tooltip";
+import { NgIf } from "@angular/common";
+import { EntitiesTableComponent } from "../../common-components/entities-table/entities-table.component";
+import { PillComponent } from "../../common-components/pill/pill.component";
+import { ChildSchoolRelation } from "../../../child-dev-project/children/model/childSchoolRelation";
+import { RelatedEntitiesComponent } from "../related-entities/related-entities.component";
+import { TimePeriod } from "./time-period";
+
+/**
+ * Display a list of entity subrecords (entities related to the current entity details view)
+ * which can be active or past/inactive.
+ *
+ * This component is similar to RelatedEntities but provides some additional UI to help users
+ * create a new entry if no currently active entry exists and
+ * show/hide inactive entries from the list.
+ */
+@DynamicComponent("RelatedTimePeriodEntities")
+@Component({
+ selector: "app-related-time-period-entities",
+ templateUrl: "./related-time-period-entities.component.html",
+ styleUrls: ["./related-time-period-entities.component.scss"],
+ imports: [
+ FontAwesomeModule,
+ EntitiesTableComponent,
+ MatSlideToggleModule,
+ FormsModule,
+ MatTooltipModule,
+ NgIf,
+ PillComponent,
+ ],
+ standalone: true,
+})
+export class RelatedTimePeriodEntitiesComponent<E extends TimePeriod>
+ extends RelatedEntitiesComponent<E>
+ implements OnInit
+{
+ // also see super class for Inputs
+
+ @Input() single = true;
+ @Input() override showInactive = false;
+
+ @Input() override set columns(value: FormFieldConfig[]) {
+ this._columns = [...value, isActiveIndicator];
+ }
+ override get columns(): FormFieldConfig[] {
+ return this._columns;
+ }
+
+ override _columns: FormFieldConfig[] = [
+ { id: "start", visibleFrom: "md" },
+ { id: "end", visibleFrom: "md" },
+ isActiveIndicator,
+ ];
+
+ backgroundColorFn = (r: E) => r.getColor();
+ hasCurrentlyActiveEntry: boolean;
+
+ override async ngOnInit() {
+ await super.ngOnInit();
+ this.hasCurrentlyActiveEntry = this.data.some((record) => record.isActive);
+ }
+
+ override createNewRecordFactory() {
+ return () => {
+ const newRelation = super.createNewRecordFactory()();
+
+ newRelation.start =
+ this.data?.length && this.data[0].end
+ ? moment(this.data[0].end).add(1, "day").toDate()
+ : moment().startOf("day").toDate();
+
+ return newRelation;
+ };
+ }
+}
+
+export const isActiveIndicator: FormFieldConfig = {
+ id: "isActive",
+ label: $localize`:Label for the currently active status|e.g. Currently active:Currently`,
+ viewComponent: "ReadonlyFunction",
+ hideFromTable: true,
+ description: $localize`:Tooltip for the status of currently active or not:Only added to linked record if active. Change the start or end date to modify this status.`,
+ additional: (csr: ChildSchoolRelation) =>
+ csr.isActive
+ ? $localize`:Indication for the currently active status of an entry:active`
+ : $localize`:Indication for the currently inactive status of an entry:not active`,
+};
+
+
+
+
+
<app-pill class="hint-badge" *ngIf="!hasCurrentlyActiveEntry && !!data">
+ Currently there is no active entry. To add a new entry, click on the
+ <fa-icon class="color-accent" aria-label="add" icon="plus-circle"></fa-icon>
+ button.
+</app-pill>
+
+<app-entities-table
+ [entityType]="entityCtr"
+ [records]="data"
+ [filter]="filter"
+ [customColumns]="_columns"
+ [newRecordFactory]="createNewRecordFactory()"
+ [getBackgroundColor]="showInactive ? backgroundColorFn : undefined"
+ [clickMode]="clickMode"
+ [(showInactive)]="showInactive"
+>
+</app-entities-table>
+
<app-view-title
+ class="view-section"
+ i18n="
+ Reports concern a group of for example children and include data about these
+ children in a certain date range
+ "
+>
+ Reports
+</app-view-title>
+
+<app-select-report
+ [reports]="reports"
+ [loading]="isLoading"
+ [exportableData]="exportableData"
+ (calculateClick)="calculateResults($event.report, $event.from, $event.to)"
+ (dataChanged)="reportCalculation = null; data = null"
+ class="view-section"
+></app-select-report>
+
+<div style="color: gray; padding: 10px" *ngIf="reportCalculation" i18n>
+ This report was calculated at:
+ {{ reportCalculation?.endDate | date: "dd.MM.yyyy HH:mm" }} <br />
+ Click again on "Calculate" to re-calculate the report including any changes of
+ records since then.
+</div>
+
+<div class="error-message" *ngIf="isError">
+ <h3 class="header" i18n>Something went wrong calculating the report</h3>
+ <div class="content">
+ <p i18n>
+ Please try again. If you continue to see this error, contact the technical
+ support team.
+ </p>
+ <p>Error details:</p>
+ <code>
+ {{ errorDetails | json }}
+ </code>
+ </div>
+</div>
+
+<app-report-row
+ *ngIf="data?.length > 0 && mode === 'reporting'"
+ [rows]="data"
+></app-report-row>
+<app-object-table
+ *ngIf="data?.length > 0 && (mode === 'exporting' || mode === 'sql')"
+ [objects]="data"
+></app-object-table>
+
import {
+ Component,
+ EventEmitter,
+ OnInit,
+ Output,
+ ViewChild,
+} from "@angular/core";
+import { AttendanceService } from "../../attendance.service";
+import { Note } from "../../../notes/model/note";
+import { EntityMapperService } from "../../../../core/entity/entity-mapper/entity-mapper.service";
+import { RecurringActivity } from "../../model/recurring-activity";
+import { FormDialogService } from "../../../../core/form-dialog/form-dialog.service";
+import { AlertService } from "../../../../core/alerts/alert.service";
+import { AlertDisplay } from "../../../../core/alerts/alert-display";
+import { FormsModule, NgModel } from "@angular/forms";
+import { FilterService } from "../../../../core/filter/filter.service";
+import { FilterConfig } from "../../../../core/entity-list/EntityListConfig";
+import { MatFormFieldModule } from "@angular/material/form-field";
+import { MatInputModule } from "@angular/material/input";
+import { MatDatepickerModule } from "@angular/material/datepicker";
+import { Angulartics2OnModule } from "angulartics2";
+import { FilterComponent } from "../../../../core/filter/filter/filter.component";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatProgressBarModule } from "@angular/material/progress-bar";
+import { ActivityCardComponent } from "../../activity-card/activity-card.component";
+import { MatButtonModule } from "@angular/material/button";
+import { CurrentUserSubject } from "../../../../core/session/current-user-subject";
+import { DataFilter } from "../../../../core/filter/filters/filters";
+
+@Component({
+ selector: "app-roll-call-setup",
+ templateUrl: "./roll-call-setup.component.html",
+ styleUrls: ["./roll-call-setup.component.scss"],
+ imports: [
+ MatFormFieldModule,
+ MatInputModule,
+ FormsModule,
+ MatDatepickerModule,
+ Angulartics2OnModule,
+ FilterComponent,
+ NgIf,
+ MatProgressBarModule,
+ ActivityCardComponent,
+ NgForOf,
+ MatButtonModule,
+ ],
+ standalone: true,
+})
+export class RollCallSetupComponent implements OnInit {
+ date = new Date();
+
+ existingEvents: NoteForActivitySetup[] = [];
+ filteredExistingEvents: NoteForActivitySetup[] = [];
+
+ @Output() eventSelected = new EventEmitter<Note>();
+
+ allActivities: RecurringActivity[] = [];
+ visibleActivities: RecurringActivity[] = [];
+ filterConfig: FilterConfig[] = [{ id: "category" }, { id: "schools" }];
+ entityType = Note;
+
+ showingAll = false;
+
+ @ViewChild("dateField") dateField: NgModel;
+
+ isLoading = true;
+
+ /**
+ * filters are displayed in the UI only if at least this many events are listed.
+ *
+ * This avoids displaying irrelevant filters for an empty or very short list.
+ */
+ readonly FILTER_VISIBLE_THRESHOLD = 4;
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private attendanceService: AttendanceService,
+ private currentUser: CurrentUserSubject,
+ private formDialog: FormDialogService,
+ private alertService: AlertService,
+ private filerService: FilterService,
+ ) {}
+
+ async ngOnInit() {
+ await this.initAvailableEvents();
+ }
+
+ private async initAvailableEvents() {
+ this.isLoading = true;
+ this.existingEvents =
+ await this.attendanceService.getEventsWithUpdatedParticipants(this.date);
+ await this.loadActivities();
+ this.sortEvents();
+ this.filteredExistingEvents = this.existingEvents;
+ this.isLoading = false;
+ }
+
+ private async loadActivities() {
+ this.allActivities = await this.entityMapper
+ .loadType(RecurringActivity)
+ .then((res) => res.filter((a) => a.isActive));
+
+ if (this.showingAll) {
+ this.visibleActivities = this.allActivities;
+ } else {
+ // TODO implement a generic function that finds the property where a entity has relations to another entity type (e.g. `authors` for `Note` when looking for `User`) to allow dynamic checks
+ this.visibleActivities = this.allActivities.filter((a) =>
+ a.isAssignedTo(this.currentUser.value?.getId()),
+ );
+ if (this.visibleActivities.length === 0) {
+ this.visibleActivities = this.allActivities.filter(
+ (a) => a.assignedTo.length === 0,
+ );
+ }
+ if (this.visibleActivities.length === 0) {
+ this.visibleActivities = this.allActivities;
+ this.showingAll = true;
+ }
+ }
+
+ const newEvents = await Promise.all(
+ this.visibleActivities.map((activity) =>
+ this.createEventForActivity(activity),
+ ),
+ );
+ this.existingEvents = this.existingEvents.concat(
+ ...newEvents.filter((e) => !!e),
+ );
+ }
+
+ async showMore() {
+ this.showingAll = !this.showingAll;
+ await this.initAvailableEvents();
+ }
+
+ async showLess() {
+ this.showingAll = !this.showingAll;
+ await this.initAvailableEvents();
+ }
+
+ async setNewDate(date: Date) {
+ this.date = date;
+
+ await this.initAvailableEvents();
+ }
+
+ private async createEventForActivity(
+ activity: RecurringActivity,
+ ): Promise<NoteForActivitySetup> {
+ if (this.existingEvents.find((e) => e.relatesTo === activity.getId())) {
+ return undefined;
+ }
+
+ const event = (await this.attendanceService.createEventForActivity(
+ activity,
+ this.date,
+ )) as NoteForActivitySetup;
+ if (this.currentUser.value) {
+ event.authors = [this.currentUser.value.getId()];
+ }
+ event.isNewFromActivity = true;
+ return event;
+ }
+
+ private sortEvents() {
+ const calculateEventPriority = (event: Note) => {
+ let score = 0;
+
+ const activityAssignedUsers = this.allActivities.find(
+ (a) => a.getId() === event.relatesTo,
+ )?.assignedTo;
+ // use parent activities' assigned users and only fall back to event if necessary
+ const assignedUsers = activityAssignedUsers ?? event.authors;
+
+ if (!RecurringActivity.isActivityEventNote(event)) {
+ // show one-time events first
+ score += 1;
+ }
+
+ if (assignedUsers.includes(this.currentUser.value?.getId())) {
+ score += 2;
+ }
+
+ return score;
+ };
+
+ this.existingEvents.sort(
+ (a, b) => calculateEventPriority(b) - calculateEventPriority(a),
+ );
+ }
+
+ createOneTimeEvent() {
+ const newNote = Note.create(new Date());
+ if (this.currentUser.value) {
+ newNote.authors = [this.currentUser.value.getId()];
+ }
+
+ this.formDialog
+ .openView(newNote, "NoteDetails")
+ .afterClosed()
+ .subscribe((createdNote: Note) => {
+ if (createdNote) {
+ this.existingEvents.push(createdNote);
+ }
+ });
+ }
+
+ filterExistingEvents(filter: DataFilter<Note>) {
+ const predicate = this.filerService.getFilterPredicate(filter);
+ this.filteredExistingEvents = this.existingEvents.filter(predicate);
+ }
+
+ selectEvent(event: NoteForActivitySetup) {
+ if (this.dateField.valid) {
+ this.eventSelected.emit(event);
+ } else {
+ this.alertService.addWarning(
+ $localize`:Alert when selected date is invalid:Invalid Date`,
+ AlertDisplay.TEMPORARY,
+ );
+ }
+ }
+}
+
+type NoteForActivitySetup = Note & { isNewFromActivity?: boolean };
+
+
+
+
+
<div class="top-control">
+ <mat-form-field>
+ <mat-label
+ i18n="
+ Event-Record label|Record an event for a particular date that is to be
+ inputted
+ "
+ >Date
+ </mat-label>
+ <input
+ matInput
+ #dateField="ngModel"
+ [(ngModel)]="date"
+ required
+ [matDatepicker]="datePicker"
+ (dateChange)="setNewDate($event.value)"
+ />
+ <mat-datepicker-toggle
+ matIconSuffix
+ [for]="datePicker"
+ angulartics2On="click"
+ angularticsCategory="Record Attendance"
+ angularticsAction="select_date"
+ ></mat-datepicker-toggle>
+ <mat-datepicker #datePicker></mat-datepicker>
+ </mat-form-field>
+
+ <app-filter
+ *ngIf="existingEvents.length >= FILTER_VISIBLE_THRESHOLD"
+ class="flex-row flex-wrap gap-small"
+ [filterConfig]="filterConfig"
+ [entityType]="entityType"
+ [entities]="existingEvents"
+ [onlyShowRelevantFilterOptions]="true"
+ (filterObjChange)="filterExistingEvents($event)"
+ ></app-filter>
+</div>
+
+<div *ngIf="isLoading" class="process-spinner">
+ <mat-progress-bar mode="indeterminate"></mat-progress-bar>
+</div>
+
+<div class="cards-list" *ngIf="!isLoading">
+ <app-activity-card
+ class="pointer"
+ *ngFor="let event of filteredExistingEvents"
+ [event]="event"
+ [recurring]="event.isNewFromActivity"
+ (click)="selectEvent(event)"
+ >
+ </app-activity-card>
+</div>
+
+<div class="padding-top-regular gap-regular flex-row">
+ <button
+ mat-stroked-button
+ (click)="showingAll ? showLess() : showMore()"
+ angulartics2On="click"
+ angularticsCategory="Record Attendance"
+ angularticsAction="show_more"
+ class="padding-right-small"
+ >
+ <span *ngIf="showingAll" i18n="Show less entries of a list">
+ Show less
+ </span>
+ <span *ngIf="!showingAll" i18n="Show more entries of a list">
+ Show more
+ </span>
+ </button>
+ <button
+ i18n="Not listed|Allows to create a new event"
+ mat-button
+ (click)="createOneTimeEvent()"
+ angulartics2On="click"
+ angularticsCategory="Record Attendance"
+ angularticsAction="create_onetime_event"
+ >
+ My event is not listed ...
+ </button>
+</div>
+
+
+
+
+
+ ./roll-call-setup.component.scss
+
+
@use "mixins/grid-layout";
+@use "variables/sizes";
+@use "variables/colors";
+
+.top-control {
+ position: sticky;
+ top: 0;
+ /* make this visible while other contents go "under" this top control */
+ z-index: 1;
+ /* These small hacks remove the global margin and re-apply them as padding.
+ This way, the margin stays consistent and scrolling works
+ as intended (there is no overflow left or right) */
+ margin-left: -(sizes.$margin-main-view-left);
+ padding-left: sizes.$margin-main-view-left;
+ margin-right: -(sizes.$margin-main-view-right);
+ padding-right: sizes.$margin-main-view-right;
+ margin-top: -(sizes.$margin-main-view-top);
+ padding-top: sizes.$margin-main-view-top;
+ background-color: colors.$background;
+}
+
+.cards-list {
+ @include grid-layout.adaptive(350px, 414px);
+}
+
+.process-spinner {
+ display: flex;
+ justify-content: center;
+}
+
import { Component, HostBinding, Input } from "@angular/core";
+import {
+ animate,
+ state,
+ style,
+ transition,
+ trigger,
+} from "@angular/animations";
+
+/**
+ * These position states are used internally as animation states for the tab body. Setting the
+ * position state to left, right, or center will transition the tab body from its current
+ * position to its respective state. If there is no current position (void, in the case of a new
+ * tab body), then there will be no transition animation to its state.
+ *
+ * In the case of a new tab body that should immediately be centered with an animating transition,
+ * then left-origin-center or right-origin-center can be used, which will use left or right as its
+ * pseudo-prior state.
+ */
+type PositionState = "left" | "center" | "right";
+
+@Component({
+ selector: "app-roll-call-tab",
+ template: "<ng-content></ng-content>",
+ styleUrls: ["./roll-call-tab.component.scss"],
+ animations: [
+ trigger("translateTab", [
+ // Transitions to `none` instead of 0, because some browsers might blur the content.
+ state("center, void", style({ transform: "none" })),
+
+ // If the tab is either on the left or right, we additionally add a `min-height` of 1px
+ // in order to ensure that the element has a height before its state changes. This is
+ // necessary because Chrome does seem to skip the transition in RTL mode if the element does
+ // not have a static height and is not rendered. See related issue: #9465
+ state(
+ "left",
+ style({
+ transform: "translate(-110%)",
+ minHeight: "1px",
+ visibility: "hidden",
+ }),
+ ),
+ state(
+ "right",
+ style({
+ transform: "translate(110%)",
+ minHeight: "1px",
+ visibility: "hidden",
+ }),
+ ),
+
+ transition("void => *", []),
+ transition(
+ "* => left, * => right, left => center, right => center",
+ animate("800ms cubic-bezier(0.35, 0, 0.25, 1)"),
+ ),
+ ]),
+ ],
+ standalone: true,
+})
+export class RollCallTabComponent {
+ @Input()
+ set position(position: number) {
+ let posState: PositionState;
+ if (position < 0) {
+ posState = "left";
+ } else if (position > 0) {
+ posState = "right";
+ } else {
+ posState = "center";
+ }
+ this.animationState = posState;
+ }
+
+ @HostBinding("@translateTab") animationState = "";
+}
+
import { Component, Inject } from "@angular/core";
+import { MAT_DIALOG_DATA, MatDialogModule } from "@angular/material/dialog";
+import { MatButtonModule } from "@angular/material/button";
+
+/**
+ * This simple component can be used to open a file in a new window, if the user's browser is blocking popups.
+ */
+@Component({
+ selector: "app-show-file",
+ templateUrl: "./show-file.component.html",
+ styleUrls: ["./show-file.component.scss"],
+ imports: [MatDialogModule, MatButtonModule],
+ standalone: true,
+})
+export class ShowFileComponent {
+ constructor(@Inject(MAT_DIALOG_DATA) private link: string) {}
+
+ showFile(): void {
+ window.open(this.link, "_blank");
+ }
+}
+
+
+
+
+
<h2 mat-dialog-title i18n="Header of popup">File downloaded</h2>
+<mat-dialog-content class="content">
+ <button
+ mat-stroked-button
+ (click)="showFile()"
+ i18n="Button to show a downloaded file"
+ >
+ Show File
+ </button>
+ <p>
+ <em i18n="Text in popup"
+ >To automatically open files after they have been downloaded, please allow
+ popups for this page in your browser.</em
+ >
+ </p>
+</mat-dialog-content>
+
A small indicator component that displays an icon when there is currently synchronization
+with the remote server going on in the background.
+
This component also triggers a blocking dialog box when an initial sync is detected that prevents
+user login (because user accounts need to be synced first).
background processes to be displayed to users, with short delay to avoid flickering
+
+
+
+
+
+
+
+
+
+
+
+
+
import { ChangeDetectionStrategy, Component } from "@angular/core";
+import { SyncState } from "../../../session/session-states/sync-state.enum";
+import { DatabaseIndexingService } from "../../../entity/database-indexing/database-indexing.service";
+import { BackgroundProcessState } from "../background-process-state.interface";
+import { BehaviorSubject } from "rxjs";
+import { debounceTime } from "rxjs/operators";
+import { BackgroundProcessingIndicatorComponent } from "../background-processing-indicator/background-processing-indicator.component";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { SyncStateSubject } from "../../../session/session-type";
+
+/**
+ * A small indicator component that displays an icon when there is currently synchronization
+ * with the remote server going on in the background.
+ *
+ * This component also triggers a blocking dialog box when an initial sync is detected that prevents
+ * user login (because user accounts need to be synced first).
+ */
+@UntilDestroy()
+@Component({
+ selector: "app-sync-status",
+ templateUrl: "./sync-status.component.html",
+ imports: [BackgroundProcessingIndicatorComponent],
+ standalone: true,
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SyncStatusComponent {
+ private indexingProcesses: BackgroundProcessState[];
+
+ private _backgroundProcesses = new BehaviorSubject<BackgroundProcessState[]>(
+ [],
+ );
+ /** background processes to be displayed to users, with short delay to avoid flickering */
+ backgroundProcesses = this._backgroundProcesses
+ .asObservable()
+ .pipe(debounceTime(1000));
+
+ constructor(
+ private syncState: SyncStateSubject,
+ private dbIndexingService: DatabaseIndexingService,
+ ) {
+ this.dbIndexingService.indicesRegistered
+ .pipe(untilDestroyed(this))
+ .subscribe((indicesStatus) => {
+ this.indexingProcesses = indicesStatus;
+ this.updateBackgroundProcessesList();
+ });
+
+ this.syncState
+ .pipe(untilDestroyed(this))
+ .subscribe(() => this.updateBackgroundProcessesList());
+ }
+
+ /**
+ * Build and emit an updated array of current background processes
+ * @private
+ */
+ private updateBackgroundProcessesList() {
+ let currentProcesses: BackgroundProcessState[] = [];
+ if (this.syncState.value === SyncState.STARTED) {
+ currentProcesses.push({
+ title: $localize`Synchronizing database`,
+ pending: true,
+ });
+ } else {
+ currentProcesses.push({
+ title: $localize`Database up-to-date`,
+ pending: false,
+ });
+ }
+ currentProcesses = currentProcesses.concat(this.indexingProcesses);
+ this._backgroundProcesses.next(currentProcesses);
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<app-background-processing-indicator
+ [backgroundProcesses]="backgroundProcesses"
+>
+</app-background-processing-indicator>
+
This provides finer control on the content to be visible on the tooltip
+This template will be injected in ToolTipRenderer directive in the consumer template
+<ng-template #template>
+ content.....
+
Property name of the related entities (type given in this.entityType) that holds the entity id
+to be matched with the id of the current main entity (given in this.entity).
+If not explicitly set, this will be inferred based on the defined relations between the entities.
+
manually setting this is only necessary if you have multiple properties referencing the same entity type
+and you want to list only records related to one of them.
+For example: if you set entityType = "Project" (to display a list of projects here) and the Project entities have a properties "participants" and "supervisors" both storing references to User entities,
+you can set property = "supervisors" to only list those projects where the current User is supervisors, not participant.
import { Component, ViewChild } from "@angular/core";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { MatDrawerMode, MatSidenavModule } from "@angular/material/sidenav";
+import { ScreenWidthObserver } from "../../../utils/media/screen-size-observer.service";
+import { MatToolbarModule } from "@angular/material/toolbar";
+import { NgIf } from "@angular/common";
+import { MatButtonModule } from "@angular/material/button";
+import { FontAwesomeModule } from "@fortawesome/angular-fontawesome";
+import { RouterLink, RouterOutlet } from "@angular/router";
+import { Angulartics2Module } from "angulartics2";
+import { SearchComponent } from "../search/search.component";
+import { SyncStatusComponent } from "../sync-status/sync-status/sync-status.component";
+import { LanguageSelectComponent } from "../../language/language-select/language-select.component";
+import { NavigationComponent } from "../navigation/navigation/navigation.component";
+import { PwaInstallComponent } from "../../pwa-install/pwa-install.component";
+import { AppVersionComponent } from "../latest-changes/app-version/app-version.component";
+import { PrimaryActionComponent } from "../primary-action/primary-action.component";
+import { SiteSettingsService } from "../../site-settings/site-settings.service";
+import { DisplayImgComponent } from "../../../features/file/display-img/display-img.component";
+import { SiteSettings } from "../../site-settings/site-settings";
+import { LoginStateSubject } from "../../session/session-type";
+import { LoginState } from "../../session/session-states/login-state.enum";
+import { SessionManagerService } from "../../session/session-service/session-manager.service";
+import { SetupWizardButtonComponent } from "../../admin/setup-wizard/setup-wizard-button/setup-wizard-button.component";
+
+/**
+ * The main user interface component as root element for the app structure
+ * which also ties different components together into the overall app layout.
+ */
+@UntilDestroy()
+@Component({
+ selector: "app-ui",
+ templateUrl: "./ui.component.html",
+ styleUrls: ["./ui.component.scss"],
+ imports: [
+ MatToolbarModule,
+ NgIf,
+ MatButtonModule,
+ FontAwesomeModule,
+ RouterLink,
+ Angulartics2Module,
+ SearchComponent,
+ SyncStatusComponent,
+ LanguageSelectComponent,
+ MatSidenavModule,
+ NavigationComponent,
+ PwaInstallComponent,
+ AppVersionComponent,
+ RouterOutlet,
+ PrimaryActionComponent,
+ DisplayImgComponent,
+ SetupWizardButtonComponent,
+ ],
+ standalone: true,
+})
+export class UiComponent {
+ /** display mode for the menu to make it responsive and usable on smaller screens */
+ sideNavMode: MatDrawerMode;
+ /** reference to sideNav component in template, required for toggling the menu on user actions */
+ @ViewChild("sideNav") sideNav;
+ /** latest version of the site settings*/
+ siteSettings = new SiteSettings();
+
+ constructor(
+ private screenWidthObserver: ScreenWidthObserver,
+ private siteSettingsService: SiteSettingsService,
+ private loginState: LoginStateSubject,
+ private sessionManager: SessionManagerService,
+ ) {
+ this.screenWidthObserver
+ .platform()
+ .pipe(untilDestroyed(this))
+ .subscribe(
+ (isDesktop) => (this.sideNavMode = isDesktop ? "side" : "over"),
+ );
+ this.siteSettingsService.siteSettings.subscribe(
+ (s) => (this.siteSettings = s),
+ );
+ }
+
+ /**
+ * Check if user is logged in.
+ */
+ isLoggedIn(): boolean {
+ return this.loginState.value === LoginState.LOGGED_IN;
+ }
+
+ /**
+ * Trigger logout of user.
+ */
+ async logout() {
+ this.sessionManager.logout();
+ }
+
+ closeSidenavOnMobile() {
+ if (this.sideNavMode === "over") {
+ this.sideNav.close();
+ }
+ }
+}
+
+
+
+
+
<!--
+ ~ This file is part of ndb-core.
+ ~
+ ~ ndb-core is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU General Public License as published by
+ ~ the Free Software Foundation, either version 3 of the License, or
+ ~ (at your option) any later version.
+ ~
+ ~ ndb-core is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License
+ ~ along with ndb-core. If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+<!-- HEADER TOOLBAR -->
+<mat-toolbar color="primary" class="ui-toolbar">
+ <!-- Left items -->
+ <div class="flex-row align-center">
+ <span *ngIf="isLoggedIn() && sideNavMode === 'over'">
+ <button mat-icon-button (click)="sideNav.toggle()">
+ <fa-icon class="header-icon" icon="bars"></fa-icon>
+ </button>
+ </span>
+
+ <a
+ *ngIf="sideNavMode !== 'over'"
+ [routerLink]="['']"
+ class="header-title"
+ angulartics2On="click"
+ angularticsCategory="Navigation"
+ angularticsAction="navbar_site_title_link"
+ >
+ {{ siteSettings.siteName }}
+ </a>
+ </div>
+
+ <!--top right icons and search-->
+ <div
+ class="flex-row align-center flex-grow-1-3 justify-content-end gap-small"
+ >
+ <app-search
+ class="hide-mobile full-width"
+ *ngIf="isLoggedIn()"
+ ></app-search>
+
+ <app-sync-status></app-sync-status>
+
+ <app-language-select
+ *ngIf="siteSettings.displayLanguageSelect"
+ ></app-language-select>
+ </div>
+</mat-toolbar>
+
+<!-- MAIN NAVIGATION + CONTENT -->
+<mat-sidenav-container (backdropClick)="closeSidenavOnMobile()" autosize>
+ <mat-sidenav
+ #sideNav
+ *ngIf="isLoggedIn()"
+ [autoFocus]="false"
+ [mode]="sideNavMode"
+ [opened]="sideNavMode === 'side'"
+ class="sidenav-menu"
+ disableClose
+ >
+ <div
+ class="flex-column justify-space-between full-height overflow-y-hidden"
+ >
+ <app-display-img
+ *ngIf="siteSettings.logo"
+ [entity]="siteSettings"
+ imgProperty="logo"
+ class="site-logo"
+ ></app-display-img>
+ <app-navigation
+ class="overflow-auto-y"
+ (click)="closeSidenavOnMobile()"
+ ></app-navigation>
+
+ <div class="flex-grow"></div>
+
+ <div class="flex-column">
+ <app-setup-wizard-button></app-setup-wizard-button>
+
+ <app-pwa-install></app-pwa-install>
+
+ <div class="flex-row">
+ <button
+ (click)="closeSidenavOnMobile()"
+ mat-button
+ routerLink="user-account"
+ i18n="Navigate to user profile page"
+ class="footer-cell width-1-2"
+ >
+ <fa-icon icon="user"></fa-icon>
+ Profile
+ </button>
+
+ <button
+ mat-button
+ (click)="logout()"
+ i18n="Sign out of the app"
+ class="footer-cell width-1-2"
+ >
+ <fa-icon icon="sign-out-alt"></fa-icon>
+ Sign out
+ </button>
+ </div>
+
+ <div class="flex-row">
+ <button
+ mat-icon-button
+ class="footer-cell"
+ routerLink="/support"
+ (click)="closeSidenavOnMobile()"
+ >
+ <fa-icon icon="info-circle" class="info-icon"></fa-icon>
+ </button>
+ <button
+ mat-button
+ class="footer-cell full-width"
+ style="height: 100%"
+ (click)="version.showLatestChanges()"
+ >
+ <app-version #version></app-version>
+ </button>
+ </div>
+ </div>
+ </div>
+ </mat-sidenav>
+
+ <mat-sidenav-content class="sidenav-content">
+ <router-outlet></router-outlet>
+ </mat-sidenav-content>
+</mat-sidenav-container>
+
+<app-primary-action *ngIf="isLoggedIn()"></app-primary-action>
+
+
+
+
+
+ ./ui.component.scss
+
+
@use "@angular/material/core/style/elevation" as mat-elevation;
+@use "variables/sizes";
+@use "variables/colors";
+@use "variables/breakpoints";
+
+/*
+ * outermost elements; make them as tall as possible.
+ * Consumes all of the available screen
+ */
+html,
+body {
+ /* height: 100%; */
+}
+
+/** Toolbar **/
+
+/*
+ * Directive for the only toolbar row.
+ * Both of these directives are required to make the shadow show
+ */
+.ui-toolbar {
+ position: relative;
+ z-index: 2;
+ justify-content: space-between;
+ @include mat-elevation.elevation(2);
+}
+
+.search-field {
+ /*
+ * Use a fixed width here because
+ * the form field does not work with
+ * relative / computed sizes
+ */
+ width: 450px;
+}
+
+.header-icon {
+ color: white;
+ font-size: 15pt;
+}
+
+/** App content **/
+
+:host {
+ background-color: colors.$background;
+ display: grid;
+ grid-template-columns: 1fr;
+ grid-template-rows: auto 1fr;
+ height: 100vh;
+
+ /*
+ This only targets iOs devices. Note that (just like the line below), this is
+ a hacky solution. While it is practically guaranteed that only iOs will have this
+ property, it is not guaranteed that iOs will keep this property for ever.
+ */
+ @supports (-webkit-touch-callout: none) {
+ /* mobile viewport bug fix.
+ The viewport height on iOs is not necessarily the visible screen size.
+ There might be a bar on the top of the screen. The following line
+ fixes this, but since this is no official css feature, this line should
+ be replaced as soon as a nicer solution exists.
+ */
+
+ height: -webkit-fill-available;
+ }
+}
+
+.sidenav-menu {
+ background-color: colors.$background-secondary;
+}
+
+/** Main content **/
+
+mat-sidenav-container {
+ background: none;
+}
+
+/**
+ * reset the styles from the anchor element
+ */
+.header-title {
+ color: white;
+ text-decoration: none;
+}
+
+/**
+ * Remove the right border so that the background color
+ * merges into the main element
+ */
+.mat-drawer-side {
+ border-right: 0;
+}
+
+.site-logo {
+ width: 180px;
+ padding: 8px;
+ margin: auto;
+}
+
+.footer-cell {
+ border-top: solid 1px rgba(0, 0, 0, 0.12);
+ border-radius: 0;
+ display: flex;
+ place-content: center;
+ place-items: center;
+ min-width: fit-content;
+
+ &:not(:last-child) {
+ border-right: solid 1px rgba(0, 0, 0, 0.12);
+ }
+
+ box-sizing: border-box;
+}
+
+.info-icon {
+ margin: auto;
+ font-size: 20px;
+ cursor: pointer;
+}
+
+.info-button {
+ width: 48px;
+ border-right: solid 1px rgba(0, 0, 0, 0.12);
+ border-radius: 0;
+ overflow: hidden;
+}
+
+.justify-content-end {
+ justify-content: end;
+}
+
import { Component, Input, OnInit } from "@angular/core";
+import { DynamicComponent } from "../../config/dynamic-components/dynamic-component.decorator";
+import {
+ FormBuilder,
+ FormControl,
+ FormGroup,
+ ReactiveFormsModule,
+ Validators,
+} from "@angular/forms";
+import {
+ KeycloakAuthService,
+ KeycloakUserDto,
+ Role,
+} from "../../session/auth/keycloak/keycloak-auth.service";
+import { AlertService } from "../../alerts/alert.service";
+import { HttpClient } from "@angular/common/http";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatButtonModule } from "@angular/material/button";
+import { MatTooltipModule } from "@angular/material/tooltip";
+import { MatFormFieldModule } from "@angular/material/form-field";
+import { MatInputModule } from "@angular/material/input";
+import { MatSelectModule } from "@angular/material/select";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { SessionSubject } from "../../session/auth/session-info";
+import { Entity } from "../../entity/model/entity";
+import { catchError } from "rxjs/operators";
+import { environment } from "../../../../environments/environment";
+
+@UntilDestroy()
+@DynamicComponent("UserSecurity")
+@Component({
+ selector: "app-user-security",
+ templateUrl: "./user-security.component.html",
+ styleUrls: ["./user-security.component.scss"],
+ imports: [
+ NgIf,
+ MatButtonModule,
+ MatTooltipModule,
+ ReactiveFormsModule,
+ MatFormFieldModule,
+ MatInputModule,
+ MatSelectModule,
+ NgForOf,
+ ],
+ standalone: true,
+})
+export class UserSecurityComponent implements OnInit {
+ @Input() entity: Entity;
+ form: FormGroup;
+ availableRoles: Role[] = [];
+ user: KeycloakUserDto;
+ editing = true;
+ userIsPermitted = false;
+
+ constructor(
+ private authService: KeycloakAuthService,
+ sessionInfo: SessionSubject,
+ private fb: FormBuilder,
+ private alertService: AlertService,
+ private http: HttpClient,
+ ) {
+ this.form = this.fb.group({
+ username: [{ value: "", disabled: true }],
+ email: ["", [Validators.required, Validators.email]],
+ roles: new FormControl<Role[]>([], Validators.required),
+ });
+
+ if (
+ sessionInfo.value?.roles.includes(
+ KeycloakAuthService.ACCOUNT_MANAGER_ROLE,
+ )
+ ) {
+ this.userIsPermitted = true;
+ } else {
+ return;
+ }
+ // automatically skip trailing and leading whitespaces when the form changes
+ this.form.valueChanges.pipe(untilDestroyed(this)).subscribe((next) => {
+ if (next.email?.startsWith(" ") || next.email?.endsWith(" ")) {
+ this.form.get("email").setValue(next.email.trim());
+ }
+ });
+ this.authService
+ .getRoles()
+ .subscribe((roles) => this.initializeRoles(roles));
+ }
+
+ private initializeRoles(roles: Role[]) {
+ this.availableRoles = roles;
+ if (!this.user) {
+ // assign "user_app" as default role for new users
+ const userAppRole = roles.find(({ name }) => name === "user_app");
+ if (userAppRole) {
+ this.form.get("roles").setValue([userAppRole]);
+ }
+ }
+ }
+
+ ngOnInit() {
+ if (!this.userIsPermitted) {
+ return;
+ }
+ this.form.get("username").setValue(this.entity.getId());
+ this.authService
+ .getUser(this.entity.getId(true))
+ .pipe(catchError(() => this.authService.getUser(this.entity.getId())))
+ .subscribe({
+ next: (res) => this.assignUser(res),
+ error: () => undefined,
+ });
+ }
+
+ private assignUser(user: KeycloakUserDto) {
+ this.user = user;
+ this.initializeForm();
+ if (this.user) {
+ this.disableForm();
+ }
+ }
+
+ private initializeForm() {
+ this.form.get("email").setValue(this.user.email);
+ this.form
+ .get("roles")
+ .setValue(
+ this.user.roles.map((role) =>
+ this.availableRoles.find((r) => r.id === role.id),
+ ),
+ );
+ this.form.markAsPristine();
+ }
+
+ toggleAccount(enabled: boolean) {
+ let message = $localize`:Snackbar message:Account has been disabled, user will not be able to login anymore.`;
+ if (enabled) {
+ message = $localize`:Snackbar message:Account has been activated, user can login again.`;
+ }
+ this.updateKeycloakUser({ enabled }, message);
+ }
+
+ editForm() {
+ this.editing = true;
+ if (this.user.enabled) {
+ this.form.enable();
+ }
+ }
+
+ disableForm() {
+ this.editing = false;
+ this.initializeForm();
+ this.form.disable();
+ }
+
+ createAccount() {
+ const user = this.getFormValues();
+ if (!user) {
+ return;
+ }
+ user.enabled = true;
+ if (user) {
+ this.authService.createUser(user).subscribe({
+ next: () => {
+ this.alertService.addInfo(
+ $localize`:Snackbar message:Account created. An email has been sent to ${
+ this.form.get("email").value
+ }`,
+ );
+ this.user = user as KeycloakUserDto;
+ this.disableForm();
+ },
+ error: ({ error }) => this.form.setErrors({ failed: error.message }),
+ });
+ }
+ }
+
+ updateAccount() {
+ const update = this.getFormValues();
+ // only send values that have changed
+ Object.keys(this.form.controls).forEach((control) =>
+ this.form.get(control).pristine ? delete update[control] : undefined,
+ );
+ if (update) {
+ this.updateKeycloakUser(
+ update,
+ $localize`:Snackbar message:Successfully updated user`,
+ );
+ }
+ }
+
+ private updateKeycloakUser(
+ update: Partial<KeycloakUserDto>,
+ message: string,
+ ) {
+ this.authService.updateUser(this.user.id, update).subscribe({
+ next: () => {
+ this.alertService.addInfo(message);
+ Object.assign(this.user, update);
+ this.disableForm();
+ if (update.roles?.length > 0) {
+ // roles changed, user might have more permissions now
+ this.triggerSyncReset();
+ }
+ },
+ error: ({ error }) => this.form.setErrors({ failed: error.message }),
+ });
+ }
+
+ getFormValues(): Partial<KeycloakUserDto> {
+ if (this.form.invalid) {
+ this.form.markAllAsTouched();
+ return;
+ }
+ this.form.setErrors({});
+ return this.form.getRawValue();
+ }
+
+ private triggerSyncReset() {
+ this.http
+ .post(
+ `${environment.DB_PROXY_PREFIX}/${environment.DB_NAME}/clear_local`,
+ undefined,
+ )
+ .subscribe({
+ next: () => undefined,
+ // request fails if no permission backend is used - this is fine
+ error: () => undefined,
+ });
+ }
+}
+
+
+
+
+
<em
+ *ngIf="!userIsPermitted"
+ i18n="Placeholder text when permissions are missing"
+>
+ You account does not have the required permissions to see this page.
+</em>
+
+<div *ngIf="userIsPermitted" class="flex-column">
+ <div *ngIf="!user" class="buttons-wrapper align-self-start">
+ <p
+ i18n="notice about user without account"
+ class="field-hint field-warning"
+ >
+ There is no user account set up for this user yet. Enable this user to log
+ into the app by filling the details below.
+ </p>
+ <button
+ *ngIf="editing && !user"
+ mat-raised-button
+ type="submit"
+ (click)="createAccount()"
+ [disabled]="form.disabled"
+ class="invite-button"
+ [color]="form.valid ? 'accent' : ''"
+ [class.invite-button-animate]="form.valid"
+ i18n="button to invite a new user"
+ >
+ Create account & send invitation
+ </button>
+ </div>
+
+ <div
+ class="padding-bottom-small flex-row gap-small align-self-end flex-wrap"
+ *ngIf="user"
+ >
+ <button
+ *ngIf="editing && user?.enabled"
+ mat-stroked-button
+ color="warn"
+ (click)="toggleAccount(false)"
+ matTooltip="User will not be able to login again, no information will be lost"
+ i18n="button to update disable a user"
+ >
+ Deactivate user
+ </button>
+ <button
+ *ngIf="editing && !user?.enabled"
+ mat-raised-button
+ color="accent"
+ (click)="toggleAccount(true)"
+ matTooltip="User can login again with the previously used credentials"
+ i18n="button to enable a user"
+ >
+ Activate user
+ </button>
+ <button
+ *ngIf="editing && user?.enabled"
+ mat-raised-button
+ color="accent"
+ class="action-button"
+ (click)="updateAccount()"
+ i18n="Save button for forms"
+ >
+ Save
+ </button>
+ <button
+ *ngIf="editing"
+ mat-stroked-button
+ class="action-button"
+ (click)="disableForm()"
+ i18n="Cancel button for forms"
+ >
+ Cancel
+ </button>
+ <button
+ *ngIf="!editing"
+ mat-raised-button
+ class="action-button"
+ (click)="editForm()"
+ i18n="Edit button for forms"
+ >
+ Edit
+ </button>
+ </div>
+
+ <p
+ *ngIf="user && !user.enabled"
+ i18n="Hint in user account page"
+ class="field-hint field-warning"
+ >
+ User is currently disabled and will not be able to login to the app
+ </p>
+ <form [formGroup]="form">
+ <div>
+ <mat-form-field>
+ <mat-label i18n="label of email input">Email</mat-label>
+ <input matInput type="text" formControlName="email" />
+ <mat-error *ngIf="form.hasError('email', 'email')" i18n>
+ Please enter a valid email
+ </mat-error>
+ <mat-error *ngIf="form.hasError('required', 'email')" i18n>
+ This field is required
+ </mat-error>
+ </mat-form-field>
+ </div>
+
+ <div>
+ <mat-form-field style="width: 100%">
+ <mat-label i18n="label of roles input">Roles</mat-label>
+ <mat-select formControlName="roles" multiple>
+ <mat-select-trigger>
+ <span *ngFor="let role of form.get('roles').value"
+ >{{ role.name }}
+ </span>
+ </mat-select-trigger>
+ <mat-option
+ *ngFor="let role of availableRoles"
+ [value]="role"
+ [matTooltip]="role.description"
+ >
+ {{ role.description }}
+ <em style="font-size: x-small">{{ role.name }}</em>
+ </mat-option>
+ </mat-select>
+
+ <mat-hint i18n="hint about assigning user roles" class="field-hint">
+ You should select at least one user role. Otherwise this user will not
+ even be able to access the basic app layout like the menu.
+ </mat-hint>
+
+ <mat-error *ngIf="form.hasError('required', 'roles')" i18n>
+ This field is required
+ </mat-error>
+ </mat-form-field>
+ </div>
+
+ <mat-error *ngIf="form.getError('failed')">{{
+ form.getError("failed")
+ }}</mat-error>
+ </form>
+</div>
+
Aam Digital is open source because we believe in building things together
+and letting people benefit from and adapt things rather than everybody reinventing their own wheel.
+
In order to build great software for small social impact organisations
+we welcome anybody willing to contribute.
+We are a small core team of full-time developers as well as a few regular volunteer contributors.
+So whether you want to extend our code for your own use case or just help out -
+we welcome any contributions to make this project better!
Do get in touch with us by creating an issue here or
+writing to info@aam-digital.com.
+
Our main communication channels in the team are
+
+
GitHub issues and pull requests.
+Feel free to open one yourself also to ask a question.
+
Slack. Write us an e-mail to get an invitation to our workspace.
+
+
Where can I help?
+
Have a look at our issues on GitHub.
+Some of them are explicitly label as suitable issues for a new contributor to work on: Community Help Wanted.
+If you are not sure whether you should work on a certain issue, just post a short comment in the issue to clarify.
+
Whenever you start working on an issue, please assign yourself on the GitHub issue and change the "status" within the project to "In Progress".
+
We organize our work using GitHub Projects' kanban boards and issue labels:
Get an overview of all issues (across all repositories) and their status here, we use a kanban-style board where issues are moved through the columns based on their status.
+
The issues in the board are sorted by priority (most important on top).
+
Please do not work on issues in the "Triage / Analysis" status, these topics still required a clearer definition and approval from the core team.
Our labels are scoped into a few logical groups (e.g. "Status" or "Type" related labels), do check the descriptions shown beside the label name in the list of GitHub labels.
+
The same labels are maintained across all our repositories.
This component can be used to display an entity in more detail.
+As an abstract base component, this provides functionality to load an entity
+and leaves the UI and special functionality to components that extend this class, like EntityDetailsComponent.
Works similar to *ngFor:
+<div *appConfigurableEnum="let item of 'interaction-type'"></div>
+will create one div for each option defined in the config for "enum:interaction-type".
import { Directive, Input, TemplateRef, ViewContainerRef } from "@angular/core";
+import { ConfigurableEnumService } from "../configurable-enum.service";
+import { ConfigurableEnumValue } from "../configurable-enum.interface";
+
+/**
+ * Enumerate over all {@link ConfigurableEnumConfig} values for the given enum config id.
+ *
+ * Works similar to `*ngFor`:
+ * `<div *appConfigurableEnum="let item of 'interaction-type'"></div>`
+ * will create one div for each option defined in the config for "enum:interaction-type".
+ */
+@Directive({
+ selector: "[appConfigurableEnum]",
+ standalone: true,
+})
+export class ConfigurableEnumDirective {
+ /**
+ * Sets the string id of the enum config id.
+ * @param enumConfigId
+ */
+ @Input() set appConfigurableEnumOf(enumConfigId: string) {
+ const options = this.enumService.getEnumValues(enumConfigId);
+ for (const item of options) {
+ this.viewContainerRef.createEmbeddedView(this.templateRef, {
+ $implicit: item,
+ });
+ }
+ }
+
+ /**
+ * For implementation details see
+ * https://www.talkinghightech.com/en/create-ngfor-directive/ and
+ * https://angular.io/guide/structural-directives#write-a-structural-directive
+ */
+ constructor(
+ private templateRef: TemplateRef<any>,
+ private viewContainerRef: ViewContainerRef,
+ private enumService: ConfigurableEnumService,
+ ) {}
+
+ /**
+ * Make sure the template checker knows the type of the context with which the
+ * template of this directive will be rendered
+ * See {@link https://angular.io/guide/structural-directives#typing-the-directives-context}
+ * @param directive
+ * @param context
+ */
+
+ static ngTemplateContextGuard(
+ directive: ConfigurableEnumDirective,
+ context: unknown,
+ ): context is { $implicit: ConfigurableEnumValue } {
+ return true;
+ }
+}
+
This directive can be used to disable a element (e.g. button) based on the current users permissions.
+Additionally, a little popup will be shown when the user hovers the disabled element.
These arguments are required to check whether the user has permissions to perform the operation.
+The operation property defines to what kind of operation an element belongs, e.g. OperationType.CREATE
+The entity property defines for which kind of entity the operation will be performed, e.g. Child
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import {
+ ComponentRef,
+ Directive,
+ Input,
+ OnChanges,
+ OnDestroy,
+ OnInit,
+ TemplateRef,
+ ViewContainerRef,
+} from "@angular/core";
+import { DisabledWrapperComponent } from "./disabled-wrapper.component";
+import { EntityActionPermission, EntitySubject } from "../permission-types";
+import { EntityAbility } from "../ability/entity-ability";
+import { Unsubscribe } from "@casl/ability";
+
+/**
+ * This directive can be used to disable a element (e.g. button) based on the current users permissions.
+ * Additionally, a little popup will be shown when the user hovers the disabled element.
+ */
+@Directive({
+ selector: "[appDisabledEntityOperation]",
+ standalone: true,
+})
+export class DisableEntityOperationDirective
+ implements OnInit, OnChanges, OnDestroy
+{
+ /**
+ * These arguments are required to check whether the user has permissions to perform the operation.
+ * The operation property defines to what kind of operation an element belongs, e.g. OperationType.CREATE
+ * The entity property defines for which kind of entity the operation will be performed, e.g. Child
+ */
+ @Input("appDisabledEntityOperation") arguments: {
+ operation: EntityActionPermission;
+ entity: EntitySubject;
+ field?: string;
+ };
+
+ private wrapperComponent: ComponentRef<DisabledWrapperComponent>;
+ private text: string = $localize`:Missing permission:Your account does not have the required permission for this action.`;
+
+ private readonly unsubscribeAbilityUpdates: Unsubscribe;
+
+ constructor(
+ private templateRef: TemplateRef<HTMLButtonElement>,
+ private viewContainerRef: ViewContainerRef,
+ private ability: EntityAbility,
+ ) {
+ this.unsubscribeAbilityUpdates = this.ability.on("updated", () =>
+ this.applyPermissions(),
+ );
+ }
+
+ ngOnDestroy(): void {
+ this.unsubscribeAbilityUpdates();
+ }
+
+ ngOnInit() {
+ this.wrapperComponent = this.viewContainerRef.createComponent(
+ DisabledWrapperComponent,
+ );
+ this.wrapperComponent.instance.template = this.templateRef;
+ this.wrapperComponent.instance.text = this.text;
+ this.applyPermissions();
+ }
+
+ ngOnChanges() {
+ this.applyPermissions();
+ }
+
+ private applyPermissions() {
+ if (
+ this.wrapperComponent &&
+ this.arguments?.operation &&
+ this.arguments?.entity
+ ) {
+ // Update the disabled property whenever the input values change
+ this.wrapperComponent.instance.elementDisabled = this.ability.cannot(
+ this.arguments.operation,
+ this.arguments.entity,
+ this.arguments.field,
+ );
+ this.wrapperComponent.instance.ngAfterViewInit();
+ }
+ }
+}
+
A simple helper class which sets up all the required information for edit-components.
+ refers to the type of the value which is processed in the component.
The parent form of the formControl this is always needed to correctly setup the mat-form-field
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { FormControl, FormGroup } from "@angular/forms";
+import { FormFieldConfig } from "../../common-components/entity-form/FormConfig";
+import { Entity } from "../model/entity";
+import { Directive, Input, OnChanges, OnInit } from "@angular/core";
+import { DefaultValueConfig } from "../schema/default-value-config";
+
+/**
+ * A simple helper class which sets up all the required information for edit-components.
+ * <T> refers to the type of the value which is processed in the component.
+ */
+@Directive()
+export abstract class EditComponent<T> implements OnInit, OnChanges {
+ /**
+ * The configuration for this form field.
+ */
+ @Input() formFieldConfig: FormFieldConfig;
+
+ /**
+ * The form control for this field which is part of a form group of the table/form component.
+ */
+ @Input() formControl: FormControl<T>;
+
+ /**
+ * The entity which is edited.
+ */
+ @Input() entity: Entity;
+
+ /**
+ * The name of the form control.
+ */
+ @Input() formControlName: string;
+
+ /**
+ * Describes the defaultValue behaviour for this field
+ */
+ @Input() defaultValueConfig: DefaultValueConfig | undefined;
+
+ /**
+ * A label for this component.
+ */
+ label: string;
+
+ /**
+ * The parent form of the `formControl` this is always needed to correctly setup the `mat-form-field`
+ */
+ parent: FormGroup;
+
+ /**
+ * Additional config details for the specific component implementation.
+ * Can be defined through entity schema also.
+ */
+ additional?: any;
+
+ /** indicating that the value is not in its original state, so that components can explain this to the user */
+ isPartiallyAnonymized: boolean;
+
+ ngOnInit() {
+ if (!this.formFieldConfig?.forTable) {
+ this.label = this.formFieldConfig?.label;
+ }
+ this.additional = this.formFieldConfig?.additional;
+ this.formControlName = this.formFieldConfig?.id;
+ // This type casts are needed as the normal types throw errors in the templates
+ this.parent = this.formControl.parent as FormGroup;
+ }
+
+ ngOnChanges() {
+ this.isPartiallyAnonymized =
+ this.entity?.anonymized &&
+ this.entity?.getSchema()?.get(this.formFieldConfig?.id)?.anonymize ===
+ "retain-anonymized";
+ }
+}
+
Memorizes the current state of a TabGroup (i.e. which tab currently is selected)
+in the URL and sets the initial value to a value that was previously set.
+
This enables navigation throughout the app while memorizing the state a tab was in
+Usage (only the directive is required, the rest is automatic):
import { ActivatedRoute, Router } from "@angular/router";
+import { MatTabGroup } from "@angular/material/tabs";
+import { Directive, OnInit, Optional } from "@angular/core";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { ViewComponentContext } from "../../core/ui/abstract-view/abstract-view.component";
+
+/**
+ * Memorizes the current state of a `TabGroup` (i.e. which tab currently is selected)
+ * in the URL and sets the initial value to a value that was previously set.
+ *
+ * This enables navigation throughout the app while memorizing the state a tab was in
+ * Usage (only the directive is required, the rest is automatic):
+ * ```
+ * <mat-tab-group appTabStateMemo>
+ * ...
+ * </mat-tab-group>
+ * ```
+ */
+@UntilDestroy()
+@Directive({
+ selector: "[appTabStateMemo]",
+})
+export class TabStateMemoDirective implements OnInit {
+ private readonly tabIndexKey = "tabIndex";
+
+ constructor(
+ private router: Router,
+ private route: ActivatedRoute,
+ private tab: MatTabGroup,
+ @Optional() private viewContext: ViewComponentContext,
+ ) {}
+
+ ngOnInit() {
+ if (this.viewContext?.isDialog) {
+ // does not apply if opened in popup
+ return;
+ }
+
+ // This logic is purposefully in `ngOnInit` and not in the constructor,
+ // so we can override values that are set by custom logic in the component
+ // (i.e. we override any binding to [(selectedIndex)] for the initial index)
+ const potentialNextTabIndex = parseInt(
+ this.route.snapshot.queryParamMap.get(this.tabIndexKey),
+ 10,
+ );
+ if (!Number.isNaN(potentialNextTabIndex)) {
+ this.tab.selectedIndex = potentialNextTabIndex;
+ }
+ this.tab.selectedIndexChange
+ .pipe(untilDestroyed(this))
+ .subscribe((next) => this.updateURLQueryParams(next));
+ }
+
+ // Update the URL
+ private async updateURLQueryParams(value: number) {
+ if (this.viewContext?.isDialog) {
+ // does not apply if opened in popup
+ return;
+ }
+
+ await this.router.navigate(["."], {
+ relativeTo: this.route,
+ queryParams: { [this.tabIndexKey]: value },
+ replaceUrl: true,
+ queryParamsHandling: "merge",
+ });
+ }
+}
+
A directive that can be used to render a custom tooltip that may contain HTML code.
+When a tooltip is only a string, the {@code MatTooltip} should be used instead.
+
The Tooltip to render is provided as a template. This template is also the main argument
+to this directive. Place the directive on the HTML-Element where the tooltip should pop out
+when hovered over.
+Example :
<div [appTemplateTooltip]="tooltip">Hover here to show the tooltip</div>
+<ng-template #tooltip>
+ Custom tooltip <i>with</i> HTML-Elements
+</ng-template>
The template that is shown in the tooltip.
+You can get the template ref of an HTML-Element by using the #<template name> syntax.
+An <ng-template> Element won't be shown to the user by default. Therefore, it is the most commonly
+used element.
+Example :
<div [appTemplateTooltip]="tooltip">Hover here to show the tooltip</div>
+<ng-template #tooltip>
+ Custom tooltip <i>with</i> HTML-Elements
+</ng-template>
Whether to disable the tooltip, so it won't ever be shown
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import {
+ Directive,
+ ElementRef,
+ Input,
+ NgZone,
+ OnDestroy,
+ OnInit,
+ TemplateRef,
+} from "@angular/core";
+import {
+ Overlay,
+ OverlayPositionBuilder,
+ OverlayRef,
+} from "@angular/cdk/overlay";
+import { ComponentPortal } from "@angular/cdk/portal";
+import { TemplateTooltipComponent } from "./template-tooltip.component";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+
+/**
+ * A directive that can be used to render a custom tooltip that may contain HTML code.
+ * When a tooltip is only a string, the {@code MatTooltip} should be used instead.
+ *
+ * The Tooltip to render is provided as a template. This template is also the main argument
+ * to this directive. Place the directive on the HTML-Element where the tooltip should pop out
+ * when hovered over.
+ *
+ * @example
+ * <div [appTemplateTooltip]="tooltip">Hover here to show the tooltip</div>
+ * <ng-template #tooltip>
+ * Custom tooltip <i>with</i> HTML-Elements
+ * </ng-template>
+ *
+ * @see contentTemplate
+ */
+@UntilDestroy()
+@Directive({
+ selector: "[appTemplateTooltip]",
+ standalone: true,
+})
+export class TemplateTooltipDirective implements OnInit, OnDestroy {
+ /**
+ * Whether to disable the tooltip, so it won't ever be shown
+ */
+ @Input() tooltipDisabled: boolean = false;
+
+ /**
+ * The amount of time in milliseconds that the user has to hover over the element before the tooltip
+ * is shown
+ */
+ @Input() delayShow: number = 1000;
+
+ /**
+ * The amount of time in milliseconds that the user's mouse has to leave the tooltip before it will
+ * be hidden
+ */
+ @Input() delayHide: number = 150;
+
+ /**
+ * The template that is shown in the tooltip.
+ * You can get the template ref of an HTML-Element by using the `#<template name>` syntax.
+ * An `<ng-template>` Element won't be shown to the user by default. Therefore, it is the most commonly
+ * used element.
+ *
+ * @example
+ * <div [appTemplateTooltip]="tooltip">Hover here to show the tooltip</div>
+ * <ng-template #tooltip>
+ * Custom tooltip <i>with</i> HTML-Elements
+ * </ng-template>
+ */
+ @Input("appTemplateTooltip") contentTemplate!: TemplateRef<any>;
+
+ /**
+ * Reference to the overlay (the Tooltip) to control the visibility of the tooltip
+ * @private
+ */
+ private overlayRef!: OverlayRef;
+
+ /**
+ * The timeout used to deal both with the show-delay and the hide-delay
+ * @see delayHide
+ * @see delayShow
+ * @private
+ */
+ private timeoutRef?: ReturnType<typeof setTimeout>;
+
+ constructor(
+ private overlay: Overlay,
+ private overlayPositionBuilder: OverlayPositionBuilder,
+ private element: ElementRef<HTMLElement>,
+ private zone: NgZone,
+ ) {}
+
+ ngOnInit(): void {
+ // Create a position strategy that determines where the overlay is positioned.
+ // In this case, it should be positioned at the bottom-center of the element.
+ const positionStrategy = this.overlayPositionBuilder
+ .flexibleConnectedTo(this.element)
+ .withPositions([
+ {
+ originX: "center",
+ originY: "bottom",
+ overlayX: "center",
+ overlayY: "top",
+ offsetY: 5,
+ },
+ ]);
+
+ this.overlayRef = this.overlay.create({ positionStrategy });
+ this.zone.runOutsideAngular(() => {
+ this.element.nativeElement.addEventListener("mouseenter", () =>
+ this.show(),
+ );
+ this.element.nativeElement.addEventListener("mouseleave", (ev) =>
+ this.hide(ev.relatedTarget as HTMLElement),
+ );
+ });
+ }
+
+ ngOnDestroy() {
+ this.hide();
+ }
+
+ /**
+ * Show the tooltip unless
+ * - it is disabled or
+ * - it is already shown
+ * @private
+ */
+ private show() {
+ if (this.tooltipDisabled) {
+ return;
+ }
+ // clear the timeout so that when the user hovers twice the last hover action is used.
+ // Also clears the timeout from `hide`
+ if (this.timeoutRef) {
+ clearTimeout(this.timeoutRef);
+ }
+ // show the tooltip after `delayShown` milliseconds when it is not already shown
+ this.timeoutRef = setTimeout(() => {
+ //attach the component if it has not already attached to the overlay
+ if (!this.overlayRef.hasAttached()) {
+ this.zone.run(() => {
+ const tooltipRef = this.overlayRef.attach(
+ new ComponentPortal(TemplateTooltipComponent),
+ );
+ tooltipRef.instance.contentTemplate = this.contentTemplate;
+ tooltipRef.instance.hide
+ .pipe(untilDestroyed(this))
+ .subscribe(() => this.hide());
+ tooltipRef.instance.show
+ .pipe(untilDestroyed(this))
+ .subscribe(() => this.show());
+ });
+ }
+ }, this.delayShow);
+ }
+
+ /**
+ * Hide the tooltip unconditionally
+ * When the tooltip is already hidden, this operation is a noop
+ * @private
+ */
+ private hide(relatedTarget?: HTMLElement) {
+ // This ensures that `hide` is not called when the popup overlaps the element that this directive is on.
+ // If the method was called, the popup would flicker; disappearing (because of this method) and then
+ // re-appearing because of the `mouseenter` method.
+ if (
+ relatedTarget?.tagName === TemplateTooltipComponent.SELECTOR.toUpperCase()
+ ) {
+ return;
+ }
+
+ if (this.timeoutRef) {
+ clearTimeout(this.timeoutRef);
+ }
+ this.timeoutRef = setTimeout(() => {
+ if (this.overlayRef.hasAttached()) {
+ this.zone.run(() => this.overlayRef.detach());
+ }
+ }, this.delayHide);
+ }
+}
+
indicating that the value is not in its original state, so that components can explain this to the user
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "../model/entity";
+import { Directive, Input, OnChanges, SimpleChanges } from "@angular/core";
+
+@Directive()
+export abstract class ViewDirective<T, C = any> implements OnChanges {
+ @Input() entity: Entity;
+ @Input() id: string;
+ @Input() tooltip: string;
+ @Input() value: T;
+ @Input() config: C;
+
+ /** indicating that the value is not in its original state, so that components can explain this to the user */
+ isPartiallyAnonymized: boolean;
+
+ /**
+ * Attention:
+ * When content is loaded async in your child component, you need to manually trigger the change detection
+ * See: https://angularindepth.com/posts/1054/here-is-what-you-need-to-know-about-dynamic-components-in-angular#ngonchanges
+ *
+ */
+ ngOnChanges(changes?: SimpleChanges) {
+ this.isPartiallyAnonymized =
+ this.entity?.anonymized &&
+ this.entity?.getSchema()?.get(this.id)?.anonymize === "retain-anonymized";
+ }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
results matching ""
+
+
+
+
No results matching ""
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/documentation/fonts/ionicons.eot b/documentation/fonts/ionicons.eot
new file mode 100644
index 0000000000..4b1fd0f48c
Binary files /dev/null and b/documentation/fonts/ionicons.eot differ
diff --git a/documentation/fonts/ionicons.svg b/documentation/fonts/ionicons.svg
new file mode 100644
index 0000000000..ba35c41f6f
--- /dev/null
+++ b/documentation/fonts/ionicons.svg
@@ -0,0 +1,2090 @@
+
+
+
+
diff --git a/documentation/fonts/ionicons.ttf b/documentation/fonts/ionicons.ttf
new file mode 100644
index 0000000000..67bd84202a
Binary files /dev/null and b/documentation/fonts/ionicons.ttf differ
diff --git a/documentation/fonts/ionicons.woff b/documentation/fonts/ionicons.woff
new file mode 100644
index 0000000000..ec1c1f8795
Binary files /dev/null and b/documentation/fonts/ionicons.woff differ
diff --git a/documentation/fonts/ionicons.woff2 b/documentation/fonts/ionicons.woff2
new file mode 100644
index 0000000000..4233951c94
Binary files /dev/null and b/documentation/fonts/ionicons.woff2 differ
diff --git a/documentation/fonts/roboto-v15-latin-300.eot b/documentation/fonts/roboto-v15-latin-300.eot
new file mode 100644
index 0000000000..826acfda91
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-300.eot differ
diff --git a/documentation/fonts/roboto-v15-latin-300.svg b/documentation/fonts/roboto-v15-latin-300.svg
new file mode 100644
index 0000000000..52b2832799
--- /dev/null
+++ b/documentation/fonts/roboto-v15-latin-300.svg
@@ -0,0 +1,314 @@
+
+
+
diff --git a/documentation/fonts/roboto-v15-latin-300.ttf b/documentation/fonts/roboto-v15-latin-300.ttf
new file mode 100644
index 0000000000..66bc5ab8e2
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-300.ttf differ
diff --git a/documentation/fonts/roboto-v15-latin-300.woff b/documentation/fonts/roboto-v15-latin-300.woff
new file mode 100644
index 0000000000..7e6c479f2c
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-300.woff differ
diff --git a/documentation/fonts/roboto-v15-latin-300.woff2 b/documentation/fonts/roboto-v15-latin-300.woff2
new file mode 100644
index 0000000000..c34c128065
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-300.woff2 differ
diff --git a/documentation/fonts/roboto-v15-latin-700.eot b/documentation/fonts/roboto-v15-latin-700.eot
new file mode 100644
index 0000000000..f89cad7b7f
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-700.eot differ
diff --git a/documentation/fonts/roboto-v15-latin-700.svg b/documentation/fonts/roboto-v15-latin-700.svg
new file mode 100644
index 0000000000..fc8d42f92f
--- /dev/null
+++ b/documentation/fonts/roboto-v15-latin-700.svg
@@ -0,0 +1,310 @@
+
+
+
diff --git a/documentation/fonts/roboto-v15-latin-700.ttf b/documentation/fonts/roboto-v15-latin-700.ttf
new file mode 100644
index 0000000000..19090afb10
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-700.ttf differ
diff --git a/documentation/fonts/roboto-v15-latin-700.woff b/documentation/fonts/roboto-v15-latin-700.woff
new file mode 100644
index 0000000000..bf737c1c39
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-700.woff differ
diff --git a/documentation/fonts/roboto-v15-latin-700.woff2 b/documentation/fonts/roboto-v15-latin-700.woff2
new file mode 100644
index 0000000000..11cde5d04c
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-700.woff2 differ
diff --git a/documentation/fonts/roboto-v15-latin-italic.eot b/documentation/fonts/roboto-v15-latin-italic.eot
new file mode 100644
index 0000000000..f2d020a874
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-italic.eot differ
diff --git a/documentation/fonts/roboto-v15-latin-italic.svg b/documentation/fonts/roboto-v15-latin-italic.svg
new file mode 100644
index 0000000000..738b8295f0
--- /dev/null
+++ b/documentation/fonts/roboto-v15-latin-italic.svg
@@ -0,0 +1,323 @@
+
+
+
diff --git a/documentation/fonts/roboto-v15-latin-italic.ttf b/documentation/fonts/roboto-v15-latin-italic.ttf
new file mode 100644
index 0000000000..b0dd4a1e52
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-italic.ttf differ
diff --git a/documentation/fonts/roboto-v15-latin-italic.woff b/documentation/fonts/roboto-v15-latin-italic.woff
new file mode 100644
index 0000000000..a2b7704818
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-italic.woff differ
diff --git a/documentation/fonts/roboto-v15-latin-italic.woff2 b/documentation/fonts/roboto-v15-latin-italic.woff2
new file mode 100644
index 0000000000..1bb77f9d11
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-italic.woff2 differ
diff --git a/documentation/fonts/roboto-v15-latin-regular.eot b/documentation/fonts/roboto-v15-latin-regular.eot
new file mode 100644
index 0000000000..d26bc8f519
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-regular.eot differ
diff --git a/documentation/fonts/roboto-v15-latin-regular.svg b/documentation/fonts/roboto-v15-latin-regular.svg
new file mode 100644
index 0000000000..ed55c105d7
--- /dev/null
+++ b/documentation/fonts/roboto-v15-latin-regular.svg
@@ -0,0 +1,308 @@
+
+
+
diff --git a/documentation/fonts/roboto-v15-latin-regular.ttf b/documentation/fonts/roboto-v15-latin-regular.ttf
new file mode 100644
index 0000000000..7b25f3ce94
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-regular.ttf differ
diff --git a/documentation/fonts/roboto-v15-latin-regular.woff b/documentation/fonts/roboto-v15-latin-regular.woff
new file mode 100644
index 0000000000..941dfa4bae
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-regular.woff differ
diff --git a/documentation/fonts/roboto-v15-latin-regular.woff2 b/documentation/fonts/roboto-v15-latin-regular.woff2
new file mode 100644
index 0000000000..120796bb71
Binary files /dev/null and b/documentation/fonts/roboto-v15-latin-regular.woff2 differ
diff --git a/documentation/graph/dependencies.svg b/documentation/graph/dependencies.svg
new file mode 100644
index 0000000000..0dfa92d5e5
--- /dev/null
+++ b/documentation/graph/dependencies.svg
@@ -0,0 +1,870 @@
+
+
+
+
+
diff --git a/documentation/guards/AbstractPermissionGuard.html b/documentation/guards/AbstractPermissionGuard.html
new file mode 100644
index 0000000000..912eddf2f4
--- /dev/null
+++ b/documentation/guards/AbstractPermissionGuard.html
@@ -0,0 +1,637 @@
+
+
+
+
+
+ ndb-core documentation
+
+
+
+
+
+
+
+
+
+
+
Implement specific permission checks here, based on the given route data (from config)
+and any required services provided by Angular dependency injection.
A guard that checks the current users permission to interact with the entity of the route.
+Define requiredPermissionOperation in the route data / config, to enable a check that will find the relevant entity from config.
import { Injectable } from "@angular/core";
+import { CanActivate, Router } from "@angular/router";
+import { EntityAbility } from "../ability/entity-ability";
+import { AbstractPermissionGuard } from "./abstract-permission.guard";
+import { DynamicComponentConfig } from "../../config/dynamic-components/dynamic-component-config.interface";
+
+/**
+ * A guard that checks the current users permission to interact with the entity of the route.
+ * Define `requiredPermissionOperation` in the route data / config, to enable a check that will find the relevant entity from config.
+ */
+@Injectable()
+export class EntityPermissionGuard
+ extends AbstractPermissionGuard
+ implements CanActivate
+{
+ constructor(
+ router: Router,
+ private ability: EntityAbility,
+ ) {
+ super(router);
+ }
+
+ protected async canAccessRoute(
+ routeData: DynamicComponentConfig,
+ ): Promise<boolean> {
+ const operation = routeData?.["requiredPermissionOperation"] ?? "read";
+ const primaryEntity =
+ routeData?.["entityType"] ??
+ routeData?.["entity"] ??
+ routeData?.["config"]?.["entityType"] ??
+ routeData?.["config"]?.["entity"];
+
+ if (!primaryEntity) {
+ // No relevant config set => all users are allowed
+ return true;
+ }
+
+ if (this.ability.rules.length === 0) {
+ // wait till rules are initialised
+ await new Promise((res) => this.ability.on("updated", res));
+ }
+
+ return this.ability.can(operation, primaryEntity);
+ }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
results matching ""
+
+
+
+
No results matching ""
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/documentation/images/CICD-Flow.svg b/documentation/images/CICD-Flow.svg
new file mode 100644
index 0000000000..c9c10b23ec
--- /dev/null
+++ b/documentation/images/CICD-Flow.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/documentation/images/architecture_concrete-project.png b/documentation/images/architecture_concrete-project.png
new file mode 100644
index 0000000000..ac2258b3d0
Binary files /dev/null and b/documentation/images/architecture_concrete-project.png differ
diff --git a/documentation/images/architecture_core.png b/documentation/images/architecture_core.png
new file mode 100644
index 0000000000..aecaddce05
Binary files /dev/null and b/documentation/images/architecture_core.png differ
diff --git a/documentation/images/cascading-delete.png b/documentation/images/cascading-delete.png
new file mode 100644
index 0000000000..178781d676
Binary files /dev/null and b/documentation/images/cascading-delete.png differ
diff --git a/documentation/images/compodoc-vectorise-inverted.png b/documentation/images/compodoc-vectorise-inverted.png
new file mode 100644
index 0000000000..e95ccfb06c
Binary files /dev/null and b/documentation/images/compodoc-vectorise-inverted.png differ
diff --git a/documentation/images/compodoc-vectorise-inverted.svg b/documentation/images/compodoc-vectorise-inverted.svg
new file mode 100644
index 0000000000..d1479a564b
--- /dev/null
+++ b/documentation/images/compodoc-vectorise-inverted.svg
@@ -0,0 +1,201 @@
+
+
+
+
diff --git a/documentation/images/compodoc-vectorise.png b/documentation/images/compodoc-vectorise.png
new file mode 100644
index 0000000000..8137403549
Binary files /dev/null and b/documentation/images/compodoc-vectorise.png differ
diff --git a/documentation/images/compodoc-vectorise.svg b/documentation/images/compodoc-vectorise.svg
new file mode 100644
index 0000000000..5e21f1e3fd
--- /dev/null
+++ b/documentation/images/compodoc-vectorise.svg
@@ -0,0 +1,201 @@
+
+
+
+
diff --git a/documentation/images/config_service.png b/documentation/images/config_service.png
new file mode 100644
index 0000000000..dd831f1c65
Binary files /dev/null and b/documentation/images/config_service.png differ
diff --git a/documentation/images/coverage-badge-documentation.svg b/documentation/images/coverage-badge-documentation.svg
new file mode 100644
index 0000000000..6f76fa97f4
--- /dev/null
+++ b/documentation/images/coverage-badge-documentation.svg
@@ -0,0 +1,9 @@
+
diff --git a/documentation/images/domain-model.png b/documentation/images/domain-model.png
new file mode 100644
index 0000000000..b46afc197f
Binary files /dev/null and b/documentation/images/domain-model.png differ
diff --git a/documentation/images/entity-details-panels.png b/documentation/images/entity-details-panels.png
new file mode 100644
index 0000000000..ab843106f4
Binary files /dev/null and b/documentation/images/entity-details-panels.png differ
diff --git a/documentation/images/favicon.ico b/documentation/images/favicon.ico
new file mode 100644
index 0000000000..4144ee4613
Binary files /dev/null and b/documentation/images/favicon.ico differ
diff --git a/documentation/images/login-flow-new-user.svg b/documentation/images/login-flow-new-user.svg
new file mode 100644
index 0000000000..b3fe0304cf
--- /dev/null
+++ b/documentation/images/login-flow-new-user.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/initial__offline.svg b/documentation/images/new-session-flows/initial__offline.svg
new file mode 100644
index 0000000000..3f3c723e20
--- /dev/null
+++ b/documentation/images/new-session-flows/initial__offline.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/initial__online_correct_pwd.svg b/documentation/images/new-session-flows/initial__online_correct_pwd.svg
new file mode 100644
index 0000000000..6e5f681f2c
--- /dev/null
+++ b/documentation/images/new-session-flows/initial__online_correct_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/initial__online_wrong_pwd.svg b/documentation/images/new-session-flows/initial__online_wrong_pwd.svg
new file mode 100644
index 0000000000..25933126bb
--- /dev/null
+++ b/documentation/images/new-session-flows/initial__online_wrong_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/initial__sync_failed.svg b/documentation/images/new-session-flows/initial__sync_failed.svg
new file mode 100644
index 0000000000..dfac2ea479
--- /dev/null
+++ b/documentation/images/new-session-flows/initial__sync_failed.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/new-session-flows.md b/documentation/images/new-session-flows/new-session-flows.md
new file mode 100644
index 0000000000..23787cc529
--- /dev/null
+++ b/documentation/images/new-session-flows/new-session-flows.md
@@ -0,0 +1,551 @@
+# Sequence Diagrams for Session Handling
+
+## Usual Flows
+
+Local database is present, we are online, remote password was not changed.
+
+### Correct Password
+
+
+
+### Wrong Password
+
+
+
+## Offline Flows
+
+Local Database is present, but we are offline
+
+### Correct Password
+
+
+
+### Wrong Password
+
+
+
+We must retry with wait here, as we might be in a situation where the remote password changed and we should actually be able to log in. See these flows for details.
+
+## Password Changed
+
+Local Database is present, but we changed the password and password state is inconsistent between local and remote.
+
+### Use old password
+
+Works locally but not on the remote.
+
+
+
+### Use new password
+
+Works on the remote but not locally.
+
+
+
+## Sync Failed Flows
+
+So the remote session connected (yay!), but for some reason other than being offline the sync fails. I don't know how, but this might happen.
+
+### Local Login succeeded
+
+Easiest case. Just start the liveSync and hope everything works out eventually. There should be some sync-indicator listening to the sync state to make the user aware that something is going wrong in the background.
+
+
+
+### Local Login failed
+
+This is most probably a changed password case. However, as the sync failed, we cannot log the user in locally, so we have to keep the login failed. We also don't start a liveSync here, as it confuses the hell out of the UI to be not logged in but have a running (and intermittently failing) liveSync here. We might want to revisit this behavior, though.
+
+
+
+## Initial Sync Flows
+
+The local database is initial. We must wait for a first sync before we can log anyone in.
+
+### Online with correct password
+
+
+
+### Online with wrong password
+
+
+
+### Offline
+
+We can't have the local login pending for too long. We also don't want the login explicitly failed (resulting in wrong password messages), so we just switch back to logged off.
+
+
+
+### Some other terrible sync failure
+
+We don't know what to do in this case. We can't have the local login pending forever. We also don't want the login explicitly failed (resulting in wrong password messages), so we just switch back to logged off.
+
+
+
+# Mermaid Source
+
+All diagrams are done with Mermaid - markdown preview integration is available for vscode.
+
+## Usual Flows
+
+Local database is present, remote password was not changed.
+
+### Correct Password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGGED_IN
+ LocalSession-->>-SyncedSession: LoginState.LOGGED_IN
+ SyncedSession-->>User: LoginState.LOGGED_IN
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.COMPLETED
+ Note over LocalSession: SyncState.COMPLETED
+ Note over SyncedSession: liveSyncDeferred
+ deactivate Session
+ deactivate User
+```
+
+### Wrong Password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ LocalSession-->>-SyncedSession: LoginState.LOGIN_FAILED
+ SyncedSession-->>User: LoginState.LOGIN_FAILED
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: rejected
+ Note over RemoteSession: ConnectionState.REJECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.REJECTED
+
+ deactivate Session
+ deactivate User
+```
+
+## Offline Flows
+
+Local Database is present, but we are offline
+
+### Correct Password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGGED_IN
+ LocalSession-->>-SyncedSession: LoginState.LOGGED_IN
+ SyncedSession-->>User: LoginState.LOGGED_IN
+
+ RemoteSession->>+Remote PouchDB: login
+ Note over RemoteSession,Remote PouchDB: Offline Detection via fetch
+ Remote PouchDB-->>-RemoteSession: failed
+ Note over RemoteSession: ConnectionState.OFFLINE
+ RemoteSession-->>-SyncedSession: ConnectionState.OFFLINE
+
+ SyncedSession->>SyncedSession: login
+ Note over SyncedSession: retry with wait
+ deactivate Session
+ deactivate User
+```
+
+### Wrong Password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ LocalSession-->>-SyncedSession: LoginState.LOGIN_FAILED
+ SyncedSession-->>User: LoginState.LOGIN_FAILED
+
+ RemoteSession->>+Remote PouchDB: login
+ Note over RemoteSession,Remote PouchDB: Offline Detection via fetch
+ Remote PouchDB-->>-RemoteSession: failed
+ Note over RemoteSession: ConnectionState.OFFLINE
+ RemoteSession-->>-SyncedSession: ConnectionState.OFFLINE
+
+ SyncedSession->>SyncedSession: login
+ Note over SyncedSession: retry with wait
+ deactivate Session
+ deactivate User
+```
+
+We must retry with wait here, as we might be in a situation where the remote password changed and we should actually be able to log in. See these flows for details.
+
+## Password Changed
+
+Local Database is present, but we changed the password and password state is inconsistent between local and remote.
+
+### Use old password
+
+Works locally but not on the remote.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGGED_IN
+ LocalSession-->>-SyncedSession: LoginState.LOGGED_IN
+ SyncedSession-->>User: LoginState.LOGGED_IN
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: rejected
+ Note over RemoteSession: ConnectionState.REJECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.REJECTED
+
+ SyncedSession->>LocalSession: logout + fail
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ Note over User,SyncedSession: Login Guard rejects
+
+ deactivate Session
+ deactivate User
+```
+
+### Use new password
+
+Works on the remote but not locally.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ LocalSession-->>-SyncedSession: LoginState.LOGIN_FAILED
+ SyncedSession-->>User: LoginState.LOGIN_FAILED
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.COMPLETED
+ Note over LocalSession: SyncState.COMPLETED
+ SyncedSession->>LocalSession: login
+ Note over LocalSession: LoginState.LOGGED_IN
+ Note over User,SyncedSession: Login Guard to passes
+ Note over SyncedSession: liveSyncDeferred
+ deactivate Session
+ deactivate User
+```
+
+## Sync Failed Flows
+
+So the remote session connected (yay!), but for some reason other than being offline the sync fails. I don't know how, but this might happen.
+
+### Local Login succeeded
+
+Easiest case. Just start the liveSync and hope everything works out eventually. There should be some sync-indicator listening to the sync state to make the user aware that something is going wrong in the background.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGGED_IN
+ LocalSession-->>-SyncedSession: LoginState.LOGGED_IN
+ SyncedSession-->>User: LoginState.LOGGED_IN
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.FAILED
+ Note over LocalSession: SyncState.FAILED
+ Note over SyncedSession: liveSyncDeferred
+ deactivate Session
+ deactivate User
+```
+
+### Local Login failed
+
+This is most probably a changed password case. However, as the sync failed, we cannot log the user in locally, so we have to keep the login failed. We also don't start a liveSync here, as it confuses the hell out of the UI to be not logged in but have a running (and intermittently failing) liveSync here. We might want to revisit this behavior, though.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ LocalSession-->>-SyncedSession: LoginState.LOGIN_FAILED
+ SyncedSession-->>User: LoginState.LOGIN_FAILED
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.FAILED
+ Note over LocalSession: SyncState.FAILED
+ deactivate Session
+ deactivate User
+```
+
+## Initial Sync Flows
+
+The local database is initial. We must wait for a first sync before we can log anyone in.
+
+### Online with correct password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+LocalSession: waitForFirstSync
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.COMPLETED
+ Note over LocalSession: SyncState.COMPLETED
+
+ LocalSession->>-LocalSession: success
+ LocalSession->>+Local PouchDB: get User
+ Local PouchDB-->>-LocalSession: User
+ Note over LocalSession: LoginState.LOGGED_IN
+ LocalSession-->>-SyncedSession: LoginState.LOGGED_IN
+ SyncedSession-->>User: LoginState.LOGGED_IN
+
+ Note over SyncedSession: liveSyncDeferred
+ deactivate Session
+ deactivate User
+```
+
+### Online with wrong password
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+LocalSession: waitForFirstSync
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: rejected
+ Note over RemoteSession: ConnectionState.REJECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.REJECTED
+
+ SyncedSession->>LocalSession: set login and sync failed
+ Note over LocalSession: LoginState.LOGIN_FAILED
+ Note over LocalSession: SyncState.FAILED
+
+ LocalSession->>-LocalSession: failure
+ LocalSession-->>-SyncedSession: LoginState.LOGIN_FAILED
+ SyncedSession-->>User: LoginState.LOGIN_FAILED
+
+ deactivate Session
+ deactivate User
+```
+
+### Offline
+
+We can't have the local login pending for too long. We also don't want the login explicitly failed (resulting in wrong password messages), so we just switch back to logged off.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+LocalSession: waitForFirstSync
+
+ RemoteSession->>+Remote PouchDB: login
+ Note over RemoteSession,Remote PouchDB: Offline Detection via fetch
+ Remote PouchDB-->>-RemoteSession: rejected
+ Note over RemoteSession: ConnectionState.OFFLINE
+ RemoteSession-->>-SyncedSession: ConnectionState.OFFLINE
+
+ SyncedSession->>LocalSession: set sync failed
+ Note over LocalSession: SyncState.FAILED
+
+ LocalSession->>-LocalSession: failure
+ Note over LocalSession: LoginState.loggedOff
+ LocalSession-->>-SyncedSession: LoginState.loggedOff
+ SyncedSession-->>User: LoginState.loggedOff
+
+ Note over SyncedSession: liveSyncDeferred
+ deactivate Session
+ deactivate User
+```
+
+### Some other terrible sync failure
+
+We don't know what to do in this case. We can't have the local login pending forever. We also don't want the login explicitly failed (resulting in wrong password messages), so we just switch back to logged off.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant SyncedSession
+ participant LocalSession
+ participant Local PouchDB
+ participant RemoteSession
+ participant Remote PouchDB
+
+ activate User
+ User->>+SyncedSession: login
+ SyncedSession->>+LocalSession: login
+ SyncedSession->>+RemoteSession: login
+
+ LocalSession->>+LocalSession: waitForFirstSync
+
+ RemoteSession->>+Remote PouchDB: login
+ Remote PouchDB-->>-RemoteSession: connected
+ Note over RemoteSession: ConnectionState.CONNECTED
+ RemoteSession-->>-SyncedSession: ConnectionState.CONNECTED
+
+ SyncedSession->>+SyncedSession: sync
+ Note over LocalSession: SyncState.STARTED
+ SyncedSession-->>-SyncedSession: SyncState.FAILED
+ Note over LocalSession: SyncState.FAILED
+
+ LocalSession->>-LocalSession: failure
+
+ Note over LocalSession: LoginState.loggedOff
+ LocalSession-->>-SyncedSession: LoginState.loggedOff
+ SyncedSession-->>User: LoginState.loggedOff
+
+ deactivate Session
+ deactivate User
+```
diff --git a/documentation/images/new-session-flows/normal__right_pwd.svg b/documentation/images/new-session-flows/normal__right_pwd.svg
new file mode 100644
index 0000000000..cbad3c723c
--- /dev/null
+++ b/documentation/images/new-session-flows/normal__right_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/normal__wrong_pwd.svg b/documentation/images/new-session-flows/normal__wrong_pwd.svg
new file mode 100644
index 0000000000..51d74373ff
--- /dev/null
+++ b/documentation/images/new-session-flows/normal__wrong_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/offline__right_pwd.svg b/documentation/images/new-session-flows/offline__right_pwd.svg
new file mode 100644
index 0000000000..2c81a15dc6
--- /dev/null
+++ b/documentation/images/new-session-flows/offline__right_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/offline__wrong_pwd.svg b/documentation/images/new-session-flows/offline__wrong_pwd.svg
new file mode 100644
index 0000000000..c3d1a15e89
--- /dev/null
+++ b/documentation/images/new-session-flows/offline__wrong_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/pwd_changed__new_pwd.svg b/documentation/images/new-session-flows/pwd_changed__new_pwd.svg
new file mode 100644
index 0000000000..2bff1f6d70
--- /dev/null
+++ b/documentation/images/new-session-flows/pwd_changed__new_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/pwd_changed__old_pwd.svg b/documentation/images/new-session-flows/pwd_changed__old_pwd.svg
new file mode 100644
index 0000000000..300fa8f899
--- /dev/null
+++ b/documentation/images/new-session-flows/pwd_changed__old_pwd.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/sync_failed__local_login_failure.svg b/documentation/images/new-session-flows/sync_failed__local_login_failure.svg
new file mode 100644
index 0000000000..1955132651
--- /dev/null
+++ b/documentation/images/new-session-flows/sync_failed__local_login_failure.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/new-session-flows/sync_failed__local_login_success.svg b/documentation/images/new-session-flows/sync_failed__local_login_success.svg
new file mode 100644
index 0000000000..cfcfe1c39f
--- /dev/null
+++ b/documentation/images/new-session-flows/sync_failed__local_login_success.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/documentation/images/routed-views.png b/documentation/images/routed-views.png
new file mode 100644
index 0000000000..37beeea660
Binary files /dev/null and b/documentation/images/routed-views.png differ
diff --git a/documentation/images/session-uml.svg b/documentation/images/session-uml.svg
new file mode 100644
index 0000000000..2990eb416a
--- /dev/null
+++ b/documentation/images/session-uml.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/documentation/images/session_classes.png b/documentation/images/session_classes.png
new file mode 100644
index 0000000000..2c06a48dec
Binary files /dev/null and b/documentation/images/session_classes.png differ
diff --git a/documentation/images/session_state.png b/documentation/images/session_state.png
new file mode 100644
index 0000000000..7b759ca2be
Binary files /dev/null and b/documentation/images/session_state.png differ
diff --git a/documentation/images/state_handler.png b/documentation/images/state_handler.png
new file mode 100644
index 0000000000..7a293747b5
Binary files /dev/null and b/documentation/images/state_handler.png differ
diff --git a/documentation/images/system_overview.png b/documentation/images/system_overview.png
new file mode 100644
index 0000000000..2f8a76f883
Binary files /dev/null and b/documentation/images/system_overview.png differ
diff --git a/documentation/images/tech-stack.png b/documentation/images/tech-stack.png
new file mode 100644
index 0000000000..75803930a8
Binary files /dev/null and b/documentation/images/tech-stack.png differ
diff --git a/documentation/index.html b/documentation/index.html
new file mode 100644
index 0000000000..5d8109825b
--- /dev/null
+++ b/documentation/index.html
@@ -0,0 +1,247 @@
+
+
+
+
+
+ ndb-core documentation
+
+
+
+
+
+
+
+
+
+
+
Enabling social organizations digitally to transform lives.
+
Aam Digital is an easy-to-use case management software for the social sector that improves the effectiveness and transparency of work with beneficiaries in the field.
+
+
+
+
For more information about the software and an open demo system visit www.aam-digital.com.
+
+
+
For more information about the code including guides see the separate Developer Documentation
+
+
+
Installation, Use & Deployment
+
You can directly run the system using Docker.
+More information in our Aam-Digital/ndb-setup repository.
+In that case you do not have to clone this repository and install all the dependencies as everything is packaged into the docker image already.
+
The Aam Digital platform can be customized for different use cases through a flexible configuration file. This doesn't require changes to the generic platform code base in this repository:
+
+
The overall architecture and tech stack including backend services looks like this:
+
+
Development
+
Setup
+
+
This project depends on npm (NodeJS) to setup its dependencies. Please make sure you have npm installed.
+
git clone this repository to get all the code with its configuration and requirements.
+
npm install the dependencies (external libraries and packages)
+
npm run start to run your local dev server and get started.
+
+
By default the app is started with a "mock" session, generating demo data into an in-memory database.
+You can change this mode by editing the environment.ts
+(or create a file assets/config.json to overwrite settings; that file is on the .gitignore list).
Our detailed Developer Documentation
+provides tutorials, guides, concepts and an API reference.
+
Code Style
+
We use prettier to enforce a consistent formatting of code to make the project easier to read.
+The project is set up with a git pre-commit hook to automatically format your commits according to these rules.
+
Using Angular CLI
+
This project is built upon Angular.
+If you are unfamiliar with the framework and Angular CLI go check out the Angular CLI README or use use ng help.
+The following sections give you a brief overview.
+
Development server
+
Run npm run start for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
+
Code scaffolding (Generate new modules and components)
+
You can use Angular CLI to add new code to the project. Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|module.
+
Build
+
Run ng build -prod to build the project. The build artifacts will be stored in the dist/ directory. Use the -prod flag for a production build.
Run npm run e2e to execute the end-to-end tests via Cypress in the terminal.
+
Run npm run e2e-open to execute the end-to-end tests via Cypress own User Interface.
+
Build a docker image locally
+
Deployment on a server can be done through a docker image, our ndb-setup project provides tools and a starting point to run the system using docker.
+For more information about Docker, please refer to their official documentation.
+
To learn more about the build process, see /build.
+
+
Contribute
+
Our project is completely run by volunteers. Contributions welcome!
+
We are trying hard to make it easy for you to join in.
+As a starting point, please refer to our CONTRIBUTING page.
import { EventEmitter, Injectable } from "@angular/core";
+import { EntityConstructor } from "../entity/model/entity";
+
+/**
+ * Simply service to centralize updates between various admin components in the form builder.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class AdminEntityService {
+ public entitySchemaUpdated = new EventEmitter<void>();
+
+ /**
+ * Set a new schema field to the given entity and trigger update event for related admin components.
+ * @param entityType
+ * @param fieldId
+ * @param updatedEntitySchema
+ */
+ updateSchemaField(
+ entityType: EntityConstructor,
+ fieldId: any,
+ updatedEntitySchema: any,
+ ) {
+ entityType.schema.set(fieldId, updatedEntitySchema);
+ this.entitySchemaUpdated.next();
+ }
+}
+
import { Injectable } from "@angular/core";
+import { MatSnackBar, MatSnackBarConfig } from "@angular/material/snack-bar";
+
+import { AlertConfig, ExtendedAlertConfig } from "./alert-config";
+import { AlertDisplay } from "./alert-display";
+
+/**
+ * Display alerts to the user as a hovering message at the bottom of the view.
+ * (Angular Material "SnackBar")
+ *
+ * Inject this service in your classes to easily trigger alerts in the app consistent style.
+ *
+ * If you want to log technical details and problems, use {@link Logging} instead!
+ * This service is for user facing messages.
+ *
+ * You can also use the {@link MatSnackBar} when you want to have more control over what you
+ * want to display to the user.
+ */
+@Injectable({ providedIn: "root" })
+export class AlertService {
+ /** All alerts currently to be displayed */
+ alerts: ExtendedAlertConfig[] = [];
+
+ private static ALERT_BASE_CLASS = "ndb-alert";
+
+ constructor(private snackBar: MatSnackBar) {}
+
+ /**
+ * Display the given alert.
+ * @param alert The alert instance to be displayed
+ */
+ addAlert(alert: AlertConfig) {
+ this.alerts.push({ ...alert, timestamp: new Date() });
+ this.displayAlert(alert);
+ }
+
+ private displayAlert(alert: AlertConfig) {
+ const snackConfig: MatSnackBarConfig = {
+ duration: 10000,
+ };
+
+ switch (alert.display) {
+ case AlertDisplay.NONE:
+ return;
+ case AlertDisplay.TEMPORARY:
+ snackConfig.duration = 5000;
+ break;
+ case AlertDisplay.PERSISTENT:
+ snackConfig.duration = 3600000;
+ break;
+ }
+
+ snackConfig.panelClass = [
+ AlertService.ALERT_BASE_CLASS,
+ AlertService.ALERT_BASE_CLASS + "--" + alert.type,
+ ];
+
+ this.snackBar.open(
+ alert.message,
+ $localize`:alert dismiss action:dismiss`,
+ snackConfig,
+ );
+ }
+
+ /**
+ * Display an alert message of "Info" level, that will automatically dismiss itself after a timeout.
+ * @param message The text to be displayed
+ * @param display Optional override of the display style (e.g. whether the alert has to be actively dismissed by the user)
+ */
+ public addInfo(
+ message: string,
+ display: AlertDisplay = AlertDisplay.TEMPORARY,
+ ) {
+ this.addAlert({ message, type: "info", display });
+ }
+
+ /**
+ * Display an alert message of "Warning" level, that will have to be actively dismissed by the user.
+ * @param message The text to be displayed
+ * @param display Optional override of the display style (e.g. whether the alert has to be actively dismissed by the user)
+ */
+ public addWarning(
+ message: string,
+ display: AlertDisplay = AlertDisplay.PERSISTENT,
+ ) {
+ this.addAlert({ message, type: "warning", display });
+ }
+
+ /**
+ * Display an alert message of "Danger" level, that is highlighted and will have to be actively dismissed by the user.
+ * @param message The text to be displayed
+ * @param display Optional override of the display style (e.g. whether the alert has to be actively dismissed by the user)
+ */
+ public addDanger(
+ message: string,
+ display: AlertDisplay = AlertDisplay.PERSISTENT,
+ ) {
+ this.addAlert({ message, type: "danger", display });
+ }
+}
+
Fills the database with the provided JSON data.
+Data should be generated by the getJsonExport function
+
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Default value
+
Description
+
+
+
+
+
documents
+
+ any[]
+
+
+
+ No
+
+
+
+
+
+
+
An array of documents/raw entities to be directly written to the database
+
+
+
+
+
forceUpdate
+
+
+
+
+ No
+
+
+
+ false
+
+
+
+
should existing objects be overridden? Default false
+
+
+
+
+
+
+
+ Returns : Promise<void>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Injectable } from "@angular/core";
+import { Database } from "../../database/database";
+import { Config } from "../../config/config";
+
+/**
+ * Create and load backups of the database.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class BackupService {
+ constructor(private db: Database) {}
+
+ /**
+ * Creates an array holding all elements of the database.
+ * This method can be used to create a backup of the data.
+ */
+ async getDatabaseExport(): Promise<any[]> {
+ return await this.db.getAll();
+ }
+
+ /**
+ * Removes all but the config of the database
+ *
+ * @returns Promise<any> a promise that resolves after all remove operations are done
+ */
+ async clearDatabase(): Promise<void> {
+ const allDocs = await this.db.getAll();
+ for (const row of allDocs) {
+ if (row._id.startsWith(Config.ENTITY_TYPE + ":")) {
+ // skip config in order to not break login!
+ continue;
+ }
+ await this.db.remove(row);
+ }
+ }
+
+ /**
+ * Fills the database with the provided JSON data.
+ * Data should be generated by the `getJsonExport` function
+ *
+ * @param documents An array of documents/raw entities to be directly written to the database
+ * @param forceUpdate should existing objects be overridden? Default false
+ */
+ async restoreData(documents: any[], forceUpdate = false): Promise<void> {
+ for (const record of documents) {
+ // Remove _rev so CouchDB treats it as a new rather than a updated document
+ delete record._rev;
+ await this.db.put(record, forceUpdate);
+ }
+ }
+}
+
(Optional) cut-off boundary how many days into the past the analysis will be done.
+
+
+
+
+
+
+
+ Returns : Promise<Map<string, number>>
+
+
+
+
A map of childIds as key and days since last note as value;
+For performance reasons the days since last note are set to infinity when larger then the forLastNDays parameter
+
+
+
+
+
+
+
+
+
+
+
+
+ Public
+ Async
+ getNotesInTimespan
+
+
+
+
+
+
+
+ getNotesInTimespan(startDay: Date | Moment, endDay: Date | Moment)
+
Show a popup dialog with the ComingSoonComponent
+explaining that the requested feature is not available yet and integrating with usage analytics to track requests.
import { Injectable } from "@angular/core";
+import { MatDialog } from "@angular/material/dialog";
+import { ComingSoonComponent } from "./coming-soon/coming-soon.component";
+
+/**
+ * Show a popup dialog with the {@link ComingSoonComponent}
+ * explaining that the requested feature is not available yet and integrating with usage analytics to track requests.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class ComingSoonDialogService {
+ constructor(private dialog: MatDialog) {}
+
+ /**
+ * Open dialog with the coming soon page.
+ * @param featureId identifier to track requests for the given feature in usage analytics
+ */
+ open(featureId: string) {
+ this.dialog.open(ComingSoonComponent, { data: { featureId: featureId } });
+ }
+}
+
Show an (indeterminate) progress bar modal that cannot be closed by the user.
+Use the returned dialogRef to close the dialog once your processing is completed.
import { Injectable, NgZone } from "@angular/core";
+import { MatDialog } from "@angular/material/dialog";
+import {
+ ConfirmationDialogButton,
+ ConfirmationDialogComponent,
+ YesNoButtons,
+} from "./confirmation-dialog/confirmation-dialog.component";
+import { firstValueFrom } from "rxjs";
+import { ProgressDialogComponent } from "./progress-dialog/progress-dialog.component";
+
+/**
+ * Inject this service instead of MatDialog if you need a simple, configurable confirmation dialog box
+ * to be displayed to the user.
+ *
+ * Import the {@link ConfirmationDialogModule} in your root module to provide this service.
+ *
+ * @example
+ this.confirmationDialog
+ .getConfirmation('Delete?', 'Are you sure you want to delete this record?')
+ .then((confirmed) => {
+ if (confirmed) {
+ // delete
+ }
+ });
+ */
+@Injectable({ providedIn: "root" })
+export class ConfirmationDialogService {
+ constructor(
+ private dialog: MatDialog,
+ private ngZone: NgZone,
+ ) {}
+
+ /**
+ * Open a dialog with the given configuration.
+ * @param title The title displayed for the dialog
+ * @param text The text displayed for the dialog
+ * @param buttons The buttons to show. Defaults to 'yes' and 'no', but can be
+ * arbitrary
+ * @param closeButton Whether a single icon-button with an 'x' is shown to the user
+ * @returns promise that resolves to true if the user confirmed and false otherwise`
+ */
+ getConfirmation(
+ title: string,
+ text: string,
+ buttons: ConfirmationDialogButton[] = YesNoButtons,
+ closeButton = true,
+ ): Promise<boolean> {
+ const dialogRef = this.ngZone.run(() => {
+ return this.dialog.open(ConfirmationDialogComponent, {
+ data: {
+ title: title,
+ text: text,
+ buttons: buttons,
+ closeButton: closeButton,
+ },
+ });
+ });
+ return firstValueFrom(dialogRef.afterClosed());
+ }
+
+ getDiscardConfirmation() {
+ return this.getConfirmation(
+ $localize`:Discard changes header:Discard Changes?`,
+ $localize`:Discard changes message:You have unsaved changes. Do you really want to leave this page? All unsaved changes will be lost.`,
+ );
+ }
+
+ /**
+ * Show an (indeterminate) progress bar modal that cannot be closed by the user.
+ * Use the returned dialogRef to close the dialog once your processing is completed.
+ * @param message
+ */
+ showProgressDialog(message: string) {
+ return this.dialog.open(ProgressDialogComponent, {
+ data: { message },
+ minWidth: "50vh",
+ disableClose: true,
+ });
+ }
+}
+
The Entity linked to the currently logged-in user, which can be used to pre-fill forms or customize workflows.
+This might be undefined even when logged in. E.g. when using an administrative support account.
import { BehaviorSubject } from "rxjs";
+import { Entity } from "../entity/model/entity";
+import { Injectable } from "@angular/core";
+
+/**
+ * The Entity linked to the currently logged-in user, which can be used to pre-fill forms or customize workflows.
+ * This might be undefined even when logged in. E.g. when using an administrative support account.
+ */
+@Injectable()
+export class CurrentUserSubject extends BehaviorSubject<Entity> {
+ constructor() {
+ super(undefined);
+ }
+}
+
Manage database query index creation and use, working as a facade in front of the Database service.
+This allows to track pending indexing processes and also show them to users in the UI.
Generate and save a new database query index for the given entity type and property.
+
This allows you to efficiently query documents of that entity type based on values of the reference property,
+e.g. query all Notes (entityType=Note) that are related to a certain user (referenceProperty="authors").
+
Query this index using the given indexId like this:
+generateIndexOnProperty("myIndex", Note, "category");
+queryIndexDocs(Note, "myIndex/by_category")
Run a query on the database.
+If the required index does not exist (yet) this blocks the request by default
+and only runs and returns once the index is available.
+Example :
If no index exists this may result in an error (e.g. 404)
import { Injectable } from "@angular/core";
+import { Database, QueryOptions } from "../../database/database";
+import { BehaviorSubject, firstValueFrom, Observable } from "rxjs";
+import { BackgroundProcessState } from "../../ui/sync-status/background-process-state.interface";
+import { Entity, EntityConstructor } from "../model/entity";
+import { EntitySchemaService } from "../schema/entity-schema.service";
+import { first } from "rxjs/operators";
+
+/**
+ * Manage database query index creation and use, working as a facade in front of the Database service.
+ * This allows to track pending indexing processes and also show them to users in the UI.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class DatabaseIndexingService {
+ private _indicesRegistered = new BehaviorSubject<BackgroundProcessState[]>(
+ [],
+ );
+
+ /** All currently registered indices with their status */
+ get indicesRegistered(): Observable<BackgroundProcessState[]> {
+ return this._indicesRegistered.asObservable();
+ }
+
+ constructor(
+ private db: Database,
+ private entitySchemaService: EntitySchemaService,
+ ) {}
+
+ /**
+ * Register a new database query to be created/updated and indexed.
+ *
+ * This also triggers updates to the observable `indicesRegistered`.
+ *
+ * @param designDoc The design document (see @link{Database}) describing the query/index.
+ */
+ async createIndex(designDoc: any): Promise<void> {
+ const indexDetails = designDoc._id.replace(/_design\//, "");
+ const indexState: BackgroundProcessState = {
+ title: $localize`Preparing data (Indexing)`,
+ details: indexDetails,
+ pending: true,
+ };
+
+ const indexCreationPromise = this.db.saveDatabaseIndex(designDoc);
+ this._indicesRegistered.next([
+ ...this._indicesRegistered.value.filter(
+ (state) => state.details !== indexDetails,
+ ),
+ indexState,
+ ]);
+
+ try {
+ await indexCreationPromise;
+ } catch (err) {
+ indexState.pending = false;
+ indexState.error = err;
+ this._indicesRegistered.next(this._indicesRegistered.value);
+ throw err;
+ }
+
+ indexState.pending = false;
+ this._indicesRegistered.next(this._indicesRegistered.value);
+ }
+
+ /**
+ * Generate and save a new database query index for the given entity type and property.
+ *
+ * This allows you to efficiently query documents of that entity type based on values of the reference property,
+ * e.g. query all Notes (entityType=Note) that are related to a certain user (referenceProperty="authors").
+ *
+ * Query this index using the given indexId like this:
+ * generateIndexOnProperty("myIndex", Note, "category");
+ * queryIndexDocs(Note, "myIndex/by_category")
+ *
+ * @param indexId id to query this index after creation (--> {indexId}/by_{referenceProperty})
+ * @param entity entity type to limit the documents included in this index
+ * @param referenceProperty property key on the documents whose value is indexed as a query key
+ * @param secondaryIndex (optional) additional property to emit as a secondary index to narrow queries further
+ */
+ generateIndexOnProperty<
+ E extends Entity,
+ REF extends keyof E & string,
+ SEC extends keyof E & string,
+ >(
+ indexId: string,
+ entity: EntityConstructor<E>,
+ referenceProperty: REF,
+ secondaryIndex?: SEC,
+ ): Promise<void> {
+ const emitParamFormatter = (primaryParam) => {
+ if (secondaryIndex) {
+ return `emit([${primaryParam}, doc.${secondaryIndex}]);`;
+ } else {
+ return `emit(${primaryParam});`;
+ }
+ };
+
+ const simpleEmit = emitParamFormatter("doc." + referenceProperty);
+ const arrayEmit = `
+ if (!Array.isArray(doc.${referenceProperty})) return;
+ doc.${referenceProperty}.forEach((relatedEntity) => {
+ ${emitParamFormatter("relatedEntity")}
+ });`;
+
+ const designDoc = {
+ _id: "_design/" + indexId,
+ views: {
+ [`by_${referenceProperty}`]: {
+ map: `(doc) => {
+ if (!doc._id.startsWith("${entity.ENTITY_TYPE}")) return;
+
+ ${
+ entity.schema.get(referenceProperty).isArray
+ ? arrayEmit
+ : simpleEmit
+ }
+ }`,
+ },
+ },
+ };
+
+ return this.createIndex(designDoc);
+ }
+
+ /**
+ * Load data from the Database through the given, previously created index.
+ * @param entityConstructor
+ * @param indexName The name of the previously created index to be queried.
+ * @param options (Optional) additional query options object or a simple value used as the exact key to retrieve
+ */
+ async queryIndexDocs<T extends Entity>(
+ entityConstructor: EntityConstructor<T>,
+ indexName: string,
+ options: QueryOptions | string = {},
+ ): Promise<T[]> {
+ if (typeof options === "string") {
+ options = { key: options };
+ }
+ options.include_docs = true;
+
+ const rawResults = await this.queryIndexRaw(indexName, options);
+ return rawResults.rows.map((loadedRecord) => {
+ const entity = new entityConstructor("");
+ this.entitySchemaService.loadDataIntoEntity(entity, loadedRecord.doc);
+ return entity;
+ });
+ }
+
+ /**
+ * Load data from the Database through the given, previously created index for a key range.
+ * @param entityConstructor
+ * @param indexName The name of the previously created index to be queried.
+ * @param startkey start id of range to query
+ * @param endkey end id of range to query (inclusive)
+ */
+ async queryIndexDocsRange<T extends Entity>(
+ entityConstructor: EntityConstructor<T>,
+ indexName: string,
+ startkey: string | any[],
+ endkey?: string | any[],
+ ): Promise<T[]> {
+ if (Array.isArray(endkey)) {
+ endkey = [...endkey, {}];
+ } else {
+ endkey = endkey + "\ufff0";
+ }
+ return this.queryIndexDocs(entityConstructor, indexName, {
+ startkey: startkey,
+ endkey: endkey,
+ });
+ }
+
+ queryIndexStats(
+ indexName: string,
+ options: QueryOptions = {
+ reduce: true,
+ group: true,
+ },
+ ): Promise<any> {
+ return this.queryIndexRaw(indexName, options);
+ }
+
+ /**
+ * Run a query on the database.
+ * If the required index does not exist (yet) this blocks the request by default
+ * and only runs and returns once the index is available.
+ *
+ * @param indexName key of the database index to be used
+ * @param options additional options for the request
+ * @param doNotWaitForIndexCreation (Optional) flag to *not* block the query if the index doesn't exist yet.
+ * If no index exists this may result in an error (e.g. 404)
+ */
+ async queryIndexRaw(
+ indexName: string,
+ options: QueryOptions,
+ doNotWaitForIndexCreation?: boolean,
+ ): Promise<any> {
+ if (!doNotWaitForIndexCreation) {
+ await this.waitForIndexAvailable(indexName);
+ }
+
+ return this.db.query(indexName, options);
+ }
+
+ /**
+ * If the index is not created yet, wait until it is ready to avoid 404 errors.
+ * Returns immediately if index is already created.
+ * @param indexName
+ * @private
+ */
+ private async waitForIndexAvailable(indexName: string): Promise<void> {
+ function relevantIndexIsReady(processes, requiredIndexName) {
+ const relevantProcess = processes.find(
+ (process) =>
+ process.details === requiredIndexName ||
+ requiredIndexName.startsWith(process.details + "/"),
+ );
+ return relevantProcess && !relevantProcess.pending;
+ }
+
+ if (relevantIndexIsReady(this._indicesRegistered.value, indexName)) {
+ return;
+ }
+
+ await firstValueFrom(
+ this._indicesRegistered.pipe(
+ first((processes) => relevantIndexIsReady(processes, indexName)),
+ ),
+ );
+ }
+}
+
Datatype for the EntitySchemaService transforming values to Date instances.
+
This type is automatically used if you annotate a class's property that has the TypeScript type "Date"
+ensuring that even if values in the database might be some kind of date string they will be cast to Date instances.
+
For example:
+
@DatabaseField() myDate: Date; // will be a valid Date even if the database previously had "2020-01-15" as string
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
The human-readable name for this dataType, used in config UIs.
+
+
+
+
+
+
+
+
+
+
+
+
+
import { DefaultDatatype } from "../../entity/default-datatype/default.datatype";
+import { Injectable } from "@angular/core";
+import { EntitySchemaField } from "../../entity/schema/entity-schema-field";
+import moment from "moment";
+import { Logging } from "../../logging/logging.service";
+
+/**
+ * Datatype for the EntitySchemaService transforming values to Date instances.
+ *
+ * This type is automatically used if you annotate a class's property that has the TypeScript type "Date"
+ * ensuring that even if values in the database might be some kind of date string they will be cast to Date instances.
+ *
+ * For example:
+ *
+ * `@DatabaseField() myDate: Date; // will be a valid Date even if the database previously had "2020-01-15" as string`
+ */
+@Injectable()
+export class DateDatatype<DBFormat = any> extends DefaultDatatype<
+ Date,
+ DBFormat
+> {
+ static override dataType = "date";
+ // currently not shown to users in Admin UI, as this is not supported well with timezones and UI
+ // static override label: string = $localize`:datatype-label:date (with time)`;
+
+ override viewComponent = "DisplayDate";
+ override editComponent = "EditDate";
+
+ override transformToDatabaseFormat(value: Date) {
+ return value as any;
+ }
+
+ override transformToObjectFormat(
+ value,
+ schemaField: EntitySchemaField,
+ parent: any,
+ ) {
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) {
+ Logging.warn(
+ `failed to convert data '${value}' to Date object for ${parent?._id}`,
+ );
+ return undefined;
+ }
+ return date;
+ }
+
+ override importConfigComponent = "DateImportConfig";
+
+ override async importMapFunction(
+ val: any,
+ schemaField: EntitySchemaField,
+ additional?: any,
+ ) {
+ const date = moment(val, additional, true);
+ if (date.isValid()) {
+ return date.toDate();
+ } else {
+ return undefined;
+ }
+ }
+
+ override async anonymize(value: Date): Promise<Date> {
+ // normalize to 01.06. of the year, which has less statistical distortion than 01.01.
+ // (roughly half the dates before anonymization will be earlier and half will be later)
+ return new Date(value.getFullYear(), 6, 1);
+ }
+}
+
Datatype for the EntitySchemaService transforming Date values to/from a date string format ("YYYY-mm-dd").
+
Throws an exception if the property is set to something that is not a Date instance and cannot be cast to Date either.
+Uses the import value mapping properties of the general DateDatatype.
+
For example:
+@DatabaseField({dataType: 'date-only'}) myDate: Date = new Date('2020-01-15'); // will be "2020-01-15" (without time) in the database
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
import { dateToString } from "../../../utils/utils";
+import { Injectable } from "@angular/core";
+import { DateDatatype } from "../date/date.datatype";
+import { EntitySchemaField } from "../../entity/schema/entity-schema-field";
+
+/**
+ * Datatype for the EntitySchemaService transforming Date values to/from a date string format ("YYYY-mm-dd").
+ *
+ * Throws an exception if the property is set to something that is not a Date instance and cannot be cast to Date either.
+ * Uses the import value mapping properties of the general DateDatatype.
+ *
+ * For example:
+ * `@DatabaseField({dataType: 'date-only'}) myDate: Date = new Date('2020-01-15'); // will be "2020-01-15" (without time) in the database`
+ */
+@Injectable()
+export class DateOnlyDatatype extends DateDatatype<string> {
+ static override dataType = "date-only";
+ static override label: string = $localize`:datatype-label:date`;
+
+ override transformToDatabaseFormat(value: Date) {
+ if (!(value instanceof Date)) {
+ return undefined;
+ }
+ return dateToString(value);
+ }
+
+ override transformToObjectFormat(
+ value: string,
+ schemaField?: EntitySchemaField,
+ parent?: any,
+ ): Date {
+ value = migrateIsoDatesToInferredDateOnly(value);
+
+ // new Date("2022-01-01") is interpreted as UTC time whereas new Date(2022, 0, 1) is local time
+ // -> we want local time to represent the same day wherever used.
+ const values = value.split("-").map((v) => Number(v));
+ let date: Date = new Date(values[0], values[1] - 1, values[2]);
+ if (isNaN(date.getTime())) {
+ // fallback to legacy date parsing if format is not "YYYY-mm-dd"
+ date = new Date(value);
+ }
+
+ // re-use error logging and basic return logic from base type
+ return super.transformToObjectFormat(date, schemaField, parent);
+ }
+}
+
+function migrateIsoDatesToInferredDateOnly(value: string): string {
+ if (!value.match(/\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d\.\d\d\dZ/)) {
+ // not ISO Date format (2023-01-06T10:03:35.726Z)
+ return value;
+ }
+
+ const date = new Date(value);
+ if (
+ date.getMinutes() % 15 === 0 &&
+ date.getSeconds() === 0 &&
+ date.getMilliseconds() === 0
+ ) {
+ // this date was originally created without time information
+ // -> infer the time zone and adjust its offset
+ if (date.getHours() > 12) {
+ // adjust because these are showing the previous day due to timezone offset
+ date.setDate(date.getDate() + 1);
+ }
+ return dateToString(date);
+ }
+
+ // not a clean offset but a custom date => cannot reliably infer timezone here
+ // cut off the time details and use the UTC date
+ return value.substring(0, 10);
+}
+
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
Generate ChildSchoolRelation entities linking a child to a school for a specific year.
+Builds upon the generated demo Child and demo School entities,
+generating relations for each Child from the date of admission till dropout or today.
The DemoDataService is the manager for all provided DemoDataGenerator implementations.
+It serves as the central service to trigger the demo data generation into the database.
import {
+ ClassProvider,
+ FactoryProvider,
+ Injectable,
+ Injector,
+ ValueProvider,
+} from "@angular/core";
+import { DemoDataGenerator } from "./demo-data-generator";
+import { EntityMapperService } from "../entity/entity-mapper/entity-mapper.service";
+import { Database } from "../database/database";
+
+/**
+ * General config object to pass all initially register DemoDataGenerators
+ * with `DemoDataModule.forRoot()`.
+ *
+ * see docs at {@link DemoDataModule}
+ */
+export class DemoDataServiceConfig {
+ /**
+ * Providers for DemoDataGenerator service implementations to be registered for data generation.
+ *
+ * This may also include providers for services a DemoDataGenerator depends on.
+ */
+ dataGeneratorProviders: (ValueProvider | ClassProvider | FactoryProvider)[] =
+ [];
+}
+
+/**
+ * The DemoDataService is the manager for all provided DemoDataGenerator implementations.
+ * It serves as the central service to trigger the demo data generation into the database.
+ *
+ * To add more demo data generators, refer the documentation
+ * [How to Generate Demo Data]{@link /additional-documentation/how-to-guides/generate-demo-data.html}
+ */
+@Injectable()
+export class DemoDataService {
+ /** All registered demo data generator services */
+ readonly dataGenerators: DemoDataGenerator<any>[] = [];
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private injector: Injector,
+ private config: DemoDataServiceConfig,
+ private database: Database,
+ ) {}
+
+ private registerAllProvidedDemoDataGenerators() {
+ for (const provider of this.config.dataGeneratorProviders) {
+ const service = this.injector.get<any>(provider.provide);
+ if (service && service instanceof DemoDataGenerator) {
+ this.dataGenerators.push(service);
+ }
+ }
+ }
+
+ /**
+ * Trigger all registered DemoDataGenerator implementations to generate demo entities
+ * and add all the generated entities to the Database.
+ */
+ async publishDemoData() {
+ if (!(await this.database.isEmpty())) {
+ return;
+ }
+ this.registerAllProvidedDemoDataGenerators();
+
+ // completely generate all data (i.e. call every generator) before starting to save the data
+ // to allow generators to delete unwanted entities of other generators before they are saved
+ // (e.g. the DropoutChildGenerator should be able to delete Attendance records of the Child after its dropout date)
+ this.dataGenerators.forEach((generator) => generator.entities);
+
+ // save the generated data
+ for (const generator of this.dataGenerators) {
+ await this.entityMapper.saveAll(generator.entities);
+ // Wait for other async tasks in the queue e.g. ConfigService setting up config after it has been saved
+ await new Promise((resolve) => setTimeout(resolve));
+ }
+ }
+}
+
This function returns a provider object to be used in an Angular Module configuration:
+ providers: [DemoEducationalMaterialGeneratorService.provider()]
This function returns a provider object to be used in an Angular Module configuration:
+ providers: [DemoProgressDashboardWidgetGeneratorService.provider()]
import { Injectable } from "@angular/core";
+import { DemoDataGenerator } from "../../core/demo-data/demo-data-generator";
+import { PublicFormConfig } from "./public-form-config";
+
+@Injectable()
+export class DemoPublicFormGeneratorService extends DemoDataGenerator<PublicFormConfig> {
+ static provider() {
+ return [
+ {
+ provide: DemoPublicFormGeneratorService,
+ useClass: DemoPublicFormGeneratorService,
+ },
+ ];
+ }
+
+ protected generateEntities(): PublicFormConfig[] {
+ const form = new PublicFormConfig("test");
+ form.title = $localize`Example form`;
+ form.description = $localize`This is a form that can be shared as a link or embedded in a website. It can be filled by users without having an account. For example you can let participants self-register their details and just review the records within Aam Digital.`;
+ form.entity = "Child";
+ form.prefilled = { status: "new" };
+ form.columns = [["name", "phone", "gender", "dateOfBirth", "center"]];
+ return [form];
+ }
+}
+
This service allows to start a download process from the browser.
+Depending on the browser and the setting this might open a popup or directly download the file.
Builds all validator functions that are part of the configuration object.
+A validator function is a function that returns possible errors based
+on the state of a Form Field.
+If there is no Validator by a given name, issues a warning.
import { Injectable } from "@angular/core";
+import { EntityAction } from "./entity-action.interface";
+
+/**
+ * Register and access actions that can be performed on an entity
+ * and displayed to users in the entity details context menu.
+ *
+ * Feature Modules can register additional actions here.
+ *
+ * TODO: rename existing EntityActionsService to avoid confusions? (I would prefer this one here to be called EntityActionsService)
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class EntityActionsMenuService {
+ private actions: EntityAction[] = [];
+
+ getActions() {
+ return this.actions;
+ }
+
+ registerActions(newActions: EntityAction[]) {
+ this.actions.push(...newActions);
+ }
+}
+
Undo the archive action on the given entity or entities.
+
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
+
+
+
+
entityParam
+
+ E | E[]
+
+
+
+ No
+
+
+
+
+
+
+
+
+ Returns : unknown
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Injectable } from "@angular/core";
+import { EntityMapperService } from "../entity-mapper/entity-mapper.service";
+import { Entity } from "../model/entity";
+import { ConfirmationDialogService } from "../../common-components/confirmation-dialog/confirmation-dialog.service";
+import { MatSnackBar } from "@angular/material/snack-bar";
+import { Router } from "@angular/router";
+import { getUrlWithoutParams } from "../../../utils/utils";
+import { EntityDeleteService } from "./entity-delete.service";
+import { EntityAnonymizeService } from "./entity-anonymize.service";
+import { OkButton } from "../../common-components/confirmation-dialog/confirmation-dialog/confirmation-dialog.component";
+import { CascadingActionResult } from "./cascading-entity-action";
+import { EntityActionsMenuService } from "../../entity-details/entity-actions-menu/entity-actions-menu.service";
+
+/**
+ * A service that can triggers a user flow for entity actions (e.g. to safely remove or anonymize an entity),
+ * including a confirmation dialog.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class EntityActionsService {
+ constructor(
+ private confirmationDialog: ConfirmationDialogService,
+ private snackBar: MatSnackBar,
+ private router: Router,
+ private entityMapper: EntityMapperService,
+ private entityDelete: EntityDeleteService,
+ private entityAnonymize: EntityAnonymizeService,
+ entityActionsMenuService: EntityActionsMenuService,
+ ) {
+ entityActionsMenuService.registerActions([
+ {
+ action: "archive",
+ execute: (e) => this.archive(e),
+ permission: "update",
+ icon: "box-archive",
+ label: $localize`:entity context menu:Archive`,
+ tooltip: $localize`:entity context menu tooltip:Mark the record as inactive, hiding it from lists by default while keeping the data.`,
+ primaryAction: true,
+ },
+ {
+ action: "anonymize",
+ execute: (e) => this.anonymize(e),
+ permission: "update",
+ icon: "user-secret",
+ label: $localize`:entity context menu:Anonymize`,
+ tooltip: $localize`:entity context menu tooltip:Remove all personal data and keep an archived basic record for statistical reporting.`,
+ },
+ {
+ action: "delete",
+ execute: (e, nav) => this.delete(e, nav),
+ permission: "delete",
+ icon: "trash",
+ label: $localize`:entity context menu:Delete`,
+ tooltip: $localize`:entity context menu tooltip:Remove the record completely from the database.`,
+ },
+ ]);
+ }
+
+ showSnackbarConfirmationWithUndo(
+ message: string,
+ previousEntitiesForUndo: Entity[],
+ navigateBackToUrl?: string,
+ ) {
+ const snackBarRef = this.snackBar.open(
+ message,
+ $localize`:Undo an entity action:Undo`,
+ {
+ duration: 8000,
+ },
+ );
+
+ // Undo Action
+ snackBarRef.onAction().subscribe(async () => {
+ const undoProgressRef = this.confirmationDialog.showProgressDialog(
+ $localize`:Undo entity action progress dialog: Reverting changes ...`,
+ );
+ await this.entityMapper.saveAll(previousEntitiesForUndo, true);
+ undoProgressRef.close();
+
+ if (navigateBackToUrl) {
+ await this.router.navigate([navigateBackToUrl]);
+ }
+ });
+ }
+
+ /**
+ * Shows a confirmation dialog to the user
+ * and removes the entity if the user confirms.
+ *
+ * This also triggers a toast message, enabling the user to undo the action.
+ *
+ * @param entityParam The entity to remove
+ * @param navigate whether upon delete the app will navigate back
+ */
+ async delete<E extends Entity>(
+ entityParam: E | E[],
+ navigate: boolean = false,
+ ): Promise<boolean> {
+ let textForDeleteEntity = "";
+ let entities = Array.isArray(entityParam) ? entityParam : [entityParam];
+ if (entities.length > 1) {
+ textForDeleteEntity =
+ $localize`:Demonstrative pronoun plural:these` +
+ " " +
+ entities.length +
+ " " +
+ entities[0].getConstructor().labelPlural;
+ } else {
+ textForDeleteEntity =
+ $localize`:Definite article singular:the` +
+ " " +
+ entities[0].getConstructor().label +
+ ' "' +
+ entities[0].toString() +
+ '"';
+ }
+
+ if (
+ !(await this.confirmationDialog.getConfirmation(
+ $localize`:Delete confirmation title:Delete?`,
+ $localize`:Delete confirmation dialog:
+ This will remove the data permanently as if it never existed. This cannot be undone. Statistical reports (also for past time periods) will change and not include this record anymore.\n
+ If you have not just created a record accidentally, deleting this is probably not what you want to do. If a record represents something that actually happened in your work, consider to use "anonymize" or just "archive" instead, so that you will not lose your documentation for reports.\n
+ Are you sure you want to delete ${textForDeleteEntity}?`,
+ ))
+ ) {
+ return false;
+ }
+
+ const progressDialogRef = this.confirmationDialog.showProgressDialog(
+ $localize`:Entity action progress dialog:Processing ...`,
+ );
+ let result = new CascadingActionResult();
+
+ for (let entity of entities) {
+ result.mergeResults(await this.entityDelete.deleteEntity(entity, true));
+ }
+
+ progressDialogRef.close();
+
+ if (result.potentiallyRetainingPII.length > 0) {
+ await this.confirmationDialog.getConfirmation(
+ $localize`:post-delete related PII warning title:Related records may still contain personal data`,
+ $localize`:post-delete related PII warning dialog:Some related records (e.g. notes) may still contain personal data in their text. We have automatically deleted all records that are linked to ONLY ${textForDeleteEntity}.
+ However, there are some records that are linked to multiple records. We have not deleted these, so that you will not lose relevant data. Please review them manually to ensure all sensitive information is removed, if required (e.g. by looking through the linked notes and editing a note's text).`,
+ OkButton,
+ );
+ }
+
+ let currentUrl: string;
+ if (navigate) {
+ currentUrl = getUrlWithoutParams(this.router);
+ const parentUrl = currentUrl.substring(0, currentUrl.lastIndexOf("/"));
+ await this.router.navigate([parentUrl]);
+ }
+
+ this.showSnackbarConfirmationWithUndo(
+ this.generateMessageForConfirmationWithUndo(
+ entities.length > 0
+ ? entities
+ : [result.originalEntitiesBeforeChange[0]],
+ $localize`:Entity action confirmation message verb:deleted`,
+ ),
+ result.originalEntitiesBeforeChange,
+ currentUrl,
+ );
+ return true;
+ }
+
+ /**
+ * Anonymize the given entity,
+ * removing properties that are not explicitly configured in the schema to be retained.
+ *
+ * This triggers UX interactions like confirmation request dialog and snackbar message as well.
+ *
+ * @param entityParam
+ */
+ async anonymize<E extends Entity>(entityParam: E | E[]) {
+ let entities = Array.isArray(entityParam) ? entityParam : [entityParam];
+ let textForAnonymizeEntity = "";
+
+ if (entities.length > 1) {
+ textForAnonymizeEntity =
+ $localize`:Demonstrative pronoun plural:these` +
+ " " +
+ entities.length +
+ " " +
+ entities[0].getConstructor().labelPlural;
+ } else {
+ textForAnonymizeEntity =
+ $localize`:Definite article singular:the` +
+ " " +
+ entities[0].getConstructor().label +
+ ' "' +
+ entities[0].toString() +
+ '"';
+ }
+
+ if (
+ !(await this.confirmationDialog.getConfirmation(
+ $localize`:Anonymize confirmation dialog:Anonymize?`,
+ $localize`:Anonymize confirmation dialog:
+ This will remove all personal information (PII) permanently and keep only a basic record for statistical reports. Details that are removed during anonymization cannot be recovered.\n
+ If a record has only become inactive and you want to keep all details, consider to use "archive" instead.\n
+ Are you sure you want to anonymize ${textForAnonymizeEntity}?`,
+ ))
+ ) {
+ return false;
+ }
+
+ const progressDialogRef = this.confirmationDialog.showProgressDialog(
+ $localize`:Entity action progress dialog:Processing ...`,
+ );
+ let result = new CascadingActionResult();
+ for (let entity of entities) {
+ result.mergeResults(await this.entityAnonymize.anonymizeEntity(entity));
+ }
+ progressDialogRef.close();
+
+ if (result.potentiallyRetainingPII.length > 0) {
+ await this.confirmationDialog.getConfirmation(
+ $localize`:post-anonymize related PII warning title:Related records may still contain personal data`,
+ $localize`:post-anonymize related PII warning dialog:Some related records (e.g. notes) may still contain personal data in their text. We have automatically anonymized all records that are linked to ONLY ${textForAnonymizeEntity}.
+ However, there are some records that are linked to multiple records. We have not anonymized these, so that you will not lose relevant data. Please review them manually to ensure all sensitive information is removed (e.g. by looking through the linked notes and editing a note's text).`,
+ OkButton,
+ );
+ }
+
+ this.showSnackbarConfirmationWithUndo(
+ this.generateMessageForConfirmationWithUndo(
+ entities.length > 0
+ ? entities
+ : [result.originalEntitiesBeforeChange[0]],
+ $localize`:Entity action confirmation message verb:anonymized`,
+ ),
+ result.originalEntitiesBeforeChange,
+ );
+ return true;
+ }
+
+ /**
+ * Mark the given entity as inactive.
+ * @param entity
+ */
+ async archive<E extends Entity>(entityParam: E | E[]) {
+ let originalEntities: E[] = Array.isArray(entityParam)
+ ? entityParam
+ : [entityParam];
+ const newEntities: E[] = originalEntities.map((e) => e.copy());
+ newEntities.forEach(async (e) => {
+ e.inactive = true;
+ await this.entityMapper.save(e);
+ });
+
+ this.showSnackbarConfirmationWithUndo(
+ this.generateMessageForConfirmationWithUndo(
+ newEntities,
+ $localize`:Entity action confirmation message verb:archived`,
+ ),
+ originalEntities,
+ );
+ return true;
+ }
+ /**
+ * Undo the archive action on the given entity or entities.
+ * @param entity
+ */
+ async undoArchive<E extends Entity>(entityParam: E | E[]) {
+ let newEntities: E[] = Array.isArray(entityParam)
+ ? entityParam
+ : [entityParam];
+ const originalEntities: E[] = newEntities.map((e) => e.copy());
+ newEntities.forEach(async (e) => {
+ e.inactive = false;
+ await this.entityMapper.save(e);
+ });
+
+ this.showSnackbarConfirmationWithUndo(
+ this.generateMessageForConfirmationWithUndo(
+ newEntities,
+ $localize`:Entity action confirmation message verb:reactivated`,
+ ),
+ originalEntities,
+ );
+ return true;
+ }
+
+ private generateMessageForConfirmationWithUndo(
+ entities: Entity[],
+ action: string,
+ ): string {
+ if (entities.length > 1) {
+ return $localize`:Entity action confirmation message:${entities.length} ${
+ entities[0].getConstructor().labelPlural
+ } ${action}`;
+ } else {
+ return $localize`:Entity action confirmation message:${
+ entities[0].getConstructor().label
+ } "${entities.toString()}" ${action}`;
+ }
+ }
+}
+
Anonymize an entity including handling references with related entities.
+This service is usually used in combination with the EntityActionsService, which provides user confirmation processes around this.
A service that allows to work with configuration-objects
+related to entities such as assigning dynamic attributes
+and their schemas to existing entities
Assigns additional schema-fields to all entities that are
+defined inside the config. Entities that are not registered
+using the DatabaseEntity-Decorator won't work and will
+trigger an error message
Safely delete an entity including handling references with related entities.
+This service is usually used in combination with the EntityActionsService, which provides user confirmation processes around this.
This function applies the changes of the formGroup to the entity.
+If the form is invalid or the entity does not pass validation after applying the changes, an error will be thrown.
+The input entity will not be modified but a copy of it will be returned in case of success.
Handles loading and saving of data for any higher-level feature module.
+The EntityMapperService implicitly transforms objects from instances of Entity classes to the format to be written
+to the database and back - ensuring they you always receive instances of Entity subclasses, that you can
+simply treat them as normal javascript class instances without worrying about database persistance logic.
+
To understand more about how to use the Entity system in your own modules, refer to the How-To Guides:
Load all entities from the database of the given type (for example a list of entities of the type User).
+Important: Loading via the constructor is always preferred compared to loading via string. The latter
+doesn't allow strict type-checking and errors can only be discovered later
subscribe to this observable to receive updates whenever the state of
+an entity of a certain type changes.
+The updated-parameter will return the new entity as well as a field that
+describes the type of update (either "new", "update" or "remove").
+
+This can be used in collaboration with the update(UpdatedEntity, Entities)-function
+to update a list of entities
+
+
Important: Loading via the constructor is always preferred compared to loading via string. The latter
+doesn't allow strict type-checking and errors can only be discovered later
Save an entity to the database after transforming it to its database representation.
+ if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
Optional flag whether any conflicting version in the database will be quietly overwritten.
+if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
Saves an array of entities that are possibly heterogeneous, i.e.
+the entity-type of all the entities does not have to be the same.
+This method should be chosen whenever a bigger number of entities needs to be
+saved
+ if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
Optional flag whether any conflicting version in the database will be quietly overwritten.
+if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
import { Injectable } from "@angular/core";
+import { Database } from "../../database/database";
+import { Entity, EntityConstructor } from "../model/entity";
+import { EntitySchemaService } from "../schema/entity-schema.service";
+import { Observable } from "rxjs";
+import { UpdatedEntity } from "../model/entity-update";
+import { EntityRegistry } from "../database-entity.decorator";
+import { map } from "rxjs/operators";
+import { UpdateMetadata } from "../model/update-metadata";
+import { CurrentUserSubject } from "../../session/current-user-subject";
+
+/**
+ * Handles loading and saving of data for any higher-level feature module.
+ * The EntityMapperService implicitly transforms objects from instances of Entity classes to the format to be written
+ * to the database and back - ensuring they you always receive instances of {@link Entity} subclasses, that you can
+ * simply treat them as normal javascript class instances without worrying about database persistance logic.
+ *
+ * To understand more about how to use the Entity system in your own modules, refer to the How-To Guides:
+ * - [How to Load and Save Data]{@link /additional-documentation/how-to-guides/load-and-save-data.html}
+ * - [How to Create a new Entity Type]{@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
+ */
+@Injectable({ providedIn: "root" })
+export class EntityMapperService {
+ constructor(
+ private _db: Database,
+ private entitySchemaService: EntitySchemaService,
+ private currentUser: CurrentUserSubject,
+ private registry: EntityRegistry,
+ ) {}
+
+ /**
+ * Load an Entity from the database with the given id or the registered name of that class.
+ *
+ * @param entityType Class that implements Entity, which is the type of Entity the results should be transformed to
+ * @param id The id of the entity to load
+ * @returns A Promise resolving to an instance of entityType filled with its data.
+ */
+ public async load<T extends Entity>(
+ entityType: EntityConstructor<T> | string,
+ id: string,
+ ): Promise<T> {
+ const ctor = this.resolveConstructor(entityType);
+ const entityId = Entity.createPrefixedId(ctor.ENTITY_TYPE, id);
+ const result = await this._db.get(entityId);
+ return this.transformToEntityFormat(result, ctor);
+ }
+
+ /**
+ * Load all entities from the database of the given type (for example a list of entities of the type User).
+ * <em>Important:</em> Loading via the constructor is always preferred compared to loading via string. The latter
+ * doesn't allow strict type-checking and errors can only be discovered later
+ *
+ * @param entityType Class that implements Entity, which is the type of Entity the results should be transformed to
+ * or the registered name of that class.
+ * @returns A Promise resolving to an array of instances of entityType with the data of the loaded entities.
+ */
+ public async loadType<T extends Entity>(
+ entityType: EntityConstructor<T> | string,
+ ): Promise<T[]> {
+ const ctor = this.resolveConstructor(entityType);
+ const records = await this._db.getAll(ctor.ENTITY_TYPE + ":");
+ return records.map((rec) => this.transformToEntityFormat(rec, ctor));
+ }
+
+ private transformToEntityFormat<T extends Entity>(
+ record: any,
+ ctor: EntityConstructor<T>,
+ ): T {
+ const entity = new ctor("");
+ try {
+ this.entitySchemaService.loadDataIntoEntity(entity, record);
+ } catch (e) {
+ // add _id information to error message
+ e.message = `Could not transform entity "${record._id}": ${e.message}`;
+ throw e;
+ }
+ return entity;
+ }
+
+ /**
+ * subscribe to this observable to receive updates whenever the state of
+ * an entity of a certain type changes.
+ * The updated-parameter will return the new entity as well as a field that
+ * describes the type of update (either "new", "update" or "remove").
+ * <br>
+ * This can be used in collaboration with the update(UpdatedEntity, Entities)-function
+ * to update a list of entities
+ * <br>
+ *
+ * <em>Important:</em> Loading via the constructor is always preferred compared to loading via string. The latter
+ * doesn't allow strict type-checking and errors can only be discovered later
+ * @param entityType the type of the entity or the registered name of that class.
+ */
+ public receiveUpdates<T extends Entity>(
+ entityType: EntityConstructor<T> | string,
+ ): Observable<UpdatedEntity<T>> {
+ const ctor = this.resolveConstructor(entityType);
+ const type = new ctor().getType();
+ return this._db.changes(type + ":").pipe(
+ map((doc) => {
+ const entity = new ctor();
+ this.entitySchemaService.loadDataIntoEntity(entity, doc);
+ if (doc._deleted) {
+ return { type: "remove", entity: entity };
+ } else if (doc._rev.startsWith("1-")) {
+ // This does not cover all the cases as docs with higher rev-number might be synchronized for the first time
+ return { type: "new", entity: entity };
+ } else {
+ return { type: "update", entity: entity };
+ }
+ }),
+ );
+ }
+
+ /**
+ * Save an entity to the database after transforming it to its database representation.
+ * @param entity The entity to be saved
+ * @param forceUpdate Optional flag whether any conflicting version in the database will be quietly overwritten.
+ * if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
+ */
+ public async save<T extends Entity>(
+ entity: T,
+ forceUpdate: boolean = false,
+ ): Promise<any> {
+ this.setEntityMetadata(entity);
+ const rawData =
+ this.entitySchemaService.transformEntityToDatabaseFormat(entity);
+ const result = await this._db.put(rawData, forceUpdate);
+ if (result?.ok) {
+ entity._rev = result.rev;
+ }
+ return result;
+ }
+
+ /**
+ * Saves an array of entities that are possibly heterogeneous, i.e.
+ * the entity-type of all the entities does not have to be the same.
+ * This method should be chosen whenever a bigger number of entities needs to be
+ * saved
+ * @param entities The entities to save
+ * @param forceUpdate Optional flag whether any conflicting version in the database will be quietly overwritten.
+ * if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
+ */
+ public async saveAll(
+ entities: Entity[],
+ forceUpdate: boolean = false,
+ ): Promise<any[]> {
+ entities.forEach((e) => this.setEntityMetadata(e));
+ const rawData = entities.map((e) =>
+ this.entitySchemaService.transformEntityToDatabaseFormat(e),
+ );
+ const results = await this._db.putAll(rawData, forceUpdate);
+ results.forEach((res, idx) => {
+ if (res.ok) {
+ const entity = entities[idx];
+ entity._rev = res.rev;
+ }
+ });
+ return results;
+ }
+
+ /**
+ * Delete an entity from the database.
+ * @param entity The entity to be deleted
+ */
+ public remove<T extends Entity>(entity: T): Promise<any> {
+ return this._db.remove(entity);
+ }
+
+ protected resolveConstructor<T extends Entity>(
+ constructible: EntityConstructor<T> | string,
+ ): EntityConstructor<T> | undefined {
+ if (typeof constructible === "string") {
+ return this.registry.get(constructible) as EntityConstructor<T>;
+ } else {
+ return constructible;
+ }
+ }
+
+ protected setEntityMetadata(entity: Entity) {
+ const newMetadata = new UpdateMetadata(this.currentUser.value?.getId());
+ if (entity.isNew) {
+ entity.created = newMetadata;
+ }
+ entity.updated = newMetadata;
+ }
+}
+
Transform between entity instances and database objects
+based on the dataType set for properties in Entity classes using the DatabaseField annotation.
+
You can inject the EntitySchemaService in your code to register your custom DefaultDatatype implementations.
+
This service is used by the EntityMapperService to internally transform objects.
+You should normally use the EntityMapperService instead of transforming objects yourself with the EntitySchemaService.
Get the name of the component that should display this property.
+The edit component has to be a registered component. Components that are registered contain the DynamicComponent
+decorator
import { Entity, EntityConstructor } from "../model/entity";
+import { Injectable, Injector } from "@angular/core";
+import { EntitySchema } from "./entity-schema";
+import { EntitySchemaField } from "./entity-schema-field";
+import { DefaultDatatype } from "../default-datatype/default.datatype";
+import { EntityRegistry } from "../database-entity.decorator";
+import { asArray } from "../../../utils/utils";
+
+/**
+ * Transform between entity instances and database objects
+ * based on the dataType set for properties in Entity classes using the {@link DatabaseField} annotation.
+ *
+ * You can inject the EntitySchemaService in your code to register your custom {@link DefaultDatatype} implementations.
+ *
+ * This service is used by the {@link EntityMapperService} to internally transform objects.
+ * You should normally use the EntityMapperService instead of transforming objects yourself with the EntitySchemaService.
+ *
+ * also see the How-To Guides:
+ * - [Create A New Entity Type]{@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
+ */
+@Injectable({ providedIn: "root" })
+export class EntitySchemaService {
+ /**
+ * Internal cache of datatype implementations.
+ */
+ private schemaTypes = new Map<string, DefaultDatatype>();
+
+ private defaultDatatype: DefaultDatatype = new DefaultDatatype();
+
+ constructor(private injector: Injector) {}
+
+ /**
+ * Get the datatype for the giving name (or the default datatype if no other registered type fits)
+ * @param datatypeName The key/name of the datatype
+ * @param failSilently If set to 'true' no error is thrown if datatype does not exist
+ */
+ public getDatatypeOrDefault(datatypeName: string, failSilently = false) {
+ if (!datatypeName) {
+ return this.defaultDatatype;
+ }
+ if (this.schemaTypes.has(datatypeName)) {
+ return this.schemaTypes.get(datatypeName);
+ }
+
+ // use Injector instead of normal dependency injection in the constructor, because some Datatypes use the SchemaService (--> Circular Dependency)
+ const dataTypes: DefaultDatatype[] = this.injector.get(
+ DefaultDatatype,
+ ) as unknown as DefaultDatatype[];
+
+ let dataType = dataTypes.find((d) => d.dataType === datatypeName);
+ if (dataType) {
+ this.schemaTypes.set(datatypeName, dataType);
+ return dataType;
+ } else if (!failSilently) {
+ throw new Error(`Data type "${datatypeName}" does not exist`);
+ }
+ }
+
+ /**
+ * Transform a database object to entity format according to the schema.
+ * @param data The database object that will be transformed to the given entity format
+ * @param schema A schema defining the transformation
+ */
+ public transformDatabaseToEntityFormat<T = Entity>(
+ data: any,
+ schema: EntitySchema,
+ ): T {
+ const transformed = {};
+ for (const key of schema.keys()) {
+ const schemaField: EntitySchemaField = schema.get(key);
+
+ if (data[key] === undefined) {
+ continue;
+ }
+
+ const newValue = this.valueToEntityFormat(data[key], schemaField, data);
+ if (newValue !== undefined) {
+ transformed[key] = newValue;
+ }
+
+ if (schemaField.generateIndex) {
+ throw new Error('schema option "isIndexed" not implemented yet');
+ }
+ }
+
+ return transformed as T;
+ }
+
+ /**
+ * Helper function to assign the giving data to the given entity instance after transforming it according to the schema.
+ * @param entity An entity instance whose properties will be overwritten with the transformed data
+ * @param data The database object that will be transformed and assigned to the entity
+ */
+ public loadDataIntoEntity<E extends Entity>(entity: E, data: any): E {
+ const transformed = this.transformDatabaseToEntityFormat(
+ data,
+ (<typeof Entity>entity.constructor).schema,
+ );
+ return Object.assign(entity, transformed);
+ }
+
+ /**
+ * Transform an entity instance to a database object according to the schema.
+ * @param entity The object (an instance of an entity type)
+ * @param schema The schema of the entity (if not explicitly defined the schema of the given entity is used)
+ */
+ public transformEntityToDatabaseFormat(
+ entity: Entity,
+ schema?: EntitySchema,
+ ): any {
+ if (!schema) {
+ schema = entity.getSchema();
+ }
+
+ const data = {};
+
+ for (const key of schema.keys()) {
+ let value = entity[key];
+ const schemaField: EntitySchemaField = schema.get(key);
+
+ if (value === undefined) {
+ // skip and keep undefined
+ continue;
+ }
+
+ try {
+ data[key] = this.valueToDatabaseFormat(value, schemaField, entity);
+ } catch (err) {
+ throw new Error(`Transformation for ${key} failed: ${err}`);
+ }
+
+ if (data[key] === undefined) {
+ delete data[key];
+ }
+ }
+
+ return data;
+ }
+
+ /**
+ * Get the name of the component that should display this property.
+ * The edit component has to be a registered component. Components that are registered contain the `DynamicComponent`
+ * decorator
+ *
+ * @param propertySchema The schema definition of the attribute for which a component should be get
+ * @param mode (Optional) The mode for which a component is required. Default is "view".
+ * @returns string The name of the component which should display this property
+ */
+ getComponent(
+ propertySchema: EntitySchemaField,
+ mode: "view" | "edit" = "view",
+ ): string {
+ if (!propertySchema) {
+ return undefined;
+ }
+ const componentAttribute =
+ mode === "view" ? "viewComponent" : "editComponent";
+ if (propertySchema[componentAttribute]) {
+ return propertySchema[componentAttribute];
+ }
+
+ const dataType = this.getDatatypeOrDefault(propertySchema.dataType);
+ if (dataType?.[componentAttribute]) {
+ return dataType[componentAttribute];
+ }
+ }
+
+ /**
+ * Transform a single value into database format
+ * @param value
+ * @param schemaField
+ * @param entity
+ */
+ valueToDatabaseFormat(
+ value: any,
+ schemaField: EntitySchemaField,
+ entity?: Entity,
+ ) {
+ if (value === null) {
+ // keep 'null' to be able to explicitly mark a value as being reset
+ return null;
+ }
+
+ const dataType = this.getDatatypeOrDefault(schemaField.dataType);
+ if (schemaField.isArray) {
+ return asArray(value).map((v) =>
+ dataType.transformToDatabaseFormat(v, schemaField, entity),
+ );
+ } else {
+ return dataType.transformToDatabaseFormat(value, schemaField, entity);
+ }
+ }
+
+ /**
+ * Transform a single value into entity format
+ * @param value
+ * @param schemaField
+ * @param dataObject
+ */
+ valueToEntityFormat(
+ value: any,
+ schemaField: EntitySchemaField,
+ dataObject?: any,
+ ) {
+ if (value === null) {
+ // keep 'null' to be able to explicitly mark a value as being reset
+ return null;
+ }
+
+ const dataType = this.getDatatypeOrDefault(schemaField.dataType);
+ if (schemaField.isArray) {
+ return asArray(value).map((v) =>
+ dataType.transformToObjectFormat(v, schemaField, dataObject),
+ );
+ } else {
+ return dataType.transformToObjectFormat(value, schemaField, dataObject);
+ }
+ }
+
+ /**
+ * Get all entity types whose schema includes fields referencing the given type.
+ *
+ * e.g. given Child -> [Note, ChildSchoolRelation, ...]
+ * @param type
+ */
+ getEntityTypesReferencingType(type: string): {
+ entityType: EntityConstructor;
+ referencingProperties: string[];
+ }[] {
+ const referencingTypes = [];
+ for (const t of this.injector.get(EntityRegistry).values()) {
+ for (const [key, field] of t.schema.entries()) {
+ if (asArray(field.additional).includes(type)) {
+ let refType = referencingTypes.find((e) => e.entityType === t);
+ if (!refType) {
+ refType = { entityType: t, referencingProperties: [] };
+ referencingTypes.push(refType);
+ }
+
+ refType.referencingProperties.push(key);
+ }
+ }
+ }
+ return referencingTypes;
+ }
+}
+
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
Infer most likely entity fields that the column from an imported file could be mapped to.
+This is used by the Import Module to give users smart pre-selections in the user interface.
Set up the inheritance value for a field, triggering an initial inheritance
+and watching future changes of the source (parent) field for automatic updates.
returns the region code of the locale currently used
+Extracts the region code (i.e. 'de', 'us', 'in') in lowercase letters
+from a locale (i.e. 'en-US', 'hi-IN')
import { Injectable } from "@angular/core";
+import { MatDialog } from "@angular/material/dialog";
+import { ChangelogComponent } from "./changelog/changelog.component";
+import { environment } from "../../../../environments/environment";
+import { LatestChangesService } from "./latest-changes.service";
+
+/**
+ * Manage the changelog information and display it to the user
+ * on request or automatically on the first visit of a new version after update.
+ */
+@Injectable({ providedIn: "root" })
+export class LatestChangesDialogService {
+ public static readonly VERSION_KEY = "AppVersion";
+
+ constructor(
+ private dialog: MatDialog,
+ private latestChangesService: LatestChangesService,
+ ) {}
+
+ /**
+ * Get current app version inferred from the latest changelog entry.
+ */
+ getCurrentVersion(): string {
+ return environment.appVersion;
+ }
+
+ /**
+ * Open a modal window displaying the changelog of the latest version.
+ * @param previousVersion (Optional) previous version back to which all changes should be displayed
+ */
+ public showLatestChanges(previousVersion?: string): void {
+ this.dialog
+ .open(ChangelogComponent, {
+ width: "80%",
+ data: this.latestChangesService.getChangelogsBetweenVersions(
+ this.getCurrentVersion(),
+ previousVersion,
+ ),
+ })
+ .afterClosed()
+ .subscribe(() => this.updateCurrentVersion());
+ }
+
+ private updateCurrentVersion() {
+ window.localStorage.setItem(
+ LatestChangesDialogService.VERSION_KEY,
+ this.getCurrentVersion(),
+ );
+ }
+
+ /**
+ * Display the latest changes info box automatically if the current user has not seen this version before.
+ */
+ public showLatestChangesIfUpdated() {
+ const previousVersion = window.localStorage.getItem(
+ LatestChangesDialogService.VERSION_KEY,
+ );
+ if (previousVersion && this.getCurrentVersion() !== previousVersion) {
+ this.showLatestChanges(previousVersion);
+ }
+ }
+}
+
import { Injectable } from "@angular/core";
+import { SessionInfo } from "../session-info";
+
+/**
+ * Manages the offline login.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class LocalAuthService {
+ private readonly STORED_USER_PREFIX = "USER-";
+
+ /**
+ * Get a list of users stored in the local storage.
+ */
+ getStoredUsers(): SessionInfo[] {
+ return Object.entries(localStorage)
+ .filter(([key]) => key.startsWith(this.STORED_USER_PREFIX))
+ .map(([_, user]) => JSON.parse(user));
+ }
+
+ /**
+ * Saves a user to the local storage
+ * @param user a object holding the username and the roles of the user
+ */
+ saveUser(user: SessionInfo) {
+ localStorage.setItem(
+ this.STORED_USER_PREFIX + user.name,
+ JSON.stringify(user),
+ );
+ }
+}
+
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
The EntitySchemaField configuration providing details of how the value should be transformed.
+This can be set as a parameter to the @DatabaseField() annotation in Entity classes.
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
A mock implementation of the file service which only stores the file temporarily in the browser.
+This can be used in the demo mode.
+NO FILES ARE UPLOADED OR DOWNLOADED
Datatype for the EntitySchemaService transforming Date values to/from a short string month format ("YYYY-mm").
+
Throws an exception if the property is set to something that is not a Date instance and cannot be cast to Date either.
+Uses the import value mapping properties of the general DateDatatype.
+
For example:
+@DatabaseField({dataType: 'month'}) myMonth: Date = new Date('2020-01-15'); // will be "2020-01" in the database
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
import { Injectable } from "@angular/core";
+import { DateOnlyDatatype } from "../date-only/date-only.datatype";
+import { EntitySchemaField } from "../../entity/schema/entity-schema-field";
+import { Logging } from "../../logging/logging.service";
+
+/**
+ * Datatype for the EntitySchemaService transforming Date values to/from a short string month format ("YYYY-mm").
+ *
+ * Throws an exception if the property is set to something that is not a Date instance and cannot be cast to Date either.
+ * Uses the import value mapping properties of the general DateDatatype.
+ *
+ * For example:
+ * `@DatabaseField({dataType: 'month'}) myMonth: Date = new Date('2020-01-15'); // will be "2020-01" in the database`
+ */
+@Injectable()
+export class MonthDatatype extends DateOnlyDatatype {
+ static override dataType = "month";
+ static override label: string = $localize`:datatype-label:month (date without day of month)`;
+
+ override viewComponent = "DisplayMonth";
+ override editComponent = "EditMonth";
+
+ override transformToDatabaseFormat(value) {
+ if (!(value instanceof Date)) {
+ value = new Date(value);
+ }
+ return (
+ value.getFullYear().toString() +
+ "-" +
+ (value.getMonth() + 1).toString().replace(/^(\d)$/g, "0$1")
+ );
+ }
+
+ override transformToObjectFormat(
+ value: string,
+ schemaField: EntitySchemaField,
+ parent: any,
+ ) {
+ const values = value.split("-").map((v) => Number(v));
+ const date = new Date(values[0], values[1] - 1);
+ if (Number.isNaN(date.getTime())) {
+ Logging.warn(
+ `failed to convert data '${value}' to Date object for ${parent?._id}`,
+ );
+ return undefined;
+ }
+ return date;
+ }
+}
+
Datatype for the EntitySchemaService transforming values to "number".
+
This type is automatically used if you annotate a class's property that has the TypeScript type "number"
+ensuring that even if values in the database from other sources are not of type number they will be cast to number.
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
A component to be display as a dialog to configure the transformation function
+(e.g. defining a format or mapping)
+
+
+
+
+
+
+
+
+
+
+
+
+
import { DefaultDatatype } from "../../entity/default-datatype/default.datatype";
+import { Injectable } from "@angular/core";
+
+/**
+ * Datatype for the EntitySchemaService transforming values to "number".
+ *
+ * This type is automatically used if you annotate a class's property that has the TypeScript type "number"
+ * ensuring that even if values in the database from other sources are not of type number they will be cast to number.
+ *
+ * For example:
+ *
+ * `@DatabaseField() myNumber: number;`
+ *
+ * `@DatabaseField({dataType: 'number'}) myValue: any;`
+ */
+@Injectable()
+export class NumberDatatype extends DefaultDatatype<number, number> {
+ static override dataType = "number";
+ static override label: string = $localize`:datatype-label:number`;
+
+ override viewComponent = "DisplayText";
+ override editComponent = "EditNumber";
+
+ override transformToDatabaseFormat(value) {
+ return Number(value);
+ }
+
+ override transformToObjectFormat(value) {
+ return Number(value);
+ }
+}
+
This service checks whether the relevant rules for the current user changed.
+If it detects a change, all Entity types that have read restrictions are collected.
+All entities of these entity types are loaded and checked whether the currently logged-in user has read permissions.
+If one entity is found for which the user does not have read permissions, then the local database is destroyed and a new sync has to start.
Load all documents (matching the given PouchDB options) from the database.
+(see Database)
+
Normally you should rather use "getAll()" or another well typed method of this class
+instead of passing PouchDB specific options here
+because that will make your code tightly coupled with PouchDB rather than any other database provider.
Save an array of documents to the database
+ The save can partially fail and return a mix of success and error states in the array (e.g. [{ ok: true, ... }, { error: true, ... }])
+
+
+
+ Parameters :
+
+
+
+
+
Name
+
Type
+
Optional
+
Default value
+
Description
+
+
+
+
+
objects
+
+ any[]
+
+
+
+ No
+
+
+
+
+
+
+
the documents to be saved
+
+
+
+
+
forceOverwrite
+
+
+
+
+ No
+
+
+
+ false
+
+
+
+
whether conflicting versions should be overwritten
+
+
+
+
+
+
+
+ Returns : Promise<any>
+
+
+
+
array with the result for each object to be saved, if any item fails to be saved, this returns a rejected Promise.
+The save can partially fail and return a mix of success and error states in the array (e.g. [{ ok: true, ... }, { error: true, ... }])
import { Injectable } from "@angular/core";
+import { Entity, EntityConstructor } from "../entity/model/entity";
+import { Note } from "../../child-dev-project/notes/model/note";
+import { EventNote } from "../../child-dev-project/attendance/model/event-note";
+import { EntityMapperService } from "../entity/entity-mapper/entity-mapper.service";
+import { ChildSchoolRelation } from "../../child-dev-project/children/model/childSchoolRelation";
+import { ChildrenService } from "../../child-dev-project/children/children.service";
+import { AttendanceService } from "../../child-dev-project/attendance/attendance.service";
+import { EventAttendance } from "../../child-dev-project/attendance/model/event-attendance";
+import jsonQuery from "json-query";
+import { EntityRegistry } from "../entity/database-entity.decorator";
+
+/**
+ * A query service which uses the json-query library (https://github.com/auditassistant/json-query).
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class QueryService {
+ private entities: { [type: string]: { [id: string]: Entity } } = {};
+
+ /**
+ * A map of information about the loading state of the different entity types
+ * @private
+ */
+ private entityInfo: {
+ [type: string]: {
+ /**
+ * A optional function which can be used to load this entity that might use a start and end date
+ * @param form
+ * @param to
+ */
+ dataFunction?: (form, to) => Promise<Entity[]>;
+ /**
+ * Whether already all entities of this type have been loaded
+ */
+ allLoaded?: boolean;
+ /**
+ * A certain range in which entities of this type have been loaded
+ */
+ rangeLoaded?: { from: Date; to: Date };
+ /**
+ * Whether updates of this entity are listened to
+ */
+ updating?: boolean;
+ };
+ } = {
+ Note: {
+ dataFunction: (from, to) =>
+ this.childrenService.getNotesInTimespan(from, to),
+ },
+ EventNote: {
+ dataFunction: (from, to) =>
+ this.attendanceService.getEventsOnDate(from, to),
+ },
+ };
+
+ /**
+ * A list of further aliases for which a certain entity needs to be loaded.
+ * This can be necessary if a function requires a certain entity to be present.
+ * @private
+ */
+ private queryStringMap: [string, EntityConstructor][] = [
+ ["getAttendanceArray\\(true\\)", ChildSchoolRelation],
+ ];
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private childrenService: ChildrenService,
+ private attendanceService: AttendanceService,
+ entityRegistry: EntityRegistry,
+ ) {
+ entityRegistry.forEach((entity, name) =>
+ this.queryStringMap.push([name, entity]),
+ );
+ }
+
+ /**
+ * Runs the query on the passed data object
+ * @param query a string or array according to the json-query language (https://github.com/auditassistant/json-query)
+ * @param from a date which can be accessed in the query using a ?.
+ * @param to a date which can be accessed in the query using another ?
+ * @param data the data on which the query should run, default is all entities
+ * @returns the results of the query on the data
+ */
+ public queryData(query: string, from?: Date, to?: Date, data?: any): any {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+
+ if (!data) {
+ data = this.entities;
+ }
+
+ return jsonQuery([query, from, to], {
+ data: data,
+ locals: {
+ toArray: this.toArray,
+ unique: this.unique,
+ count: this.count,
+ sum: this.sum,
+ avg: this.avg,
+ toEntities: this.toEntities.bind(this),
+ getRelated: this.getRelated.bind(this),
+ filterByObjectAttribute: this.filterByObjectAttribute,
+ getIds: this.getIds,
+ getParticipantsWithAttendance: this.getParticipantsWithAttendance,
+ getAttendanceArray: this.getAttendanceArray.bind(this),
+ getAttendanceReport: this.getAttendanceReport,
+ addEntities: this.addEntities.bind(this),
+ setString: this.setString,
+ },
+ }).value;
+ }
+
+ /**
+ * Call this function to prefetch required data
+ * @param query single query or concatenation of all query strings that will be executed soon
+ * @param from date from which data should be available
+ * @param to date to which data should be available
+ */
+ async cacheRequiredData(query: string, from: Date, to: Date) {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+ const uncachedEntities = this.getUncachedEntities(query, from, to);
+ const dataPromises = uncachedEntities.map((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ if (info?.dataFunction) {
+ return info.dataFunction(from, to).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ info.rangeLoaded = { from, to };
+ });
+ } else {
+ return this.entityMapper.loadType(entity).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ this.entityInfo[entity.ENTITY_TYPE] = { allLoaded: true };
+ });
+ }
+ });
+ await Promise.all(dataPromises);
+ this.applyEntityUpdates(uncachedEntities);
+ }
+
+ private applyEntityUpdates(uncachedEntities: EntityConstructor[]) {
+ uncachedEntities
+ .filter(({ ENTITY_TYPE }) => !this.entityInfo[ENTITY_TYPE].updating)
+ .forEach(({ ENTITY_TYPE }) => {
+ this.entityInfo[ENTITY_TYPE].updating = true;
+ this.entityMapper
+ .receiveUpdates(ENTITY_TYPE)
+ .subscribe(({ entity, type }) => {
+ if (type === "remove") {
+ delete this.entities[ENTITY_TYPE][entity.getId()];
+ } else {
+ this.entities[ENTITY_TYPE][entity.getId()] = entity;
+ }
+ });
+ });
+ }
+
+ /**
+ * Get entities that are referenced in the query string and are not sufficiently cached.
+ * @param query
+ * @param from
+ * @param to
+ * @private
+ */
+ private getUncachedEntities(query: string, from: Date, to: Date) {
+ return this.queryStringMap
+ .filter(([matcher]) =>
+ // matches query string without any alphanumeric characters before or after (e.g. so Child does not match ChildSchoolRelation)
+ query?.match(new RegExp(`(^|\\W)${matcher}(\\W|$)`)),
+ )
+ .map(([_, entity]) => entity)
+ .filter((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ return (
+ info === undefined ||
+ !(
+ info.allLoaded ||
+ (info.rangeLoaded?.from <= from && info.rangeLoaded?.to >= to)
+ )
+ );
+ });
+ }
+
+ private setEntities<T extends Entity>(
+ entityClass: EntityConstructor<T>,
+ entities: T[],
+ ) {
+ this.entities[entityClass.ENTITY_TYPE] = {};
+ entities.forEach(
+ (entity) =>
+ (this.entities[entityClass.ENTITY_TYPE][entity.getId()] = entity),
+ );
+ }
+
+ /**
+ * Creates an array containing the value of each key of the object.
+ * e.g. `{a: 1, b: 2} => [1,2]`
+ * This should be used when iterating over all documents of a given entity type because they are stored as
+ * `"{entity._id}": {entity}`
+ * @param obj the object which should be transformed to an array
+ * @returns the values of the input object as a list
+ */
+ private toArray(obj): any[] {
+ return Object.values(obj);
+ }
+
+ /**
+ * Returns a copy of the input array without duplicates
+ * @param data the array where duplicates should be removed
+ * @returns a list without duplicates
+ */
+ private unique(data: any[]): any[] {
+ return new Array(...new Set(data));
+ }
+
+ /**
+ * Get the size of an array
+ * @param data the data for which the length should be returned
+ * @returns the length of the input array or 0 if no array is provided
+ */
+ private count(data: any[]): number {
+ return data ? data.length : 0;
+ }
+
+ /**
+ * Returns the (integer) sum of the provided array.
+ * It can also handle integers in strings, e.g. "3"
+ * @param data an integer array
+ * @private
+ */
+ private sum(data: any[]): number {
+ return data.reduce((res, cur) => {
+ const parsed = Number.parseInt(cur);
+ return Number.isNaN(parsed) ? res : res + parsed;
+ }, 0);
+ }
+
+ /**
+ * Returns the avg of the provided array as string.
+ * It can also handle integers in strings, e.g. "3".
+ * The average is only calculated if the value exists and is a valid number.
+ * @param data an integer array
+ * @param decimals the amount of decimals for the result, default 0
+ * @private
+ */
+ private avg(data: any[], decimals = 0): string {
+ const numbers = data
+ .map((d) => Number.parseInt(d))
+ .filter((i) => !Number.isNaN(i));
+ const result =
+ numbers.length === 0
+ ? 0
+ : numbers.reduce((i, sum) => sum + i, 0) / numbers.length;
+ return result.toFixed(decimals);
+ }
+
+ /**
+ * Turns a list of ids (with the entity prefix) into a list of entities
+ * @param ids the array of ids with entity prefix
+ * @param entityPrefix indicate the type of entity that should be loaded. This is required for pre-loading the required entities.
+ * @returns a list of entity objects
+ */
+ private toEntities(ids: string[], entityPrefix: string): Entity[] {
+ if (!entityPrefix) {
+ throw new Error("Entity type not defined");
+ }
+ if (!ids) {
+ return [];
+ }
+
+ return ids
+ .filter((id) => {
+ if (typeof id !== "string") {
+ console.debug("invalid entity id in Query :toEntities", id);
+ return false;
+ }
+ return true;
+ })
+ .map((id) => {
+ const prefix = id.split(":")[0];
+ return this.entities[prefix][id];
+ })
+ .filter((entity) => !!entity);
+ }
+
+ /**
+ * Returns all entities which reference a entity from the passed list of entities (by their id)
+ * @param srcEntities the entities for which relations should be found
+ * @param entityType the type of entities where relations should be looked for
+ * @param relationKey the name of the attribute that holds the reference.
+ * The attribute can be a string or a list of strings
+ * @returns a list of the related unique entities
+ */
+ private getRelated(
+ srcEntities: Entity[],
+ entityType: string,
+ relationKey: string,
+ ): Entity[] {
+ const targetEntities = this.toArray(this.entities[entityType]);
+ const srcIds = srcEntities
+ .filter((entity) => typeof entity.getId === "function") // skip empty placeholder objects
+ .map((entity) => entity.getId());
+ if (
+ targetEntities.length > 0 &&
+ Array.isArray(targetEntities[0][relationKey])
+ ) {
+ return targetEntities.filter((entity) =>
+ (entity[relationKey] as string[]).some((id) => srcIds.includes(id)),
+ );
+ } else {
+ return targetEntities.filter((entity) =>
+ entity[relationKey] ? srcIds.includes(entity[relationKey]) : false,
+ );
+ }
+ }
+
+ /**
+ * Filters the data when the filter value is a object (e.g. configurable enum) rather than a simple value
+ * @param objs the objects to be filtered
+ * @param attr the attribute of the objects which is a object itself
+ * @param key the key of the attribute-object which should be compared
+ * @param value the value which will be compared with `obj[attr][key]` for each obj in objs.
+ * The value can be a simple value or list of values separated by `|` (e.g. SCHOOL_CLASS|LIFE_SKILLS).
+ * If it is a list of values, then the object is returned if its value matches any of the given values.
+ * @returns the filtered objects
+ */
+ private filterByObjectAttribute(
+ objs: any[],
+ attr: string,
+ key: string,
+ value: string,
+ ): any[] {
+ // splits at "|" and removes optional whitespace before or after the symbol
+ const values = value.trim().split(/\s*\|\s*/);
+ return objs.filter((obj) => {
+ if (obj?.hasOwnProperty(attr)) {
+ return values.includes(obj[attr][key]?.toString());
+ }
+ return false;
+ });
+ }
+
+ /**
+ * Returns a list of IDs held by each object (e.g. the children-IDs held by an array of notes)
+ * @param objs the objects which each holds a list of IDs
+ * @param key the key on which each object holds a list of IDs
+ * @returns a one dimensional string array holding all IDs which are held by the objects.
+ * This list may contain duplicate IDs. If this is not desired, use `:unique` afterwards.
+ */
+ private getIds(objs: any[], key: string): string[] {
+ const ids: string[] = [];
+ objs.forEach((obj) => {
+ if (obj.hasOwnProperty(key)) {
+ ids.push(...obj[key]);
+ }
+ });
+ return ids;
+ }
+
+ /**
+ * Return the ids of all the participants of the passed events with the defined attendance status using the `countAs`
+ * attribute. The list may contain duplicates and the id does not necessarily have the entity prefix.
+ * @param events the array of events
+ * @param attendanceStatus the status for which should be looked for
+ * @returns the ids of children which have the specified attendance in an event
+ */
+ private getParticipantsWithAttendance(
+ events: EventNote[],
+ attendanceStatus: string,
+ ): string[] {
+ const attendedChildren: string[] = [];
+ events.forEach((e) =>
+ e.children.forEach((childId) => {
+ if (e.getAttendance(childId).status.countAs === attendanceStatus) {
+ attendedChildren.push(childId);
+ }
+ }),
+ );
+ return attendedChildren;
+ }
+
+ /**
+ * Transforms a list of notes or event-notes into a flattened list of participants and their attendance for each event.
+ * @param events the input list of type Note or EventNote
+ * @param includeSchool (optional) also include the school to which a participant belongs
+ * @returns AttendanceInfo[] a list holding information about the attendance of a single participant
+ */
+ private getAttendanceArray(
+ events: Note[],
+ includeSchool = false,
+ ): AttendanceInfo[] {
+ const attendances: AttendanceInfo[] = [];
+ for (const event of events) {
+ const linkedRelations = includeSchool
+ ? this.getMembersOfGroupsForEvent(event)
+ : [];
+
+ for (const child of event.children) {
+ const attendance: AttendanceInfo = {
+ participant: child,
+ status: event.getAttendance(child),
+ };
+
+ const relation = linkedRelations.find((rel) => rel.childId === child);
+ if (relation) {
+ attendance.school = relation.schoolId;
+ }
+
+ attendances.push(attendance);
+ }
+ }
+ return attendances;
+ }
+
+ private getMembersOfGroupsForEvent(event: Note) {
+ return this.toArray(this.entities[ChildSchoolRelation.ENTITY_TYPE]).filter(
+ (relation) =>
+ event.schools.includes(relation.schoolId) &&
+ relation.isActiveAt(event.date),
+ );
+ }
+
+ /**
+ * Transforms a list of attendances infos into an aggregated report for each participant
+ * @param attendances an array of AttendanceInfo objects
+ * @returns AttendanceReport[] for each participant the ID, the number of present and total absences as well as the attendance percentage.
+ */
+ private getAttendanceReport(
+ attendances: AttendanceInfo[],
+ ): AttendanceReport[] {
+ const participantMap: { [key in string]: AttendanceReport } = {};
+ attendances.forEach((attendance) => {
+ if (!participantMap.hasOwnProperty(attendance.participant)) {
+ participantMap[attendance.participant] = {
+ participant: attendance.participant,
+ total: 0,
+ present: 0,
+ percentage: "",
+ detailedStatus: {},
+ };
+ }
+ const report = participantMap[attendance.participant];
+ report.detailedStatus[attendance.status.status.id] = report
+ .detailedStatus[attendance.status.status.id]
+ ? report.detailedStatus[attendance.status.status.id] + 1
+ : 1;
+ if (attendance.status.status.countAs === "PRESENT") {
+ report.present++;
+ }
+ if (attendance.status.status.countAs !== "IGNORE") {
+ report.total++;
+ }
+ if (report.total > 0) {
+ report.percentage = (report.present / report.total).toFixed(2);
+ }
+ });
+ return Object.values(participantMap);
+ }
+
+ /**
+ * Adds all entities of the given type to the input array
+ * @param entities the array before
+ * @param entityType the type of entities which should be added
+ * @returns the input array concatenated with all entities of the entityType
+ */
+ private addEntities(entities: Entity[], entityType: string): Entity[] {
+ return entities.concat(...this.toArray(this.entities[entityType]));
+ }
+
+ /**
+ * Replaces all input values by the string provided
+ * @param data the data which will be replaced
+ * @param value the string which should replace initial data
+ * @returns array of same length as data where every input is value
+ */
+ private setString(data: any[], value: string): string[] | string {
+ return Array.isArray(data) ? data.map(() => value) : value;
+ }
+}
+
+export interface AttendanceInfo {
+ participant: string;
+ status: EventAttendance;
+ school?: string;
+}
+
+export interface AttendanceReport {
+ participant: string;
+ total: number;
+ present: number;
+ percentage: string;
+
+ /** counts by all custom configured status **/
+ detailedStatus?: { [key: string]: number };
+}
+
The RouterService dynamically sets up Angular routing from config loaded through the ConfigService.
+
You can define ViewConfig objects in the central configuration and build the routing at runtime
+rather than hard-coding the available paths and settings.
This can be used to check the current screen size programmatically
+and get notified when it changes. Use the shared observable to
+get notified on any changes. This observable is shared across all instances and
+will persist throughout the lifespan of the app.
+
The platform observable emits changes whenever the screen size changes to
+where the app is considered to be in Mobile mode vs. desktop mode.
+
This class can also be used statically to check the current screen size and/or check whether
+the app is currently considered to be in mobile mode or desktop mode.
The observable shared amongst all instances.
+Subscribers to this observable get notified whenever the current screen size changes.
+
When getting a new observable (or, in other words, when calling this function), the current
+screen size is injected so that when you subscribe the first element that arrives is the current screen size.
import { combineLatest, fromEvent, Observable } from "rxjs";
+import { Inject, Injectable } from "@angular/core";
+import { distinctUntilChanged, map, startWith } from "rxjs/operators";
+import { WINDOW_TOKEN } from "../di-tokens";
+
+/*
+ * Constants describing the threshold values.
+ * These constants are considered the lower limit, i.e. if
+ * a screen is more than 576px large but less than 768px
+ * the screen is considered SM.
+ *
+ * Any screen smaller than `SM` is considered `XS`
+ */
+const SM = "576px";
+const MD = "768px";
+const LG = "992px";
+const XL = "1200px";
+const XXL = "1400px";
+
+/**
+ * Different ranges of screen sizes.
+ */
+
+/* Implementation note: This is implemented as an enum (as opposed to a string-type)
+ * so that
+ * ```
+ * sizeA: ScreenSize = ...
+ * sizeB: ScreenSize = ...
+ *
+ * aIsGreaterThanB: boolean = sizeA > sizeB
+ * ```
+ * makes sense.
+ */
+export enum ScreenSize {
+ // extra small (0px <= width < 576px)
+ xs = 0,
+ // medium small (576px <= width < 768px)
+ sm = 1,
+ // medium (768px <= width < 992px)
+ md = 2,
+ // large (992px <= width < 1200px)
+ lg = 3,
+ // extra large (1200px <= width < 1400px)
+ xl = 4,
+ // extra-extra large (1400 <= width)
+ xxl = 5,
+}
+
+/**
+ * The screen size where anything smaller and this size itself is considered mobile while anything strictly larger
+ * is considered desktop.
+ *
+ */
+export const MOBILE_THRESHOLD: ScreenSize = ScreenSize.sm;
+
+/**
+ * A type that is used to document the return type of the `platform` observable.
+ * A variable that has this type shall only have two values that are encoded in
+ * a boolean way:
+ *
+ * - `true`: the variable represents that the width of something is considered 'desktop width'
+ * - `false`: the variable represents that the width of something is considered 'mobile width'
+ */
+export type IsDesktop = boolean;
+
+/**
+ * This can be used to check the current screen size programmatically
+ * and get notified when it changes. Use the {@link shared} observable to
+ * get notified on any changes. This observable is shared across all instances and
+ * will persist throughout the lifespan of the app.
+ *
+ * The `platform` observable emits changes whenever the screen size changes to
+ * where the app is considered to be in Mobile mode vs. desktop mode.
+ *
+ * This class can also be used statically to check the current screen size and/or check whether
+ * the app is currently considered to be in mobile mode or desktop mode.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class ScreenWidthObserver {
+ /**
+ * create an observable that emits whenever the `query` matches.
+ * Also emits the current state to begin with.
+ * @param query The query to check
+ * @private
+ */
+ private static matching(
+ query: MediaQueryList,
+ ): Observable<MediaQueryListEvent> {
+ return fromEvent<MediaQueryListEvent>(query, "change").pipe(
+ startWith({
+ matches: query.matches,
+ media: query.media,
+ } as MediaQueryListEvent),
+ );
+ }
+
+ /**
+ * The internal query lists that are used to check the current screen sizes
+ * @private
+ */
+ private queryLists: MediaQueryList[] = [SM, MD, LG, XL, XXL].map((size) =>
+ // matches when the screen's width is greater than `size`
+ this.window.matchMedia(`screen and (min-width: ${size})`),
+ );
+
+ private readonly _shared: Observable<ScreenSize>;
+
+ /**
+ * The observable shared amongst all instances.
+ * Subscribers to this observable get notified whenever the current screen size changes.
+ *
+ * When getting a new observable (or, in other words, when calling this function), the current
+ * screen size is injected so that when you subscribe the first element that arrives is the current screen size.
+ */
+ public shared(): Observable<ScreenSize> {
+ return this._shared.pipe(startWith(this.currentScreenSize()));
+ }
+
+ private readonly _platform: Observable<IsDesktop>;
+
+ /**
+ * An observable that emits whenever the screen size changes so that the app is considered
+ * to be on a mobile device or a desktop device.
+ */
+ public platform(): Observable<IsDesktop> {
+ return this._platform.pipe(startWith(this.isDesktop()));
+ }
+
+ constructor(@Inject(WINDOW_TOKEN) private window: Window) {
+ this._shared = combineLatest(
+ this.queryLists.map((queryList) =>
+ ScreenWidthObserver.matching(queryList),
+ ),
+ ).pipe(
+ map(() => {
+ // Listening to the events requires parsing (or understanding) the event and the
+ // attached media-string which requires more logic than simply computing the result in-place.
+ return this.currentScreenSize();
+ }),
+ );
+
+ this._platform = this._shared.pipe(
+ map((screenSize) => screenSize > MOBILE_THRESHOLD),
+ distinctUntilChanged(),
+ );
+ }
+
+ /**
+ * Return the current screen size as determined by the media queries
+ */
+ public currentScreenSize(): ScreenSize {
+ // when this returns -1 then no query is active. This means
+ // that the screen size is less than `SM`, i.e. `XS`
+ return (
+ this.queryLists.map((queryList) => queryList.matches).lastIndexOf(true) +
+ 1
+ );
+ }
+
+ /**
+ * returns whether the app is currently considered to be in desktop mode
+ * looking only at the screen size.
+ */
+ public isDesktop(): IsDesktop {
+ return this.currentScreenSize() > MOBILE_THRESHOLD;
+ }
+}
+
This service handles the user session.
+This includes an online and offline login and logout.
+After a successful login, the database for the current user is initialised.
Login for a remote session and start the sync.
+After a user has logged in once online, this user can later also use the app offline.
+Should only be called if there is an internet connection
import { Injectable } from "@angular/core";
+import { BehaviorSubject } from "rxjs";
+
+/**
+ * The session info which holds information about the currently logged-in user.
+ * This is retrieved during the login process and will always be present once state changes to `LOGGED_IN`.
+ */
+export interface SessionInfo {
+ /*
+ * The user account id from the auth server (e.g. User ID in Keycloak)
+ */
+ id: string;
+
+ /**
+ * Name of user account.
+ * @deprecated Use id or entityId instead as this is an unpredictable mix from different sources
+ */
+ name: string;
+
+ /**
+ * List of roles the logged-in user hold.
+ */
+ roles: string[];
+
+ /**
+ * List of linked projects
+ */
+ projects?: string[];
+
+ /**
+ * ID of the entity which is connected with the user account.
+ *
+ * This is either a full ID or (e.g. Child:123) or only the last part.
+ * In the later case it refers to the `User` entity.
+ */
+ entityId?: string;
+
+ /**
+ * Email address of a user
+ */
+ email?: string;
+}
+
+/**
+ * Use this provider to get information about the currently active session.
+ * E.g. for checking required roles or accessing the unique user identifier.
+ */
+@Injectable()
+export class SessionSubject extends BehaviorSubject<SessionInfo> {
+ constructor() {
+ super(undefined);
+ }
+}
+
Datatype for the EntitySchemaService transforming values to "string".
+
This type is automatically used if you annotate a class's property that has the TypeScript type "string"
+ensuring that even if values in the database from other sources are not of type string, the property will be a string.
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
The default component how this datatype should be displayed in lists and forms.
+
The edit component has to be a registered component. Components that are registered contain the DynamicComponent
+decorator
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Injectable } from "@angular/core";
+import { DefaultDatatype } from "../../entity/default-datatype/default.datatype";
+
+/**
+ * Datatype for the EntitySchemaService transforming values to "string".
+ *
+ * This type is automatically used if you annotate a class's property that has the TypeScript type "string"
+ * ensuring that even if values in the database from other sources are not of type string, the property will be a string.
+ *
+ * For example:
+ *
+ * `@DatabaseField() myString: string;`
+ *
+ * `@DatabaseField({dataType: 'string'}) myValue: any;`
+ */
+@Injectable()
+export class StringDatatype extends DefaultDatatype<string, string> {
+ static override dataType = "string";
+ static override label: string = $localize`:datatype-label:text`;
+
+ override transformToDatabaseFormat(value) {
+ return String(value);
+ }
+
+ override transformToObjectFormat(value) {
+ return String(value);
+ }
+}
+
This service handles the state whether there are currently some unsaved changes in the app.
+These pending changes might come from a form component or popup.
+If there are pending changes, certain actions in the app should trigger a user confirmation if the changes should be discarded.
Set to true if the user has pending changes that are not yet saved.
+Set to false once the changes have been saved or discarded.
+
+
+
+
+
+
+
+
+
+
+
+
+
import { Injectable } from "@angular/core";
+import { ConfirmationDialogService } from "../../common-components/confirmation-dialog/confirmation-dialog.service";
+
+/**
+ * This service handles the state whether there are currently some unsaved changes in the app.
+ * These pending changes might come from a form component or popup.
+ * If there are pending changes, certain actions in the app should trigger a user confirmation if the changes should be discarded.
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class UnsavedChangesService {
+ /**
+ * Set to true if the user has pending changes that are not yet saved.
+ * Set to false once the changes have been saved or discarded.
+ */
+ pending = false;
+
+ constructor(private confirmation: ConfirmationDialogService) {
+ // prevent browser navigation if changes are pending
+ window.onbeforeunload = (e) => {
+ if (this.pending) {
+ e.preventDefault();
+ e.returnValue = "onbeforeunload";
+ }
+ };
+ }
+
+ /**
+ * Shows a user confirmation popup if there are unsaved changes which will be discarded.
+ */
+ async checkUnsavedChanges() {
+ if (this.pending) {
+ const confirmed = await this.confirmation.getDiscardConfirmation();
+ if (confirmed) {
+ this.pending = false;
+ return true;
+ } else {
+ return false;
+ }
+ }
+ return true;
+ }
+}
+
Check with the server whether a new version of the app is available in order to notify the user.
+
As we are using ServiceWorkers to cache the app to also work offline, explicit checking for updates is necessary.
+The user receives a toast (hover message) if an update is available
+and can click that to reload the app with the new version.
import { ApplicationRef, Inject, Injectable } from "@angular/core";
+import { SwUpdate } from "@angular/service-worker";
+import { filter, first } from "rxjs/operators";
+import { concat, interval } from "rxjs";
+import { MatSnackBar } from "@angular/material/snack-bar";
+import { Logging } from "../../logging/logging.service";
+import { LatestChangesDialogService } from "./latest-changes-dialog.service";
+import { LOCATION_TOKEN } from "../../../utils/di-tokens";
+import { UnsavedChangesService } from "../../entity-details/form/unsaved-changes.service";
+
+/**
+ * Check with the server whether a new version of the app is available in order to notify the user.
+ *
+ * As we are using ServiceWorkers to cache the app to also work offline, explicit checking for updates is necessary.
+ * The user receives a toast (hover message) if an update is available
+ * and can click that to reload the app with the new version.
+ */
+@Injectable({ providedIn: "root" })
+export class UpdateManagerService {
+ private readonly UPDATE_PREFIX = "update-";
+
+ constructor(
+ private appRef: ApplicationRef,
+ private updates: SwUpdate,
+ private snackBar: MatSnackBar,
+ private latestChangesDialogService: LatestChangesDialogService,
+ private unsavedChanges: UnsavedChangesService,
+ @Inject(LOCATION_TOKEN) private location: Location,
+ ) {
+ this.updates.unrecoverable.subscribe((err) => {
+ Logging.error("App is in unrecoverable state: " + err.reason);
+ this.location.reload();
+ });
+ const currentVersion = localStorage.getItem(
+ LatestChangesDialogService.VERSION_KEY,
+ );
+ if (currentVersion && currentVersion.startsWith(this.UPDATE_PREFIX)) {
+ localStorage.setItem(
+ LatestChangesDialogService.VERSION_KEY,
+ currentVersion.replace(this.UPDATE_PREFIX, ""),
+ );
+ this.location.reload();
+ } else {
+ this.latestChangesDialogService.showLatestChangesIfUpdated();
+ }
+ }
+
+ /**
+ * Display a notification to the user in case a new app version is detected by the ServiceWorker.
+ */
+ public listenToAppUpdates() {
+ if (!this.updates.isEnabled) {
+ return;
+ }
+ this.updates.versionUpdates
+ .pipe(filter((e) => e.type === "VERSION_READY"))
+ .subscribe(() => this.updateIfPossible());
+ }
+
+ /**
+ * Schedule a regular check with the server for updates.
+ */
+ public regularlyCheckForUpdates() {
+ if (!this.updates.isEnabled) {
+ return;
+ }
+
+ // Allow the app to stabilize first, before starting polling for updates with `interval()`.
+ const appIsStable$ = this.appRef.isStable.pipe(
+ first((isStable) => isStable === true),
+ );
+ const everyHours$ = interval(60 * 60 * 1000);
+ const everyHoursOnceAppIsStable$ = concat(appIsStable$, everyHours$);
+
+ everyHoursOnceAppIsStable$.subscribe(() =>
+ this.updates.checkForUpdate().catch((err) => Logging.error(err)),
+ );
+ }
+
+ private updateIfPossible() {
+ const currentVersion =
+ localStorage.getItem(LatestChangesDialogService.VERSION_KEY) || "";
+ if (currentVersion.startsWith(this.UPDATE_PREFIX)) {
+ // Sometimes this is triggered multiple times for one update
+ return;
+ }
+
+ if (this.unsavedChanges.pending) {
+ // app cannot be safely reloaded
+ localStorage.setItem(
+ LatestChangesDialogService.VERSION_KEY,
+ this.UPDATE_PREFIX + currentVersion,
+ );
+ this.snackBar
+ .open(
+ $localize`A new version of the app is available!`,
+ $localize`:Action that a user can update the app with:Update`,
+ )
+ .onAction()
+ .subscribe(() => {
+ localStorage.setItem(
+ LatestChangesDialogService.VERSION_KEY,
+ currentVersion,
+ );
+
+ this.location.reload();
+ });
+ } else {
+ this.location.reload();
+ }
+ }
+
+ /**
+ * Notifies user if app ends up in an unrecoverable state due to SW updates
+ */
+ public detectUnrecoverableState() {
+ if (!this.updates.isEnabled) {
+ return;
+ }
+
+ this.updates.unrecoverable.subscribe(({ reason }) => {
+ Logging.warn(`SW in unrecoverable state: ${reason}`);
+ this.snackBar
+ .open(
+ $localize`The app is in a unrecoverable state, please reload.`,
+ $localize`:Action that a user can reload the app with:Reload`,
+ )
+ .onAction()
+ .subscribe(() => this.location.reload());
+ });
+ }
+}
+
Output a label indicating whether the given column mapping needs user configuration for the "additional" config
+or has a valid, complete "additional" config.
+returns "undefined" if no user action is required.
import { Injectable } from "@angular/core";
+import { Router } from "@angular/router";
+import { AbstractPermissionGuard } from "./abstract-permission.guard";
+import { DynamicComponentConfig } from "../../config/dynamic-components/dynamic-component-config.interface";
+import { SessionSubject } from "../../session/auth/session-info";
+
+/**
+ * A guard that checks the roles of the current user against the permissions which are saved in the route data.
+ */
+@Injectable()
+export class UserRoleGuard extends AbstractPermissionGuard {
+ constructor(
+ router: Router,
+ private sessionInfo: SessionSubject,
+ ) {
+ super(router);
+ }
+
+ protected async canAccessRoute(
+ routeData: DynamicComponentConfig,
+ ): Promise<boolean> {
+ const permittedRoles = routeData?.permittedUserRoles;
+ const user = this.sessionInfo.value;
+
+ if (permittedRoles?.length > 0) {
+ // Check if user has a role which is in the list of permitted roles
+ return permittedRoles.some((role) => user.roles.includes(role));
+ } else {
+ // No config set => all users are allowed
+ return true;
+ }
+ }
+}
+
import { Entity, EntityConstructor } from "../../core/entity/model/entity";
+import { DatabaseEntity } from "../../core/entity/database-entity.decorator";
+import { Aggregation } from "./data-aggregation.service";
+import { ExportColumnConfig } from "../../core/export/data-transformation-service/export-column-config";
+import { DatabaseField } from "../../core/entity/database-field.decorator";
+
+/**
+ * A report can be accessed by users to generate aggregated statistics or customized exports calculated from available data.
+ * "read" permission for a ReportConfig entity is also used to control which users can generate the report's results.
+ *
+ * This is the class which is saved to the database.
+ * However, when using this in code, use the {@link ReportEntity} instead which provides better type safety.
+ */
+@DatabaseEntity("ReportConfig")
+class ReportConfig extends Entity {
+ /** human-readable title of the report */
+ @DatabaseField() title: string;
+
+ /**
+ * (optional) mode of export.
+ * The {@link ReportEntity} holds the restriction on valid report modes.
+ * Default is "reporting"
+ */
+ @DatabaseField() mode?: string;
+
+ /**
+ * (sql only) list of arguments needed for the sql query. Placeholder "?" will be replaced.
+ */
+ @DatabaseField() neededArgs?: string[] = [];
+
+ /** the definitions to calculate the report's aggregations */
+ @DatabaseField() aggregationDefinitions: any[] = [];
+
+ /** (sql only) the definition to calculate the report */
+ @DatabaseField() aggregationDefinition: string | undefined = undefined;
+}
+
+/**
+ * Union type to enable type safety for report configs.
+ * Use this instead of the {@class ReportConfig}
+ */
+export type ReportEntity = AggregationReport | ExportingReport | SqlReport;
+/**
+ * This allows the `ReportEntity` to also be used as a constructor or in the `EntityMapper`
+ */
+export const ReportEntity = ReportConfig as EntityConstructor<ReportEntity>;
+
+/**
+ * Reports handles by the {@class DataAggregationService}
+ */
+export interface AggregationReport extends ReportConfig {
+ mode: "reporting";
+ aggregationDefinitions: Aggregation[];
+}
+
+/**
+ * Reports handles by the {@class DataTransformationService}
+ */
+export interface ExportingReport extends ReportConfig {
+ /**
+ * If no mode is set, it will default to 'exporting'
+ */
+ mode?: "exporting";
+ aggregationDefinitions: ExportColumnConfig[];
+}
+
+/**
+ * Reports handles by the {@class SqlReportService}
+ */
+export interface SqlReport extends ReportConfig {
+ mode: "sql";
+ /**
+ * a valid SQL SELECT statements, can contain "?" placeholder for arguments
+ */
+ aggregationDefinition: string;
+
+ /**
+ * a list of arguments, passed into the sql statement
+ */
+ neededArgs: string[];
+}
+
Info messages provide feedback or information to the user without any required action
+
Warning messages provide feedback about unexpected or potentially unintended events
+
Danger messages inform about errors or critical conditions that the user should not overlook
+
+
+
+
+
+
+
+
+
+
+
+
import { AlertDisplay } from "./alert-display";
+
+export interface AlertConfig {
+ /** The text of the message */
+ message: string;
+
+ /** The type of the message
+ *
+ * - Info messages provide feedback or information to the user without any required action
+ * - Warning messages provide feedback about unexpected or potentially unintended events
+ * - Danger messages inform about errors or critical conditions that the user should not overlook
+ */
+ type: "info" | "warning" | "danger";
+
+ /** The display style (e.g. whether the alert has to be actively dismissed by the user) */
+ display: AlertDisplay;
+}
+
+export interface ExtendedAlertConfig extends AlertConfig {
+ timestamp: Date;
+}
+
import { Injectable } from "@angular/core";
+import { Entity, EntityConstructor } from "../entity/model/entity";
+import { Note } from "../../child-dev-project/notes/model/note";
+import { EventNote } from "../../child-dev-project/attendance/model/event-note";
+import { EntityMapperService } from "../entity/entity-mapper/entity-mapper.service";
+import { ChildSchoolRelation } from "../../child-dev-project/children/model/childSchoolRelation";
+import { ChildrenService } from "../../child-dev-project/children/children.service";
+import { AttendanceService } from "../../child-dev-project/attendance/attendance.service";
+import { EventAttendance } from "../../child-dev-project/attendance/model/event-attendance";
+import jsonQuery from "json-query";
+import { EntityRegistry } from "../entity/database-entity.decorator";
+
+/**
+ * A query service which uses the json-query library (https://github.com/auditassistant/json-query).
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class QueryService {
+ private entities: { [type: string]: { [id: string]: Entity } } = {};
+
+ /**
+ * A map of information about the loading state of the different entity types
+ * @private
+ */
+ private entityInfo: {
+ [type: string]: {
+ /**
+ * A optional function which can be used to load this entity that might use a start and end date
+ * @param form
+ * @param to
+ */
+ dataFunction?: (form, to) => Promise<Entity[]>;
+ /**
+ * Whether already all entities of this type have been loaded
+ */
+ allLoaded?: boolean;
+ /**
+ * A certain range in which entities of this type have been loaded
+ */
+ rangeLoaded?: { from: Date; to: Date };
+ /**
+ * Whether updates of this entity are listened to
+ */
+ updating?: boolean;
+ };
+ } = {
+ Note: {
+ dataFunction: (from, to) =>
+ this.childrenService.getNotesInTimespan(from, to),
+ },
+ EventNote: {
+ dataFunction: (from, to) =>
+ this.attendanceService.getEventsOnDate(from, to),
+ },
+ };
+
+ /**
+ * A list of further aliases for which a certain entity needs to be loaded.
+ * This can be necessary if a function requires a certain entity to be present.
+ * @private
+ */
+ private queryStringMap: [string, EntityConstructor][] = [
+ ["getAttendanceArray\\(true\\)", ChildSchoolRelation],
+ ];
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private childrenService: ChildrenService,
+ private attendanceService: AttendanceService,
+ entityRegistry: EntityRegistry,
+ ) {
+ entityRegistry.forEach((entity, name) =>
+ this.queryStringMap.push([name, entity]),
+ );
+ }
+
+ /**
+ * Runs the query on the passed data object
+ * @param query a string or array according to the json-query language (https://github.com/auditassistant/json-query)
+ * @param from a date which can be accessed in the query using a ?.
+ * @param to a date which can be accessed in the query using another ?
+ * @param data the data on which the query should run, default is all entities
+ * @returns the results of the query on the data
+ */
+ public queryData(query: string, from?: Date, to?: Date, data?: any): any {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+
+ if (!data) {
+ data = this.entities;
+ }
+
+ return jsonQuery([query, from, to], {
+ data: data,
+ locals: {
+ toArray: this.toArray,
+ unique: this.unique,
+ count: this.count,
+ sum: this.sum,
+ avg: this.avg,
+ toEntities: this.toEntities.bind(this),
+ getRelated: this.getRelated.bind(this),
+ filterByObjectAttribute: this.filterByObjectAttribute,
+ getIds: this.getIds,
+ getParticipantsWithAttendance: this.getParticipantsWithAttendance,
+ getAttendanceArray: this.getAttendanceArray.bind(this),
+ getAttendanceReport: this.getAttendanceReport,
+ addEntities: this.addEntities.bind(this),
+ setString: this.setString,
+ },
+ }).value;
+ }
+
+ /**
+ * Call this function to prefetch required data
+ * @param query single query or concatenation of all query strings that will be executed soon
+ * @param from date from which data should be available
+ * @param to date to which data should be available
+ */
+ async cacheRequiredData(query: string, from: Date, to: Date) {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+ const uncachedEntities = this.getUncachedEntities(query, from, to);
+ const dataPromises = uncachedEntities.map((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ if (info?.dataFunction) {
+ return info.dataFunction(from, to).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ info.rangeLoaded = { from, to };
+ });
+ } else {
+ return this.entityMapper.loadType(entity).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ this.entityInfo[entity.ENTITY_TYPE] = { allLoaded: true };
+ });
+ }
+ });
+ await Promise.all(dataPromises);
+ this.applyEntityUpdates(uncachedEntities);
+ }
+
+ private applyEntityUpdates(uncachedEntities: EntityConstructor[]) {
+ uncachedEntities
+ .filter(({ ENTITY_TYPE }) => !this.entityInfo[ENTITY_TYPE].updating)
+ .forEach(({ ENTITY_TYPE }) => {
+ this.entityInfo[ENTITY_TYPE].updating = true;
+ this.entityMapper
+ .receiveUpdates(ENTITY_TYPE)
+ .subscribe(({ entity, type }) => {
+ if (type === "remove") {
+ delete this.entities[ENTITY_TYPE][entity.getId()];
+ } else {
+ this.entities[ENTITY_TYPE][entity.getId()] = entity;
+ }
+ });
+ });
+ }
+
+ /**
+ * Get entities that are referenced in the query string and are not sufficiently cached.
+ * @param query
+ * @param from
+ * @param to
+ * @private
+ */
+ private getUncachedEntities(query: string, from: Date, to: Date) {
+ return this.queryStringMap
+ .filter(([matcher]) =>
+ // matches query string without any alphanumeric characters before or after (e.g. so Child does not match ChildSchoolRelation)
+ query?.match(new RegExp(`(^|\\W)${matcher}(\\W|$)`)),
+ )
+ .map(([_, entity]) => entity)
+ .filter((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ return (
+ info === undefined ||
+ !(
+ info.allLoaded ||
+ (info.rangeLoaded?.from <= from && info.rangeLoaded?.to >= to)
+ )
+ );
+ });
+ }
+
+ private setEntities<T extends Entity>(
+ entityClass: EntityConstructor<T>,
+ entities: T[],
+ ) {
+ this.entities[entityClass.ENTITY_TYPE] = {};
+ entities.forEach(
+ (entity) =>
+ (this.entities[entityClass.ENTITY_TYPE][entity.getId()] = entity),
+ );
+ }
+
+ /**
+ * Creates an array containing the value of each key of the object.
+ * e.g. `{a: 1, b: 2} => [1,2]`
+ * This should be used when iterating over all documents of a given entity type because they are stored as
+ * `"{entity._id}": {entity}`
+ * @param obj the object which should be transformed to an array
+ * @returns the values of the input object as a list
+ */
+ private toArray(obj): any[] {
+ return Object.values(obj);
+ }
+
+ /**
+ * Returns a copy of the input array without duplicates
+ * @param data the array where duplicates should be removed
+ * @returns a list without duplicates
+ */
+ private unique(data: any[]): any[] {
+ return new Array(...new Set(data));
+ }
+
+ /**
+ * Get the size of an array
+ * @param data the data for which the length should be returned
+ * @returns the length of the input array or 0 if no array is provided
+ */
+ private count(data: any[]): number {
+ return data ? data.length : 0;
+ }
+
+ /**
+ * Returns the (integer) sum of the provided array.
+ * It can also handle integers in strings, e.g. "3"
+ * @param data an integer array
+ * @private
+ */
+ private sum(data: any[]): number {
+ return data.reduce((res, cur) => {
+ const parsed = Number.parseInt(cur);
+ return Number.isNaN(parsed) ? res : res + parsed;
+ }, 0);
+ }
+
+ /**
+ * Returns the avg of the provided array as string.
+ * It can also handle integers in strings, e.g. "3".
+ * The average is only calculated if the value exists and is a valid number.
+ * @param data an integer array
+ * @param decimals the amount of decimals for the result, default 0
+ * @private
+ */
+ private avg(data: any[], decimals = 0): string {
+ const numbers = data
+ .map((d) => Number.parseInt(d))
+ .filter((i) => !Number.isNaN(i));
+ const result =
+ numbers.length === 0
+ ? 0
+ : numbers.reduce((i, sum) => sum + i, 0) / numbers.length;
+ return result.toFixed(decimals);
+ }
+
+ /**
+ * Turns a list of ids (with the entity prefix) into a list of entities
+ * @param ids the array of ids with entity prefix
+ * @param entityPrefix indicate the type of entity that should be loaded. This is required for pre-loading the required entities.
+ * @returns a list of entity objects
+ */
+ private toEntities(ids: string[], entityPrefix: string): Entity[] {
+ if (!entityPrefix) {
+ throw new Error("Entity type not defined");
+ }
+ if (!ids) {
+ return [];
+ }
+
+ return ids
+ .filter((id) => {
+ if (typeof id !== "string") {
+ console.debug("invalid entity id in Query :toEntities", id);
+ return false;
+ }
+ return true;
+ })
+ .map((id) => {
+ const prefix = id.split(":")[0];
+ return this.entities[prefix][id];
+ })
+ .filter((entity) => !!entity);
+ }
+
+ /**
+ * Returns all entities which reference a entity from the passed list of entities (by their id)
+ * @param srcEntities the entities for which relations should be found
+ * @param entityType the type of entities where relations should be looked for
+ * @param relationKey the name of the attribute that holds the reference.
+ * The attribute can be a string or a list of strings
+ * @returns a list of the related unique entities
+ */
+ private getRelated(
+ srcEntities: Entity[],
+ entityType: string,
+ relationKey: string,
+ ): Entity[] {
+ const targetEntities = this.toArray(this.entities[entityType]);
+ const srcIds = srcEntities
+ .filter((entity) => typeof entity.getId === "function") // skip empty placeholder objects
+ .map((entity) => entity.getId());
+ if (
+ targetEntities.length > 0 &&
+ Array.isArray(targetEntities[0][relationKey])
+ ) {
+ return targetEntities.filter((entity) =>
+ (entity[relationKey] as string[]).some((id) => srcIds.includes(id)),
+ );
+ } else {
+ return targetEntities.filter((entity) =>
+ entity[relationKey] ? srcIds.includes(entity[relationKey]) : false,
+ );
+ }
+ }
+
+ /**
+ * Filters the data when the filter value is a object (e.g. configurable enum) rather than a simple value
+ * @param objs the objects to be filtered
+ * @param attr the attribute of the objects which is a object itself
+ * @param key the key of the attribute-object which should be compared
+ * @param value the value which will be compared with `obj[attr][key]` for each obj in objs.
+ * The value can be a simple value or list of values separated by `|` (e.g. SCHOOL_CLASS|LIFE_SKILLS).
+ * If it is a list of values, then the object is returned if its value matches any of the given values.
+ * @returns the filtered objects
+ */
+ private filterByObjectAttribute(
+ objs: any[],
+ attr: string,
+ key: string,
+ value: string,
+ ): any[] {
+ // splits at "|" and removes optional whitespace before or after the symbol
+ const values = value.trim().split(/\s*\|\s*/);
+ return objs.filter((obj) => {
+ if (obj?.hasOwnProperty(attr)) {
+ return values.includes(obj[attr][key]?.toString());
+ }
+ return false;
+ });
+ }
+
+ /**
+ * Returns a list of IDs held by each object (e.g. the children-IDs held by an array of notes)
+ * @param objs the objects which each holds a list of IDs
+ * @param key the key on which each object holds a list of IDs
+ * @returns a one dimensional string array holding all IDs which are held by the objects.
+ * This list may contain duplicate IDs. If this is not desired, use `:unique` afterwards.
+ */
+ private getIds(objs: any[], key: string): string[] {
+ const ids: string[] = [];
+ objs.forEach((obj) => {
+ if (obj.hasOwnProperty(key)) {
+ ids.push(...obj[key]);
+ }
+ });
+ return ids;
+ }
+
+ /**
+ * Return the ids of all the participants of the passed events with the defined attendance status using the `countAs`
+ * attribute. The list may contain duplicates and the id does not necessarily have the entity prefix.
+ * @param events the array of events
+ * @param attendanceStatus the status for which should be looked for
+ * @returns the ids of children which have the specified attendance in an event
+ */
+ private getParticipantsWithAttendance(
+ events: EventNote[],
+ attendanceStatus: string,
+ ): string[] {
+ const attendedChildren: string[] = [];
+ events.forEach((e) =>
+ e.children.forEach((childId) => {
+ if (e.getAttendance(childId).status.countAs === attendanceStatus) {
+ attendedChildren.push(childId);
+ }
+ }),
+ );
+ return attendedChildren;
+ }
+
+ /**
+ * Transforms a list of notes or event-notes into a flattened list of participants and their attendance for each event.
+ * @param events the input list of type Note or EventNote
+ * @param includeSchool (optional) also include the school to which a participant belongs
+ * @returns AttendanceInfo[] a list holding information about the attendance of a single participant
+ */
+ private getAttendanceArray(
+ events: Note[],
+ includeSchool = false,
+ ): AttendanceInfo[] {
+ const attendances: AttendanceInfo[] = [];
+ for (const event of events) {
+ const linkedRelations = includeSchool
+ ? this.getMembersOfGroupsForEvent(event)
+ : [];
+
+ for (const child of event.children) {
+ const attendance: AttendanceInfo = {
+ participant: child,
+ status: event.getAttendance(child),
+ };
+
+ const relation = linkedRelations.find((rel) => rel.childId === child);
+ if (relation) {
+ attendance.school = relation.schoolId;
+ }
+
+ attendances.push(attendance);
+ }
+ }
+ return attendances;
+ }
+
+ private getMembersOfGroupsForEvent(event: Note) {
+ return this.toArray(this.entities[ChildSchoolRelation.ENTITY_TYPE]).filter(
+ (relation) =>
+ event.schools.includes(relation.schoolId) &&
+ relation.isActiveAt(event.date),
+ );
+ }
+
+ /**
+ * Transforms a list of attendances infos into an aggregated report for each participant
+ * @param attendances an array of AttendanceInfo objects
+ * @returns AttendanceReport[] for each participant the ID, the number of present and total absences as well as the attendance percentage.
+ */
+ private getAttendanceReport(
+ attendances: AttendanceInfo[],
+ ): AttendanceReport[] {
+ const participantMap: { [key in string]: AttendanceReport } = {};
+ attendances.forEach((attendance) => {
+ if (!participantMap.hasOwnProperty(attendance.participant)) {
+ participantMap[attendance.participant] = {
+ participant: attendance.participant,
+ total: 0,
+ present: 0,
+ percentage: "",
+ detailedStatus: {},
+ };
+ }
+ const report = participantMap[attendance.participant];
+ report.detailedStatus[attendance.status.status.id] = report
+ .detailedStatus[attendance.status.status.id]
+ ? report.detailedStatus[attendance.status.status.id] + 1
+ : 1;
+ if (attendance.status.status.countAs === "PRESENT") {
+ report.present++;
+ }
+ if (attendance.status.status.countAs !== "IGNORE") {
+ report.total++;
+ }
+ if (report.total > 0) {
+ report.percentage = (report.present / report.total).toFixed(2);
+ }
+ });
+ return Object.values(participantMap);
+ }
+
+ /**
+ * Adds all entities of the given type to the input array
+ * @param entities the array before
+ * @param entityType the type of entities which should be added
+ * @returns the input array concatenated with all entities of the entityType
+ */
+ private addEntities(entities: Entity[], entityType: string): Entity[] {
+ return entities.concat(...this.toArray(this.entities[entityType]));
+ }
+
+ /**
+ * Replaces all input values by the string provided
+ * @param data the data which will be replaced
+ * @param value the string which should replace initial data
+ * @returns array of same length as data where every input is value
+ */
+ private setString(data: any[], value: string): string[] | string {
+ return Array.isArray(data) ? data.map(() => value) : value;
+ }
+}
+
+export interface AttendanceInfo {
+ participant: string;
+ status: EventAttendance;
+ school?: string;
+}
+
+export interface AttendanceReport {
+ participant: string;
+ total: number;
+ present: number;
+ percentage: string;
+
+ /** counts by all custom configured status **/
+ detailedStatus?: { [key: string]: number };
+}
+
import { Injectable } from "@angular/core";
+import { Entity, EntityConstructor } from "../entity/model/entity";
+import { Note } from "../../child-dev-project/notes/model/note";
+import { EventNote } from "../../child-dev-project/attendance/model/event-note";
+import { EntityMapperService } from "../entity/entity-mapper/entity-mapper.service";
+import { ChildSchoolRelation } from "../../child-dev-project/children/model/childSchoolRelation";
+import { ChildrenService } from "../../child-dev-project/children/children.service";
+import { AttendanceService } from "../../child-dev-project/attendance/attendance.service";
+import { EventAttendance } from "../../child-dev-project/attendance/model/event-attendance";
+import jsonQuery from "json-query";
+import { EntityRegistry } from "../entity/database-entity.decorator";
+
+/**
+ * A query service which uses the json-query library (https://github.com/auditassistant/json-query).
+ */
+@Injectable({
+ providedIn: "root",
+})
+export class QueryService {
+ private entities: { [type: string]: { [id: string]: Entity } } = {};
+
+ /**
+ * A map of information about the loading state of the different entity types
+ * @private
+ */
+ private entityInfo: {
+ [type: string]: {
+ /**
+ * A optional function which can be used to load this entity that might use a start and end date
+ * @param form
+ * @param to
+ */
+ dataFunction?: (form, to) => Promise<Entity[]>;
+ /**
+ * Whether already all entities of this type have been loaded
+ */
+ allLoaded?: boolean;
+ /**
+ * A certain range in which entities of this type have been loaded
+ */
+ rangeLoaded?: { from: Date; to: Date };
+ /**
+ * Whether updates of this entity are listened to
+ */
+ updating?: boolean;
+ };
+ } = {
+ Note: {
+ dataFunction: (from, to) =>
+ this.childrenService.getNotesInTimespan(from, to),
+ },
+ EventNote: {
+ dataFunction: (from, to) =>
+ this.attendanceService.getEventsOnDate(from, to),
+ },
+ };
+
+ /**
+ * A list of further aliases for which a certain entity needs to be loaded.
+ * This can be necessary if a function requires a certain entity to be present.
+ * @private
+ */
+ private queryStringMap: [string, EntityConstructor][] = [
+ ["getAttendanceArray\\(true\\)", ChildSchoolRelation],
+ ];
+
+ constructor(
+ private entityMapper: EntityMapperService,
+ private childrenService: ChildrenService,
+ private attendanceService: AttendanceService,
+ entityRegistry: EntityRegistry,
+ ) {
+ entityRegistry.forEach((entity, name) =>
+ this.queryStringMap.push([name, entity]),
+ );
+ }
+
+ /**
+ * Runs the query on the passed data object
+ * @param query a string or array according to the json-query language (https://github.com/auditassistant/json-query)
+ * @param from a date which can be accessed in the query using a ?.
+ * @param to a date which can be accessed in the query using another ?
+ * @param data the data on which the query should run, default is all entities
+ * @returns the results of the query on the data
+ */
+ public queryData(query: string, from?: Date, to?: Date, data?: any): any {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+
+ if (!data) {
+ data = this.entities;
+ }
+
+ return jsonQuery([query, from, to], {
+ data: data,
+ locals: {
+ toArray: this.toArray,
+ unique: this.unique,
+ count: this.count,
+ sum: this.sum,
+ avg: this.avg,
+ toEntities: this.toEntities.bind(this),
+ getRelated: this.getRelated.bind(this),
+ filterByObjectAttribute: this.filterByObjectAttribute,
+ getIds: this.getIds,
+ getParticipantsWithAttendance: this.getParticipantsWithAttendance,
+ getAttendanceArray: this.getAttendanceArray.bind(this),
+ getAttendanceReport: this.getAttendanceReport,
+ addEntities: this.addEntities.bind(this),
+ setString: this.setString,
+ },
+ }).value;
+ }
+
+ /**
+ * Call this function to prefetch required data
+ * @param query single query or concatenation of all query strings that will be executed soon
+ * @param from date from which data should be available
+ * @param to date to which data should be available
+ */
+ async cacheRequiredData(query: string, from: Date, to: Date) {
+ from = from ?? new Date(0);
+ to = to ?? new Date();
+ const uncachedEntities = this.getUncachedEntities(query, from, to);
+ const dataPromises = uncachedEntities.map((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ if (info?.dataFunction) {
+ return info.dataFunction(from, to).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ info.rangeLoaded = { from, to };
+ });
+ } else {
+ return this.entityMapper.loadType(entity).then((loadedEntities) => {
+ this.setEntities(entity, loadedEntities);
+ this.entityInfo[entity.ENTITY_TYPE] = { allLoaded: true };
+ });
+ }
+ });
+ await Promise.all(dataPromises);
+ this.applyEntityUpdates(uncachedEntities);
+ }
+
+ private applyEntityUpdates(uncachedEntities: EntityConstructor[]) {
+ uncachedEntities
+ .filter(({ ENTITY_TYPE }) => !this.entityInfo[ENTITY_TYPE].updating)
+ .forEach(({ ENTITY_TYPE }) => {
+ this.entityInfo[ENTITY_TYPE].updating = true;
+ this.entityMapper
+ .receiveUpdates(ENTITY_TYPE)
+ .subscribe(({ entity, type }) => {
+ if (type === "remove") {
+ delete this.entities[ENTITY_TYPE][entity.getId()];
+ } else {
+ this.entities[ENTITY_TYPE][entity.getId()] = entity;
+ }
+ });
+ });
+ }
+
+ /**
+ * Get entities that are referenced in the query string and are not sufficiently cached.
+ * @param query
+ * @param from
+ * @param to
+ * @private
+ */
+ private getUncachedEntities(query: string, from: Date, to: Date) {
+ return this.queryStringMap
+ .filter(([matcher]) =>
+ // matches query string without any alphanumeric characters before or after (e.g. so Child does not match ChildSchoolRelation)
+ query?.match(new RegExp(`(^|\\W)${matcher}(\\W|$)`)),
+ )
+ .map(([_, entity]) => entity)
+ .filter((entity) => {
+ const info = this.entityInfo[entity.ENTITY_TYPE];
+ return (
+ info === undefined ||
+ !(
+ info.allLoaded ||
+ (info.rangeLoaded?.from <= from && info.rangeLoaded?.to >= to)
+ )
+ );
+ });
+ }
+
+ private setEntities<T extends Entity>(
+ entityClass: EntityConstructor<T>,
+ entities: T[],
+ ) {
+ this.entities[entityClass.ENTITY_TYPE] = {};
+ entities.forEach(
+ (entity) =>
+ (this.entities[entityClass.ENTITY_TYPE][entity.getId()] = entity),
+ );
+ }
+
+ /**
+ * Creates an array containing the value of each key of the object.
+ * e.g. `{a: 1, b: 2} => [1,2]`
+ * This should be used when iterating over all documents of a given entity type because they are stored as
+ * `"{entity._id}": {entity}`
+ * @param obj the object which should be transformed to an array
+ * @returns the values of the input object as a list
+ */
+ private toArray(obj): any[] {
+ return Object.values(obj);
+ }
+
+ /**
+ * Returns a copy of the input array without duplicates
+ * @param data the array where duplicates should be removed
+ * @returns a list without duplicates
+ */
+ private unique(data: any[]): any[] {
+ return new Array(...new Set(data));
+ }
+
+ /**
+ * Get the size of an array
+ * @param data the data for which the length should be returned
+ * @returns the length of the input array or 0 if no array is provided
+ */
+ private count(data: any[]): number {
+ return data ? data.length : 0;
+ }
+
+ /**
+ * Returns the (integer) sum of the provided array.
+ * It can also handle integers in strings, e.g. "3"
+ * @param data an integer array
+ * @private
+ */
+ private sum(data: any[]): number {
+ return data.reduce((res, cur) => {
+ const parsed = Number.parseInt(cur);
+ return Number.isNaN(parsed) ? res : res + parsed;
+ }, 0);
+ }
+
+ /**
+ * Returns the avg of the provided array as string.
+ * It can also handle integers in strings, e.g. "3".
+ * The average is only calculated if the value exists and is a valid number.
+ * @param data an integer array
+ * @param decimals the amount of decimals for the result, default 0
+ * @private
+ */
+ private avg(data: any[], decimals = 0): string {
+ const numbers = data
+ .map((d) => Number.parseInt(d))
+ .filter((i) => !Number.isNaN(i));
+ const result =
+ numbers.length === 0
+ ? 0
+ : numbers.reduce((i, sum) => sum + i, 0) / numbers.length;
+ return result.toFixed(decimals);
+ }
+
+ /**
+ * Turns a list of ids (with the entity prefix) into a list of entities
+ * @param ids the array of ids with entity prefix
+ * @param entityPrefix indicate the type of entity that should be loaded. This is required for pre-loading the required entities.
+ * @returns a list of entity objects
+ */
+ private toEntities(ids: string[], entityPrefix: string): Entity[] {
+ if (!entityPrefix) {
+ throw new Error("Entity type not defined");
+ }
+ if (!ids) {
+ return [];
+ }
+
+ return ids
+ .filter((id) => {
+ if (typeof id !== "string") {
+ console.debug("invalid entity id in Query :toEntities", id);
+ return false;
+ }
+ return true;
+ })
+ .map((id) => {
+ const prefix = id.split(":")[0];
+ return this.entities[prefix][id];
+ })
+ .filter((entity) => !!entity);
+ }
+
+ /**
+ * Returns all entities which reference a entity from the passed list of entities (by their id)
+ * @param srcEntities the entities for which relations should be found
+ * @param entityType the type of entities where relations should be looked for
+ * @param relationKey the name of the attribute that holds the reference.
+ * The attribute can be a string or a list of strings
+ * @returns a list of the related unique entities
+ */
+ private getRelated(
+ srcEntities: Entity[],
+ entityType: string,
+ relationKey: string,
+ ): Entity[] {
+ const targetEntities = this.toArray(this.entities[entityType]);
+ const srcIds = srcEntities
+ .filter((entity) => typeof entity.getId === "function") // skip empty placeholder objects
+ .map((entity) => entity.getId());
+ if (
+ targetEntities.length > 0 &&
+ Array.isArray(targetEntities[0][relationKey])
+ ) {
+ return targetEntities.filter((entity) =>
+ (entity[relationKey] as string[]).some((id) => srcIds.includes(id)),
+ );
+ } else {
+ return targetEntities.filter((entity) =>
+ entity[relationKey] ? srcIds.includes(entity[relationKey]) : false,
+ );
+ }
+ }
+
+ /**
+ * Filters the data when the filter value is a object (e.g. configurable enum) rather than a simple value
+ * @param objs the objects to be filtered
+ * @param attr the attribute of the objects which is a object itself
+ * @param key the key of the attribute-object which should be compared
+ * @param value the value which will be compared with `obj[attr][key]` for each obj in objs.
+ * The value can be a simple value or list of values separated by `|` (e.g. SCHOOL_CLASS|LIFE_SKILLS).
+ * If it is a list of values, then the object is returned if its value matches any of the given values.
+ * @returns the filtered objects
+ */
+ private filterByObjectAttribute(
+ objs: any[],
+ attr: string,
+ key: string,
+ value: string,
+ ): any[] {
+ // splits at "|" and removes optional whitespace before or after the symbol
+ const values = value.trim().split(/\s*\|\s*/);
+ return objs.filter((obj) => {
+ if (obj?.hasOwnProperty(attr)) {
+ return values.includes(obj[attr][key]?.toString());
+ }
+ return false;
+ });
+ }
+
+ /**
+ * Returns a list of IDs held by each object (e.g. the children-IDs held by an array of notes)
+ * @param objs the objects which each holds a list of IDs
+ * @param key the key on which each object holds a list of IDs
+ * @returns a one dimensional string array holding all IDs which are held by the objects.
+ * This list may contain duplicate IDs. If this is not desired, use `:unique` afterwards.
+ */
+ private getIds(objs: any[], key: string): string[] {
+ const ids: string[] = [];
+ objs.forEach((obj) => {
+ if (obj.hasOwnProperty(key)) {
+ ids.push(...obj[key]);
+ }
+ });
+ return ids;
+ }
+
+ /**
+ * Return the ids of all the participants of the passed events with the defined attendance status using the `countAs`
+ * attribute. The list may contain duplicates and the id does not necessarily have the entity prefix.
+ * @param events the array of events
+ * @param attendanceStatus the status for which should be looked for
+ * @returns the ids of children which have the specified attendance in an event
+ */
+ private getParticipantsWithAttendance(
+ events: EventNote[],
+ attendanceStatus: string,
+ ): string[] {
+ const attendedChildren: string[] = [];
+ events.forEach((e) =>
+ e.children.forEach((childId) => {
+ if (e.getAttendance(childId).status.countAs === attendanceStatus) {
+ attendedChildren.push(childId);
+ }
+ }),
+ );
+ return attendedChildren;
+ }
+
+ /**
+ * Transforms a list of notes or event-notes into a flattened list of participants and their attendance for each event.
+ * @param events the input list of type Note or EventNote
+ * @param includeSchool (optional) also include the school to which a participant belongs
+ * @returns AttendanceInfo[] a list holding information about the attendance of a single participant
+ */
+ private getAttendanceArray(
+ events: Note[],
+ includeSchool = false,
+ ): AttendanceInfo[] {
+ const attendances: AttendanceInfo[] = [];
+ for (const event of events) {
+ const linkedRelations = includeSchool
+ ? this.getMembersOfGroupsForEvent(event)
+ : [];
+
+ for (const child of event.children) {
+ const attendance: AttendanceInfo = {
+ participant: child,
+ status: event.getAttendance(child),
+ };
+
+ const relation = linkedRelations.find((rel) => rel.childId === child);
+ if (relation) {
+ attendance.school = relation.schoolId;
+ }
+
+ attendances.push(attendance);
+ }
+ }
+ return attendances;
+ }
+
+ private getMembersOfGroupsForEvent(event: Note) {
+ return this.toArray(this.entities[ChildSchoolRelation.ENTITY_TYPE]).filter(
+ (relation) =>
+ event.schools.includes(relation.schoolId) &&
+ relation.isActiveAt(event.date),
+ );
+ }
+
+ /**
+ * Transforms a list of attendances infos into an aggregated report for each participant
+ * @param attendances an array of AttendanceInfo objects
+ * @returns AttendanceReport[] for each participant the ID, the number of present and total absences as well as the attendance percentage.
+ */
+ private getAttendanceReport(
+ attendances: AttendanceInfo[],
+ ): AttendanceReport[] {
+ const participantMap: { [key in string]: AttendanceReport } = {};
+ attendances.forEach((attendance) => {
+ if (!participantMap.hasOwnProperty(attendance.participant)) {
+ participantMap[attendance.participant] = {
+ participant: attendance.participant,
+ total: 0,
+ present: 0,
+ percentage: "",
+ detailedStatus: {},
+ };
+ }
+ const report = participantMap[attendance.participant];
+ report.detailedStatus[attendance.status.status.id] = report
+ .detailedStatus[attendance.status.status.id]
+ ? report.detailedStatus[attendance.status.status.id] + 1
+ : 1;
+ if (attendance.status.status.countAs === "PRESENT") {
+ report.present++;
+ }
+ if (attendance.status.status.countAs !== "IGNORE") {
+ report.total++;
+ }
+ if (report.total > 0) {
+ report.percentage = (report.present / report.total).toFixed(2);
+ }
+ });
+ return Object.values(participantMap);
+ }
+
+ /**
+ * Adds all entities of the given type to the input array
+ * @param entities the array before
+ * @param entityType the type of entities which should be added
+ * @returns the input array concatenated with all entities of the entityType
+ */
+ private addEntities(entities: Entity[], entityType: string): Entity[] {
+ return entities.concat(...this.toArray(this.entities[entityType]));
+ }
+
+ /**
+ * Replaces all input values by the string provided
+ * @param data the data which will be replaced
+ * @param value the string which should replace initial data
+ * @returns array of same length as data where every input is value
+ */
+ private setString(data: any[], value: string): string[] | string {
+ return Array.isArray(data) ? data.map(() => value) : value;
+ }
+}
+
+export interface AttendanceInfo {
+ participant: string;
+ status: EventAttendance;
+ school?: string;
+}
+
+export interface AttendanceReport {
+ participant: string;
+ total: number;
+ present: number;
+ percentage: string;
+
+ /** counts by all custom configured status **/
+ detailedStatus?: { [key: string]: number };
+}
+
import { ConfigurableEnumValue } from "../../../core/basic-datatypes/configurable-enum/configurable-enum.interface";
+
+/**
+ * logical type of an attendance status, i.e. how it will be considered for statistics and analysis.
+ */
+export enum AttendanceLogicalStatus {
+ PRESENT = "PRESENT",
+ ABSENT = "ABSENT",
+ IGNORE = "IGNORE",
+}
+
+/**
+ * the id through which the available attendance status types can be loaded from the ConfigService.
+ */
+export const ATTENDANCE_STATUS_CONFIG_ID = "attendance-status";
+
+/**
+ * Details of one status option users can assign to a participant's details attending an event.
+ */
+export interface AttendanceStatusType extends ConfigurableEnumValue {
+ /** persistent id that remains unchanged in the config database */
+ id: string;
+
+ /** a clear, spelled out title of the status */
+ label: string;
+
+ /** a short (one letter) representation e.g. used in calendar view */
+ shortName: string;
+
+ /**
+ * how this status will be categorized and considered for statistics and analysis
+ */
+ countAs: AttendanceLogicalStatus;
+
+ /** a css class with styling related to the status */
+ style?: string;
+}
+
+/**
+ * Null object representing an unknown attendance status.
+ *
+ * This allows easier handling of attendance status logic because exceptional checks for undefined are not necessary.
+ */
+export const NullAttendanceStatusType: AttendanceStatusType = {
+ id: "",
+ label: "",
+ shortName: "",
+ countAs: AttendanceLogicalStatus.IGNORE,
+};
+
export interface BackgroundProcessState {
+ /** unique name of the process as displayed to user */
+ title: string;
+
+ /**
+ * specific details or context of the process.
+ * this can serve as a "subtitle" for a common title of several similar processes also
+ */
+ details?: string;
+
+ /** additional optional details explaining the process */
+ description?: string;
+
+ /** whether the process is still running */
+ pending: boolean;
+
+ /** if the process has failed, contains the error details; otherwise undefined */
+ error?: any;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
The name of the group that should be selected by default on a mobile device.
+Default is the name of the first group.
+
+
+
+
+
+
+
+
+
+
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
export interface ColumnMapping {
+ /** import data column header id */
+ column: string;
+
+ /** mapped entity property id */
+ propertyName?: string;
+
+ /**
+ * details of data transformation or parsing into the property.
+ *
+ * e.g. date format to be parsed or key-value transformation map
+ */
+ additional?: any;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
Mandatory properties of each option of an configurable enum
+the actual object can contain additional properties in the specific context of that enum (e.g. a color property)
indicates this is a fallback option generated by configurable-enum datatype for
+a value that is not included in the selectable enum options of the config.
optional styling class that should be applied when displaying this value
+
+
+
+
+
+
+
+
+
+
+
import { Ordering } from "./configurable-enum-ordering";
+import HasOrdinal = Ordering.HasOrdinal;
+
+/**
+ * Interface specifying overall object representing an enum with all its options
+ * as stored in the config database
+ */
+export type ConfigurableEnumConfig<
+ T extends ConfigurableEnumValue = ConfigurableEnumValue,
+> = Array<T>;
+
+/**
+ * Mandatory properties of each option of an configurable enum
+ * the actual object can contain additional properties in the specific context of that enum (e.g. a `color` property)
+ */
+export interface ConfigurableEnumValue extends HasOrdinal {
+ /**
+ * identifier that is unique among all values of the same enum and does not change even when label or other things are edited
+ */
+ id: string;
+
+ /**
+ * human-readable name that is displayed representing the value in the UI
+ */
+ label: string;
+
+ /**
+ * an optional color code which should be displayed
+ */
+ color?: string;
+
+ /**
+ * indicates this is a fallback option generated by configurable-enum datatype for
+ * a value that is not included in the selectable enum options of the config.
+ */
+ isInvalidOption?: boolean;
+
+ /**
+ * optional styling class that should be applied when displaying this value
+ */
+ style?: string;
+}
+
+export const EMPTY: ConfigurableEnumValue = {
+ id: "",
+ label: "",
+};
+
import { Component, Inject } from "@angular/core";
+import {
+ MAT_DIALOG_DATA,
+ MatDialogModule,
+ MatDialogRef,
+} from "@angular/material/dialog";
+import { DialogCloseComponent } from "../../dialog-close/dialog-close.component";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatButtonModule } from "@angular/material/button";
+
+/**
+ * A configurable confirmation dialog box
+ * used by the {@link ConfirmationDialogService}.
+ */
+@Component({
+ selector: "app-confirmation-dialog",
+ templateUrl: "./confirmation-dialog.component.html",
+ imports: [
+ DialogCloseComponent,
+ NgIf,
+ MatDialogModule,
+ MatButtonModule,
+ NgForOf,
+ ],
+ standalone: true,
+})
+export class ConfirmationDialogComponent {
+ /**
+ * This component is used as a template for MatDialog, created with the required dependencies through that service.
+ * @param dialogRef The reference to the dialog this component is displayed within
+ * @param data The configuration defining what text and buttons will be displayed
+ */
+ constructor(
+ public dialogRef: MatDialogRef<ConfirmationDialogComponent>,
+ @Inject(MAT_DIALOG_DATA) public data: ConfirmationDialogConfig,
+ ) {}
+}
+
+/**
+ * Options to configure the {@link ConfirmationDialogComponent}.
+ */
+export interface ConfirmationDialogConfig {
+ /** title of the dialog box */
+ title: string;
+
+ /** description text in the dialog box */
+ text: string;
+
+ /** The buttons that should be displayed */
+ buttons: ConfirmationDialogButton[];
+
+ /** Whether or not to specify a 'close' icon-button.
+ * This button is on the top-right of the dialog and closes it with no result
+ */
+ closeButton?: boolean;
+}
+
+export interface ConfirmationDialogButton {
+ text: string;
+ dialogResult?: boolean | undefined;
+ click();
+}
+
+export const OkButton: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog OK:OK`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+];
+
+export const YesNoButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+];
+
+export const YesNoCancelButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+ {
+ text: $localize`:Confirmation dialog Cancel:Cancel`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: undefined,
+ },
+];
+
import { Component, Inject } from "@angular/core";
+import {
+ MAT_DIALOG_DATA,
+ MatDialogModule,
+ MatDialogRef,
+} from "@angular/material/dialog";
+import { DialogCloseComponent } from "../../dialog-close/dialog-close.component";
+import { NgForOf, NgIf } from "@angular/common";
+import { MatButtonModule } from "@angular/material/button";
+
+/**
+ * A configurable confirmation dialog box
+ * used by the {@link ConfirmationDialogService}.
+ */
+@Component({
+ selector: "app-confirmation-dialog",
+ templateUrl: "./confirmation-dialog.component.html",
+ imports: [
+ DialogCloseComponent,
+ NgIf,
+ MatDialogModule,
+ MatButtonModule,
+ NgForOf,
+ ],
+ standalone: true,
+})
+export class ConfirmationDialogComponent {
+ /**
+ * This component is used as a template for MatDialog, created with the required dependencies through that service.
+ * @param dialogRef The reference to the dialog this component is displayed within
+ * @param data The configuration defining what text and buttons will be displayed
+ */
+ constructor(
+ public dialogRef: MatDialogRef<ConfirmationDialogComponent>,
+ @Inject(MAT_DIALOG_DATA) public data: ConfirmationDialogConfig,
+ ) {}
+}
+
+/**
+ * Options to configure the {@link ConfirmationDialogComponent}.
+ */
+export interface ConfirmationDialogConfig {
+ /** title of the dialog box */
+ title: string;
+
+ /** description text in the dialog box */
+ text: string;
+
+ /** The buttons that should be displayed */
+ buttons: ConfirmationDialogButton[];
+
+ /** Whether or not to specify a 'close' icon-button.
+ * This button is on the top-right of the dialog and closes it with no result
+ */
+ closeButton?: boolean;
+}
+
+export interface ConfirmationDialogButton {
+ text: string;
+ dialogResult?: boolean | undefined;
+ click();
+}
+
+export const OkButton: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog OK:OK`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+];
+
+export const YesNoButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+];
+
+export const YesNoCancelButtons: ConfirmationDialogButton[] = [
+ {
+ text: $localize`:Confirmation dialog Yes:Yes`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: true,
+ },
+ {
+ text: $localize`:Confirmation dialog No:No`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: false,
+ },
+ {
+ text: $localize`:Confirmation dialog Cancel:Cancel`,
+ click() {
+ // Intentionally blank
+ // To react to emissions from this button, use the `MatDialogRef.beforeClosed()` hook
+ },
+ dialogResult: undefined,
+ },
+];
+
import { InjectionToken } from "@angular/core";
+
+/**
+ * Use this token to provide (and thereby register) custom implementations of {@link ConflictResolutionStrategy}.
+ *
+ * `{ provide: CONFLICT_RESOLUTION_STRATEGY, useClass: MyConflictResolutionStrategy, multi: true }`
+ *
+ * see {@link ConflictResolutionModule}
+ */
+export const CONFLICT_RESOLUTION_STRATEGY =
+ new InjectionToken<ConflictResolutionStrategy>("ConflictResolutionStrategy");
+
+/**
+ * Implement this interface to provide custom strategies how certain conflicts of an Entity type can be resolved automatically.
+ *
+ * see {@link ConflictResolutionModule}
+ */
+export interface ConflictResolutionStrategy {
+ autoDeleteConflictingRevision(currentDoc: any, conflictingDoc: any): boolean;
+}
+
The format of the JSON object which defines the rules for each role.
+The format is <user-role>: <array of DatabaseRule>, meaning for each role an array of rules can be defined.
+The rules defined in 'default' will be prepended to any other rules defined for a user
import { Ability, RawRuleOf } from "@casl/ability";
+import { Entity, EntityConstructor } from "../entity/model/entity";
+
+/**
+ * The list of action strings that can be used for permissions
+ */
+const actions = [
+ "read",
+ "create",
+ "update",
+ "delete",
+ "manage", // Matches any actions
+] as const;
+
+/**
+ * The type which defines which actions can be used for permissions.
+ * The type allows all strings defined in the `actions` array.
+ * E.g. "read" or "manage"
+ */
+export type EntityActionPermission = (typeof actions)[number];
+
+/**
+ * The type which defines which subjects can be used for permissions.
+ * This matches any entity classes, entity objects and the wildcard string "all"
+ * E.g. `Child`, `new Note()` or `all`
+ */
+export type EntitySubject = EntityConstructor | Entity | string;
+
+/**
+ * The format that the JSON defined rules need to have.
+ * In the JSON object the Entities can be specified by using their ENTITY_TYPE string representation.
+ */
+export type DatabaseRule = RawRuleOf<Ability<[EntityActionPermission, string]>>;
+
+/**
+ * The format of the JSON object which defines the rules for each role.
+ * The format is `<user-role>: <array of DatabaseRule>`, meaning for each role an array of rules can be defined.
+ * The rules defined in 'default' will be prepended to any other rules defined for a user
+ */
+export interface DatabaseRules {
+ public?: DatabaseRule[];
+ default?: DatabaseRule[];
+
+ [key: string]: DatabaseRule[];
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
used as default value in "static" and "dynamic" mode
+
+
+
+
+
+
+
+
+
+
+
export interface DefaultValueConfig {
+ /**
+ * What kind of logic is used to generate the default value:
+ *
+ * mode: inherited
+ * use the value from linked entity field
+ *
+ * mode: static
+ * use a static default value
+ *
+ * mode: dynamic
+ * use a placeholder value, see PLACEHOLDERS enum for available options
+ */
+ mode: DefaultValueMode;
+
+ /** used as default value in "static" and "dynamic" mode */
+ value?: string | number;
+
+ /** local field holding the reference to an Entity (for inherited only) */
+ localAttribute?: string;
+
+ /** field on the referenced Entity (identified by the id value in `localAttribute`), which is used as default value (for inherited only) */
+ field?: string;
+}
+
+export type DefaultValueMode = "inherited" | "static" | "dynamic";
+
This interface is set on the data property of the route.
+It contains static data which are used to build components and manage permissions.
+The generic type defines the interface for the component specific configuration.
+
The properties given in the config object here are automatically assigned to the component as @Input() properties.
+e.g. for an DynamicComponentConfig { config: { "entityType: "Child", "filtered": true } }
+your component MyViewComponent will receive the values mapped to its properties:
string id/name of the component to be displaying this view.
+The component id has to be registered in the component map.
+
(optional) if the ladyLoaded is true, this is not required (and will be ignored)
+ This allows hard-coded lazy-loaded components to be dynamically extended with config or permissions.
Allows to restrict the route to the given list of user roles.
+If set, the route can only be visited by users which have a role which is in the list.
+If not set, all logged-in users can visit the route.
+
+
+
+
+
+
+
+
+
+
+
export interface DynamicComponentConfig<T = any> {
+ /**
+ * string id/name of the component to be displaying this view.
+ * The component id has to be registered in the component map.
+ *
+ * (optional) if the `ladyLoaded` is true, this is not required (and will be ignored)
+ * This allows hard-coded lazy-loaded components to be dynamically extended with config or permissions.
+ */
+ component?: string;
+
+ /** optional object providing any kind of config to be interpreted by the component for this view */
+ config?: T;
+
+ /**
+ * Allows to restrict the route to the given list of user roles.
+ * If set, the route can only be visited by users which have a role which is in the list.
+ * If not set, all logged-in users can visit the route.
+ */
+ permittedUserRoles?: string[];
+}
+
import { Entity } from "../../entity/model/entity";
+import { EntityActionPermission } from "../../permissions/permission-types";
+
+/**
+ * Details of an action that users can trigger for a specific entity, displayed in the context menu.
+ */
+export interface EntityAction {
+ /**
+ * ID for identifying this action in analytics, etc.
+ */
+ action: string;
+
+ /**
+ * human-readable label displayed in menu
+ */
+ label: string;
+ icon: string;
+ tooltip?: string;
+
+ /**
+ * If marked as primary action, it will be displayed directly rather than hidden in the three-dot menu in some contexts.
+ */
+ primaryAction?: boolean;
+
+ /**
+ * The "operation" for Entity Permissions checks that the user needs permission for executing this action.
+ */
+ permission?: EntityActionPermission;
+
+ /**
+ * The method being executed when the action is triggered.
+ * @param e The entity on which the action is executed
+ */
+ execute: (entity: Entity, navigateOnDelete?: boolean) => Promise<boolean>;
+}
+
A list of attributes which should be shown when calling the .toString() method of this entity.
+E.g. showing the first and last name of a child.
+
(optional) the default is the ID of the entity (.entityId)
+
+
+
+
+
+
+
+
+
+
+
import { EntitySchemaField } from "./schema/entity-schema-field";
+
+/**
+ * Dynamic configuration for a entity.
+ * This allows to change entity metadata based on the configuration.
+ */
+export interface EntityConfig {
+ /**
+ * A list of attributes that will be dynamically added/overwritten to the entity.
+ */
+ attributes?: { [key: string]: EntitySchemaField };
+
+ /**
+ * A list of attributes which should be shown when calling the `.toString()` method of this entity.
+ * E.g. showing the first and last name of a child.
+ *
+ * (optional) the default is the ID of the entity (`.entityId`)
+ */
+ toStringAttributes?: string[];
+
+ /**
+ * human-readable name/label of the entity in the UI
+ */
+ label?: string;
+
+ /**
+ * human-readable name/label of the entity in the UI when referring to multiple
+ */
+ labelPlural?: string;
+
+ /**
+ * icon used to visualize the entity type
+ */
+ icon?: string;
+
+ /**
+ * color used for to highlight this entity type across the app
+ */
+ color?: string;
+
+ /**
+ * base route of views for this entity type
+ */
+ route?: string;
+
+ /**
+ * when a new entity is created, all properties from this class will also be available
+ */
+ extends?: string;
+
+ /**
+ * whether the type can contain personally identifiable information (PII)
+ */
+ hasPII?: boolean;
+}
+
The configuration for the panels on this details page.
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "../entity/model/entity";
+
+/**
+ * The configuration for an entity details page
+ */
+export interface EntityDetailsConfig {
+ /**
+ * The name of the entity (according to the ENTITY_TYPE).
+ */
+ entityType: string;
+
+ /**
+ * The configuration for the panels on this details page.
+ */
+ panels: Panel[];
+}
+
+/**
+ * A panel is a simple accordion that can be expanded and closed.
+ * It can hold multiple components.
+ */
+export interface Panel {
+ /**
+ * The title of this panel. This should group the contained components.
+ */
+ title: string;
+
+ /**
+ * The configurations for the components in this panel.
+ */
+ components: PanelComponent[];
+}
+
+/**
+ * The configuration for a component displayed inside a panel.
+ */
+export interface PanelComponent {
+ /**
+ * An optional second title for only this component.
+ */
+ title?: string;
+
+ /**
+ * The name of the component. When registered, this usually is the name of the
+ * component without the `component` suffix
+ */
+ component: string;
+
+ /**
+ * An addition config which will be passed to the component.
+ */
+ config?: any;
+}
+
+/**
+ * This interface represents the config which will be created by the entity-details component and passed to each of
+ * the panel components.
+ *
+ * This is not config that is defined and stored in the config file for customization.
+ */
+export interface PanelConfig<T = any> {
+ /**
+ * The full entity which is displayed in this details page.
+ */
+ entity: Entity;
+
+ /**
+ * Whether this entity has been newly created.
+ */
+ creatingNew?: boolean;
+
+ /**
+ * An additional config which has been defined in the PanelComponent.
+ */
+ config?: T;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
(Optional) Assign any custom "extension" configuration you need for a specific datatype extension.
+
You can pass any kind of value here to allow complex custom datatype transformations
+that are not part of the core datatypes and therefore not included in this core interface.
Configure the default value mode of this field.
+Default values are applied to form fields, if field is empty
+The form will be disabled, until all default value configs are applied
(Optional) Define using which component this property should be editable in lists and forms.
+
The edit component has to be a registered component. Components that are registered contain the DynamicComponent
+decorator
+If nothing is defined, the default component for this datatype will be used.
(Optional) If the dataType of this field references another entity,
+ define the role of this relationship for the entity containing this field.
+
i.e. how "important" is the entity this field is referencing?
+Does this the entity containing this field (not the referenced entity) still have meaning after the referenced entity has been deleted?
(Optional) Define using which component this property should be displayed in lists and forms.
+
The edit component has to be a registered component. Components that are registered contain the DynamicComponent
+decorator
+If nothing is defined, the default component for this datatype will be used.
+
+
+
+
+
+
+
+
+
+
+
import { FormValidatorConfig } from "../../common-components/entity-form/dynamic-form-validators/form-validator-config";
+import { EntityReferenceRole } from "../../basic-datatypes/entity/entity-reference-role";
+import { DefaultValueConfig } from "./default-value-config";
+
+/**
+ * Interface for additional configuration about a DatabaseField schema.
+ *
+ * This is used as parameter for the DatabaseField annotation:
+ *
+ * `@DatabaseField(fieldConfig: EntitySchemaField)`
+ */
+export interface EntitySchemaField {
+ /**
+ * The datatype of this field. This will trigger to matching datatype transformer when saving/loading the entity.
+ *
+ * If you don't set this explicitly, the dataType is inferred from the TypeScript type of the property that is annotated.
+ */
+ dataType?: string;
+
+ /**
+ * If the dataType can hold multiple values, as an array of the given dataType.
+ */
+ isArray?: boolean;
+
+ /**
+ * Set to true to make the framework automatically create an index to retrieve/filter Entities quickly based on this field
+ *
+ * @todo not implemented yet
+ */
+ generateIndex?: boolean;
+
+ /**
+ * If set to `true`, the entity can be found in the global search by entering this value
+ */
+ searchable?: boolean;
+
+ /**
+ * Configure the default value mode of this field.
+ * Default values are applied to form fields, if field is empty
+ * The form will be disabled, until all default value configs are applied
+ *
+ */
+ defaultValue?: DefaultValueConfig;
+
+ /**
+ * (Optional) Assign any custom "extension" configuration you need for a specific datatype extension.
+ *
+ * You can pass any kind of value here to allow complex custom datatype transformations
+ * that are not part of the core datatypes and therefore not included in this core interface.
+ */
+ additional?: any;
+
+ /**
+ * (Optional) If the dataType of this field references another entity,
+ * define the role of this relationship for the entity containing this field.
+ *
+ * i.e. how "important" is the entity this field is referencing?
+ * Does this the entity containing this field (not the referenced entity) still have meaning after the referenced entity has been deleted?
+ *
+ * see options of the `EntityReferenceRole` type
+ */
+ entityReferenceRole?: EntityReferenceRole;
+
+ // TODO: possibly remove viewComponent + editComponent from schema and only infer via dataType (or overwrite in FormFieldConfig)
+
+ /**
+ * (Optional) Define using which component this property should be displayed in lists and forms.
+ *
+ * The edit component has to be a registered component. Components that are registered contain the `DynamicComponent`
+ * decorator
+ * If nothing is defined, the default component for this datatype will be used.
+ */
+ viewComponent?: string;
+
+ /**
+ * (Optional) Define using which component this property should be editable in lists and forms.
+ *
+ * The edit component has to be a registered component. Components that are registered contain the `DynamicComponent`
+ * decorator
+ * If nothing is defined, the default component for this datatype will be used.
+ */
+ editComponent?: string;
+
+ /**
+ * A label which explains this value in a human-readable way
+ */
+ label?: string;
+
+ /**
+ * A short label which can be used in tables.
+ * If nothing is specified, the long name will be used.
+ */
+ labelShort?: string;
+
+ /**
+ * A further description of the property which can be displayed in tooltips.
+ */
+ description?: string;
+
+ validators?: FormValidatorConfig;
+
+ /** whether to show this field in the default details view */
+ showInDetailsView?: boolean;
+
+ /**
+ * whether the field will be retained when the entity is "anonymized".
+ *
+ * By default, fields are removed (data minimization by default).
+ *
+ * "retain-anonymized" triggers a special dataType action to retain the data partially in a special, anonymized form.
+ */
+ anonymize?: "retain" | "retain-anonymized";
+}
+
+/**
+ * Available placeholder variables that can be used to configure a dynamic default value.
+ * (e.g. "$now" to set to current date)
+ */
+export enum PLACEHOLDERS {
+ NOW = "$now",
+ CURRENT_USER = "$current_user",
+}
+
true when the daysSinceLastNote is not accurate but was cut off for performance optimization
+
+
+
+
+
+
+
+
+
+
+
import { Component, Input, OnInit } from "@angular/core";
+import { ChildrenService } from "../../../children/children.service";
+import moment from "moment";
+import { MatTableModule } from "@angular/material/table";
+import { DynamicComponent } from "../../../../core/config/dynamic-components/dynamic-component.decorator";
+import { EntityRegistry } from "../../../../core/entity/database-entity.decorator";
+import { EntityConstructor } from "../../../../core/entity/model/entity";
+import { DecimalPipe, NgIf } from "@angular/common";
+import { EntityBlockComponent } from "../../../../core/basic-datatypes/entity/entity-block/entity-block.component";
+import { DashboardWidget } from "../../../../core/dashboard/dashboard-widget/dashboard-widget";
+import { Note } from "../../model/note";
+import { DashboardListWidgetComponent } from "../../../../core/dashboard/dashboard-list-widget/dashboard-list-widget.component";
+
+interface NotesDashboardConfig {
+ entity?: string;
+ sinceDays?: number;
+ fromBeginningOfWeek?: boolean;
+ mode?: "with-recent-notes" | "without-recent-notes";
+}
+
+/**
+ * Dashboard Widget displaying entities that do not have a recently added Note.
+ *
+ * If you do not set "sinceDays" of "fromBeginningOfWeek" inputs
+ * by default notes since beginning of the current week are considered.
+ */
+@DynamicComponent("NotesDashboard")
+@Component({
+ selector: "app-no-recent-notes-dashboard",
+ templateUrl: "./notes-dashboard.component.html",
+ styleUrls: ["./notes-dashboard.component.scss"],
+ standalone: true,
+ imports: [
+ NgIf,
+ MatTableModule,
+ EntityBlockComponent,
+ DecimalPipe,
+ DashboardListWidgetComponent,
+ ],
+})
+export class NotesDashboardComponent
+ extends DashboardWidget
+ implements OnInit, NotesDashboardConfig
+{
+ static override getRequiredEntities(config: NotesDashboardConfig) {
+ return config?.entity || Note.ENTITY_TYPE;
+ }
+
+ /**
+ * Entity for which the recent notes should be counted.
+ */
+ @Input() set entity(value: string) {
+ this._entity = this.entities.get(value);
+ }
+
+ _entity: EntityConstructor;
+ /**
+ * number of days since last note that entities should be considered having a "recent" note.
+ */
+ @Input() sinceDays = 0;
+
+ /** Whether an additional offset should be automatically added to include notes from the beginning of the week */
+ @Input() fromBeginningOfWeek = true;
+
+ @Input() mode: "with-recent-notes" | "without-recent-notes";
+
+ /**
+ * Entities displayed in the template with additional "daysSinceLastNote" field
+ */
+ entries: EntityWithRecentNoteInfo[];
+
+ subtitle: string;
+
+ constructor(
+ private childrenService: ChildrenService,
+ private entities: EntityRegistry,
+ ) {
+ super();
+ }
+
+ ngOnInit() {
+ if (!this._entity) {
+ this.entity = "Child";
+ }
+
+ let dayRangeBoundary = this.sinceDays;
+ if (this.fromBeginningOfWeek) {
+ dayRangeBoundary += moment().diff(moment().startOf("week"), "days");
+ }
+ switch (this.mode) {
+ case "with-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] <= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities with recent reports:${this._entity.labelPlural} with recent report`;
+ break;
+ case "without-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] >= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities without recent reports:${this._entity.labelPlural} having no recent reports`;
+ break;
+ }
+ }
+
+ private async loadConcernedEntities(
+ filter: (stat: [string, number]) => boolean,
+ dayRangeBoundary: number,
+ ) {
+ const queryRange = Math.round((dayRangeBoundary * 3) / 10) * 10; // query longer range to be able to display exact date of last note for recent
+
+ // recent notes are sorted ascending, without recent notes descending
+ const order = this.mode === "with-recent-notes" ? -1 : 1;
+ const recentNotesMap =
+ await this.childrenService.getDaysSinceLastNoteOfEachEntity(
+ this._entity.ENTITY_TYPE,
+ queryRange,
+ );
+ this.entries = Array.from(recentNotesMap)
+ .filter(filter)
+ .map((stat) => statsToEntityWithRecentNoteInfo(stat, queryRange))
+ .sort((a, b) => order * (b.daysSinceLastNote - a.daysSinceLastNote));
+ }
+
+ get tooltip(): string {
+ switch (this.mode) {
+ case "with-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases with a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ case "without-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases without a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ }
+ }
+
+ get sinceBeginningOfTheWeek(): string {
+ if (this.fromBeginningOfWeek) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note since the beginning of the week':since the beginning of the week`
+ );
+ }
+ }
+
+ get withinTheLastNDays(): string {
+ if (this.sinceDays > 0) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note within the last x days':without a note within the last ${this.sinceDays} days`
+ );
+ }
+ }
+}
+
+/**
+ * details on entity stats to be displayed
+ */
+interface EntityWithRecentNoteInfo {
+ entityId: string;
+ daysSinceLastNote: number;
+ /** true when the daysSinceLastNote is not accurate but was cut off for performance optimization */
+ moreThanDaysSince: boolean;
+}
+
+/**
+ * Map a result entry from getDaysSinceLastNoteOfEachEntity to the EntityWithRecentNoteInfo interface
+ * @param stat Array of [entityId, daysSinceLastNote]
+ * @param queryRange The query range (the maximum of days that exactly calculated)
+ */
+function statsToEntityWithRecentNoteInfo(
+ stat: [string, number],
+ queryRange: number,
+): EntityWithRecentNoteInfo {
+ if (stat[1] < Number.POSITIVE_INFINITY) {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: stat[1],
+ moreThanDaysSince: false,
+ };
+ } else {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: queryRange,
+ moreThanDaysSince: true,
+ };
+ }
+}
+
Group the results of the query based on unique values at property.
+This will also add another column to the list with the title label and the distinct values in the rows.
One or more sub queries to expand one column into multiple columns and/or rows.
+
The queries in the subQueries are executed based on the result(s) from the parent query where:
+each object in the parent query result will lead to its own row in the final export (extending one object into multiple export rows);
+each query in the subQueries will lead to one (or recursively more) columns in the export rows.
export interface ExportColumnConfig {
+ /**
+ * label shown in the header row.
+ *
+ * If not specified, query is used.
+ */
+ label?: string;
+
+ /** The query to access the value for this column from the object to be exported */
+ query: string;
+
+ /**
+ * One or more sub queries to expand one column into multiple columns and/or rows.
+ *
+ * The queries in the subQueries are executed based on the result(s) from the parent query where:
+ * each object in the parent query result will lead to its own row in the final export (extending one object into multiple export rows);
+ * each query in the subQueries will lead to one (or recursively more) columns in the export rows.
+ *
+ * e.g. `{ query: ".participants:toEntities(Child), subQueries: [ {query: "name"}, {query: "phone"} ] }`
+ * => parent query (not output in export): [{..child1}, {..child2}]
+ * => overall result: two export rows: [{ name: "child1", phone: "123"}, {name: "child2", phone: "567"}]
+ */
+ subQueries?: ExportColumnConfig[];
+
+ /**
+ * Group the results of the query based on unique values at `property`.
+ * This will also add another column to the list with the title `label` and the distinct values in the rows.
+ */
+ groupBy?: { label: string; property: string };
+}
+
import { Entity, EntityConstructor } from "../../core/entity/model/entity";
+import { DatabaseEntity } from "../../core/entity/database-entity.decorator";
+import { Aggregation } from "./data-aggregation.service";
+import { ExportColumnConfig } from "../../core/export/data-transformation-service/export-column-config";
+import { DatabaseField } from "../../core/entity/database-field.decorator";
+
+/**
+ * A report can be accessed by users to generate aggregated statistics or customized exports calculated from available data.
+ * "read" permission for a ReportConfig entity is also used to control which users can generate the report's results.
+ *
+ * This is the class which is saved to the database.
+ * However, when using this in code, use the {@link ReportEntity} instead which provides better type safety.
+ */
+@DatabaseEntity("ReportConfig")
+class ReportConfig extends Entity {
+ /** human-readable title of the report */
+ @DatabaseField() title: string;
+
+ /**
+ * (optional) mode of export.
+ * The {@link ReportEntity} holds the restriction on valid report modes.
+ * Default is "reporting"
+ */
+ @DatabaseField() mode?: string;
+
+ /**
+ * (sql only) list of arguments needed for the sql query. Placeholder "?" will be replaced.
+ */
+ @DatabaseField() neededArgs?: string[] = [];
+
+ /** the definitions to calculate the report's aggregations */
+ @DatabaseField() aggregationDefinitions: any[] = [];
+
+ /** (sql only) the definition to calculate the report */
+ @DatabaseField() aggregationDefinition: string | undefined = undefined;
+}
+
+/**
+ * Union type to enable type safety for report configs.
+ * Use this instead of the {@class ReportConfig}
+ */
+export type ReportEntity = AggregationReport | ExportingReport | SqlReport;
+/**
+ * This allows the `ReportEntity` to also be used as a constructor or in the `EntityMapper`
+ */
+export const ReportEntity = ReportConfig as EntityConstructor<ReportEntity>;
+
+/**
+ * Reports handles by the {@class DataAggregationService}
+ */
+export interface AggregationReport extends ReportConfig {
+ mode: "reporting";
+ aggregationDefinitions: Aggregation[];
+}
+
+/**
+ * Reports handles by the {@class DataTransformationService}
+ */
+export interface ExportingReport extends ReportConfig {
+ /**
+ * If no mode is set, it will default to 'exporting'
+ */
+ mode?: "exporting";
+ aggregationDefinitions: ExportColumnConfig[];
+}
+
+/**
+ * Reports handles by the {@class SqlReportService}
+ */
+export interface SqlReport extends ReportConfig {
+ mode: "sql";
+ /**
+ * a valid SQL SELECT statements, can contain "?" placeholder for arguments
+ */
+ aggregationDefinition: string;
+
+ /**
+ * a list of arguments, passed into the sql statement
+ */
+ neededArgs: string[];
+}
+
import { AlertDisplay } from "./alert-display";
+
+export interface AlertConfig {
+ /** The text of the message */
+ message: string;
+
+ /** The type of the message
+ *
+ * - Info messages provide feedback or information to the user without any required action
+ * - Warning messages provide feedback about unexpected or potentially unintended events
+ * - Danger messages inform about errors or critical conditions that the user should not overlook
+ */
+ type: "info" | "warning" | "danger";
+
+ /** The display style (e.g. whether the alert has to be actively dismissed by the user) */
+ display: AlertDisplay;
+}
+
+export interface ExtendedAlertConfig extends AlertConfig {
+ timestamp: Date;
+}
+
import { ColumnConfig } from "../../common-components/entity-form/FormConfig";
+
+/**
+ * A group of related form fields displayed within a Form component.
+ */
+export interface FieldGroup {
+ header?: string;
+ fields: ColumnConfig[];
+}
+
label displayed for this option to the user in the UI
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "../../entity/model/entity";
+import { MongoQuery } from "@casl/ability";
+import { ListFilterComponent } from "../list-filter/list-filter.component";
+import { EventEmitter, Type } from "@angular/core";
+
+/**
+ * This filter can be used to filter an array of entities.
+ * It has to follow the MongoDB Query Syntax {@link https://www.mongodb.com/docs/manual/reference/operator/query/}.
+ *
+ * The filter is parsed using ucast {@link https://github.com/stalniy/ucast/tree/master/packages/mongo2js}
+ */
+export type DataFilter<T> = MongoQuery<T> | {};
+
+export abstract class Filter<T extends Entity> {
+ /**
+ * The component used to display filter option to the user.
+ */
+ component: Type<any> = ListFilterComponent;
+
+ public selectedOptionValues: string[] = [];
+
+ /**
+ * Triggered when this filter changes value
+ * (e.g. when the user selects a new value in a FilterComponent).
+ *
+ * This is part of the filter object because dynamic filter components can't expose @Outputs
+ */
+ selectedOptionChange = new EventEmitter<string[]>();
+
+ protected constructor(
+ public name: string,
+ public label: string = name,
+ ) {}
+
+ abstract getFilter(): DataFilter<T>;
+}
+
+/**
+ * Generic configuration for a filter with different selectable {@link FilterSelectionOption} options.
+ *
+ * This is a reusable format for any kind of dropdown or selection component that offers the user a choice
+ * to narrow down a list of data items.
+ * As the filter function is provided as part of each {@link FilterSelectionOption}
+ * an instance of this FilterSelection class can manage all filter selection logic.
+ */
+export class SelectableFilter<T extends Entity> extends Filter<T> {
+ /**
+ * Generate filter options dynamically from the given value to be matched.
+ *
+ * This is a utility function to make it easier to generate {@link FilterSelectionOption}s for standard cases
+ * if you simply want each option to filter items having the given attribute matching different values.
+ * If you have more sophisticated filtering needs, use the constructor to set {@link FilterSelectionOption}s that
+ * you created yourself.
+ *
+ * @param valuesToMatchAsOptions An array of values to be matched.
+ * A separate FilterSelectionOption is created for each value with a filter
+ * that is true of a data item's property exactly matches that value.
+ * @param attributeName The name of the property of a data item that is compared to the value in the filter function.
+ */
+ public static generateOptions<T extends Entity>(
+ valuesToMatchAsOptions: (string | number)[],
+ attributeName: string,
+ ): FilterSelectionOption<T>[] {
+ return valuesToMatchAsOptions
+ .filter((k) => !!k)
+ .map((k) => ({
+ key: k.toString().toLowerCase(),
+ label: k.toString(),
+ filter: { [attributeName]: k } as DataFilter<T>,
+ }));
+ }
+
+ /**
+ * Create a FilterSelection with different options to be selected.
+ * @param name The name or id describing this filter
+ * @param options An array of different filtering variants to chose between
+ * @param label The user-friendly label describing this filter-selection
+ * (optional, defaults to the name of the selection)
+ */
+ constructor(
+ public override name: string,
+ public options: FilterSelectionOption<T>[],
+ public override label: string = name,
+ ) {
+ super(name, label);
+ this.selectedOptionValues = [];
+ }
+
+ /**
+ * Get the full filter option by its key.
+ * @param key The identifier of the requested option
+ */
+ getOption(key: string): FilterSelectionOption<T> | undefined {
+ return this.options.find((option: FilterSelectionOption<T>): boolean => {
+ return option.key === key;
+ });
+ }
+
+ /**
+ * Get the filter query for the given option.
+ * If the given key is undefined or invalid, the returned filter matches any elements.
+ */
+ public getFilter(): DataFilter<T> {
+ const filters: DataFilter<T>[] = this.selectedOptionValues
+ .map((value: string) => this.getOption(value))
+ .filter((value: FilterSelectionOption<T>) => value !== undefined)
+ .map((previousValue: FilterSelectionOption<T>) => {
+ return previousValue.filter as DataFilter<T>;
+ });
+
+ if (filters.length === 0) {
+ return {} as DataFilter<T>;
+ }
+ return {
+ $or: [...filters],
+ } as unknown as DataFilter<T>;
+ }
+}
+
+/**
+ * Represents one specific option to filter data in a certain way.
+ * used by {@link SelectableFilter}
+ */
+export interface FilterSelectionOption<T> {
+ /** identifier for this option in the parent FilterSelection instance */
+ key: string;
+
+ /** label displayed for this option to the user in the UI */
+ label: string;
+
+ /** Optional color */
+ color?: string;
+
+ /**
+ * The filter query which should be used if this filter is selected
+ */
+ filter: DataFilter<T>;
+}
+
When set to true, the sorting of this column will be disabled.
+Should be used when the sorting will not work correctly/does not make sense.
+E.g. when displaying a list of entities
visibleFrom The minimal screen size where the column is shown.
+ screen size classes: xs 'screen and (max-width: 599px)'
+ sm 'screen and (min-width: 600px) and (max-width: 959px)'
+ md 'screen and (min-width: 960px) and (max-width: 1279px)'
+ lg 'screen and (min-width: 1280px) and (max-width: 1919px)'
+ xl 'screen and (min-width: 1920px) and (max-width: 5000px)'
+
+
+
+
+
+
+
+
+
+
+
import { EntitySchemaField } from "../../entity/schema/entity-schema-field";
+
+/**
+ * The general configuration for fields in tables and forms.
+ * This defines which property is displayed and how it should be displayed.
+ *
+ * You can just provide the id as string or overwrite any EntitySchemaField property here as necessary.
+ */
+export interface FormFieldConfig extends EntitySchemaField {
+ /**
+ * The id of the entity which should be accessed
+ */
+ id: string;
+
+ /**
+ * When set to true, the sorting of this column will be disabled.
+ * Should be used when the sorting will not work correctly/does not make sense.
+ * E.g. when displaying a list of entities
+ */
+ noSorting?: boolean;
+
+ /**
+ * visibleFrom The minimal screen size where the column is shown.
+ * screen size classes: xs 'screen and (max-width: 599px)'
+ * sm 'screen and (min-width: 600px) and (max-width: 959px)'
+ * md 'screen and (min-width: 960px) and (max-width: 1279px)'
+ * lg 'screen and (min-width: 1280px) and (max-width: 1919px)'
+ * xl 'screen and (min-width: 1920px) and (max-width: 5000px)'
+ */
+ visibleFrom?: "xs" | "sm" | "md" | "lg" | "xl";
+
+ /**
+ * If true, the field will only be shown in forms and popups, but not in tables.
+ */
+ hideFromTable?: boolean;
+
+ /**
+ * If true, the field will only be shown in tables and excluded from forms and popups.
+ */
+ hideFromForm?: boolean;
+
+ /**
+ * An internal flag that will be automatically set in the entity subrecord in order to adapt the view/edit components.
+ */
+ forTable?: boolean;
+}
+
+/**
+ * Type for the definition of a single column in the EntitySubrecord
+ */
+export type ColumnConfig = string | FormFieldConfig;
+
+export function toFormFieldConfig(column: ColumnConfig): FormFieldConfig {
+ if (typeof column === "string") {
+ return { id: column };
+ } else {
+ return column;
+ }
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
Support for types of configurable enums that impose a total ordering of their elements.
+Not all configurable enums (should sensibly) be able to be ordered. For example, it does
+not make sense to see which school / center is "greater than" another center, or which gender is above
+which other gender.
+
For other enum types it is, however, sensible to impose a total ordering such as warning levels ('OK' is
+somewhat 'better' than 'WARNING').
+
Configurable enum values that impose a total ordering can be compared, which also means that they can be sorted,
+and thus have a notion of one element being 'greater than' or 'less than' to another element. The interpretation
+of 'greater' or 'less' than is dependent on the concrete enum.
import {
+ ConfigurableEnumConfig,
+ ConfigurableEnumValue,
+} from "./configurable-enum.interface";
+import { isObject } from "lodash-es";
+
+export namespace Ordering {
+ /**
+ * Support for types of configurable enums that impose a total ordering of their elements.
+ * Not all configurable enums (should sensibly) be able to be ordered. For example, it does
+ * not make sense to see which school / center is "greater than" another center, or which gender is above
+ * which other gender.
+ *
+ * For other enum types it is, however, sensible to impose a total ordering such as warning levels ('OK' is
+ * somewhat 'better' than 'WARNING').
+ *
+ * Configurable enum values that impose a total ordering can be compared, which also means that they can be sorted,
+ * and thus have a notion of one element being 'greater than' or 'less than' to another element. The interpretation
+ * of 'greater' or 'less' than is dependent on the concrete enum.
+ */
+ export interface HasOrdinal {
+ _ordinal?: number;
+ }
+
+ export function hasOrdinalValue(value: any): value is HasOrdinal {
+ return isObject(value) && "_ordinal" in value;
+ }
+
+ export type EnumValue<
+ T extends ConfigurableEnumValue = ConfigurableEnumValue,
+ > = T & HasOrdinal;
+
+ export type Config<T extends ConfigurableEnumValue> = ConfigurableEnumConfig<
+ T & HasOrdinal
+ >;
+
+ /**
+ * Extends an array of configurable enum values with an ordinal value so that the
+ * ordinal value of each enum value matches the position of the element in the array.
+ *
+ * Note that this should be used 'early' in the pipeline, i.e. when the `ConfigurableEnumConfig` is just
+ * created. It is technically not incorrect to use this function on any array that contains configurable
+ * enum values, but it doesn't make sense to apply this function to 'scrambled' arrays, i.e. arrays where the
+ * ordering of values is _not_ the natural order of these values.
+ *
+ * @param values The values to impose a total ordering on
+ */
+ export function imposeTotalOrdering<T extends ConfigurableEnumValue>(
+ values: ConfigurableEnumConfig<T>,
+ ): ConfigurableEnumConfig<EnumValue<T>> {
+ return values.map((val, i) => Object.assign({ _ordinal: i }, val));
+ }
+}
+
whether the Note is a group type category that stores attendance details for each related person
+
+
+
+
+
+
+
+
+
+
+
import { ConfigurableEnumValue } from "../../../core/basic-datatypes/configurable-enum/configurable-enum.interface";
+
+/**
+ * Additional properties defined in the "interaction-type" {@link ConfigurableEnumValue} values
+ * providing special context for {@link Note} categories.
+ */
+export interface InteractionType extends ConfigurableEnumValue {
+ /** whether the Note is a group type category that stores attendance details for each related person */
+ isMeeting?: boolean;
+}
+
+/**
+ * ID of the Note category {@link ConfigurableEnumValue} in the config database.
+ */
+export const INTERACTION_TYPE_CONFIG_ID = "interaction-type";
+
Mapped properties which should be displayed in a map (of left and right entity).
+The properties need to have the format { lat: number, lon: number}.
+
e.g. `["address", "location"]
+
+
+
+
+
+
+
+
+
+
+
import { FilterConfig } from "../../../core/entity-list/EntityListConfig";
+import { Entity, EntityConstructor } from "../../../core/entity/model/entity";
+import { ColumnConfig } from "../../../core/common-components/entity-form/FormConfig";
+import { DataFilter } from "../../../core/filter/filters/filters";
+
+/**
+ * Config to be defined to set up a MatchingEntitiesComponent.
+ */
+export interface MatchingEntitiesConfig {
+ /**
+ * mapped columns to be compared side-by-side between the two entities to match.
+ *
+ * e.g. [["name", "name"], ["motherTongue", "language"]]
+ */
+ columns?: [string, string][];
+
+ /**
+ * Mapped properties which should be displayed in a map (of left and right entity).
+ * The properties need to have the format `{ lat: number, lon: number}`.
+ *
+ * e.g. `["address", "location"]
+ */
+ showMap?: [string, string];
+
+ /** overwrite the button label to describe the matching action */
+ matchActionLabel?: string;
+
+ /** details of what is created when matching two entities */
+ onMatch?: NewMatchAction;
+
+ /** details of entities on this side of the matching view */
+ leftSide?: MatchingSideConfig;
+
+ /** details of entities on this side of the matching view */
+ rightSide?: MatchingSideConfig;
+}
+
+export interface MatchingSideConfig {
+ /**
+ * entity type of matching, used to load a list of available entities for manual selection
+ */
+ entityType?: EntityConstructor | string;
+
+ /** fixed pre-filters applied to remove some entities from the list of available entities */
+ prefilter?: DataFilter<Entity>;
+
+ /** UI filter elements displayed for users to filter available entities */
+ availableFilters?: FilterConfig[];
+
+ /** columns of the available entities table. Usually inferred from matching columns of the component */
+ columns?: ColumnConfig[];
+}
+
+export interface NewMatchAction {
+ /** the entity type to be created on matching to represent the new match */
+ newEntityType: string;
+
+ /** name of the property on newEntityType that should take the id of the left matching entity */
+ newEntityMatchPropertyLeft: string;
+
+ /** name of the property on newEntityType that should take the id of the right matching entity */
+ newEntityMatchPropertyRight: string;
+
+ /**
+ * columns to display in a popup to review, edit and confirm during creation of a match.
+ * If undefined, match is created immediately without a popup form.
+ */
+ columnsToReview?: ColumnConfig[];
+}
+
fixed pre-filters applied to remove some entities from the list of available entities
+
+
+
+
+
+
+
+
+
+
+
import { FilterConfig } from "../../../core/entity-list/EntityListConfig";
+import { Entity, EntityConstructor } from "../../../core/entity/model/entity";
+import { ColumnConfig } from "../../../core/common-components/entity-form/FormConfig";
+import { DataFilter } from "../../../core/filter/filters/filters";
+
+/**
+ * Config to be defined to set up a MatchingEntitiesComponent.
+ */
+export interface MatchingEntitiesConfig {
+ /**
+ * mapped columns to be compared side-by-side between the two entities to match.
+ *
+ * e.g. [["name", "name"], ["motherTongue", "language"]]
+ */
+ columns?: [string, string][];
+
+ /**
+ * Mapped properties which should be displayed in a map (of left and right entity).
+ * The properties need to have the format `{ lat: number, lon: number}`.
+ *
+ * e.g. `["address", "location"]
+ */
+ showMap?: [string, string];
+
+ /** overwrite the button label to describe the matching action */
+ matchActionLabel?: string;
+
+ /** details of what is created when matching two entities */
+ onMatch?: NewMatchAction;
+
+ /** details of entities on this side of the matching view */
+ leftSide?: MatchingSideConfig;
+
+ /** details of entities on this side of the matching view */
+ rightSide?: MatchingSideConfig;
+}
+
+export interface MatchingSideConfig {
+ /**
+ * entity type of matching, used to load a list of available entities for manual selection
+ */
+ entityType?: EntityConstructor | string;
+
+ /** fixed pre-filters applied to remove some entities from the list of available entities */
+ prefilter?: DataFilter<Entity>;
+
+ /** UI filter elements displayed for users to filter available entities */
+ availableFilters?: FilterConfig[];
+
+ /** columns of the available entities table. Usually inferred from matching columns of the component */
+ columns?: ColumnConfig[];
+}
+
+export interface NewMatchAction {
+ /** the entity type to be created on matching to represent the new match */
+ newEntityType: string;
+
+ /** name of the property on newEntityType that should take the id of the left matching entity */
+ newEntityMatchPropertyLeft: string;
+
+ /** name of the property on newEntityType that should take the id of the right matching entity */
+ newEntityMatchPropertyRight: string;
+
+ /**
+ * columns to display in a popup to review, edit and confirm during creation of a match.
+ * If undefined, match is created immediately without a popup form.
+ */
+ columnsToReview?: ColumnConfig[];
+}
+
The url fragment to which the item will route to (e.g. '/dashboard')
+
+
+
+
+
+
+
+
+
+
+
export interface MenuItem {
+ /**
+ * The text to be displayed in the menu.
+ */
+ label: string;
+ /**
+ * The icon to be displayed left of the label.
+ */
+ icon?: string;
+ /**
+ * The url fragment to which the item will route to (e.g. '/dashboard')
+ */
+ link: string;
+}
+
+/**
+ * Object specifying overall navigation menu
+ * as stored in the config database
+ */
+export interface NavigationMenuConfig {
+ items: MenuItem[];
+}
+
export interface MenuItem {
+ /**
+ * The text to be displayed in the menu.
+ */
+ label: string;
+ /**
+ * The icon to be displayed left of the label.
+ */
+ icon?: string;
+ /**
+ * The url fragment to which the item will route to (e.g. '/dashboard')
+ */
+ link: string;
+}
+
+/**
+ * Object specifying overall navigation menu
+ * as stored in the config database
+ */
+export interface NavigationMenuConfig {
+ items: MenuItem[];
+}
+
columns to display in a popup to review, edit and confirm during creation of a match.
+If undefined, match is created immediately without a popup form.
the entity type to be created on matching to represent the new match
+
+
+
+
+
+
+
+
+
+
+
import { FilterConfig } from "../../../core/entity-list/EntityListConfig";
+import { Entity, EntityConstructor } from "../../../core/entity/model/entity";
+import { ColumnConfig } from "../../../core/common-components/entity-form/FormConfig";
+import { DataFilter } from "../../../core/filter/filters/filters";
+
+/**
+ * Config to be defined to set up a MatchingEntitiesComponent.
+ */
+export interface MatchingEntitiesConfig {
+ /**
+ * mapped columns to be compared side-by-side between the two entities to match.
+ *
+ * e.g. [["name", "name"], ["motherTongue", "language"]]
+ */
+ columns?: [string, string][];
+
+ /**
+ * Mapped properties which should be displayed in a map (of left and right entity).
+ * The properties need to have the format `{ lat: number, lon: number}`.
+ *
+ * e.g. `["address", "location"]
+ */
+ showMap?: [string, string];
+
+ /** overwrite the button label to describe the matching action */
+ matchActionLabel?: string;
+
+ /** details of what is created when matching two entities */
+ onMatch?: NewMatchAction;
+
+ /** details of entities on this side of the matching view */
+ leftSide?: MatchingSideConfig;
+
+ /** details of entities on this side of the matching view */
+ rightSide?: MatchingSideConfig;
+}
+
+export interface MatchingSideConfig {
+ /**
+ * entity type of matching, used to load a list of available entities for manual selection
+ */
+ entityType?: EntityConstructor | string;
+
+ /** fixed pre-filters applied to remove some entities from the list of available entities */
+ prefilter?: DataFilter<Entity>;
+
+ /** UI filter elements displayed for users to filter available entities */
+ availableFilters?: FilterConfig[];
+
+ /** columns of the available entities table. Usually inferred from matching columns of the component */
+ columns?: ColumnConfig[];
+}
+
+export interface NewMatchAction {
+ /** the entity type to be created on matching to represent the new match */
+ newEntityType: string;
+
+ /** name of the property on newEntityType that should take the id of the left matching entity */
+ newEntityMatchPropertyLeft: string;
+
+ /** name of the property on newEntityType that should take the id of the right matching entity */
+ newEntityMatchPropertyRight: string;
+
+ /**
+ * columns to display in a popup to review, edit and confirm during creation of a match.
+ * If undefined, match is created immediately without a popup form.
+ */
+ columnsToReview?: ColumnConfig[];
+}
+
import { Component, Input, OnInit } from "@angular/core";
+import { ChildrenService } from "../../../children/children.service";
+import moment from "moment";
+import { MatTableModule } from "@angular/material/table";
+import { DynamicComponent } from "../../../../core/config/dynamic-components/dynamic-component.decorator";
+import { EntityRegistry } from "../../../../core/entity/database-entity.decorator";
+import { EntityConstructor } from "../../../../core/entity/model/entity";
+import { DecimalPipe, NgIf } from "@angular/common";
+import { EntityBlockComponent } from "../../../../core/basic-datatypes/entity/entity-block/entity-block.component";
+import { DashboardWidget } from "../../../../core/dashboard/dashboard-widget/dashboard-widget";
+import { Note } from "../../model/note";
+import { DashboardListWidgetComponent } from "../../../../core/dashboard/dashboard-list-widget/dashboard-list-widget.component";
+
+interface NotesDashboardConfig {
+ entity?: string;
+ sinceDays?: number;
+ fromBeginningOfWeek?: boolean;
+ mode?: "with-recent-notes" | "without-recent-notes";
+}
+
+/**
+ * Dashboard Widget displaying entities that do not have a recently added Note.
+ *
+ * If you do not set "sinceDays" of "fromBeginningOfWeek" inputs
+ * by default notes since beginning of the current week are considered.
+ */
+@DynamicComponent("NotesDashboard")
+@Component({
+ selector: "app-no-recent-notes-dashboard",
+ templateUrl: "./notes-dashboard.component.html",
+ styleUrls: ["./notes-dashboard.component.scss"],
+ standalone: true,
+ imports: [
+ NgIf,
+ MatTableModule,
+ EntityBlockComponent,
+ DecimalPipe,
+ DashboardListWidgetComponent,
+ ],
+})
+export class NotesDashboardComponent
+ extends DashboardWidget
+ implements OnInit, NotesDashboardConfig
+{
+ static override getRequiredEntities(config: NotesDashboardConfig) {
+ return config?.entity || Note.ENTITY_TYPE;
+ }
+
+ /**
+ * Entity for which the recent notes should be counted.
+ */
+ @Input() set entity(value: string) {
+ this._entity = this.entities.get(value);
+ }
+
+ _entity: EntityConstructor;
+ /**
+ * number of days since last note that entities should be considered having a "recent" note.
+ */
+ @Input() sinceDays = 0;
+
+ /** Whether an additional offset should be automatically added to include notes from the beginning of the week */
+ @Input() fromBeginningOfWeek = true;
+
+ @Input() mode: "with-recent-notes" | "without-recent-notes";
+
+ /**
+ * Entities displayed in the template with additional "daysSinceLastNote" field
+ */
+ entries: EntityWithRecentNoteInfo[];
+
+ subtitle: string;
+
+ constructor(
+ private childrenService: ChildrenService,
+ private entities: EntityRegistry,
+ ) {
+ super();
+ }
+
+ ngOnInit() {
+ if (!this._entity) {
+ this.entity = "Child";
+ }
+
+ let dayRangeBoundary = this.sinceDays;
+ if (this.fromBeginningOfWeek) {
+ dayRangeBoundary += moment().diff(moment().startOf("week"), "days");
+ }
+ switch (this.mode) {
+ case "with-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] <= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities with recent reports:${this._entity.labelPlural} with recent report`;
+ break;
+ case "without-recent-notes":
+ this.loadConcernedEntities(
+ (stat) => stat[1] >= dayRangeBoundary,
+ dayRangeBoundary,
+ );
+ this.subtitle = $localize`:Subtitle|Subtitle informing the user that these are the entities without recent reports:${this._entity.labelPlural} having no recent reports`;
+ break;
+ }
+ }
+
+ private async loadConcernedEntities(
+ filter: (stat: [string, number]) => boolean,
+ dayRangeBoundary: number,
+ ) {
+ const queryRange = Math.round((dayRangeBoundary * 3) / 10) * 10; // query longer range to be able to display exact date of last note for recent
+
+ // recent notes are sorted ascending, without recent notes descending
+ const order = this.mode === "with-recent-notes" ? -1 : 1;
+ const recentNotesMap =
+ await this.childrenService.getDaysSinceLastNoteOfEachEntity(
+ this._entity.ENTITY_TYPE,
+ queryRange,
+ );
+ this.entries = Array.from(recentNotesMap)
+ .filter(filter)
+ .map((stat) => statsToEntityWithRecentNoteInfo(stat, queryRange))
+ .sort((a, b) => order * (b.daysSinceLastNote - a.daysSinceLastNote));
+ }
+
+ get tooltip(): string {
+ switch (this.mode) {
+ case "with-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases with a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ case "without-recent-notes":
+ return $localize`:Tooltip|Spaces in front of the variables are added automatically:includes cases without a note${this.sinceBeginningOfTheWeek}:sinceBeginningOfWeek:${this.withinTheLastNDays}:withinTheLastDays:`;
+ }
+ }
+
+ get sinceBeginningOfTheWeek(): string {
+ if (this.fromBeginningOfWeek) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note since the beginning of the week':since the beginning of the week`
+ );
+ }
+ }
+
+ get withinTheLastNDays(): string {
+ if (this.sinceDays > 0) {
+ return (
+ " " +
+ $localize`:Tooltip-part|'includes cases without a note within the last x days':without a note within the last ${this.sinceDays} days`
+ );
+ }
+ }
+}
+
+/**
+ * details on entity stats to be displayed
+ */
+interface EntityWithRecentNoteInfo {
+ entityId: string;
+ daysSinceLastNote: number;
+ /** true when the daysSinceLastNote is not accurate but was cut off for performance optimization */
+ moreThanDaysSince: boolean;
+}
+
+/**
+ * Map a result entry from getDaysSinceLastNoteOfEachEntity to the EntityWithRecentNoteInfo interface
+ * @param stat Array of [entityId, daysSinceLastNote]
+ * @param queryRange The query range (the maximum of days that exactly calculated)
+ */
+function statsToEntityWithRecentNoteInfo(
+ stat: [string, number],
+ queryRange: number,
+): EntityWithRecentNoteInfo {
+ if (stat[1] < Number.POSITIVE_INFINITY) {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: stat[1],
+ moreThanDaysSince: false,
+ };
+ } else {
+ return {
+ entityId: stat[0],
+ daysSinceLastNote: queryRange,
+ moreThanDaysSince: true,
+ };
+ }
+}
+
The title of this panel. This should group the contained components.
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "../entity/model/entity";
+
+/**
+ * The configuration for an entity details page
+ */
+export interface EntityDetailsConfig {
+ /**
+ * The name of the entity (according to the ENTITY_TYPE).
+ */
+ entityType: string;
+
+ /**
+ * The configuration for the panels on this details page.
+ */
+ panels: Panel[];
+}
+
+/**
+ * A panel is a simple accordion that can be expanded and closed.
+ * It can hold multiple components.
+ */
+export interface Panel {
+ /**
+ * The title of this panel. This should group the contained components.
+ */
+ title: string;
+
+ /**
+ * The configurations for the components in this panel.
+ */
+ components: PanelComponent[];
+}
+
+/**
+ * The configuration for a component displayed inside a panel.
+ */
+export interface PanelComponent {
+ /**
+ * An optional second title for only this component.
+ */
+ title?: string;
+
+ /**
+ * The name of the component. When registered, this usually is the name of the
+ * component without the `component` suffix
+ */
+ component: string;
+
+ /**
+ * An addition config which will be passed to the component.
+ */
+ config?: any;
+}
+
+/**
+ * This interface represents the config which will be created by the entity-details component and passed to each of
+ * the panel components.
+ *
+ * This is not config that is defined and stored in the config file for customization.
+ */
+export interface PanelConfig<T = any> {
+ /**
+ * The full entity which is displayed in this details page.
+ */
+ entity: Entity;
+
+ /**
+ * Whether this entity has been newly created.
+ */
+ creatingNew?: boolean;
+
+ /**
+ * An additional config which has been defined in the PanelComponent.
+ */
+ config?: T;
+}
+
import { Entity } from "../entity/model/entity";
+
+/**
+ * The configuration for an entity details page
+ */
+export interface EntityDetailsConfig {
+ /**
+ * The name of the entity (according to the ENTITY_TYPE).
+ */
+ entityType: string;
+
+ /**
+ * The configuration for the panels on this details page.
+ */
+ panels: Panel[];
+}
+
+/**
+ * A panel is a simple accordion that can be expanded and closed.
+ * It can hold multiple components.
+ */
+export interface Panel {
+ /**
+ * The title of this panel. This should group the contained components.
+ */
+ title: string;
+
+ /**
+ * The configurations for the components in this panel.
+ */
+ components: PanelComponent[];
+}
+
+/**
+ * The configuration for a component displayed inside a panel.
+ */
+export interface PanelComponent {
+ /**
+ * An optional second title for only this component.
+ */
+ title?: string;
+
+ /**
+ * The name of the component. When registered, this usually is the name of the
+ * component without the `component` suffix
+ */
+ component: string;
+
+ /**
+ * An addition config which will be passed to the component.
+ */
+ config?: any;
+}
+
+/**
+ * This interface represents the config which will be created by the entity-details component and passed to each of
+ * the panel components.
+ *
+ * This is not config that is defined and stored in the config file for customization.
+ */
+export interface PanelConfig<T = any> {
+ /**
+ * The full entity which is displayed in this details page.
+ */
+ entity: Entity;
+
+ /**
+ * Whether this entity has been newly created.
+ */
+ creatingNew?: boolean;
+
+ /**
+ * An additional config which has been defined in the PanelComponent.
+ */
+ config?: T;
+}
+
The full entity which is displayed in this details page.
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "../entity/model/entity";
+
+/**
+ * The configuration for an entity details page
+ */
+export interface EntityDetailsConfig {
+ /**
+ * The name of the entity (according to the ENTITY_TYPE).
+ */
+ entityType: string;
+
+ /**
+ * The configuration for the panels on this details page.
+ */
+ panels: Panel[];
+}
+
+/**
+ * A panel is a simple accordion that can be expanded and closed.
+ * It can hold multiple components.
+ */
+export interface Panel {
+ /**
+ * The title of this panel. This should group the contained components.
+ */
+ title: string;
+
+ /**
+ * The configurations for the components in this panel.
+ */
+ components: PanelComponent[];
+}
+
+/**
+ * The configuration for a component displayed inside a panel.
+ */
+export interface PanelComponent {
+ /**
+ * An optional second title for only this component.
+ */
+ title?: string;
+
+ /**
+ * The name of the component. When registered, this usually is the name of the
+ * component without the `component` suffix
+ */
+ component: string;
+
+ /**
+ * An addition config which will be passed to the component.
+ */
+ config?: any;
+}
+
+/**
+ * This interface represents the config which will be created by the entity-details component and passed to each of
+ * the panel components.
+ *
+ * This is not config that is defined and stored in the config file for customization.
+ */
+export interface PanelConfig<T = any> {
+ /**
+ * The full entity which is displayed in this details page.
+ */
+ entity: Entity;
+
+ /**
+ * Whether this entity has been newly created.
+ */
+ creatingNew?: boolean;
+
+ /**
+ * An additional config which has been defined in the PanelComponent.
+ */
+ config?: T;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
import { FilterSelectionOption } from "../filter/filters/filters";
+import { FormFieldConfig } from "../common-components/entity-form/FormConfig";
+import { ExportColumnConfig } from "../export/data-transformation-service/export-column-config";
+import { Sort } from "@angular/material/sort";
+import { unitOfTime } from "moment";
+
+export interface EntityListConfig {
+ /**
+ * Title that is shown on top of the component
+ */
+ title?: string;
+
+ /**
+ * Select which entities should be displayed in the table
+ * (optional) This is only used and necessary if EntityListComponent is used directly in config
+ */
+ entityType?: string;
+
+ /**
+ * Custom overwrites or additional columns to be displayed in the table.
+ *
+ * If any special columns aside from the entity's fields are needed, add them here.
+ * Fields of the entity type are available automatically.
+ */
+ columns?: (FormFieldConfig | string)[];
+
+ /**
+ * Optional config for which columns are displayed.
+ * By default, all columns are shown
+ */
+ columnGroups?: ColumnGroupsConfig;
+
+ /**
+ * Optional config for available filters.
+ * Default is no filters.
+ */
+ filters?: FilterConfig[];
+
+ /**
+ * Optional initial sort order.
+ * Default is to sort by the first column.
+ */
+ defaultSort?: Sort;
+
+ /**
+ * Optional config defining what fields are included in exports.
+ */
+ exportConfig?: ExportColumnConfig[];
+}
+
+export interface ColumnGroupsConfig {
+ groups: GroupConfig[];
+
+ /**
+ * The name of the group that should be selected by default.
+ * Default is the name of the first group.
+ */
+ default?: string;
+
+ /**
+ * The name of the group that should be selected by default on a mobile device.
+ * Default is the name of the first group.
+ */
+ mobile?: string;
+}
+
+export interface GroupConfig {
+ name: string;
+ columns: string[];
+}
+
+export type FilterConfig<T = any> =
+ | BasicFilterConfig
+ | BooleanFilterConfig
+ | PrebuiltFilterConfig<T>
+ | ConfigurableEnumFilterConfig<T>;
+
+export interface BasicFilterConfig {
+ id: string;
+ type?: string;
+ default?: string;
+ label?: string;
+}
+
+export interface BooleanFilterConfig extends BasicFilterConfig {
+ true: string;
+ false: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+export interface DateRangeFilterConfig extends BasicFilterConfig {
+ options: DateRangeFilterConfigOption[];
+}
+
+export interface DateRangeFilterConfigOption {
+ startOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ endOffsets?: { amount: number; unit: unitOfTime.Base }[];
+ label: string;
+}
+
+export interface PrebuiltFilterConfig<T> extends BasicFilterConfig {
+ options: FilterSelectionOption<T>[];
+}
+
+export interface ConfigurableEnumFilterConfig<T> extends BasicFilterConfig {
+ enumId: string;
+}
+
For breadcrumbs created from browser events, the Sentry SDK often supplies the event to the breadcrumb as a hint.
+This can be used to extract data from the target DOM element into a breadcrumb, for example.
The session info which holds information about the currently logged-in user.
+This is retrieved during the login process and will always be present once state changes to LOGGED_IN.
import { Injectable } from "@angular/core";
+import { BehaviorSubject } from "rxjs";
+
+/**
+ * The session info which holds information about the currently logged-in user.
+ * This is retrieved during the login process and will always be present once state changes to `LOGGED_IN`.
+ */
+export interface SessionInfo {
+ /*
+ * The user account id from the auth server (e.g. User ID in Keycloak)
+ */
+ id: string;
+
+ /**
+ * Name of user account.
+ * @deprecated Use id or entityId instead as this is an unpredictable mix from different sources
+ */
+ name: string;
+
+ /**
+ * List of roles the logged-in user hold.
+ */
+ roles: string[];
+
+ /**
+ * List of linked projects
+ */
+ projects?: string[];
+
+ /**
+ * ID of the entity which is connected with the user account.
+ *
+ * This is either a full ID or (e.g. Child:123) or only the last part.
+ * In the later case it refers to the `User` entity.
+ */
+ entityId?: string;
+
+ /**
+ * Email address of a user
+ */
+ email?: string;
+}
+
+/**
+ * Use this provider to get information about the currently active session.
+ * E.g. for checking required roles or accessing the unique user identifier.
+ */
+@Injectable()
+export class SessionSubject extends BehaviorSubject<SessionInfo> {
+ constructor() {
+ super(undefined);
+ }
+}
+
import { MenuItem } from "../../ui/navigation/menu-item";
+
+export const CONFIG_SETUP_WIZARD_ID = "Config:SetupWizard";
+
+export interface SetupWizardConfig {
+ /** whether the wizard has been completed overall and should be hidden */
+ finished?: boolean;
+
+ /** whether users should on startup be navigated automatically to the setup wizard screen while it is not finished */
+ openOnStart?: boolean;
+
+ steps: SetupWizardStep[];
+}
+
+export interface SetupWizardStep {
+ title: string;
+ text: string;
+ actions?: MenuItem[];
+}
+
+export const defaultSetupWizardConfig: SetupWizardConfig = {
+ openOnStart: false,
+ steps: [
+ {
+ title: $localize`:Setup Wizard Step Title:Welcome`,
+ text: $localize`:Setup Wizard Step Text:
+# Welcome to Aam Digital!
+We are here to help you manage your participants' or beneficiaries' details
+and your team's interactions with them.
+
+The Aam Digital platform is very flexible and you can customize the structures and views
+to exactly fit your project needs.
+The following steps guide you through the most important configuration options for this.
+And you can start working with your data within a few minutes already.
+
+We also have some short video guides for you: [Aam Digital Video Guides (YouTube)](https://www.youtube.com/channel/UCZSFOX_MBa8zz5Mtfv_qlnA/videos)
+
+Feel free to leave this setup wizard in between to explore the existing system first.
+You can always come back to this view through the "Setup Wizard" button at the bottom of the main menu on the left.
+To dismiss and hide this wizard, go to the last step of the wizard and "finish" the setup process.`,
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Profiles & Fields`,
+ text: $localize`:Setup Wizard Step Text:
+The system already holds some basic structures for your case management.
+You can adapt the fields and how the details are displayed.
+
+If you have further requirements, don't hesitate to reach out to us at [support@aam-digital.com](mailto:support@aam-digital.com).
+
+_Please note that the setup wizard and form builder is still under active development ("beta" version).
+Some advanced configuration options are not available here yet for you to configure yourself and may need assistance from the tech support team.
+We are currently extending and optimizing the user interfaces for these steps._
+`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Customize Child profile`,
+ link: "/admin/entity/Child",
+ },
+ {
+ label: $localize`:Setup Wizard Step Action:Customize School profile`,
+ link: "/admin/entity/School",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:User Accounts`,
+ text: $localize`:Setup Wizard Step Text:
+You can collaborate on Aam Digital as a team.
+Data is synced and all users have access to the latest information.`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Manage User Accounts`,
+ link: "/user",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Import Data`,
+ text: $localize`:Setup Wizard Step Text:
+If you have exising data from a previous system, you can easily import it.
+Save the data in ".csv" format (e.g. from MS Excel).
+You do not need any specific column names in your file to be imported.
+The Import Module helps your map your spreadsheet data to the relevant fields in your Aam Digital profiles.`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Import Data`,
+ link: "/import",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Done!`,
+ text: $localize`:Setup Wizard Step Text:
+That's it. You are ready to explore your system and start work!
+
+You can always adapt your setup further, after you started using it.
+We recommend to keep things simple in the beginning,
+start using it for some of your tasks
+and then add further fields and adjust your setup.
+
+Feel free to reach out to us with your questions or feedback: [support@aam-digital.com](mailto:support@aam-digital.com)`,
+ },
+ ],
+};
+
import { MenuItem } from "../../ui/navigation/menu-item";
+
+export const CONFIG_SETUP_WIZARD_ID = "Config:SetupWizard";
+
+export interface SetupWizardConfig {
+ /** whether the wizard has been completed overall and should be hidden */
+ finished?: boolean;
+
+ /** whether users should on startup be navigated automatically to the setup wizard screen while it is not finished */
+ openOnStart?: boolean;
+
+ steps: SetupWizardStep[];
+}
+
+export interface SetupWizardStep {
+ title: string;
+ text: string;
+ actions?: MenuItem[];
+}
+
+export const defaultSetupWizardConfig: SetupWizardConfig = {
+ openOnStart: false,
+ steps: [
+ {
+ title: $localize`:Setup Wizard Step Title:Welcome`,
+ text: $localize`:Setup Wizard Step Text:
+# Welcome to Aam Digital!
+We are here to help you manage your participants' or beneficiaries' details
+and your team's interactions with them.
+
+The Aam Digital platform is very flexible and you can customize the structures and views
+to exactly fit your project needs.
+The following steps guide you through the most important configuration options for this.
+And you can start working with your data within a few minutes already.
+
+We also have some short video guides for you: [Aam Digital Video Guides (YouTube)](https://www.youtube.com/channel/UCZSFOX_MBa8zz5Mtfv_qlnA/videos)
+
+Feel free to leave this setup wizard in between to explore the existing system first.
+You can always come back to this view through the "Setup Wizard" button at the bottom of the main menu on the left.
+To dismiss and hide this wizard, go to the last step of the wizard and "finish" the setup process.`,
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Profiles & Fields`,
+ text: $localize`:Setup Wizard Step Text:
+The system already holds some basic structures for your case management.
+You can adapt the fields and how the details are displayed.
+
+If you have further requirements, don't hesitate to reach out to us at [support@aam-digital.com](mailto:support@aam-digital.com).
+
+_Please note that the setup wizard and form builder is still under active development ("beta" version).
+Some advanced configuration options are not available here yet for you to configure yourself and may need assistance from the tech support team.
+We are currently extending and optimizing the user interfaces for these steps._
+`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Customize Child profile`,
+ link: "/admin/entity/Child",
+ },
+ {
+ label: $localize`:Setup Wizard Step Action:Customize School profile`,
+ link: "/admin/entity/School",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:User Accounts`,
+ text: $localize`:Setup Wizard Step Text:
+You can collaborate on Aam Digital as a team.
+Data is synced and all users have access to the latest information.`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Manage User Accounts`,
+ link: "/user",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Import Data`,
+ text: $localize`:Setup Wizard Step Text:
+If you have exising data from a previous system, you can easily import it.
+Save the data in ".csv" format (e.g. from MS Excel).
+You do not need any specific column names in your file to be imported.
+The Import Module helps your map your spreadsheet data to the relevant fields in your Aam Digital profiles.`,
+ actions: [
+ {
+ label: $localize`:Setup Wizard Step Action:Import Data`,
+ link: "/import",
+ },
+ ],
+ },
+ {
+ title: $localize`:Setup Wizard Step Title:Done!`,
+ text: $localize`:Setup Wizard Step Text:
+That's it. You are ready to explore your system and start work!
+
+You can always adapt your setup further, after you started using it.
+We recommend to keep things simple in the beginning,
+start using it for some of your tasks
+and then add further fields and adjust your setup.
+
+Feel free to reach out to us with your questions or feedback: [support@aam-digital.com](mailto:support@aam-digital.com)`,
+ },
+ ],
+};
+
a list of arguments, passed into the sql statement
+
+
+
+
+
+
+
+
+
+
+
import { Entity, EntityConstructor } from "../../core/entity/model/entity";
+import { DatabaseEntity } from "../../core/entity/database-entity.decorator";
+import { Aggregation } from "./data-aggregation.service";
+import { ExportColumnConfig } from "../../core/export/data-transformation-service/export-column-config";
+import { DatabaseField } from "../../core/entity/database-field.decorator";
+
+/**
+ * A report can be accessed by users to generate aggregated statistics or customized exports calculated from available data.
+ * "read" permission for a ReportConfig entity is also used to control which users can generate the report's results.
+ *
+ * This is the class which is saved to the database.
+ * However, when using this in code, use the {@link ReportEntity} instead which provides better type safety.
+ */
+@DatabaseEntity("ReportConfig")
+class ReportConfig extends Entity {
+ /** human-readable title of the report */
+ @DatabaseField() title: string;
+
+ /**
+ * (optional) mode of export.
+ * The {@link ReportEntity} holds the restriction on valid report modes.
+ * Default is "reporting"
+ */
+ @DatabaseField() mode?: string;
+
+ /**
+ * (sql only) list of arguments needed for the sql query. Placeholder "?" will be replaced.
+ */
+ @DatabaseField() neededArgs?: string[] = [];
+
+ /** the definitions to calculate the report's aggregations */
+ @DatabaseField() aggregationDefinitions: any[] = [];
+
+ /** (sql only) the definition to calculate the report */
+ @DatabaseField() aggregationDefinition: string | undefined = undefined;
+}
+
+/**
+ * Union type to enable type safety for report configs.
+ * Use this instead of the {@class ReportConfig}
+ */
+export type ReportEntity = AggregationReport | ExportingReport | SqlReport;
+/**
+ * This allows the `ReportEntity` to also be used as a constructor or in the `EntityMapper`
+ */
+export const ReportEntity = ReportConfig as EntityConstructor<ReportEntity>;
+
+/**
+ * Reports handles by the {@class DataAggregationService}
+ */
+export interface AggregationReport extends ReportConfig {
+ mode: "reporting";
+ aggregationDefinitions: Aggregation[];
+}
+
+/**
+ * Reports handles by the {@class DataTransformationService}
+ */
+export interface ExportingReport extends ReportConfig {
+ /**
+ * If no mode is set, it will default to 'exporting'
+ */
+ mode?: "exporting";
+ aggregationDefinitions: ExportColumnConfig[];
+}
+
+/**
+ * Reports handles by the {@class SqlReportService}
+ */
+export interface SqlReport extends ReportConfig {
+ mode: "sql";
+ /**
+ * a valid SQL SELECT statements, can contain "?" placeholder for arguments
+ */
+ aggregationDefinition: string;
+
+ /**
+ * a list of arguments, passed into the sql statement
+ */
+ neededArgs: string[];
+}
+
the next task that was automatically created based on the repetitionInterval
+
+
+
+
+
+
+
+
+
+
+
export interface TodoCompletion {
+ /** user id of who completed the task */
+ completedBy: string;
+
+ /** when the item was completed */
+ completedAt: Date;
+
+ /** the next task that was automatically created based on the repetitionInterval */
+ nextRepetition?: string;
+}
+
The type of the update, either:
+"new" - a new entity was created,
+"update" - an existing entity was updated
+"remove" - the entity was deleted
+
+
+
+
+
+
+
+
+
+
+
import { Entity } from "./entity";
+
+/**
+ * Interface that conveys an updated entity as well as information
+ * on the update-type
+ */
+export interface UpdatedEntity<T extends Entity> {
+ /**
+ * The updated entity
+ */
+ entity: T;
+
+ /**
+ * The type of the update, either:
+ * "new" - a new entity was created,
+ * "update" - an existing entity was updated
+ * "remove" - the entity was deleted
+ */
+ type: "new" | "update" | "remove";
+}
+
+/**
+ * Updates a list of entities given an updated version of the entity. This updated version
+ * can either be a new entity (that should be inserted into the list), or an existing entity
+ * that should be updated or deleted.
+ * The given array will not be mutated but will be returned when the given new entity
+ * or type is illegal
+ * @param next An entity that should be updated as well as the type of update. This, as well as the entity
+ * may be undefined or null. In this event, the entities-array is returned as is.
+ * @param entities The entities to update, must be defined
+ * @param addIfMissing (Optional) whether to add an entity that comes through an update event but is not part of the array yet,
+ * default is to add, disable this if you do special filtering or calculations on the data
+ * @return An array of the given entities with the update applied
+ */
+export function applyUpdate<T extends Entity>(
+ entities: T[],
+ next: UpdatedEntity<T>,
+ addIfMissing: boolean = true,
+): T[] {
+ if (!next || !next.entity || !entities) {
+ return entities;
+ }
+
+ if (
+ (next.type === "new" || (addIfMissing && next.type === "update")) &&
+ !entities.find((e) => e.getId() === next.entity.getId())
+ ) {
+ return [next.entity].concat(entities);
+ }
+
+ if (next.type === "update") {
+ return entities.map((e) =>
+ e.getId() === next.entity.getId() ? next.entity : e,
+ );
+ }
+
+ if (next.type === "remove") {
+ return entities.filter((e) => e.getId() !== next.entity.getId());
+ }
+
+ return entities;
+}
+
export interface UsageAnalyticsConfig {
+ /** url of the backend to report usage data to */
+ url: string;
+
+ /** the id by which this site is represented in the analytics backend */
+ site_id: string;
+
+ /** do not set any cookies for analytics */
+ no_cookies?: boolean;
+}
+
+export const USAGE_ANALYTICS_CONFIG_ID = "appConfig:usage-analytics";
+
At the moment that means the routing is set in the app.routing.ts and not loaded from the config.
+The ViewConfig of a lazy-loaded route is only used for additional flags like requiresAdmin.
+
+
+
+
+
+
+
+
+
+
+
import { DynamicComponentConfig } from "../dynamic-components/dynamic-component-config.interface";
+
+/**
+ * Object specifying a route and config of its view
+ * as stored in the config database
+ */
+export interface ViewConfig<T = any> extends DynamicComponentConfig<T> {
+ /** config object id which equals the route path */
+ _id: string;
+
+ /**
+ * indicate that the route is lazy loaded.
+ *
+ * At the moment that means the routing is set in the app.routing.ts and not loaded from the config.
+ * The ViewConfig of a lazy-loaded route is only used for additional flags like `requiresAdmin`.
+ */
+ lazyLoaded?: boolean;
+}
+
+/**
+ * The prefix which is used to find the ViewConfig's in the config file
+ */
+export const PREFIX_VIEW_CONFIG = "view:";
+
.
.
+The tabs (in the config called "panels") within the Entity Details view can display one or more "panel components", as shown above.
+
