Start restructuring web presences

evennia/game_template/gitignore

@@ -29,8 +29,8 @@ __pycache__
 # For group efforts, comment out some or all of these.
 server/conf/secret_settings.py
 server/logs/*.log.*
-web/static/*
-web/media/*
+server/.static/*
+server/.media/*
 
 # Installer logs
 pip-log.txt

evennia/game_template/web/media/README.md

@@ -1,2 +0,0 @@
-This directory is where file uploads from Django apps are placed by
-default.

evennia/game_template/web/static/README.md

@@ -1,4 +1,17 @@
-DO NOT EDIT FILES IN THIS DIRECTORY! THEY WILL BE OVERWRITTEN.
+## Static files
 
-If you need to edit static files, replace them (using the same path)
-in the static_overrides directory.
+This is the place to put static resources you want to serve from the 
+Evennia server. This is usually CSS and Javascript files but you _could_ also
+serve other media like images, videos and music files from here.
+
+> If you serve a lot of large files (especially videos) you will see a lot
+> better performance doing so from a separate dedicated media host.
+
+You can also override default Evennia files from here. The original files are
+found in `evennia/web/static/`. Copy the original file into the same
+corresponding location/sublocation in this folder (such as website CSS files
+into `mygame/static/website/css/`) and modify it, then reload the server.
+
+Note that all static resources will be collected from all over Evennia into
+`mygame/server/.static` for serving by the webserver. That folder should not be
+modified manually.

evennia/game_template/web/static_overrides/README.md

@@ -1,13 +0,0 @@
-If you want to override one of the static files (such as a CSS or JS file) used by Evennia or a Django app installed in your Evennia project,
-copy it into this directory's corresponding subdirectory, and it will be placed in the static folder when you run:
-
-    python manage.py collectstatic
-
-...or when you reload the server via the command line.
-
-Do note you may have to reproduce any preceeding directory structures for the file to end up in the right place.
-
-Also note that you may need to clear out existing static files for your new ones to be gathered in some cases. Deleting files in static/ 
-will force them to be recollected.
-
-To see what files can be overridden, find where your evennia package is installed, and look in `evennia/web/static/`

evennia/game_template/web/template_overrides/README.md

@@ -1,4 +0,0 @@
-Place your own version of templates into this file to override the default ones.
-For instance, if there's a template at: `evennia/web/website/templates/website/index.html`
-and you want to replace it, create the file `template_overrides/website/index.html`
-and it will be loaded instead.

evennia/game_template/web/template_overrides/webclient/README.md

@@ -1,3 +0,0 @@
-Replace Evennia's webclient django templates with your own here.
-
-You can find the original files in `evennia/web/webclient/templates/webclient/`

evennia/game_template/web/template_overrides/website/README.md

@@ -1,7 +0,0 @@
-You can replace the django templates (html files) for the website
-here. It uses the default "prosimii" theme. If you want to maintain
-multiple themes rather than just change the default one in-place, 
-make new folders under `template_overrides/` and change
-`settings.ACTIVE_THEME` to point to the folder name to use.
-
-You can find the original files under `evennia/web/website/templates/website/`

evennia/game_template/web/templates/README.md

@@ -0,0 +1,14 @@
+# HTML templates
+
+Templates are HTML files that (usually) have special `{{ ... }}` template
+markers in them to allow Evennia/Django to insert dynamic content in a web
+page. An example is listing how many users are currently online in the game.
+
+Templates are referenced by _views_ - Python functions or callable classes that
+prepare the data needed by the template and 'renders' them into a finished 
+HTML page to return to the user.
+
+You can replace Evennia's default templates by overriding them in this folder.
+The originals are in `evennia/web/templates/` - just copy the template into the
+corresponding location here (so the website's `index.html` should be copied to
+`website/index.html` where it can be modified). Reload the server to see your changes.

evennia/game_template/web/templates/webclient/README.md

@@ -0,0 +1,4 @@
+Replace Evennia's webclient django template with your own here.
+
+You can find the original files in `evennia/web/templates/webclient/`. Just copy
+the original here and modify - after a reload the new template will be used.

evennia/game_template/web/templates/website/README.md

@@ -0,0 +1,5 @@
+You can replace the django templates (html files) for the website
+here. 
+
+You can find the original files under `evennia/web/templates/website/`. Just 
+copy a template here and modify to have it override the default.

evennia/game_template/web/urls.py

@@ -1,18 +1,27 @@
 """
-Url definition file to redistribute incoming URL requests to django
-views. Search the Django documentation for "URL dispatcher" for more
-help.
+This is the starting point when a user enters a url in their web browser. 
+
+The urls is matched (by regex) and mapped to a 'view' - a Python function or
+callable class that in turn (usually) makes use of a 'template' (a html file
+with slots that can be replaced by dynamic content) in order to render a HTML
+page to show the user.
+
+This file is already set up to correctly handle all of Evennia's existing web
+pages (including the webclient). But if you want to add a new page you needs to
+start add by adding its view to `custom_patterns`. 
+
+Search the Django documentation for "URL dispatcher" for more help.
 
 """
 from django.conf.urls import url, include
 
 # default evennia patterns
-from evennia.web.urls import urlpatterns
+from evennia.web.urls import urlpatterns as evennia_default_urlpatterns
 
-# eventual custom patterns
-custom_patterns = [
-    # url(r'/desired/url/', view, name='example'),
+# add custom patterns here
+urlpatterns = [
+    # url(r'/desired/url/regex', 'path.to.python.view', name='example'),
 ]
 
-# this is required by Django.
-urlpatterns = custom_patterns + urlpatterns
+# 'urlpatterns' must be named such for Django to find it.
+urlpatterns = urlpatterns + evennia_default_urlpatterns

evennia/game_template/web/views.py

@@ -0,0 +1,19 @@
+"""
+A 'view' is python code (can be a function or a callabl class) responsible for
+producing a HTML page for a user to view in response for going to a given URL
+in their browser. In Evennia lingo, it's similar in function to a Command, with
+the input/args being the URL/request and the output being a new web-page.
+
+The urls.py file contains regular expressions that are run against the provided
+URL - when a match is found, the execution is passed to a view which is
+then responsible (usually) for producing the web page by filling in a
+_template_ - a HTML document that can have special tags in it that are replaced
+for dynamic content. It then returns the finished HTML page for the user to
+view.
+
+See the [Django docs on Views](https://docs.djangoproject.com/en/3.2/topics/http/views/) for 
+more information.
+
+"""
+
+