Commit | Line | Data |
---|---|---|
7a690a5a CAW |
1 | .. _flatpagesfile-chapter: |
2 | ||
4bd65f69 WKG |
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 | ||
54b42ee5 WKG |
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. | |
4bd65f69 | 52 | |
54b42ee5 WKG |
53 | It should be "unique" and it should be alphanumeric characters and |
54 | hyphens. I wouldn't put spaces in there. | |
4bd65f69 | 55 | |
54b42ee5 | 56 | Examples: ``flatpages-about``, ``about-view``, ``contact-view``, ... |
4bd65f69 | 57 | |
54b42ee5 | 58 | The value has two parts separated by commas: |
4bd65f69 | 59 | |
54b42ee5 | 60 | 1. **route path**: This is the url that this route matches. |
4bd65f69 WKG |
61 | |
62 | Examples: ``/about``, ``/contact``, ``/pages/about``, ... | |
63 | ||
54b42ee5 WKG |
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/>`_. | |
4bd65f69 WKG |
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 | ||
54b42ee5 | 77 | 2. **template**: The template to use for this url. The template is in |
4bd65f69 WKG |
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]] | |
54b42ee5 WKG |
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. | |
4bd65f69 WKG |
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 | ||
54b42ee5 WKG |
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. |