Merge pull request #657 from pietervdvn/riQQ-patch-1
Editorial improvements in Architecture docs
This commit is contained in:
GitHub
commit
02fb73f578
1 changed files with 31 additions and 29 deletions
|
|
@ -12,7 +12,7 @@ There are no servers for MapComplete, all services are configured by third parti
|
|||
Minimal HTML - Minimal CSS
|
||||
--------------------------
|
||||
|
||||
There is quasi no HTML. Most of the components are generated by TypeScript and attached dynamically. The html is a
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -23,19 +23,21 @@ Most (but not all) objects in MapComplete get all the state they need as a param
|
|||
the case with most graphical applications, there are quite some dynamical values.
|
||||
|
||||
All values which change regularly are wrapped into
|
||||
a [UIEventSource](https://github.com/pietervdvn/MapComplete/blob/master/Logic/UIEventSource.ts). An UiEventSource is a
|
||||
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)
|
||||
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,
|
||||
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 an UIEventSource is responsible of responding onto changes of this object. This is especially
|
||||
true for UI-components
|
||||
An object which receives a `UIEventSource` is responsible of responding to changes of this object. This is especially
|
||||
true for UI-components.
|
||||
|
||||
UI --```
|
||||
UI
|
||||
--
|
||||
```typescript
|
||||
|
||||
export default class MyComponent {
|
||||
|
||||
|
|
@ -47,21 +49,21 @@ export default class MyComponent {
|
|||
|
||||
```
|
||||
|
||||
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.
|
||||
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, unchangeble element
|
||||
- Img to show an image
|
||||
- Combine which wrap everything given (strings and other elements) in a div
|
||||
- List
|
||||
- `FixedUIElement` which shows a fixed, unchangeble 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.
|
||||
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
|
||||
|
|
@ -78,9 +80,9 @@ To add a translation:
|
|||
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
|
||||
5. `Translations.t.<your-translation>.Clone()` is the `UIElement` offering your translation
|
||||
|
||||
### Input elements`
|
||||
### Input elements
|
||||
|
||||
Input elements are a special kind of BaseElement and which offer a piece of a form to the user, e.g. a TextField, a Radio button, a dropdown, ...
|
||||
|
||||
|
|
@ -92,16 +94,16 @@ 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.
|
||||
- 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 exmaple: ` 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.
|
||||
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, `baseUiElement.SetStyle("background: red; someOtherCssRule: abc;")`
|
||||
If Tailwind is not enough, use `baseUiElement.SetStyle("background: red; someOtherCssRule: abc;")`.
|
||||
|
||||
### An example
|
||||
|
||||
|
|
@ -116,7 +118,7 @@ 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,
|
||||
|
|
@ -145,7 +147,7 @@ If you make a specialized class to offer a certain functionality, you can organi
|
|||
|
||||
1. Create a new class:
|
||||
|
||||
```
|
||||
```typescript
|
||||
|
||||
export default class MyComponent {
|
||||
|
||||
|
|
@ -160,7 +162,7 @@ export default class MyComponent {
|
|||
2. Construct the needed UI in the constructor
|
||||
|
||||
|
||||
```
|
||||
```typescript
|
||||
|
||||
export default class MyComponent {
|
||||
|
||||
|
|
@ -180,10 +182,10 @@ export default class MyComponent {
|
|||
|
||||
```
|
||||
|
||||
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:
|
||||
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 {
|
||||
|
||||
|
|
@ -203,17 +205,17 @@ Assets
|
|||
|
||||
### Themes
|
||||
|
||||
Theme and layer configuration files go into /assets/layers and 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
|
||||
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 'Logic'. Actors are small objects which react to UIEventSources to update other eventSources.
|
||||
The last part is the business logic of the application, found in '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 a mess
|
||||
`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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue