docs/source/siteadmin/theming.rst

   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
  14 .. _theming-chapter:
  15
  16 =====================
  17  Theming MediaGoblin
  18 =====================
  19
  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
  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
 102 Making a theme
 103 --------------
 104
 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
 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
 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)
 127     '- CC0_1.0.txt                 # CC0 1.0 legalcode for the assets [if appropriate!]
 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
 140 ===============
 141
 142 The config file is not presently strictly required, though it is nice to have.
 143 Only a few things need to go in here.
 144
 145    [theme]
 146    name = Hedgehog-ification
 147    description = For hedgehog lovers ONLY
 148    licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0
 149
 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.
 158
 159
 160 Templates
 161 =========
 162
 163 Your template directory is where you can put any override and custom
 164 templates for MediaGoblin.
 165
 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.
 169
 170 You can copy files right out of MediaGoblin core and modify them in
 171 this matter if you wish.
 172
 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:
 176
 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    #}
 194
 195
 196 Assets
 197 =======
 198
 199 Put any files, such as images, CSS, etc, that are specific to your
 200 theme in here.
 201
 202 You can reference these in your templates like so:
 203
 204     <img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" />
 205
 206 This will tell MediaGoblin to reference this image from the current theme.
 207
 208
 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
 226
 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
 251 Packaging it up!
 252 ================
 253
 254 Packaging a theme is really easy.  It's just a matter of making an archive!
 255
 256 Change to the installed themes directory and run the following:
 257
 258   tar cvfz yourtheme.tar.gz yourtheme
 259
 260 Where "yourtheme" is replaced with your theme name.
 261
 262 That's it!