Start restructuring web presences

evennia/web/README.md

@@ -0,0 +1,21 @@
+# Web resources
+
+This folder holds the functioning code, html, js and css files for use by the
+Evennia website and -client. This is a standard Django web application.
+
+1. When a user enters an url (or clicks a link) in their web browser, Django will 
+   use this incoming request to refer to the `urls.py` file.
+2. The `urls.py` file will use regex to match the url to a _view_ - a Python function
+   or callable class. The incoming request data will be passed to this code.
+3. The view will (usually) refer to a _template_, which is a html document with 
+   templating slots that allows the system to replace parts of it with dynamic 
+   content (like how many users are currently in-game).
+4. The view will render the template with any context into a final HTML page 
+   that is returned to the user to view.
+  
+I many ways this works like an Evennia Command, with input being the browser's
+request and the view being the Command's function body for producing a result.
+
+In the case of the webclient, the html page is rendered once and when doing so
+it loads a Javascript application in the browser that opens a websocket to
+communicate with the server.

evennia/web/urls.py

@@ -1,10 +1,21 @@
-#
-# File that determines what each URL points to. This uses _Python_ regular
-# expressions, not Perl's.
-#
-# See:
-# http://diveintopython.org/regular_expressions/street_addresses.html#re.matching.2.3
-#
+"""
+File that determines what each URL points to. This uses Python regular expressions.
+This is the starting point when a user enters an URL.
+
+ 1. The URL is matched with a regex, tying it to a given view. Note that this central url.py
+    file includes url.py from all the various web-components found in views/ so the search
+    space is much larger than what is shown here.
+ 2. The view (a Python function or class is executed)
+ 3. The view uses a template (a HTML file which may contain template markers for dynamically
+    modifying its contents; the locations of such templates are given by
+    `settings.TEMPLATES[0]['DIRS']`) and which may in turn may include static
+    assets (CSS, images etc).
+ 4. The view 'renders' the template into a finished HTML page, replacing all
+ dynamic content as appropriate.
+ 5. The HTML page is returned to the user.
+
+"""
+
 
 from django.conf.urls import url
 from django.conf import settings
@@ -24,4 +35,5 @@ urlpatterns = [
 ]
 
 if settings.REST_API_ENABLED:
+    # Rest API
     urlpatterns += [url(r"^api/", include("evennia.web.api.urls", namespace="api"))]

evennia/web/webclient/urls.py

@@ -1,10 +1,10 @@
 """
-This structures the (simple) structure of the
-webpage 'application'.
+This structures the (simple) structure of the webpage 'application'.
+
 """
 from django.urls import path
-from evennia.web.webclient import views as webclient_views
+from . import views
 
 app_name = "webclient"
 
-urlpatterns = [path("", webclient_views.webclient, name="index")]
+urlpatterns = [path("", views.webclient, name="index")]

evennia/web/website/urls.py

@@ -6,63 +6,70 @@ from django.conf import settings
 from django.contrib import admin
 from django.conf.urls import url, include
 from django import views as django_views
