From d6f0d4799f530f70fd92fe3b44b206265aac7f9c Mon Sep 17 00:00:00 2001 From: iLPdev Date: Fri, 14 Jul 2023 06:09:20 -0700 Subject: [PATCH 1/4] docs(how-to): :memo: Update for v1.0+ Update add a new django view and html page to reflect Evennia v1.0+ Various grammar/syntax changes --- .../Part5/Add-a-simple-new-web-page.md | 120 ++++++++++-------- 1 file changed, 66 insertions(+), 54 deletions(-) diff --git a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md index 2ec92b70ff..1000d8bbd2 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md @@ -1,27 +1,31 @@ # Add a simple new web page - - Evennia leverages [Django](https://docs.djangoproject.com) which is a web development framework. Huge professional websites are made in Django and there is extensive documentation (and books) on it . You are encouraged to at least look at the Django basic tutorials. Here we will just give a brief introduction for how things hang together, to get you started. -We assume you have installed and set up Evennia to run. A webserver and website comes out of the -box. You can get to that by entering `http://localhost:4001` in your web browser - you should see a -welcome page with some game statistics and a link to the web client. Let us add a new page that you -can get to by going to `http://localhost:4001/story`. +We assume you have installed and set up Evennia to run. A webserver and website comes along with the +default Evennia install out of the box. You can view the default website by pointing your web browser +to `http://localhost:4001`. You will see a generic welcome page with some game statistics and a link +to the Evennia web client. -## Create the view +In this tutorial, we will add a new page that you can visit at `http://localhost:4001/story`. + +### Create the view A django "view" is a normal Python function that django calls to render the HTML page you will see -in the web browser. Here we will just have it spit back the raw html, but Django can do all sorts of -cool stuff with the page in the view, like adding dynamic content or change it on the fly. Open -`mygame/web` folder and add a new module there named `story.py` (you could also put it in its own -folder if you wanted to be neat. Don't forget to add an empty `__init__.py` file if you do, to tell -Python you can import from the new folder). Here's how it looks: +in the web browser. Django can do all sorts of cool stuff to a page by using the view function -- like +adding dynamic content or making changes to a page on the fly -- but, here, we will just have it spit +back raw HTML. + +Open `mygame/web/website` folder and create a new module file there named `story.py`. (You could also +put it in its own folder if you wanted to be neat but, if you do, don't forget to add an empty +`__init__.py` file in the new folfder. Adding the `__init__.py` file tells Python that modules can be +imported from the new folder. For this tutorial, here's what the example contents of your new `story.py` +module should look like: ```python -# in mygame/web/story.py +# in mygame/web/website/story.py from django.shortcuts import render @@ -29,72 +33,80 @@ def storypage(request): return render(request, "story.html") ``` -This view takes advantage of a shortcut provided to use by Django, _render_. This shortcut gives the -template some information from the request, for instance, the game name, and then renders it. +The above view takes advantage of a shortcut provided for use by Django: _render_. Thre render shortcut +gives the template information from the request. For instance, it might provide the game name, and then +renders it. -## The HTML page +### The HTML page -We need to find a place where Evennia (and Django) looks for html files (called *templates* in -Django parlance). You can specify such places in your settings (see the `TEMPLATES` variable in -`default_settings.py` for more info), but here we'll use an existing one. Go to -`mygame/template/overrides/website/` and create a page `story.html` there. +Next, we need to find the location where Evennia (and Django) looks for HTML files, which are referred +to as *templates* in Django's parlance. You can specify such locations in your settings (see the +`TEMPLATES` variable in `default_settings.py` for more info) but, here we'll use an existing one. -This is not a HTML tutorial, so we'll go simple: +Navigate to `mygame/web/templates/website/` and create a new file there called `story.html`. This +is not an HTML tutorial, so this file's content will be simple: ```html {% extends "base.html" %} +{% endblock %} + {% block content %}
-

A story about a tree

-

- This is a story about a tree, a classic tale ... -

