Usage#
Once installed you can configure some static pages to mount on urls in different ways.
The basic way#
This is the simpliest method to configure your static pages, more appropriated when for basic needing: each page has its own template with a basic name and all pages are in the same path directory.
So you got page templates in directory templates/staticpages/
:
templates/
└── staticpages
├── bar.html
├── foo.html
└── index.html
Note
Eventually if you need to store your templates in another directory, like
templates/prototypes/samples/
you can define it from settings:
STATICPAGES_DEFAULT_TEMPLATEPATH = "prototypes/samples"
In your settings, you will just have to list their template names:
STATICPAGES = [
"bar",
"foo",
"index",
]
And finally mount them in your root urls.py
like so:
from staticpages.loader import StaticpagesLoader
staticpages_loader = StaticpagesLoader()
urlpatterns = [
*staticpages_loader.build_urls(),
]
Your pages will be reachable on urls /
, /foo/
and /bar/
.
Note
Note how index
item have been resolved to /
and not /index/
, this is
from default behavior which assert than index
is an index page, you can change
this from settings STATICPAGES_INDEX_NAME
.
The explicit way#
The basic way is the quickest method to do but if you need to manage multiple pages from various template directories or with specific path or different template names, you will need to define a page with a dictionnary of options.
Options format#
Here is a sample of all possible options for a page:
{
"extra": "anything anykind",
"name": "foo",
"path": "foo/",
"re_path": r"foo/$",
"template": "foo",
"template_path": "foo.html",
}
Specifications#
extra
Extra data to pass to view in its options.
name
Optional page url name used to mount url, it can be used to reverse it to page url with Django function
django.urls.reverse
.This option becomes required if
template_path
option has been given.It must be a valid url name so no space or any special characters, only letters, numbers,
-
and_
. If you need to pass a display name to use in template, use theextra
option to do so.path
Optional page url path that will be used to mount page on urls. So if
foo/
is given and you mount your pages on root urls, the page will be reachable from/foo/
.If not given, path will be resolved from template name suffixed by an ending slash.
re_path
Optional page url regex path. Works exactly like
path
but is marked as a regex path to be mounted with Django functionre_path()
instead ofpath()
.If this option is given
path
is ignored.template
Template name without any leading path and ending file extension suffix (aka:
foo
, notbar/foo.html
).If
template_path
is not given, this option is required. It will be used to resolvename
orpath
options if they are not given.template_path
Full relative template path. If
template
option is not given, this one is required.If this option is given the
name
option is required since we can not resolve correctly an url name from a real path. And also thetemplate
option will be ignored.Using this option is a way to explicitely define a full template path instead of
template
option magic.
Defining page with options#
So you got page templates in directory templates/staticpages/
:
templates/
└── staticpages
├── index.html
├── page.html
└── ping
└── pong.html
In your settings, you will define them like so:
STATICPAGES = [
"index",
{
"template": "page",
},
{
"template_path": "page.html",
"name": "foo",
},
{
"template_path": "ping/pong.html",
"name": "ping-pong",
"extra": "Ping-pong is magic!",
},
]
Note
Note how you can mix both template name (a string) and option formats (dictionnary) in the same list. Because sometime you may have only a single page which needs options and vice versa.
And finally mount them in your root urls.py
like so:
from staticpages.loader import StaticpagesLoader
staticpages_loader = StaticpagesLoader()
urlpatterns = [
*staticpages_loader.build_urls(),
]
Resulting in:
The first item will be the index using
index.html
template and mounted on/
url;The second item is for demonstration purpose, it works exactly like the string format and will results to an url
/page/
using thepage.html
template;The third will results to an url
/foo/
using thepage.html
template;The fourth will results to an url
/ping-pong/
using theping/pong.html
template which will have context variablepage_extra
with valuePing-pong is magic!
;
Loader options#
If you need to load different static pages from different applications, you won’t be able to manage them all from the settings.
To resolve this situation, Loader accept some arguments to override settings, see Loader documentation for details. Obviously you will need to use different loader instance for each application to be able to provided different arguments.
Static page template#
There is no ready to use template shipped with application since it is very basic without any specific logic, you just have some template variables available that you can use like you want.
But here is a basic sample:
<!DOCTYPE html>
<head>{% spaceless %}
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{% block head_title %}Staticpages sample{% endblock head_title %}</title>
{% endspaceless %}
</head>
<body>{% spaceless %}
{% block content %}
{% comment %}Make a basic title using page name{% endcomment %}
<h1>Sample {{ page_options.name }}</h1>
{% comment %}Make a basic paragraph using page url name{% endcomment %}
<p>{{ page_options.urlname }}</p>
{% comment %}Use 'is_index' value as condition to list pages or not{% endcomment %}
{% if page_options.is_index %}
<ul class="menu">
{% for item in staticpages %}
{% comment %}Do not list index page in the menu{% endcomment %}
{% if not item.is_index %}
<li>{{ item.name }}</li>
{% endif %}
{% endfor %}
</ul>
{% endif %}
{% comment %}Display 'extra' content if not empty{% endcomment %}
{% if page_options.extra %}
<div class="extra">{{ page_options.extra }}</div>
{% endif %}
{% endblock content %}
{% endspaceless %}</body>
</html>
Template context variables#
The variable page_options
will contains the following items.
- name
The page name which is ever the template name or the url name depending provided options.
- urlname
The url name with possible prefix depending settings and loader arguments.
- template
The full template path.
- path
The url path or url regex path depending provided options.
- is_regex
A boolean to indicate if
path
is a regex path (True) or not (False)- is_index
A boolean to mark a page as an index page. At this stage it only have an informational meaning which can be used in a template to distinguish a page from non index ones.
- extra
Some extra data you may want to pass to template. You can put anything you need in this variable.
There will be also a variable staticpages
that is a list of all static pages
options related to a same loader instance (multiple loader instances won’t share all
static pages).