feat: library documentation

openmfp · Sep 26, 2024 · 00bc004 · 00bc004
1 parent 2001a4f
commit 00bc004
Show file tree

Hide file tree

Showing 3 changed files with 95 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -10,14 +10,14 @@ Main features of this library are:
 
 ## Table of Contents
 - [Getting started](#Getting-started)
-  - [Configure the project](##Configure-the-project) 
-  - [Import the module and bootstrap component](##Import-the-module-and-bootstrap-component)
-  - [Update index.html file](##Update-index.html-file-of-the-project)
-  - [Implement custom services with portal options](##Implement-custom-services-with-portal-options)
-    - [Configuration services](###Configuration-services)
-    - [Functional services](###Functional-services)
-  - [Start your project ](##Start-your-project)
-- [Local Extension development](#Local-Extension-development)
+  - [Configure the project](#Configure-the-project) 
+  - [Import the PortalModule and Bootstrap the PortalComponent](#Import-the-PortalModule-and-Bootstrap-the-PortalComponent)
+  - [Update index.html file](#Update-index-file-of-the-project)
+  - [Implement the Custom Service](#Implement-the-Custom-Service)
+    - [Configuration services](#Configuration-services)
+    - [Functional services](#Functional-services)
+  - [Start your project](#Start-your-project)
+- [Local Application Development](#Local-Application-Development)
 - [Library development](#Library-development)
 
 
@@ -40,8 +40,6 @@ into the project assets, as shown below:
   // ... the rest of the angular.json configuration
   
   "assets": [
-    "src/favicon.ico",
-    "src/assets",
     {
       "glob": "**",
       "input": "node_modules/@luigi-project/core",
@@ -92,7 +90,7 @@ export class AppModule {
 }
 ```
 
-## Update index.html file of the project
+## Update index file of the project
 
 The next step in order to have the portal working is to update the `index.html` file with the inclusion of: 
 - the `/luigi-core/luigi.js` script, 
@@ -104,13 +102,13 @@ Below is an example:
 ```html
 <!DOCTYPE html>
 <html lang="en">
-<head>
-    <meta charset="utf-8">
-    <title>App</title>
-    <base href="/">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link rel="stylesheet" href="/luigi-core/luigi_horizon.css" />
-</head>
+    <head>
+        <meta charset="utf-8">
+        <title>App</title>
+        <base href="/">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="stylesheet" href="/luigi-core/luigi_horizon.css" />
+    </head>
     <body>
         <noscript>You need to enable JavaScript to run this app.</noscript>
         <script src="/luigi-core/luigi.js"></script>
@@ -475,9 +473,12 @@ const portalOptions: PortalModuleOptions = {
 }
 ```
 
-## Start your project 
-
+## Start your project
 
+After finishing all the required steps you might want to check your integration with the library and run your local application.
+In order to do that, firstly you need to run the local server part of the portal, please follow the instruction provided here [TODO LINK TO PORTAL-SERVER-LIB README]
+Once the server is running execute your ui starting script (e.g. `ng serve --port 4300` ) remembering that the default localhost port 
+should be `4300` otherwise you need to set the environment variable to expected `FRONTEND_PORT=ZZZZ` and restart the server.
 
 # Local Application Development
 

diff --git a/readme-luigi-context.md b/readme-luigi-context.md
@@ -0,0 +1,71 @@
+# Luigi Context
+
+The Luigi context contains information about the current context such as the user ID or api urls.
+
+## Portal Context
+
+The `portalContext` field in the context provides API URLs to often used services:
+
+```json
+ "frameContext": {
+    "accountsServiceApiUrl": "https://api.example.com/accounts/query",
+    "organizationServiceApiUrl": "https://api.example.com/org/query"
+  },
+```
+
+## Entity Context
+
+The `entityContext` field in the context provides information about the current entity. 
+For example, when the user navigates to a `project` (or a sub entity such as `project.component`) 
+information about the project is provided. Currently, information about a project and a component are provided. Structure:
+
+```json
+"entityContext": {
+    "entity1": {...},
+    "entity2": {...}
+}
+```
+
+### Project
+
+```json
+"entityContext": {
+   "project": {
+      "id": "PROJECT_ID",
+      "policies": ["POLICY_1","POLICY_2"] // policies for the current user in this project
+    }
+}
+```
+
+
+### Component
+
+For the entity `component` information from the metadata service is provided, currently the following fields are available:
+
+```json
+"entityContext": {
+    "component": {
+      "id": "...",
+      "type": {
+        "name": "...",
+        "lifecycle": "...",
+        "categories": ["..."]
+      },
+      "labels": [
+          {
+              "name": "...",
+              "value": "..."
+          }
+      ],
+      "annotations": [
+           {
+              "name": "...",
+              "value": "..."
+          }
+      ],
+      "tags": [
+        "...",
+      ]
+    }
+}
+```
diff --git a/readme-nodes-configuration.md b/readme-nodes-configuration.md
@@ -244,7 +244,7 @@ Further Portal specific parameters are supported on node level:
 - **children** - contains child elements. The children nodes can have the following Luigi navigation parameters: **pathSegment**, **label**, **hideFromNav**, **icon**, **useHashRouting**, **virtualTree**, **urlSuffix** and **category**.
   To build the viewUrl of the child node the **urlSuffix** property of the parent is used: `urlTemplateParams.url`+`node.urlSuffix`+`child.urlSuffix`.
 
-- **visibleForEntityContext** - allows to filter the nodes that are shown based on the [entity context](./luigi-context.md#entity-context). Currently, the backend provides an entity context for the entities `project` and `component`. A node is shown, if the entity context provides all values as required by the filter, for this the [_.isMatch](https://lodash.com/docs/4.17.15#isMatch) function is used. The format of the filter is the following:
+- **visibleForEntityContext** - allows to filter the nodes that are shown based on the [entity context](./readme-luigi-context.md#entity-context). Currently, the backend provides an entity context for the entities `project` and `component`. A node is shown, if the entity context provides all values as required by the filter, for this the [_.isMatch](https://lodash.com/docs/4.17.15#isMatch) function is used. The format of the filter is the following:
 
 ```json
 "visibleForEntityContext": {
@@ -259,9 +259,9 @@ Further Portal specific parameters are supported on node level:
 }
 ```
 
-- **visibleForContext** - allows to filter the nodes that are shown based on the [context](./luigi-context.md). In this field, a [JMESPath](https://jmespath.org/specification.html) query can be defined. When it evaluates to `true`, the node will be shown.
+- **visibleForContext** - allows to filter the nodes that are shown based on the [context](./readme-luigi-context.md). In this field, a [JMESPath](https://jmespath.org/specification.html) query can be defined. When it evaluates to `true`, the node will be shown.
 
-- **configurationMissing** - allows to show a "configuration missing" page based on the [context](./luigi-context.md). In this field, a [JMESPath](https://jmespath.org/specification.html) query can be defined. When it evaluates to `true`, the "configuration missing" page will be shown, otherwise the normal page.
+- **configurationMissing** - allows to show a "configuration missing" page based on the [context](./readme-luigi-context.md). In this field, a [JMESPath](https://jmespath.org/specification.html) query can be defined. When it evaluates to `true`, the "configuration missing" page will be shown, otherwise the normal page.
 
 - **configurationHint** - Allows to customise the "configuration missing" page with an extension specific hint.