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