mirror of
https://github.com/evennia/evennia.git
synced 2026-03-27 02:06:32 +01:00
Continue documentation of web components
This commit is contained in:
Griatch
parent
72e9fd6fd1
commit
4bea4d5703
18 changed files with 450 additions and 84 deletions
|
|
@ -1,11 +1,71 @@
|
|||
# Webserver
|
||||
|
||||
When Evennia starts it also spins up its own Twisted-based web server. The webserver is responsible for serving the html pages of the game's website. It can also serve static resources like images and music.
|
||||
When Evennia starts it also spins up its own Twisted-based web server. The
|
||||
webserver is responsible for serving the html pages of the game's website. It
|
||||
can also serve static resources like images and music.
|
||||
|
||||
The webclient runs as part of the [Server](Portal-And-Server) process of Evennia. This means that it can directly access cached objects modified in-game, and there is no risk of working with objects that are temporarily out-of-sync in the database.
|
||||
The webclient runs as part of the [Server](Portal-And-Server) process of
|
||||
Evennia. This means that it can directly access cached objects modified
|
||||
in-game, and there is no risk of working with objects that are temporarily
|
||||
out-of-sync in the database.
|
||||
|
||||
The webserver runs on Twisted and is meant to be used in a production environment. It leverages the Django web framework and provides:
|
||||
The webserver runs on Twisted and is meant to be used in a production
|
||||
environment. It leverages the Django web framework and provides:
|
||||
|
||||
- A [Game Website](Website) - this is what you see when you go to `localhost:4001`. The look of the website is meant to be customized to your game. Users logged into the website will be auto-logged into the game if they do so with the webclient since they share the same login credentials (there is no way to safely do auto-login with telnet clients).
|
||||
- The [Web Admin](Web-Admin) is based on the Django web admin and allows you to edit the game database in a graphical interface.
|
||||
- The [Webclient](Webclient) page is served by the webserver, but the actual game communication (sending/receiving data) is done by the javascript client on the page opening a websocket connection directly to Evennia's Portal.
|
||||
- A [Game Website](Website) - this is what you see when you go to
|
||||
- `localhost:4001`. The look of the website is meant to be customized to your
|
||||
- game. Users logged into the website will be auto-logged into the game if they
|
||||
- do so with the webclient since they share the same login credentials (there
|
||||
- is no way to safely do auto-login with telnet clients).
|
||||
- The [Web Admin](Web-Admin) is based on the Django web admin and allows you to
|
||||
- edit the game database in a graphical interface.
|
||||
- The [Webclient](Webclient) page is served by the webserver, but the actual
|
||||
- game communication (sending/receiving data) is done by the javascript client
|
||||
on the page opening a websocket connection directly to Evennia's Portal.
|
||||
|
||||
|
||||
## Basic Webserver data flow
|
||||
|
||||
1. A user enters an url in their browser (or clicks a button). This leads to
|
||||
the browser sending a _HTTP request_ to the server containing an url-path
|
||||
(like for `https://localhost:4001/`, the part of the url we need to consider
|
||||
`/`). Other possibilities would be `/admin/`, `/login/`, `/channels/` etc.
|
||||
2. evennia (through Django) will make use of the regular expressions registered
|
||||
in the `urls.py` file. This acts as a rerouter to _views_, which are
|
||||
regular Python functions or callable classes able to process the incoming
|
||||
request (think of these as similar to the right Evennia Command being
|
||||
selected to handle your input - views are like Commands in this sense). In
|
||||
the case of `/` we reroute to a view handling the main index-page of the
|
||||
website.
|
||||
3. The view code will prepare all the data needed by the web page. For the default
|
||||
index page, this means gather the game statistics so you can see how many
|
||||
are currently connected to the game etc.
|
||||
4. The view will next fetch a _template_. A template is a HTML-document with special
|
||||
'placeholder' tags (written as `{{...}}` or `{% ... %}` usually). These
|
||||
placeholders allow the view to inject dynamic content into the HTML and make
|
||||
the page customized to the current situation. For the index page, it means
|
||||
injecting the current player-count in the right places of the html page. This
|
||||
is called 'rendering' the template. The result is a complete HTML page.
|
||||
5. (The view can also pull in a _form_ to customize user-input in a similar way.)
|
||||
6. The finished HTML page is packed into a _HTTP response_ and returned to the
|
||||
web browser, which can now display the page!
|
||||
|
||||
### A note on the webclient
|
||||
|
||||
The web browser can also execute code directly without talking to the Server.
|
||||
This code must be written/loaded into the web page and is written using the
|
||||
Javascript programming language (there is no way around this, it is what web
|
||||
browsers understand). Executing Javascript is something the web browser does,
|
||||
it operates independently from Evennia. Small snippets of javascript can be
|
||||
used on a page to have buttons react, make small animations etc that doesn't
|
||||
require the server.
|
||||
|
||||
In the case of the [Webclient](Webclient), Evennia will load the Webclient page
|
||||
as above, but the page then initiates Javascript code (a lot of it) responsible
|
||||
for actually displaying the client GUI, allows you to resize windows etc.
|
||||
|
||||
After it starts, the webclient 'calls home' and spins up a
|
||||
[websocket](https://en.wikipedia.org/wiki/WebSocket) link to the Evennia Portal - this
|
||||
is how all data is then exchanged. So after the initial loading of the
|
||||
webclient page, the above sequence doesn't happen again until close the tab and
|
||||
come back or you reload it manually in your browser.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,209 @@
|
|||
# Game Website
|
||||
|
||||
When Evennia starts it will also start a [Webserver](Webserver) as part of the [Server](Portal-And-Server) process. This uses Django to serve a simple but functional default game website.
|
||||
When Evennia starts it will also start a [Webserver](Webserver) as part of the
|
||||
[Server](Portal-And-Server) process. This uses Django to serve a simple but
|
||||
functional default game website. With the default setup, open your browser to
|
||||
`localhost:4001` or `127.0.0.1:4001` to see it.
|
||||
|
||||
With the default setup, open your browser to `localhost:4001` or `127.0.0.1:4001` to see it.
|
||||
The website allows existing players to log in using an account-name and
|
||||
password they previously used to register with the game. If a user logs in with
|
||||
the [Webclient](Webclient) they will also log into the website and vice-versa.
|
||||
So if you are logged into the website, opening the webclient will automatically
|
||||
log you into the game as that account.
|
||||
|
||||
The default website allows you to
|
||||
The default website shows a "Welcome!" page with a few links to useful
|
||||
resources. It also shows some statistics about how many players are currently
|
||||
connected.
|
||||
|
||||
In the top menu you can find
|
||||
- Home - Get back to front page.
|
||||
- Document - A link to the latest stable Evennia documentation.
|
||||
- Characters - This is a demo of connecting in-game characters to the website.
|
||||
It will display a list of all entities of the
|
||||
_typeclasses.characters.Character` typeclass and allow you to view their
|
||||
description with an optional image. The list is only available to logged-in
|
||||
users.
|
||||
- Channels - This is a demo of connecting in-game chats to the website. It will
|
||||
show a list of all channels available to you and allow you to view the latest
|
||||
discussions. Most channels require logging in, but the `Public` channel can
|
||||
also be viewed by non-loggedin users.
|
||||
- Help - This ties the in-game [Help system](Help-System) to the website. All
|
||||
database-based help entries that are publicly available or accessible to your
|
||||
account can be read. This is a good way to present a body of help for people
|
||||
to read outside of the game.
|
||||
- Play Online - This opens the [Webclient](Webclient) in the browser.
|
||||
|
||||
|
||||
## Modifying the default Website
|
||||
|
||||
You can modify and override all aspects of the web site from your game dir.
|
||||
You'll mostly be doing so in your settings file
|
||||
(`mygame/server/conf/settings.py` and in the gamedir's `web/folder`
|
||||
(`mygame/web/` if your game folder is `mygame/`).
|
||||
|
||||
As explained on the [Webserver](Webserver) page, the process for getting a web
|
||||
page is
|
||||
|
||||
1. Web browser sends HTTP request to server with an URL
|
||||
2. `urls.py` uses regex to match that URL to a _view_ (a Python function or callable class).
|
||||
3. The correct Python view is loaded and executes.
|
||||
4. The view pulls in a _template_, a HTML document with placeholder markers in it,
|
||||
and fills those in as needed (it may also use a _form_ to customize user-input in the same way).
|
||||
A HTML page may also in turn point to static resources (usually CSS, sometimes images etc).
|
||||
5. The rendered HTML page is returned to the browser as a HTTP response. If
|
||||
the HTML page requires static resources are requested, the browser will
|
||||
fetch those separately before displaying it to the user.
|
||||
|
||||
If you look at the [evennia/web/](github:develop/evennia/web) directory you'll find the following
|
||||
structure (leaving out stuff not relevant to the website):
|
||||
|
||||
```
|
||||
evennia/web/
|
||||
...
|
||||
static/
|
||||
website/
|
||||
css/
|
||||
(css style files)
|
||||
images/
|
||||
(images to show)
|
||||
|
||||
templates/
|
||||
website/
|
||||
(html files)
|
||||
|
||||
website/
|
||||
urls.py
|
||||
views/
|
||||
(all python files related to website)
|
||||
|
||||
urls.py
|
||||
|
||||
```
|
||||
|
||||
The top-level `web/urls.py` file 'includes' the `web/website/urls.py` file -
|
||||
that way all the website-related url-handling is kept in the same place.
|
||||
|
||||
This is the layout of the `mygame/web/` folder relevant for the website:
|
||||
|
||||
```
|
||||
mygame/web/
|
||||
...
|
||||
static/
|
||||
website/
|
||||
css/
|
||||
images/
|
||||
|
||||
templates/
|
||||
website/
|
||||
|
||||
website/
|
||||
urls.py
|
||||
views/
|
||||
|
||||
urls.py
|
||||
|
||||
```
|
||||
|
||||
```versionchanged:: 1.0
|
||||
|
||||
Game folders created with older versions of Evennia will lack most of this
|
||||
convenient `mygame/web/` layout. If you use a game dir from an older version,
|
||||
you should copy over the missing `evennia/game_template/web/` folders from
|
||||
there, as well as the main urls.py file.
|
||||
|
||||
```
|
||||
|
||||
As you can see, the `mygame/web/` folder is a copy of the `evennia/web/` folder
|
||||
structure except the `mygame` folders are mostly empty.
|
||||
|
||||
For static- and template-files, Evennia will _first_
|
||||
look in `mygame/static` and `mygame/templates` before going to the default
|
||||
locations in `evennia/web/`. So override these resources, you just need to put
|
||||
a file with the same name in the right spot under `mygame/web/` (and then
|
||||
reload the server). Easiest is often to copy the original over and modify it.
|
||||
|
||||
Overridden views (Python modules) also need an additional tweak to the
|
||||
`website/urls.py` file - you must make sure to repoint the url to the new
|
||||
version rather than it using the original.
|
||||
|
||||
### Title and blurb
|
||||
|
||||
The website's title and blurb are simply changed by tweaking
|
||||
`settings.SERVERNAME` and `settings.GAME_SLOGAN`. Your settings file is in
|
||||
`mygame/server/conf/settings.py`, just change `SERVERNAME = "My Awesome Game"`
|
||||
and add `GAME_SLOGAN = "The best game in the world"` or something.
|
||||
|
||||
### Logo
|
||||
|
||||
The Evennia googly-eyed snake logo is probably not what you want for your game.
|
||||
The template looks for a file `web/static/website/images/evennia_logo.png`. Just
|
||||
plop your own PNG logo (64x64 pixels large) in there and name it the same.
|
||||
|
||||
### Index page
|
||||
|
||||
This is the front page of the website (the 'index' in HTML parlance).
|
||||
|
||||
#### Index HTML template
|
||||
|
||||
The frontpage template is found in
|
||||
`evennia/web/templates/website/index.html`. Just copy this to the equivalent place in
|
||||
`mygame/web/`. Modify it there and reload the server to see your changes.
|
||||
|
||||
Django templates has a few special features that separate them from normal HTML
|
||||
documents - they contain a special templating language marked with `{% ... %}` and
|
||||
`{{ ... }}`.
|
||||
|
||||
Some important things to know:
|
||||
|
||||
- `{% extends "base.html" %}` - This is equivalent to a Python
|
||||
`from othermodule import *` statement, but for templates. It allows a given template
|
||||
to use everything from the imported (extended) template, but also to override anything
|
||||
it wants to change. This makes it easy to keep all pages looking the same and avoids
|
||||
a lot of boiler plate.
|
||||
- `{% block blockname %}...{% endblock %}` - Blocks are inheritable, named pieces of code
|
||||
that are modified in one place and then used elsewhere. This works a bit in reverse to
|
||||
normal inheritance, because it's commonly in such a way that `base.html` defines an empty
|
||||
block, let's say `contents`: `{% block contents %}{% endblock %}` but makes sure to put
|
||||
that _in the right place_, say in the main body, next to the sidebar etc. Then each page
|
||||
does `{% extends "base.html %"}` and makes their own `{% block contents} <actual content> {% endblock %}`.
|
||||
Their `contents` block will now override the empty one in `base.html` and appear in the right
|
||||
place in the document, without the extending template having to specifying everything else
|
||||
around it!
|
||||
- `{{ ... }}` are 'slots' usually embedded inside HTML tags or content. They reference a
|
||||
_context_ (basically a dict) that the Python _view_ makes available to it.
|
||||
Keys on the context are accessed with dot-notation, so if you provide a
|
||||
context `{"stats": {"hp": 10, "mp": 5}}` to your template, you could access
|
||||
that as `{{ stats.hp }}` to display `10` at that location to display `10` at
|
||||
that location.
|
||||
|
||||
|
||||
This allows for template inheritance (making it easier to make all
|
||||
pages look the same without rewriting the same thing over and over)
|
||||
|
||||
There's a lot more information to be found in the [Django template language documentation](https://docs.djangoproject.com/en/3.2/ref/templates/language/).
|
||||
|
||||
#### Index View
|
||||
|
||||
To find where the index view is found, we look in `evennia/web/website/urls.py`. Here
|
||||
we find the following line:
|
||||
|
||||
This is found in `evennia/web/website/views/index.py`. If you don't know
|
||||
|
||||
The frontpage view is a class `EvenniaIndexView`. This is a [Django class-based view](https://docs.djangoproject.com/en/3.2/topics/class-based-views/).
|
||||
It's a little less visible what happens in a class-based view than in a function (since
|
||||
the class implements a lot of functionality as methods), but it's powerful and
|
||||
much easier to extend/modify.
|
||||
|
||||
The class property `template_name` sets the location of the template used under
|
||||
the `templates/` folder. So `website/index.html` points to
|
||||
`web/templates/website/index.html` (as we already explored above.
|
||||
|
||||
The `get_context_data` is a convenient method for providing the context for the
|
||||
template. In the index-page's case we want the game stats (number of recent
|
||||
players etc). These are then made available to use in `{{ ... }}` slots in the
|
||||
template as described in the previous section.
|
||||
|
||||
### Other website pages
|
||||
|
||||
The other sub pages are handled in the same way - copy the template or static
|
||||
resource to the right place
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue