mapcomplete/Docs/Architecture.md

Architecture
============

This document aims to give an architectural overview of how MapCompelte is built. It should give some feeling on how
everything fits together.

Servers?
--------

There are no servers for MapComplete, all services are configured by third parties.

Minimal HTML - Minimal CSS
--------------------------

There is quasi no HTML. Most of the components are generated by TypeScript and attached dynamically. The HTML is a
barebones skeleton which serves every theme.


The UIEventSource
-----------------

Most (but not all) objects in MapComplete get all the state they need as a parameter in the constructor. However, as is
the case with most graphical applications, there are quite some dynamical values.

All values which change regularly are wrapped into
a [`UIEventSource`](../Logic/UIEventSource.ts). A `UIEventSource` is a
wrapper containing a value and offers the possibility to add a callback function which is called every time the value is
changed (with `setData`)

Furthermore, there are various helper functions, the most widely used one being `map` - generating a new event source
with the new value applied. Note that `map` will also absorb some changes,
e.g. `const someEventSource : UIEventSource<string[]> = ... ; someEventSource.map(list = list.length)` will only trigger
when the length of the list has changed.

An object which receives a `UIEventSource` is responsible of responding to changes of this object. This is especially
true for UI-components.

UI
--
```typescript

export default class MyComponent {

    constructor(neededParameters, neededUIEventSources) {
    
    }

}

```

The Graphical User Interface is composed of various UI-elements. For every UI-element, there is a `BaseUIElement` which creates the actual `HTMLElement` when needed.

There are some basic elements, such as:

- `FixedUIElement` which shows a fixed, unchangeable element
- `Img` to show an image
- `Combine` which wraps everything given (strings and other elements) in a div
- `List`

There is one special component: the `VariableUIElement`
The `VariableUIElement` takes a `UIEventSource<string|BaseUIElement>` and will dynamicaly show whatever the `UIEventSource` contains at the moment.

For example:

```typescript

const src : UIEventSource<string> = ... // E.g. user input, data that will be updated... new VariableUIElement(src)
.AttachTo('some-id') // attach it to the html

```

Note that every component offers support for `onClick( someCallBack)`

### Translations

To add a translation:

1. Open `langs/en.json`
2. Find a correct spot for your translation in the tree
3. run `npm run generate:translations`
4. `import Translations`
5. `Translations.t.<your-translation>.Clone()` is the `UIElement` offering your translation

### Input elements

Input elements are a special kind of BaseElement which offer a piece of a form to the user, e.g. a TextField, a Radio button, a dropdown, ...

The constructor will ask all the parameters to configure them. The actual value can be obtained via `inputElement.GetValue()`, which is a `UIEventSource` that will be triggered every time the user changes the input.

### Advanced elements

There are some components which offer useful functionality:


- The `subtleButton` which is a friendly, big button
- The Toggle: `const t = new Toggle( componentA, componentB, source)` is a `UIEventSource` which shows `componentA` as long as `source` contains `true` and will show `componentB` otherwise.


### Styling

Styling is done as much as possible with [TailwindCSS](https://tailwindcss.com/). It contains a ton of utility classes, each of them containing a few rules.

For example: ` someBaseUIElement.SetClass("flex flex-col border border-black rounded-full")` will set the component to be a flex object, as column, with a black border and pill-shaped.

If Tailwind is not enough, use `baseUiElement.SetStyle("background: red; someOtherCssRule: abc;")`.

### An example

For example: the user should input wether or not a shop is closed during public holidays. There are three options:

1. closed
2. opened as usual
3. opened with different hours as usual

In the case of different hours, input hours should be too.

This can be constructed as following:


```typescript

    // We construct the dropdown element with values and labelshttps://tailwindcss.com/
    const isOpened = new Dropdown<string>(Translations.t.is_this_shop_opened_during_holidays,
        [
         { value: "closed", Translation.t.shop_closed_during_holidays.Clone()},
         { value: "open", Translations.t.shop_opened_as_usual.Clone()},
         { value: "hours", Translations.t.shop_opened_with_other_hours.Clone()}
        ] )
        
     const startHour = new DateInput(...)drop
     const endHour = new DateInput( ... )   
     // We construct a toggle which'll only show the extra questions if needed
     const extraQuestion = new Toggle(
            new Combine([Translations.t.openFrom, startHour, Translations.t.openTill, endHour]),
            undefined,
            isOpened.GetValue().map(isopened => isopened === "hours")
         )

    return new Combine([isOpened, extraQuestion])

```

### Constructing a special class

If you make a specialized class to offer a certain functionality, you can organize it as following:

1. Create a new class:

```typescript

export default class MyComponent {

    constructor(neededParameters, neededUIEventSources) {
    
    }

}

```

2. Construct the needed UI in the constructor


```typescript

export default class MyComponent {

    constructor(neededParameters, neededUIEventSources) {
    
    
            const component = ...
            const toggle = ...
            ... other components ...
            
            toggle.GetValue.AddCallbackAndRun(isSelected => { .. some actions ... }
            
            new Combine([everything, ...] )
    }

}

```

3. You'll notice that you'll end up with one certain component (in this example the combine) to wrap it all together. Change the class to extend this type of component and use `super()` to wrap it all up:


```typescript

export default class MyComponent extends Combine {

    constructor(...) {
    
        ...
        super([everything, ...])
    
    }

}

```

Assets
------

### Themes

Theme and layer configuration files go into `assets/layers` and `assets/themes`.

### Images

Other files (mostly images that are part of the core of MapComplete) go into `assets/svg` and are usable with `Svg.image_file_ui()`. Run `npm run generate:images` if you added a new image.


Logic
-----

The last part is the business logic of the application, found in the directory [Logic](../Logic). Actors are small objects which react to `UIEventSources` to update other eventSources.

`State.state` is a big singleton object containing a lot of the state of the entire application. That one is a bit of a mess.