Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(how-to): 📝 Update for v1.0+

Browse source 
Update add a new django view and html page to reflect Evennia v1.0+
Various grammar/syntax changes
This commit is contained in:
iLPdev 2023-07-14 06:09:20 -07:00 • committed by GitHub
parent 675a2beb9c
commit d6f0d4799f
1 changed files with 66 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

120
docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md
View file

@ -1,27 +1,31 @@
# Add a simple new web page # Add a simple new web page
Evennia leverages [Django](https://docs.djangoproject.com) which is a web development framework. 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 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 . 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. 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 We assume you have installed and set up Evennia to run. A webserver and website comes along with the
box. You can get to that by entering `http://localhost:4001` in your web browser - you should see a default Evennia install out of the box. You can view the default website by pointing your web browser
welcome page with some game statistics and a link to the web client. Let us add a new page that you to `http://localhost:4001`. You will see a generic welcome page with some game statistics and a link
can get to by going to `http://localhost:4001/story`. 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 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 in the web browser. Django can do all sorts of cool stuff to a page by using the view function -- like
cool stuff with the page in the view, like adding dynamic content or change it on the fly. Open adding dynamic content or making changes to a page on the fly -- but, here, we will just have it spit
`mygame/web` folder and add a new module there named `story.py` (you could also put it in its own back raw HTML.
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: 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 ```python
# in mygame/web/story.py # in mygame/web/website/story.py
from django.shortcuts import render from django.shortcuts import render
@ -29,72 +33,80 @@ def storypage(request):
return render(request, "story.html") return render(request, "story.html")
``` ```
This view takes advantage of a shortcut provided to use by Django, _render_. This shortcut gives the The above view takes advantage of a shortcut provided for use by Django: _render_. Thre render shortcut
template some information from the request, for instance, the game name, and then renders it. 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 Next, we need to find the location where Evennia (and Django) looks for HTML files, which are referred
Django parlance). You can specify such places in your settings (see the `TEMPLATES` variable in to as *templates* in Django's parlance. You can specify such locations in your settings (see the
`default_settings.py` for more info), but here we'll use an existing one. Go to `TEMPLATES` variable in `default_settings.py` for more info) but, here we'll use an existing one.
`mygame/template/overrides/website/` and create a page `story.html` there.
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 ```html
{% extends "base.html" %} {% extends "base.html" %}
{% endblock %}
{% block content %} {% block content %}
<div class="row"> <div class="row">
<div class="col"> <div class="col">
<h1>A story about a tree</h1> Expand All
<p> @@ -55,9 +64,9 @@ This is not a HTML tutorial, so we'll go simple:
This is a story about a tree, a classic tale ...
</p>
</div>
</div>
{% endblock %} {% endblock %}
``` ```
Since we've used the _render_ shortcut, Django will allow us to extend our base styles easily. 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
If you'd rather not take advantage of Evennia's base styles, you can do something like this instead: instead do something like this:
```html ```html
<html> <html>
<body> Expand All
<h1>A story about a tree</h1> @@ -69,32 +78,46 @@ If you'd rather not take advantage of Evennia's base styles, you can do somethin
<p>
This is a story about a tree, a classic tale ...
</body>
</html> </html>
``` ```
### 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 Django looks for the variable `urlpatterns` in this file. You will want to add your new `story` pattern
field to figure out which page you want to go to. You tell it which patterns are relevant in the and corresponding path to `urlpatterns` list - which is then, in turn, merged with the default
file `urlpatterns`. Here's how it could look:
[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:
```python ```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 = [ from evennia.web.website.urls import urlpatterns as evennia_website_urlpatterns
url(r'story', story.storypage, name='Story'),
# 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` The above code imports our `story.py` Python view module from where we created it earlier -- in
instance. The first argument to `url` is the pattern of the url we want to find (`"story"`) (this is `mygame/web/website/` -- and then add the corresponding `path` instance. The first argument to
a regular expression if you are familiar with those) and then our view function we want to direct `path` is the pattern of the URL that we want to find (`"story"`) as a regular expression, and
to. 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!