mediagoblin/plugins/flatpagesfile/README.rst

   1 .. _flatpagesfile-chapter:
   2
   3 ======================
   4  flatpagesfile plugin
   5 ======================
   6
   7 This is the flatpages file plugin. It allows you to add pages to your
   8 MediaGoblin instance which are not generated from user content. For
   9 example, this is useful for these pages:
  10
  11 * About this site
  12 * Terms of service
  13 * Privacy policy
  14 * How to get an account here
  15 * ...
  16
  17
  18 How to configure
  19 ================
  20
  21 Add the following to your MediaGoblin .ini file in the ``[plugins]``
  22 section::
  23
  24     [[mediagoblin.plugins.flatpagesfile]]
  25
  26
  27 This tells MediaGoblin to load the flatpagesfile plugin. This is the
  28 subsection that you'll do all flatpagesfile plugin configuration in.
  29
  30
  31 How to add pages
  32 ================
  33
  34 To add a new page to your site, you need to do two things:
  35
  36 1. add a route to the MediaGoblin .ini file in the flatpagesfile
  37    subsection
  38
  39 2. write a template that will get served when that route is requested
  40
  41
  42 Routes
  43 ------
  44
  45 First, let's talk about the route.
  46
  47 A route is a key/value in your configuration file.
  48
  49 The key for the route is the route name You can use this with `url()`
  50 in templates to have MediaGoblin automatically build the urls for
  51 you. It's very handy.
  52
  53 It should be "unique" and it should be alphanumeric characters and
  54 hyphens. I wouldn't put spaces in there.
  55
  56 Examples: ``flatpages-about``, ``about-view``, ``contact-view``, ...
  57
  58 The value has two parts separated by commas:
  59
  60 1. **route path**: This is the URL that this route matches.
  61
  62    Examples: ``/about``, ``/contact``, ``/pages/about``, ...
  63
  64    You can do anything with this that you can do with the routepath
  65    parameter of `routes.Route`. For more details, see `the routes
  66    documentation <http://routes.readthedocs.org/en/latest/>`_.
  67
  68    Example: ``/siteadmin/{adminname:\w+}``
  69
  70    .. Note::
  71
  72       If you're doing something fancy, enclose the route in single
  73       quotes.
  74
  75       For example: ``'/siteadmin/{adminname:\w+}'``
  76
  77 2. **template**: The template to use for this URL. The template is in
  78    the flatpagesfile template directory, so you just need to specify
  79    the file name.
  80
  81    Like with other templates, if it's an HTML file, it's good to use
  82    the ``.html`` extensions.
  83
  84    Examples: ``index.html``, ``about.html``, ``contact.html``, ...
  85
  86
  87 Here's an example configuration that adds two flat pages: one for an
  88 "About this site" page and one for a "Terms of service" page::
  89
  90     [[mediagoblin.plugins.flatpagesfile]]
  91     about-view = '/about', about.html
  92     terms-view = '/terms', terms.html
  93
  94
  95 .. Note::
  96
  97    The order in which you define the routes in the config file is the
  98    order in which they're checked for incoming requests.
  99
 100
 101 Templates
 102 ---------
 103
 104 To add pages, you must edit template files on the file system in your
 105 `local_templates` directory.
 106
 107 The directory structure looks kind of like this::
 108
 109     local_templates
 110     |- flatpagesfile
 111        |- flatpage1.html
 112        |- flatpage2.html
 113        |- ...
 114
 115
 116 The ``.html`` file contains the content of your page. It's just a
 117 template like all the other templates you have.
 118
 119 Here's an example that extends the `flatpagesfile/base.html`
 120 template::
 121
 122    {% extends "flatpagesfile/base.html" %}
 123    {% block mediagoblin_content %}
 124    <h1>About this site</h1>
 125    <p>
 126      This site is a MediaGoblin instance set up to host media for
 127      me, my family and my friends.
 128    </p>
 129    {% endblock %}
 130
 131
 132 .. Note::
 133
 134    If you have a bunch of flatpages that kind of look like one
 135    another, take advantage of Jinja2 template extending and create a
 136    base template that the others extend.
 137
 138
 139 Recipes
 140 =======
 141
 142 URL variables
 143 -------------
 144
 145 You can handle URLs like ``/about/{name}`` and access the name that's
 146 passed in in the template.
 147
 148 Sample route::
 149
 150     about-page = '/about/{name}', about.html
 151
 152 Sample template::
 153
 154    {% extends "flatpagesfile/base.html" %}
 155    {% block mediagoblin_content %}
 156
 157    <h1>About page for {{ request.matchdict['name'] }}</h1>
 158
 159    {% endblock %}
 160
 161 See the `the routes documentation
 162 <http://routes.readthedocs.org/en/latest/>`_ for syntax details for
 163 the route. Values will end up in the ``request.matchdict`` dict.