Merge pull request #1440 from umap-project/almet/rework-docs

docs/architecture/frontend.md

@@ -0,0 +1,77 @@
+# The frontend
+
+!!! info "These are notes"
+
+    Consider this page as notes taken while exploring uMap. It's not covering everything but hopefully will help you get a basic understanding of how things work.
+
+uMap uses Leaflet on the frontend. A lot of uMap objects extends the ones from Leaflet with additional abilities.
+
+```mermaid
+erDiagram
+    Map ||--o{ DataLayer : datalayers
+    Map{
+	    JSON permissions
+	    JSON metadata
+    }
+    DataLayer ||--o{Feature : data
+    DataLayer {
+	    JSON metadata
+	    JSON permissions
+    }
+```
+
+Here are the important concepts and files:
+
+- `umap.js` contains `Map`, the map object. It's the main entry point, which references all the related properties. It contains metadata, permissions, and data layers.
+- `umap.layer.js` contains `DataLayer`, which contains metadata, permissions, and data.
+- `umap.permissions.js` handles the permissions of the map. There is a different file handling the permissions of the datalayer:
+- `umap.datalayer.permissions.js`.
+
+## Map (`L.U.Map`)
+
+`L.U.Map` is the class that's called by the server templates (in `map_init.html` and `map_fragment.html` used when we display lists of maps, like the homepage).
+
+It contains references to datalayers, and to the controls (the buttons that appears on the map)
+
+To be able to change the way the client behaves, querystring parameters can be used to overload the settings stored in the database. This is useful for instance when using iframes to display the map on a different website.
+
+uMap has an edit mode. If you don't have the rights you cannot save nor edit, you can't edit the permissions as well.
+
+A map contains references to:
+
+- controls
+- datalayers
+
+## DataLayers (`L.U.Datalayer`)
+
+The datalayers contains data, and a layer (a way to represent them).
+
+Each data layer contains a "layer", to know what type of layer it is. It's one of:
+
+- Choropleth (`L.U.Layer.Choropleth`)
+- Cluster (`L.U.Layer.Cluster`)
+- Heat (`L.U.Layer.Heat`)
+
+When the data layers are initialized, they can have two states:
+- `loaded`: the object is loaded in memory. At this stage we have access to all the datalayer's metada (name, type, id)
+- `dataLoaded` : the data is available to be used, so we can for instance compute the center of the map (when it's dynamic).
+
+- `backupOptions` is here to make it possible to cancel what have been done (using undo). It stores the old settings for the data-layer.
+
+## Storage
+
+To mark what needs to be synced with the server, uMap currently mark objects as "dirty". Something marked as "dirty" has changed on the client, but is not yet saved on the server.
+
+Each map, datalayer and permission objects can be marked as "dirty". When a change is made on an object, it will mark its parent as "dirty" as well, so it can be updated accordingly.
+
+### Saving data to the server with `umap.save()`
+
+Here is what's being done when you call `map.save()`:
+
+1. `map.saveSelf()`, posting `name`, `center` and `settings` to the server, and then
+2. calls `permission.save()`, which will post the permissions to the server, and then call back
+3. `map.continueSaving()`, which will take the first dirtyLayer and call
+4. `datalayer.save()` on it. It does the following:
+	1. Post the data (`name`, `displayOnLoad`, `rank`, `settings`, and `geojson`)
+	2. Calls `permission.save()`, posting `edit_status` to the server, and then calling `map.continue_saving()` and remove the datalayer from `dirtyDatalayers`.
+5. When the `dirtyDatalayers` list is empty, we are done.

docs/architecture/overview.md

@@ -0,0 +1,11 @@
+# Overview of uMap
+
+uMap is a server and a client. The server is build with the Django framework, and the client uses (vanilla) JavaScript, on top of Leaflet.
+
+Basically, here is how it works:
+
+- Most of the data is stored as [geoJSON files](https://geojson.org/), on the server.
+- Some other parts of the data is stored in the database (users, permissions, etc)
+- PostGIS is used for some of its geo features, but for the most part, the computation is done on the frontend with Leaflet.
+
+The server is meant to be a simple layer to do the storage and serve the JavaScript.

docs/custom.md → docs/config/customize.md

@@ -1,7 +1,6 @@
 # Customize your uMap installation
 
-
-When running your own uMap, you may want to changed its appearance, for example
+When running your own uMap, you may want to change its appearance, for example
 you want your own logo on the home page, or you want to apply some design, or
 you want to add some tracking (but anonymous!) script…
 
@@ -10,7 +9,7 @@ that.
 So basically you'll have your own templates and/or statics directories where
 you will put the templates or statics you want to control (and only those).
 
-Inside thore directory, you need to respect the exact relative path of the
+Inside those directories, you need to respect the exact relative path of the
 templates or statics you are adding, relatively to the
 [templates](https://github.com/umap-project/umap/tree/master/umap/templates)
 and
@@ -100,4 +99,4 @@ There are three settings you can play with to control that:
     # Which field to use in the URL, may also be for example "pk" to use the
     # primary key and not expose the username (which may be private or may change too
     # often for URL persistance)
-    USER_URL_FIELD = "username"
+    USER_URL_FIELD = "username"

docs/administration.md → docs/config/icons.md

@@ -1,10 +1,4 @@
-# Administration
-
-You can access uMap administration page by navigating to `https://your.server.org/admin`
-
-You will have to connect with the admin account created during installation. Default admin username is "umap".
-
-## Icons
+# Icons
 
 Icons (aka pictograms in uMap sources) can be used in your map markers.
 
@@ -22,21 +16,23 @@ Example of icons libraries you may want to use:
 - [SJJB Icons](http://www.sjjb.co.uk/mapicons/contactsheet)
 - [Remix](https://remixicon.com/)
 
-### Import icons manually
+## Import icons manually
 
 You can import icons manually by going to your uMap admin page: `https://your.server.org/admin`
 
-### Import icons automatically
+## Import icons automatically
 
 To import icons on your uMap server, you will need to use the command `umap import_pictograms`.
 
 Note: you can get help with `umap import_pictograms -h`
 
 Basic usage:
 
-    umap import_pictograms --attribution "Maki Icons by Mapbox" path/to/icons/directory/
+```bash
+umap import_pictograms --attribution "Maki Icons by Mapbox" path/to/icons/directory/
+```
 
-### Categories
+## Categories
 
 uMap can render icons grouped into categories. When using the import script, any
 subfolder will be used as category.

docs/settings.md → docs/config/settings.md

@@ -5,7 +5,7 @@ are doing.
 
 The Django settings reference is here: https://docs.djangoproject.com/en/4.2/ref/settings/
 
-Here are a few relevent settings for uMap.
+Here are a few relevant settings for uMap.
 
 ## Usage
 
@@ -16,22 +16,54 @@ Those settings should either:
   `UMAP_SETTINGS` env var
 - be declared as env vars directly, for simple ones (string/boolean/list)
 
+
 #### ALLOWED_HOSTS
 
 The hosts that uMap expects.
 `ALLOWED_HOSTS = ['umap.mydomain.org']`
 
 Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org,u.mydomain.org`
 
+#### COMPRESS_ENABLED
+#### COMPRESS_STORAGE
+
+To activate the compression of the static files, you can set this flag to `True`.
+
+You can then run the following command to compress the assets:
+
+```bash
+umap compress
+```
+
+Optionally add `COMPRESS_STORAGE = "compressor.storage.GzipCompressorFileStorage"`
+and add `gzip_static on` directive to Nginx `/static` location, so Nginx will
+serve pregenerated files instead of compressing them on the fly.
+
 #### DEBUG
 
-Set it to True for easier debugging in case of error.
+Set it to `True` for easier debugging in case of error.
 
 #### EMAIL_BACKEND
 
 Must be configured if you want uMap to send emails to anonymous users.
 
-See [Emails](install.md#emails) for more details.
+UMap can send the anonymous edit link by email. For this to work, you need to
+add email specific settings. See [Django](https://docs.djangoproject.com/en/4.2/topics/email/#smtp-backend)
+documentation.
+
+In general, you'll need to add something like this in your local settings:
+
+```python title="local_settings.py"
+FROM_EMAIL = "youradmin@email.org"
+EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
+EMAIL_HOST = "smtp.provider.org"
+EMAIL_PORT = 456
+EMAIL_HOST_USER = "username"
+EMAIL_HOST_PASSWORD = "xxxx"
+EMAIL_USE_TLS = True
+# or
+EMAIL_USE_SSL = True
+```
 
 #### ENABLE_ACCOUNT_LOGIN
 
@@ -48,6 +80,7 @@ See `EMAIL_BACKEND`.
 
 Set it to the default language you want. `LANGUAGE_CODE = "it"`
 
+#### Default map center
 #### LEAFLET_LONGITUDE, LEAFLET_LATITUDE, LEAFLET_ZOOM
 
 Default longitude, latitude and zoom for the map
@@ -128,14 +161,14 @@ To be used when you want to override some HTML templates:
 
     UMAP_CUSTOM_TEMPLATES = "/path/to/custom/templates"
 
-See [customization](custom.md) for details.
+See [customization](customize.md) for details.
 
 #### UMAP_CUSTOM_STATICS
 To be used when you want to override some CSS or images:
 
     UMAP_CUSTOM_STATICS = "/path/to/custom/static"
 
-See [customization](custom.md) for details.
+See [customization](customize.md) for details.
 
 #### UMAP_EXTRA_URLS
 
@@ -198,7 +231,27 @@ How many maps to show in the user "my maps" page.
 
 Use it if you take control over the search configuration.
 
-See [search](install.md#search) for details.
+UMap uses PostgreSQL tsvector for searching. In case your database is big, you
+may want to add an index. For that, here are the SQL commands to run:
+
+```SQL
+# Create a basic search configuration
+CREATE TEXT SEARCH CONFIGURATION umapdict (COPY=simple);
+
+# If you also want to deal with accents and case, add this before creating the index
+CREATE EXTENSION unaccent;
+CREATE EXTENSION btree_gin;
+ALTER TEXT SEARCH CONFIGURATION umapdict ALTER MAPPING FOR hword, hword_part, word WITH unaccent, simple;
+
+# Now create the index
+CREATE INDEX IF NOT EXISTS search_idx ON umap_map USING GIN(to_tsvector('umapdict', COALESCE(name, ''::character varying)::text), share_status);
+```
+
+Then set:
+
+```python title="settings.py"
+UMAP_SEARCH_CONFIGURATION = "umapdict"
+```
 
 #### UMAP_READONLY
 
@@ -208,6 +261,12 @@ Is your instance readonly? Useful for server maintenance.
 
 Should uMap gzip datalayers geojson.
 
+#### UMAP_XSENDFILE_HEADER
+
+Can be set to `X-Accel-Redirect` to enable the [NGINX X-Accel](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/) feature.
+
+See the NGINX documentation in addition.
+
 #### SOCIAL_AUTH_OPENSTREETMAP_KEY, SOCIAL_AUTH_OPENSTREETMAP_SECRET
 
 If you use OpenStreetMap as OAuth provider, use those settings.