| 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. |