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

Resolve merge conflicts

Browse source
This commit is contained in:
Griatch 2022-09-24 18:33:32 +02:00
commit 79d16b9ead
1 changed files with 91 additions and 113 deletions
Download patch file Download diff file Expand all files Collapse all files

204
docs/source/Howtos/Add-a-wiki-on-your-website.md
View file

@ -1,8 +1,7 @@
# Add a wiki on your website # Add a wiki on your website
**Before doing this tutorial you will probably want to read the intro in
**Before doing this tutorial you will probably want to read the intro in [Basic Web tutorial](Beginner-Tutorial/Part5/Web-Tutorial.md).** Reading the three first parts of the
[Basic Web tutorial](Beginner-Tutorial/Part5/Web-Tutorial.md).** Reading the three first parts of the
[Django tutorial](https://docs.djangoproject.com/en/1.9/intro/tutorial01/) might help as well. [Django tutorial](https://docs.djangoproject.com/en/1.9/intro/tutorial01/) might help as well.
This tutorial will provide a step-by-step process to installing a wiki on your website. This tutorial will provide a step-by-step process to installing a wiki on your website.
@ -10,13 +9,8 @@ Fortunately, you don't have to create the features manually, since it has been d
we can integrate their work quite easily with Django. I have decided to focus on we can integrate their work quite easily with Django. I have decided to focus on
the [Django-wiki](https://django-wiki.readthedocs.io/). the [Django-wiki](https://django-wiki.readthedocs.io/).
> Note: this article has been updated for Evennia 0.9. If you're not yet using this version, be
careful, as the django wiki doesn't support Python 2 anymore. (Remove this note when enough time
has passed.)
The [Django-wiki](https://django-wiki.readthedocs.io/) offers a lot of features associated with The [Django-wiki](https://django-wiki.readthedocs.io/) offers a lot of features associated with
wikis, is wikis, is actively maintained (at this time, anyway), and isn't too difficult to install in Evennia. You can
actively maintained (at this time, anyway), and isn't too difficult to install in Evennia. You can
see a [demonstration of Django-wiki here](https://demo.django-wiki.org). see a [demonstration of Django-wiki here](https://demo.django-wiki.org).
## Basic installation ## Basic installation
@ -25,6 +19,8 @@ You should begin by shutting down the Evennia server if it is running. We will
alter the virtual environment just a bit. Open a terminal and activate your Python environment, the alter the virtual environment just a bit. Open a terminal and activate your Python environment, the
one you use to run the `evennia` command. one you use to run the `evennia` command.
If you used the default location from the Evennia installation instructions, it should be one of the following:
* On Linux: * On Linux:
``` ```
source evenv/bin/activate source evenv/bin/activate
@ -40,26 +36,15 @@ Install the wiki using pip:
pip install wiki pip install wiki
> Note: this will install the last version of Django wiki. Version >0.4 doesn't support Python 2, so
install wiki 0.3 if you haven't updated to Python 3 yet.
It might take some time, the Django-wiki having some dependencies. It might take some time, the Django-wiki having some dependencies.
### Adding the wiki in the settings ### Adding the wiki in the settings
You will need to add a few settings to have the wiki app on your website. Open your You will need to add a few settings to have the wiki app on your website. Open your
`server/conf/settings.py` file and add the following at the bottom (but before importing `server/conf/settings.py` file and add the following at the bottom (but before importing
`secret_settings`). Here's what you'll find in my own setting file (add the whole Django-wiki `secret_settings`). Here's an example of a settings file with the Django-wiki added:
section):
```python ```python
r"""
Evennia settings file.
...
"""
# Use the defaults from Evennia unless explicitly overridden # Use the defaults from Evennia unless explicitly overridden
from evennia.settings_default import * from evennia.settings_default import *
@ -98,65 +83,87 @@ except ImportError:
print("secret_settings.py file not found or failed to import.") print("secret_settings.py file not found or failed to import.")
``` ```
Everything in the section "Django-wiki settings" is what you'll need to include.
### Adding the new URLs ### Adding the new URLs
Next we need to add two URLs in our `web/urls.py` file. Open it and compare the following output: Next you will need to add two URLs to the file `web/urls.py`. You'll do that by modifying
you will need to add two URLs in `custom_patterns` and add one import line: `urlpatterns` to look something like this:
```python ```python
from django.conf.urls import url, include # add patterns
from django.urls import path # NEW! urlpatterns = [
# website
# default evenni a patterns path("", include("web.website.urls")),
from evennia.web.urls import urlpatterns # webclient
path("webclient/", include("web.webclient.urls")),
# eventual custom patterns # web admin
custom_patterns = [ path("admin/", include("web.admin.urls")),
# url(r'/desired/url/', view, name='example'), # wiki
url('notifications/', include('django_nyt.urls')), # NEW! path("wiki/", include("wiki.urls")),
url('wiki/', include('wiki.urls')), # NEW! path("notifications/", include("django_nyt.urls")),
] ]
# this is required by Django.
urlpatterns = custom_patterns + urlpatterns
``` ```
You will probably need to copy line 2, 10, and 11. Be sure to place them correctly, as shown in The last two lines are what you'll need to add.
the example above.
### Running migrations ### Running migrations
It's time to run the new migrations. The wiki app adds a few tables in our database. We'll need to Next you'll need to run migrations, since the wiki app adds a few tables in our database:
run:
evennia migrate evennia migrate
And that's it, you can start the server. If you go to http://localhost:4001/wiki , you should see
the wiki. Use your account's username and password to connect to it. That's how simple it is.
## Customizing privileges ### Initializing the wiki
A wiki can be a great collaborative tool, but who can see it? Who can modify it? Django-wiki comes Last step! Go ahead and start up your server again.
with a privilege system centered around four values per wiki page. The owner of an article can
always read and write in it (which is somewhat logical). The group of the article defines who can
read and who can write, if the user seeing the page belongs to this group. The topic of groups in
wiki pages will not be discussed here. A last setting determines which other user (that is, these
who aren't in the groups, and aren't the article's owner) can read and write. Each article has
these four settings (group read, group write, other read, other write). Depending on your purpose,
it might not be a good default choice, particularly if you have to remind every builder to keep the
pages private. Fortunately, Django-wiki gives us additional settings to customize who can read, and
who can write, a specific article.
These settings must be placed, as usual, in your `server/conf/settings.py` file. They take a evennia start
function as argument, said function (or callback) will be called with the article and the user.
Remember, a Django user, for us, is an account. So we could check lockstrings on them if needed. Once that's finished booting, go to your evennia website (e.g. http://localhost:4001 ) and log in
Here is a default setting to restrict the wiki: only builders can write in it, but anyone (including with your superuser account, if you aren't already. Then, go to your new wiki (e.g.
non-logged in users) can read it. The superuser has some additional privileges. http://localhost:4001/wiki ). It'll prompt you to create a starting page - put whatever you want,
you can change it later.
Congratulations! You're all done!
## Defining wiki permissions
A wiki is usually intended as a collaborative effort - but you probably still want to set
some rules about who is allowed to do what. Who can create new articles? Edit them? Delete
them? Etc.
The two simplest ways to do this are to use Django-wiki's group-based permissions
system - or, since this is an Evennia site, to define your own custom permission rules
tied to Evennia's permissions system in your settings file.
### Group permissions
The wiki itself controls reading/editing permissions per article. The creator of an article will
always have read/write permissions on that article. Additionally, the article will have Group-based
permissions and general permissions.
By default, Evennia's permission groups *won't* be recognized by the wiki, so you'll have to create your own.
Go to the Groups page of your game's Django admin panel (e.g. http://localhost:4001/admin/auth/group )
and add whichever permission groups you want for your wiki here.
***Note:*** *If you want to connect those groups to your game's permission levels, you'll need to modify the game to apply both to accounts.*
Once you've added those groups, they'll be usable in your wiki right away!
### Settings permissions
Django-wiki also allows you to bypass its article-based permissions with custom site-wide permissions
rules in your settings file. If you don't want to use the Group system, or if you want a simple
solution for connecting the Evennia permission levels to wiki access, this is the way to go.
Here's an example of a basic set-up that would go in your `settings.py` file:
```python ```python
# In server/conf/settings.py # In server/conf/settings.py
# ... # ...
# Custom methods to link wiki permissions to game perms
def is_superuser(article, user): def is_superuser(article, user):
"""Return True if user is a superuser, False otherwise.""" """Return True if user is a superuser, False otherwise."""
return not user.is_anonymous() and user.is_superuser return not user.is_anonymous() and user.is_superuser
@ -165,68 +172,39 @@ def is_builder(article, user):
"""Return True if user is a builder, False otherwise.""" """Return True if user is a builder, False otherwise."""
return not user.is_anonymous() and user.locks.check_lockstring(user, "perm(Builders)") return not user.is_anonymous() and user.locks.check_lockstring(user, "perm(Builders)")
def is_anyone(article, user): def is_player(article, user):
"""Return True even if the user is anonymous.""" """Return True if user is a builder, False otherwise."""
return True return not user.is_anonymous() and user.locks.check_lockstring(user, "perm(Players)")
# Who can create new groups and users from the wiki? # Create new users
WIKI_CAN_ADMIN = is_superuser WIKI_CAN_ADMIN = is_superuser
# Who can change owner and group membership?
# Change the owner and group for an article
WIKI_CAN_ASSIGN = is_superuser WIKI_CAN_ASSIGN = is_superuser
# Who can change group membership?
# Change the GROUP of an article, despite the name
WIKI_CAN_ASSIGN_OWNER = is_superuser WIKI_CAN_ASSIGN_OWNER = is_superuser
# Who can change read/write access to groups or others?
# Change read/write permissions on an article
WIKI_CAN_CHANGE_PERMISSIONS = is_superuser WIKI_CAN_CHANGE_PERMISSIONS = is_superuser
# Who can soft-delete an article?
# Mark an article as deleted
WIKI_CAN_DELETE = is_builder WIKI_CAN_DELETE = is_builder
# Who can lock an article and permanently delete it?
# Lock or permanently delete an article
WIKI_CAN_MODERATE = is_superuser WIKI_CAN_MODERATE = is_superuser
# Who can edit articles?
# Create or edit any pages
WIKI_CAN_WRITE = is_builder WIKI_CAN_WRITE = is_builder
# Who can read articles?
WIKI_CAN_READ = is_anyone # Read any pages
WIKI_CAN_READ = is_player
# Completely disallow editing and article creation when not logged in
WIKI_ANONYMOUS_WRITE = False
``` ```
Here, we have created three functions: one to return `True` if the user is the superuser, one to The permission functions can check anything you like on the accessing user, so long as the function
return `True` if the user is a builder, one to return `True` no matter what (this includes if the returns either True (they're allowed) or False (they're not).
user is anonymous, E.G. if it's not logged-in). We then change settings to allow either the
superuser or
each builder to moderate, read, write, delete, and more. You can, of course, add more functions,
adapting them to your need. This is just a demonstration.
Providing the `WIKI_CAN*...` settings will bypass the original permission system. The superuser For a full list of possible settings, you can check out [the django-wiki documentation](https://django-wiki.readthedocs.io/en/latest/settings.html).
could change permissions of an article, but still, only builders would be able to write it. If you
need something more custom, you will have to expand on the functions you use.
### Managing wiki pages from Evennia
Unfortunately, Django wiki doesn't provide a clear and clean entry point to read and write articles
from Evennia and it doesn't seem to be a very high priority. If you really need to keep Django wiki
and to create and manage wiki pages from your code, you can do so, but this article won't elaborate,
as this is somewhat more technical.
However, it is a good opportunity to present a small project that has been created more recently:
[evennia-wiki](https://github.com/vincent-lg/evennia-wiki) has been created to provide a simple
wiki, more tailored to Evennia and easier to connect. It doesn't, as yet, provide as many options
as does Django wiki, but it's perfectly usable:
- Pages have an inherent and much-easier to understand hierarchy based on URLs.
- Article permissions are connected to Evennia groups and are much easier to accommodate specific
requirements.
- Articles can easily be created, read or updated from the Evennia code itself.
- Markdown is fully-supported with a default integration to Bootstrap to look good on an Evennia
website. Tables and table of contents are supported as well as wiki links.
- The process to override wiki templates makes full use of the `template_overrides` directory.
However evennia-wiki doesn't yet support:
- Images in markdown and the uploading schema. If images are important to you, please consider
contributing to this new project.
- Modifying permissions on a per page/setting basis.
- Moving pages to new locations.
- Viewing page history.
Considering the list of features in Django wiki, obviously other things could be added to the list.
However, these features may be the most important and useful. Additional ones might not be that
necessary. If you're interested in supporting this little project, you are more than welcome to
[contribute to it](https://github.com/vincent-lg/evennia-wiki). Thanks!