Finish flatpagesplugin; add plugin docs
This commit is contained in:
Will Kahn-Greene
@@ -1,50 +0,0 @@
|
||||
========
|
||||
README
|
||||
========
|
||||
|
||||
This is the flatpages file plugin. It allows you to add pages to your
|
||||
MediaGoblin instance which are not generated from user content. For
|
||||
example, this is useful for these pages:
|
||||
|
||||
* About this site
|
||||
* Terms of service
|
||||
* Privacy policy
|
||||
* How to get an account here
|
||||
* ...
|
||||
|
||||
|
||||
How to add pages
|
||||
================
|
||||
|
||||
To add pages, you must edit template files on the file system in your
|
||||
`local_templates` directory.
|
||||
|
||||
The directory structure looks kind of like this::
|
||||
|
||||
local_templates
|
||||
|- flatpagesfile
|
||||
|- flatpage1.html
|
||||
|- flatpage2.html
|
||||
|- ...
|
||||
|
||||
|
||||
The ``.html`` file contains the content of your page. It's just a
|
||||
template like all the other templates you have.
|
||||
|
||||
Here's an example::
|
||||
|
||||
{% extends "flatpagesfile/base.html" %}
|
||||
{% block mediagoblin_content %}
|
||||
<h1>About this site</h1>
|
||||
<p>
|
||||
This site is a MediaGoblin instance set up to host media for
|
||||
me, my family and my friends.
|
||||
</p>
|
||||
{% endblock %}
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
If you have a bunch of flatpages that kind of look like one
|
||||
another, take advantage of Jinja2 template extending and create a
|
||||
base template that the others extend.
|
||||
132
mediagoblin/plugins/flatpagesfile/README.rst
Normal file
132
mediagoblin/plugins/flatpagesfile/README.rst
Normal file
@@ -0,0 +1,132 @@
|
||||
======================
|
||||
flatpagesfile plugin
|
||||
======================
|
||||
|
||||
This is the flatpages file plugin. It allows you to add pages to your
|
||||
MediaGoblin instance which are not generated from user content. For
|
||||
example, this is useful for these pages:
|
||||
|
||||
* About this site
|
||||
* Terms of service
|
||||
* Privacy policy
|
||||
* How to get an account here
|
||||
* ...
|
||||
|
||||
|
||||
How to configure
|
||||
================
|
||||
|
||||
Add the following to your MediaGoblin .ini file in the ``[plugins]``
|
||||
section::
|
||||
|
||||
[[mediagoblin.plugins.flatpagesfile]]
|
||||
|
||||
|
||||
This tells MediaGoblin to load the flatpagesfile plugin. This is the
|
||||
subsection that you'll do all flatpagesfile plugin configuration in.
|
||||
|
||||
|
||||
How to add pages
|
||||
================
|
||||
|
||||
To add a new page to your site, you need to do two things:
|
||||
|
||||
1. add a route to the MediaGoblin .ini file in the flatpagesfile
|
||||
subsection
|
||||
|
||||
2. write a template that will get served when that route is requested
|
||||
|
||||
|
||||
Routes
|
||||
------
|
||||
|
||||
First, let's talk about the route.
|
||||
|
||||
A route is a key/value in your configuration file.
|
||||
|
||||
The key starts with ``path`` and then has a number after that. For
|
||||
example: ``path1``, ``path2``, ... ``path15``, ...
|
||||
|
||||
The value has three parts separated by commas:
|
||||
|
||||
1. **route name**: You can use this with `url()` in templates to have
|
||||
MediaGoblin automatically build the urls for you. It's very handy.
|
||||
|
||||
It should be "unique" and it should be alphanumeric characters and
|
||||
hyphens. I wouldn't put spaces in there.
|
||||
|
||||
Examples: ``flatpages-about``, ``about-view``, ``contact-view``, ...
|
||||
|
||||
2. **route path**: This is the url that this route matches.
|
||||
|
||||
Examples: ``/about``, ``/contact``, ``/pages/about``, ...
|
||||
|
||||
Technically, this is a regular expression and you can do anything
|
||||
with this that you can do with the routepath parameter of
|
||||
`routes.Route`. For more details, see `the routes documentation
|
||||
<http://routes.readthedocs.org/en/latest/>`_.
|
||||
|
||||
Example: ``/siteadmin/{adminname:\w+}``
|
||||
|
||||
.. Note::
|
||||
|
||||
If you're doing something fancy, enclose the route in single
|
||||
quotes.
|
||||
|
||||
For example: ``'/siteadmin/{adminname:\w+}'``
|
||||
|
||||
3. **template**: The template to use for this url. The template is in
|
||||
the flatpagesfile template directory, so you just need to specify
|
||||
the file name.
|
||||
|
||||
Like with other templates, if it's an HTML file, it's good to use
|
||||
the ``.html`` extensions.
|
||||
|
||||
Examples: ``index.html``, ``about.html``, ``contact.html``, ...
|
||||
|
||||
|
||||
Here's an example configuration that adds two flat pages: one for an
|
||||
"About this site" page and one for a "Terms of service" page::
|
||||
|
||||
[[mediagoblin.plugins.flatpagesfile]]
|
||||
page1 = about-view, '/about', about.html
|
||||
page2 = terms-view, '/terms', terms.html
|
||||
|
||||
|
||||
Templates
|
||||
---------
|
||||
|
||||
To add pages, you must edit template files on the file system in your
|
||||
`local_templates` directory.
|
||||
|
||||
The directory structure looks kind of like this::
|
||||
|
||||
local_templates
|
||||
|- flatpagesfile
|
||||
|- flatpage1.html
|
||||
|- flatpage2.html
|
||||
|- ...
|
||||
|
||||
|
||||
The ``.html`` file contains the content of your page. It's just a
|
||||
template like all the other templates you have.
|
||||
|
||||
Here's an example that extends the `flatpagesfile/base.html`
|
||||
template::
|
||||
|
||||
{% extends "flatpagesfile/base.html" %}
|
||||
{% block mediagoblin_content %}
|
||||
<h1>About this site</h1>
|
||||
<p>
|
||||
This site is a MediaGoblin instance set up to host media for
|
||||
me, my family and my friends.
|
||||
</p>
|
||||
{% endblock %}
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
If you have a bunch of flatpages that kind of look like one
|
||||
another, take advantage of Jinja2 template extending and create a
|
||||
base template that the others extend.
|
||||
|
||||
@@ -17,7 +17,10 @@
|
||||
import logging
|
||||
import os
|
||||
|
||||
from routes.route import Route
|
||||
|
||||
from mediagoblin.tools import pluginapi
|
||||
from mediagoblin.tools.response import render_to_response
|
||||
|
||||
|
||||
PLUGIN_DIR = os.path.dirname(__file__)
|
||||
@@ -26,16 +29,45 @@ PLUGIN_DIR = os.path.dirname(__file__)
|
||||
_log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class FlatpagesPlugin(pluginapi.Plugin):
|
||||
def flatpage_handler(template):
|
||||
"""Flatpage view generator
|
||||
|
||||
Given a template, generates the controller function for handling that
|
||||
route.
|
||||
|
||||
"""
|
||||
def _flatpage_handler(request, *args, **kwargs):
|
||||
return render_to_response(
|
||||
request, 'flatpagesfile/%s' % template,
|
||||
{'args': args, 'kwargs': kwargs})
|
||||
return _flatpage_handler
|
||||
|
||||
|
||||
class FlatpagesFilePlugin(pluginapi.Plugin):
|
||||
"""
|
||||
This is the flatpages plugin class. See the README for how to use
|
||||
flatpages.
|
||||
"""
|
||||
def __init__(self):
|
||||
self._setup_plugin_called = 0
|
||||
|
||||
def setup_plugin(self):
|
||||
self.config = pluginapi.get_config('mediagoblin.plugins.flatpagesfile')
|
||||
|
||||
_log.info('Setting up flatpages....')
|
||||
_log.info('Setting up flatpagesfile....')
|
||||
|
||||
# Register the template path.
|
||||
pluginapi.register_template_path(os.path.join(PLUGIN_DIR, 'templates'))
|
||||
|
||||
# Set up and register routes.
|
||||
pages = [(int(key.replace('page', '')), val)
|
||||
for key, val in self.config.items()
|
||||
if key.startswith('page')]
|
||||
|
||||
pages = [mapping for index, mapping in sorted(pages)]
|
||||
routes = []
|
||||
for name, url, template in pages:
|
||||
name = 'flatpagesfile.%s' % name.strip()
|
||||
controller = flatpage_handler(template)
|
||||
routes.append(
|
||||
Route(name, url, controller=controller))
|
||||
|
||||
pluginapi.register_routes(routes)
|
||||
_log.info('Done setting up flatpagesfile!')
|
||||
|
||||
Reference in New Issue
Block a user