Commit | Line | Data |
---|---|---|
473a4431 CAW |
1 | .. MediaGoblin Documentation |
2 | ||
3 | Written in 2011, 2012 by MediaGoblin contributors | |
4 | ||
5 | To the extent possible under law, the author(s) have dedicated all | |
6 | copyright and related and neighboring rights to this software to | |
7 | the public domain worldwide. This software is distributed without | |
8 | any warranty. | |
9 | ||
10 | You should have received a copy of the CC0 Public Domain | |
11 | Dedication along with this software. If not, see | |
12 | <http://creativecommons.org/publicdomain/zero/1.0/>. | |
13 | ||
917d4663 | 14 | .. _theming-chapter: |
6a338d8e | 15 | |
917d4663 WKG |
16 | ===================== |
17 | Theming MediaGoblin | |
18 | ===================== | |
5a40e1ec | 19 | |
e6aaaa96 CAW |
20 | We try to provide a nice theme for MediaGoblin by default. But of |
21 | course, you might want something different! Maybe you want something | |
22 | more light and colorful, or maybe you want something specifically | |
23 | tailored to your organization. Have no fear, MediaGoblin has theming | |
24 | support! This guide should walk you through installing and making themes. | |
25 | ||
26 | ||
04b24107 CAW |
27 | Installing a theme |
28 | ------------------ | |
29 | ||
30 | Installing the archive | |
31 | ====================== | |
32 | ||
33 | Say you have a theme archive such as goblincities.tar.gz. You want to | |
34 | install this theme! Don't worry, it's fairly painless. | |
35 | ||
36 | Simply cd to the "install directory" for themes (by default, | |
37 | ./user_dev/themes/ relative to the mediagoblin install directory... to | |
38 | configure these things, see the next section), move the archive there, | |
39 | and decompress. | |
40 | ||
41 | tar xvfz goblincities.tar.gz | |
42 | ||
43 | Next, open up your mediagoblin configuration file (probably | |
44 | mediagoblin_local.ini) and set the theme name: | |
45 | ||
46 | [mediagoblin] | |
47 | # ... | |
48 | theme = goblincities | |
49 | ||
50 | Finally, "link the assets" so that they can be served by your web | |
51 | server. | |
52 | ||
53 | ./bin/gmg theme assetlink | |
54 | ||
55 | Note, if you ever change the current theme in your config file, you | |
56 | should re-run the above command! | |
57 | ||
58 | (In the near future this should be even easier ;)) | |
59 | ||
60 | .. In the future, this might look more like: | |
61 | .. Installing a theme in MediaGoblin is fairly easy! Assuming you | |
62 | .. already have a theme package, just do this: | |
63 | ||
64 | .. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz | |
65 | ||
66 | .. This would install the theme, set it as current, and symlink its | |
67 | .. assets. | |
68 | ||
69 | ||
70 | Set up your webserver to serve theme assets | |
71 | =========================================== | |
72 | ||
73 | Section to be written, ask on #mediagoblin in irc.freenode.net in the | |
74 | meanwhile ;) | |
75 | ||
76 | Configuring where things go | |
77 | =========================== | |
78 | ||
79 | By default, MediaGoblin's install directory for themes is | |
80 | ./user_dev/themes/ (relative to the MediaGoblin checkout or base | |
81 | config file.) However, you can change this location easily. In your | |
82 | mediagoblin config file, under the section [mediagoblin] set the | |
83 | following parameter: | |
84 | ||
85 | [mediagoblin] | |
86 | # ... other parameters go here ... | |
87 | theme_install_dir = /path/to/themes/ | |
88 | ||
89 | Other variables you may consider setting: | |
90 | ||
91 | - theme_web_path: when theme-specific assets are specified, this is | |
92 | where MediaGoblin will set the urls. By default this is | |
93 | "/theme_static/" so in the case that your theme was trying to | |
94 | access its file "images/shiny_button.png" MediaGoblin would link | |
95 | to /theme_static/images/shiny_button.png | |
96 | - theme_linked_assets_dir: Your web server needs to serve the theme | |
97 | files out of some directory, and MediaGoblin will symlink the | |
98 | current theme's assets here. (See "Linking assets" in the theme | |
99 | install section) | |
100 | ||
101 | ||
e6aaaa96 CAW |
102 | Making a theme |
103 | -------------- | |
104 | ||
e6aaaa96 CAW |
105 | Okay, so a theme layout is pretty simple. Let's assume we're making a |
106 | theme for an instance about hedgehogs! We'll call this the | |
107 | "hedgehogified" theme. | |
108 | ||
04b24107 CAW |
109 | Change to where your theme_install_dir is set to (by default, |
110 | ./user_dev/themes/ ... make those directories if necessary and | |
111 | otherwise adjust if necessary) | |
112 | ||
e6aaaa96 CAW |
113 | hedgehogified/ |
114 | |- theme.cfg # configuration file for this theme | |
115 | |- templates/ # override templates | |
116 | | '- mediagoblin/ | |
117 | | |- base.html # overriding mediagoblin/base.html | |
118 | | '- root.html # overriding mediagoblin/root.html | |
119 | '- assets/ | |
120 | | '- images/ | |
121 | | | |- im_a_hedgehog.png # hedgehog-containing image used by theme | |
122 | | | '- custom_logo.png # your theme's custom logo | |
123 | | '- css/ | |
124 | | '- hedgehog.css # your site's hedgehog-specific css | |
125 | |- README.txt # Optionally, a readme file (not required) | |
126 | |- AGPLv3.txt # AGPL license file for your theme. (good practice) | |
04b24107 | 127 | '- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!] |
e6aaaa96 CAW |
128 | |
129 | The top level directory of your theme should be the symbolic name for | |
130 | your theme. This is the name that users will use to refer to activate | |
131 | your theme. | |
132 | ||
133 | It's important to note that templates based on MediaGoblin's code | |
134 | should be released as AGPLv3 (or later), like MediaGoblin's code | |
135 | itself. However, all the rest of your assets are up to you. In this | |
136 | case, we are waiving our copyright for images and CSS into the public | |
137 | domain via CC0 (as MediaGoblin does) but do what's appropriate to you. | |
138 | ||
139 | The config file | |
04b24107 | 140 | =============== |
e6aaaa96 | 141 | |
04b24107 | 142 | The config file is not presently strictly required, though it is nice to have. |
e6aaaa96 CAW |
143 | Only a few things need to go in here. |
144 | ||
145 | [theme] | |
04b24107 | 146 | name = Hedgehog-ification |
e6aaaa96 CAW |
147 | description = For hedgehog lovers ONLY |
148 | licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 | |
149 | ||
04b24107 CAW |
150 | The name and description fields here are to give users an idea of what |
151 | your theme is about. For the moment, we don't have any listing | |
152 | directories or admin interface, so this probably isn't useful, but | |
153 | feel free to set it in anticipation of a more glorious future. | |
154 | ||
155 | Licensing field is likewise a textual description of the stuff here; | |
156 | it's recommended that you preserve the "AGPLv3 or later templates" and | |
157 | specify whatever is appropriate to your assets. | |
e6aaaa96 | 158 | |
e6aaaa96 CAW |
159 | |
160 | Templates | |
04b24107 | 161 | ========= |
e6aaaa96 | 162 | |
04b24107 CAW |
163 | Your template directory is where you can put any override and custom |
164 | templates for MediaGoblin. | |
e6aaaa96 | 165 | |
04b24107 CAW |
166 | These follow the general MediaGoblin theming layout, which means that |
167 | the MediaGoblin core templates are all kept under the ./mediagoblin/ | |
168 | prefix directory. | |
e6aaaa96 | 169 | |
04b24107 CAW |
170 | You can copy files right out of MediaGoblin core and modify them in |
171 | this matter if you wish. | |
e6aaaa96 | 172 | |
04b24107 CAW |
173 | To fit with best licensing form, you should either preserve the |
174 | MediaGoblin copyright header borrowing from a MediaGoblin template, or | |
175 | you may include one like the following if a new file: | |
e6aaaa96 | 176 | |
04b24107 CAW |
177 | {# |
178 | # [YOUR THEME], a MediaGoblin theme | |
179 | # Copyright (C) [YEAR] [YOUR NAME] | |
180 | # | |
181 | # This program is free software: you can redistribute it and/or modify | |
182 | # it under the terms of the GNU Affero General Public License as published by | |
183 | # the Free Software Foundation, either version 3 of the License, or | |
184 | # (at your option) any later version. | |
185 | # | |
186 | # This program is distributed in the hope that it will be useful, | |
187 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | |
188 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
189 | # GNU Affero General Public License for more details. | |
190 | # | |
191 | # You should have received a copy of the GNU Affero General Public License | |
192 | # along with this program. If not, see <http://www.gnu.org/licenses/>. | |
193 | #} | |
e6aaaa96 | 194 | |
e6aaaa96 | 195 | |
04b24107 CAW |
196 | Assets |
197 | ======= | |
e6aaaa96 | 198 | |
04b24107 CAW |
199 | Put any files, such as images, CSS, etc, that are specific to your |
200 | theme in here. | |
e6aaaa96 | 201 | |
04b24107 | 202 | You can reference these in your templates like so: |
e6aaaa96 | 203 | |
04b24107 | 204 | <img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" /> |
e6aaaa96 | 205 | |
04b24107 | 206 | This will tell MediaGoblin to reference this image from the current theme. |
e6aaaa96 | 207 | |
e6aaaa96 | 208 | |
04b24107 CAW |
209 | Licensing file(s) |
210 | ================= | |
211 | ||
212 | You should include AGPLv3.txt with your theme as this is required for | |
213 | the assets. You can copy this from mediagoblin/licenses/ | |
214 | ||
215 | In the above example, we also use CC0 to waive our copyrights to | |
216 | images and css, so we also included CC0_1.0.txt | |
217 | ||
218 | ||
219 | A README.txt file | |
220 | ================= | |
221 | ||
222 | A readme file is not strictly required, but probably a good idea. You | |
223 | can put whatever in here, but restating the license choice clearly is | |
224 | probably a good idea. | |
225 | ||
e6aaaa96 | 226 | |
62157a89 CAW |
227 | Simple theming by adding CSS |
228 | ============================ | |
229 | ||
230 | Many themes won't require anything other than the ability to override | |
231 | some of MediaGoblin's core css. Thankfully, doing so is easy if you | |
232 | combine the above steps! | |
233 | ||
234 | In your theme, do the following (make sure you make the necessary | |
235 | directories and cd to your theme's directory first): | |
236 | ||
237 | $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/ | |
238 | ||
239 | Great, now open that file and add something like this at the end: | |
240 | ||
241 | <link rel="stylesheet" type="text/css" | |
242 | href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/> | |
243 | ||
244 | You can name the css file whatever you like. Now make the directory | |
245 | for assets/css/ and add the file assets/css/theme.css | |
246 | ||
247 | You can now put custom CSS files in here and any CSS you add will | |
248 | override default MediaGoblin CSS. | |
249 | ||
250 | ||
04b24107 CAW |
251 | Packaging it up! |
252 | ================ | |
e6aaaa96 | 253 | |
04b24107 | 254 | Packaging a theme is really easy. It's just a matter of making an archive! |
e6aaaa96 | 255 | |
04b24107 | 256 | Change to the installed themes directory and run the following: |
e6aaaa96 | 257 | |
04b24107 | 258 | tar cvfz yourtheme.tar.gz yourtheme |
e6aaaa96 | 259 | |
04b24107 | 260 | Where "yourtheme" is replaced with your theme name. |
e6aaaa96 | 261 | |
04b24107 | 262 | That's it! |