-from evennia.web.website import views as website_views
+from . import views
 
 urlpatterns = [
-    url(r"^$", website_views.EvenniaIndexView.as_view(), name="index"),
-    url(r"^tbi/", website_views.to_be_implemented, name="to_be_implemented"),
+    url(r"^$", views.EvenniaIndexView.as_view(), name="index"),
+    url(r"^tbi/", views.to_be_implemented, name="to_be_implemented"),
+
     # User Authentication (makes login/logout url names available)
-    url(r"^auth/register", website_views.AccountCreateView.as_view(), name="register"),
+    url(r"^auth/register", views.AccountCreateView.as_view(), name="register"),
     url(r"^auth/", include("django.contrib.auth.urls")),
+
     # Help Topics
-    url(r"^help/$", website_views.HelpListView.as_view(), name="help"),
+    url(r"^help/$", views.HelpListView.as_view(), name="help"),
     url(
         r"^help/(?P<category>[\w\d\-]+)/(?P<topic>[\w\d\-]+)/$",
-        website_views.HelpDetailView.as_view(),
+        views.HelpDetailView.as_view(),
         name="help-entry-detail",
     ),
+
     # Channels
-    url(r"^channels/$", website_views.ChannelListView.as_view(), name="channels"),
+    url(r"^channels/$", views.ChannelListView.as_view(), name="channels"),
     url(
         r"^channels/(?P<slug>[\w\d\-]+)/$",
-        website_views.ChannelDetailView.as_view(),
+        views.ChannelDetailView.as_view(),
         name="channel-detail",
     ),
+
     # Character management
-    url(r"^characters/$", website_views.CharacterListView.as_view(), name="characters"),
+    url(r"^characters/$", views.CharacterListView.as_view(), name="characters"),
     url(
         r"^characters/create/$",
-        website_views.CharacterCreateView.as_view(),
+        views.CharacterCreateView.as_view(),
         name="character-create",
     ),
     url(
         r"^characters/manage/$",
-        website_views.CharacterManageView.as_view(),
+        views.CharacterManageView.as_view(),
         name="character-manage",
     ),
     url(
         r"^characters/detail/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$",
-        website_views.CharacterDetailView.as_view(),
+        views.CharacterDetailView.as_view(),
         name="character-detail",
     ),
     url(
         r"^characters/puppet/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$",
-        website_views.CharacterPuppetView.as_view(),
+        views.CharacterPuppetView.as_view(),
         name="character-puppet",
     ),
     url(
         r"^characters/update/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$",
-        website_views.CharacterUpdateView.as_view(),
+        views.CharacterUpdateView.as_view(),
         name="character-update",
     ),
     url(
         r"^characters/delete/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$",
-        website_views.CharacterDeleteView.as_view(),
+        views.CharacterDeleteView.as_view(),
         name="character-delete",
     ),
+
     # Django original admin page. Make this URL is always available, whether
     # we've chosen to use Evennia's custom admin or not.
-    url(r"django_admin/", website_views.admin_wrapper, name="django_admin"),
+
+    url(r"django_admin/", views.admin_wrapper, name="django_admin"),
+
     # Admin docs
     url(r"^admin/doc/", include("django.contrib.admindocs.urls")),
 ]
@@ -70,7 +77,7 @@ urlpatterns = [
 if settings.EVENNIA_ADMIN:
     urlpatterns += [
         # Our override for the admin.
-        url("^admin/$", website_views.evennia_admin, name="evennia_admin"),
+        url("^admin/$", views.evennia_admin, name="evennia_admin"),
         # Makes sure that other admin pages get loaded.
         url(r"^admin/", admin.site.urls),
     ]

evennia/web/website/views.py

@@ -26,7 +26,7 @@ from evennia.objects.models import ObjectDB
 from evennia.accounts.models import AccountDB
 from evennia.utils import class_from_module
 from evennia.utils.logger import tail_log_file
-from evennia.web.website import forms as website_forms
+from . import forms
 
 from django.utils.text import slugify
 
@@ -165,7 +165,7 @@ class EvenniaIndexView(TemplateView):
         return context
 
 
-class TypeclassMixin(object):
+class TypeclassMixin:
     """
     This is a "mixin", a modifier of sorts.
 
@@ -523,7 +523,7 @@ class AccountMixin(TypeclassMixin):
     # -- Django constructs --
     model = class_from_module(settings.BASE_ACCOUNT_TYPECLASS,
                               fallback=settings.FALLBACK_ACCOUNT_TYPECLASS)
-    form_class = website_forms.AccountForm
+    form_class = forms.AccountForm
 
 
 class AccountCreateView(AccountMixin, EvenniaCreateView):
@@ -589,7 +589,7 @@ class CharacterMixin(TypeclassMixin):
     # -- Django constructs --
     model = class_from_module(settings.BASE_CHARACTER_TYPECLASS,
                               fallback=settings.FALLBACK_CHARACTER_TYPECLASS)
-    form_class = website_forms.CharacterForm
+    form_class = forms.CharacterForm
     success_url = reverse_lazy("character-manage")
 
     def get_queryset(self):
@@ -713,7 +713,7 @@ class CharacterUpdateView(CharacterMixin, ObjectUpdateView):
     """
 
     # -- Django constructs --
-    form_class = website_forms.CharacterUpdateForm
+    form_class = forms.CharacterUpdateForm
     template_name = "website/character_form.html"