-
-
+Expand All + @@ -55,9 +64,9 @@ This is not a HTML tutorial, so we'll go simple: {% endblock %} ``` -Since we've used the _render_ shortcut, Django will allow us to extend our base styles easily. - -If you'd rather not take advantage of Evennia's base styles, you can do something like this instead: +As shown above, Django will allow us to extend our base styles easily because we've used the +_render_ shortcut. If you'd prefer to not take advantage of Evennia's base styles, you might +instead do something like this: ```html - -

A story about a tree

-

- This is a story about a tree, a classic tale ... - +Expand All + @@ -69,32 +78,46 @@ If you'd rather not take advantage of Evennia's base styles, you can do somethin ``` +### The URL -## The URL +When you enter the address `http://localhost:4001/story` in your web browser, Django will parse the +stub following the port -- here, `/story` -- to find out to which page you would like displayed. How +does Django know what HTML file `/story` should link to? You inform Django about what address stub +patterns correspond to what files in the file `mygame/web/website/urls.py`. Open it in your editor now. -When you enter the address `http://localhost:4001/story` in your web browser, Django will parse that -field to figure out which page you want to go to. You tell it which patterns are relevant in the -file -[mygame/web/urls.py](https://github.com/evennia/evennia/blob/main/evennia/game_template/web/urls.py). -Open it now - -Django looks for the variable `urlpatterns` in this file. You want to add your new pattern to the -`custom_patterns` list we have prepared - that is then merged with the default `urlpatterns`. Here's -how it could look: +Django looks for the variable `urlpatterns` in this file. You will want to add your new `story` pattern +and corresponding path to `urlpatterns` list - which is then, in turn, merged with the default +`urlpatterns`. Here's how it could look: ```python -from web import story +""" +This reroutes from an URL to a python view-function/class. +The main web/urls.py includes these routes for all urls (the root of the url) +so it can reroute to all website pages. +""" +from django.urls import path -# ... +from web.website import story -custom_patterns = [ - url(r'story', story.storypage, name='Story'), +from evennia.web.website.urls import urlpatterns as evennia_website_urlpatterns + +# add patterns here +urlpatterns = [ + # path("url-pattern", imported_python_view), + path(r"story", story.storypage, name="Story"), ] + +# read by Django +urlpatterns = urlpatterns + evennia_website_urlpatterns ``` -That is, we import our story view module from where we created it earlier and then create an `url` -instance. The first argument to `url` is the pattern of the url we want to find (`"story"`) (this is -a regular expression if you are familiar with those) and then our view function we want to direct -to. +The above code imports our `story.py` Python view module from where we created it earlier -- in +`mygame/web/website/` -- and then add the corresponding `path` instance. The first argument to +`path` is the pattern of the URL that we want to find (`"story"`) as a regular expression, and +then the view function from `story.py` that we want to call. -That should be it. Reload Evennia and you should be able to browse to your new story page! +That should be it. Reload Evennia -- `evennia reload` -- and you should now be able to navigate +your browser to the `http://localhost:4001/story` location and view your new story page as +rendered by Python! From 70d690bdeda1ef84b9ba19d4c378208101f43e3a Mon Sep 17 00:00:00 2001 From: iLPdev Date: Sun, 23 Jul 2023 14:41:05 -0700 Subject: [PATCH 2/4] docs(howto): typos and `—`s --- .../Part5/Add-a-simple-new-web-page.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md index 1000d8bbd2..73fdf975b1 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md @@ -1,7 +1,7 @@ # Add a simple new web page Evennia leverages [Django](https://docs.djangoproject.com) which is a web development framework. -Huge professional websites are made in Django and there is extensive documentation (and books) on it -. You are encouraged to at least look at the Django basic tutorials. Here we will just give a brief +Huge professional websites are made in Django and there is extensive documentation (and books) on it. +You are encouraged to at least look at the Django basic tutorials. Here we will just give a brief introduction for how things hang together, to get you started. We assume you have installed and set up Evennia to run. A webserver and website comes along with the @@ -14,8 +14,8 @@ In this tutorial, we will add a new page that you can visit at `http://localhost ### Create the view A django "view" is a normal Python function that django calls to render the HTML page you will see -in the web browser. Django can do all sorts of cool stuff to a page by using the view function -- like -adding dynamic content or making changes to a page on the fly -- but, here, we will just have it spit +in the web browser. Django can do all sorts of cool stuff to a page by using the view function — like +adding dynamic content or making changes to a page on the fly — but, here, we will just have it spit back raw HTML. Open `mygame/web/website` folder and create a new module file there named `story.py`. (You could also @@ -33,7 +33,7 @@ def storypage(request): return render(request, "story.html") ``` -The above view takes advantage of a shortcut provided for use by Django: _render_. Thre render shortcut +The above view takes advantage of a shortcut provided for use by Django: _render_. The render shortcut gives the template information from the request. For instance, it might provide the game name, and then renders it. @@ -72,12 +72,12 @@ Expand All ### The URL When you enter the address `http://localhost:4001/story` in your web browser, Django will parse the -stub following the port -- here, `/story` -- to find out to which page you would like displayed. How +stub following the port — here, `/story` — to find out to which page you would like displayed. How does Django know what HTML file `/story` should link to? You inform Django about what address stub patterns correspond to what files in the file `mygame/web/website/urls.py`. Open it in your editor now. Django looks for the variable `urlpatterns` in this file. You will want to add your new `story` pattern -and corresponding path to `urlpatterns` list - which is then, in turn, merged with the default +and corresponding path to `urlpatterns` list — which is then, in turn, merged with the default `urlpatterns`. Here's how it could look: ```python @@ -102,11 +102,11 @@ urlpatterns = [ urlpatterns = urlpatterns + evennia_website_urlpatterns ``` -The above code imports our `story.py` Python view module from where we created it earlier -- in -`mygame/web/website/` -- and then add the corresponding `path` instance. The first argument to +The above code imports our `story.py` Python view module from where we created it earlier — in +`mygame/web/website/` — and then add the corresponding `path` instance. The first argument to `path` is the pattern of the URL that we want to find (`"story"`) as a regular expression, and then the view function from `story.py` that we want to call. -That should be it. Reload Evennia -- `evennia reload` -- and you should now be able to navigate +That should be it. Reload Evennia — `evennia reload` — and you should now be able to navigate your browser to the `http://localhost:4001/story` location and view your new story page as rendered by Python! From 35d7b95c48901f6e2e7530eff710e389acaac58f Mon Sep 17 00:00:00 2001 From: iLPdev Date: Sun, 23 Jul 2023 14:50:20 -0700 Subject: [PATCH 3/4] docs(how-to): fix first github html parsing error --- .../Part5/Add-a-simple-new-web-page.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md index 73fdf975b1..db6458d04b 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md @@ -48,13 +48,15 @@ is not an HTML tutorial, so this file's content will be simple: ```html {% extends "base.html" %} -{% endblock %} - {% block content %}

-Expand All - @@ -55,9 +64,9 @@ This is not a HTML tutorial, so we'll go simple: +

A story about a tree

+

+ This is a story about a tree, a classic tale ... +

+
+
{% endblock %} ``` From 31a21786143ddecb3a4334e520457b1a1d232220 Mon Sep 17 00:00:00 2001 From: iLPdev Date: Sun, 23 Jul 2023 14:52:43 -0700 Subject: [PATCH 4/4] docs(howto): fix second instance of github html parsing error --- .../Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md index db6458d04b..01e4be1d2f 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md @@ -66,8 +66,11 @@ instead do something like this: ```html -Expand All - @@ -69,32 +78,46 @@ If you'd rather not take advantage of Evennia's base styles, you can do somethin + +

A story about a tree

+

+ This is a story about a tree, a classic tale ... + ```