Merge pull request #34 from SICKAG/improve-developer-documentation

Improve developer documentation

README.md

@@ -11,6 +11,8 @@ With Collage you can upgrade a web application of all sorts to either a micro fr
 For information about collage and its capabilities, please have a look at our [Official Documentation](https://sickag.github.io/collage/).
 
 ---
+## Developer Documentation
+For details about the architecture and structure of collage, please have a look at our [Developer Documentation](./src/DEVELOPER_DOCUMENTATION.md).
 
 ## Preview
 To create and embed micro frontends with collage you just need to add a few lines on top of your already existing Application:
@@ -20,7 +22,7 @@ To create and embed micro frontends with collage you just need to add a few line
   <div class="somewhere">
     <!-- include a micro frontend effortlessly -->
     <collage-fragment
-      src="/url/to/micro-frontend"
+      url="/url/to/micro-frontend"
       config-something="Configure this!"
       name="my-micro-frontend">
     </collage-fragment>
@@ -55,4 +57,4 @@ const api = await expose({
 - Easy to use - Create a micro frontend with just a few lines of code.
 - Use a self explainatory api to describe your micro frontends and orchestrate them in complex arrangements effortlessly.
 - Built on web standards and only a few simple core concepts means that you never run into magic behaviour that ruins your day.
-- Easy to use - Simply wrap the expose() call to create custom functionality.
+- Easy to use - Simply wrap the expose() call to create custom functionality.

docs/README.md

@@ -29,7 +29,7 @@ features:
   <div class="somewhere">
     <!-- include a micro frontend effortlessly -->
     <collage-fragment
-      src="/url/to/micro-frontend"
+      url="/url/to/micro-frontend"
       config-something="Configure this!"
       name="my-micro-frontend">
     </collage-fragment>

docs/docs/core-api.md

@@ -470,7 +470,7 @@ contextApi.topics.foo.myTopic.publish('a new Value');
 ```
 
 
-### Lifecycle Hooks
+## Lifecycle Hooks
 Collage is asynchronous. To trigger certain activities in an Arrangement or Fragment, you can use Lifecycle Hooks.
 
 A hook returns a function, which can be executed to deregister the hook (analogous to addEventListener and removeEventListener).
@@ -496,7 +496,7 @@ const options = { once: true };
 // No need for using the returned deregister function
 onUpdated(callback, options);
 ```
-##### onLoaded
+#### onLoaded
 To be sure, that the initialization process is completed and the embedded fragment can be used on the arrangement, this hook exists. This hook takes the name of a fragment as first parameter and a callback as second. The third parameter is optional and represents the options argument of addEventListener.
 
 The onLoaded hook Executes a callback if a fragment with a specific name is loaded.
@@ -510,7 +510,7 @@ onLoaded("myFragment", () => {
 The onLoaded hook is based on the `collage-fragment-loaded` event, which is dispatched, if an embedded fragment is completed with the initial loading. The event emits the context id of the fragment, which was loaded.
 You can use the event if necessary, but you should prefere the hook. 
 
-##### onUpdated
+#### onUpdated
 Executes a callback if the context of this fragment is updated. This hook takes a callback as first parameter. The second parameter is optional and represents the options argument of addEventListener.
 
  ```js {2-5}
@@ -524,7 +524,7 @@ onUpdated(() => {
 The onUpdated hook is based on the `collage-context-updated` event, which is dispatched, everytime something on the own context changed. The event emits the updated context.
 You can use the event if necessary, but you should prefere the hook. 
 
-##### onConfigUpdated
+#### onConfigUpdated
 Executes a callback if the config of this context was updated. This hook takes a callback as first parameter. The second parameter is optional and represents the options argument of addEventListener.
 
  ```js {2-9}
@@ -543,7 +543,7 @@ onConfigUpdated(() => {
 The onConfigUpdated hook is also based on the `collage-context-updated` event, which is dispatched, everytime something on the own context changed. The event emits the updated context.
 You can use the event if necessary, but you should prefer the hook.
 
-### Deregistering a fragment
+## Deregistering a fragment
 If you want to remove a fragment from your arrangement, just remove it from the DOM. Collage takes care that the parents context gets cleaned up.
 
 :::tip

docs/docs/features.md

@@ -11,6 +11,9 @@ Embed micro frontends in your application.
 ### Configure embedded micro frontends
 Configure embedded micro frontends to fit them perfectly into your application.
 
+### Fragment Functions
+Provide functions which are directly executable on the micro frontend by an Arrangement
+
 ### Service API
 Provide services to other micro frontends and the whole Arrangement and use services, other Contexts are exposing.
 
@@ -20,9 +23,6 @@ Publish messages or subscribe to topics which are available for all parts of you
 ### (coming soon) Style Synchronization
 Define styles for your application, the embedded micro frontends will adopt it. Users of your application can also change styles at runtime, e.g. to switch to a dark-theme.
 
-### (coming soon) Style Synchronization
-Micro frontends adopt the styling of their parents to make your application look like one piece.
-
 ## Non-functional Features
 
 ### Framework Agnosticity

index.html

@@ -16,13 +16,15 @@ <h1>Collage Development Dashboard</h1>
 
     <section>
       <h2>Features</h2>
+      <a id="createcontext" href="/src/core/create-context/samples/" target="nav-target">Create Context</a>
+      <a id="embedding" href="/src/elements/samples/" target="nav-target">Embedding a Fragment</a>
       <a id="servicecalls" href="/src/core/services-plugin/service-functions/samples/" target="nav-target">Service Calls</a>
       <a id="modal" href="/src/core/services-plugin/service-functions/samples/modalArrangement.html" target="nav-target">Modal Service</a>
       <a id="directfunctions" href="/src/core/direct-functions-plugin/samples/" target="nav-target">Direct Functions</a>
       <a id="simpletopics" href="/src/core/topics-plugin/simple-topics/samples/" target="nav-target">Simple Topics</a>
       <a id="servicetopics" href="/src/core/topics-plugin/service-topics/samples/" target="nav-target">Service Topics</a>
       <a id="config" href="/src/core/config-plugin/samples/" target="nav-target">Config</a>
-      <a id="reloadBug" href="/src/core/handshake-plugin/samples/locationReloadArrangement.html" target="nav-target">Reload bug</a>
+      <!-- <a id="reloadBug" href="/src/core/handshake-plugin/samples/locationReloadArrangement.html" target="nav-target">Reload bug</a> -->
 
     </section>
     <section>

src/DEVELOPER_DOCUMENTATION.md

@@ -0,0 +1,119 @@
+# Developer Documentation
+
+Before starting to develop collage, please read the documentation about the collage [features](../docs/docs/features.md), [core concepts](../docs/docs/concepts.md) and [core api](../docs/docs/core-api.md).
+
+## Getting started
+
+```bash
+git clone https://github.com/SICKAG/collage.git
+cd collage
+npm install
+```
+
+Now you are ready for developing
+
+### Start the dev server
+
+You can start the dev server by running
+
+```bash
+npm run dev
+```
+
+This will start a dev server. You can then view and debug the example and integration tests defined in the sample folders of the plugins (src/core/)
+
+### Running the tests
+
+You can (and should) keep the unit test running in watch mode while developing
+
+```bash
+npm run test:watch
+```
+
+> Hint: you can keep the dev server and the unit test running at the same time
+
+## What we are building upon:
+
+- typescript (see [typescript](https://www.typescriptlang.org/) and [tsconfig.json](../tsconfig.json))
+- vite for serving our examples and integration tests and bundling the library (see [vite](https://vitejs.dev) and [vite.config.js](../vite.config.js))
+- jest for unit tests (see [jest](https://jestjs.io) and [jest.config.js](../jest.config.js))
+- vuepress for building our user documentation (see [vuepress](https://vuepress) and [vuepress-config.mjs](../docs/vuepress-config.mjs))
+- github actions for ci/cd
+- penpal for the communication between fragments and arrangements (see [penpal](https://github.com/Aaronius/penpal#readme))
+
+## Structure of the Repository
+
+The structure of the repository is as follows.
+In each folder, you will find a documenting markdown file explaining the details of the respective part.
+
+```md
+collage/
+|-- .github/          // github actions configurations
+|-- docs/             // user documentation built with vuepress
+|-- e2e/              // our e2e tests
+|-- src/              // source code
+|   |-- core/         // core concepts of collage implemented as collage plugins
+|   |-- elements/     // custom elements for a convenient usage of collage
+|   |-- lib/          // internal library structure of collage
+|   |   |-- api/      // collage api 
+
+```
+
+- [core](./core/CORE_CONCEPTS.md)
+- [elements](./elements/README.md)
+- [lib](./lib/README.md)
+
+## Architecture
+
+Collage is build as a plugin library. Each basic feature is defined as a plugin. All default plugins are configured and bootstrapped together.
+
+How this is done, you can read in the documentation about the [internal structure of the collage library](./lib/README.md).
+
+In short:
+
+- all types, and everything needed to put collage and the plugins together can be found in lib.
+- everything that implements functionality for the user is a plugin and can be found in core.
+
+## Contributing
+
+Every contribution is welcome, as we want to make collage a vivid community project.
+
+At the moment we lack a system to enable plugins dynamically, so each plugin must be built and bundled with the library. We are evaluating to change that in the future, so everybody could add functionality to collage.
+
+### Creating a new plugin/feature
+
+#### Workflow
+
+1. create the plugin
+   1. create a new folder in the src/core directory
+   1. create a plugin file as ts (orient at the core plugins)
+   1. create a samples folder for integration testing examples
+1. create tests
+   1. create e2e test for the new feature
+   1. create unit tests in the plugin folder
+1. create documentation
+   1. create a documentation file as md if necessary
+1. add the plugin to collage
+   1. import the plugin
+   1. add to the plugins array
+
+#### How a plugin is made
+
+With a plugin, you are able to enhance collage by new features.
+For an example of a minimal plugin, please have a look at the [create-context](./core/create-context/create-context.ts).
+
+In short, a valid plugin needs to export the default function `plugin` where it can pass an object, that uses the PluginFunctions to enhance collage by the new features (see [src/types.ts>PluginFunctions](./types.ts) and [collage-plugin](./lib/collage-plugin.ts)).
+
+```ts
+import plugin from '../../lib/collage-plugin';
+
+export default plugin({
+  enhanceExpose: async () => {
+    console.log('I send a message everytime expose() is called');
+  },
+});
+```
+
+## Core Concepts
+
+Read further in the [Core Concepts Documentation](./core/CORE_CONCEPTS.md)