282 lines
9.2 KiB
ReStructuredText
282 lines
9.2 KiB
ReStructuredText
.. MediaGoblin Documentation
|
|
|
|
Written in 2011, 2012 by MediaGoblin contributors
|
|
|
|
To the extent possible under law, the author(s) have dedicated all
|
|
copyright and related and neighboring rights to this software to
|
|
the public domain worldwide. This software is distributed without
|
|
any warranty.
|
|
|
|
You should have received a copy of the CC0 Public Domain
|
|
Dedication along with this software. If not, see
|
|
<http://creativecommons.org/publicdomain/zero/1.0/>.
|
|
|
|
.. _theming-chapter:
|
|
|
|
=====================
|
|
Theming MediaGoblin
|
|
=====================
|
|
|
|
We try to provide a nice theme for MediaGoblin by default, but of
|
|
course, you might want something different! Maybe you want something
|
|
more light and colorful, or maybe you want something specifically
|
|
tailored to your organization. Have no fear---MediaGoblin has theming
|
|
support! This guide should walk you through installing and making
|
|
themes.
|
|
|
|
|
|
Installing a theme
|
|
==================
|
|
|
|
.. _theming-installing-section:
|
|
|
|
Installing the archive
|
|
----------------------
|
|
|
|
Say you have a theme archive such as ``goblincities.tar.gz`` and you
|
|
want to install this theme! Don't worry, it's fairly painless.
|
|
|
|
1. ``cd ./user_dev/themes/``
|
|
|
|
2. Move the theme archive into this directory
|
|
|
|
3. ``tar -xzvf <tar-archive>``
|
|
|
|
4. Open your configuration file (probably named
|
|
``mediagoblin.ini``) and set the theme name::
|
|
|
|
[mediagoblin]
|
|
# ...
|
|
theme = goblincities
|
|
|
|
5. Link the assets so that they can be served by your web server::
|
|
|
|
$ ./bin/gmg assetlink
|
|
|
|
.. Note::
|
|
|
|
If you ever change the current theme in your config file, you
|
|
should re-run the above command!
|
|
|
|
(In the near future this should be even easier ;))
|
|
|
|
.. In the future, this might look more like:
|
|
.. Installing a theme in MediaGoblin is fairly easy! Assuming you
|
|
.. already have a theme package, just do this::
|
|
..
|
|
.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
|
|
..
|
|
.. This would install the theme, set it as current, and symlink its
|
|
.. assets.
|
|
|
|
|
|
Set up your webserver to serve theme assets
|
|
-------------------------------------------
|
|
|
|
If you followed the Nginx setup example in :ref:`webserver-config` you
|
|
should already have theme asset setup. However, if you set up your
|
|
server config with an older version of MediaGoblin and the MediaGoblin
|
|
docs, it's possible you don't have the "theme static files" alias, so
|
|
double check to make sure that section is there if you are having
|
|
problems.
|
|
|
|
If you are simply using this for local development and serving the
|
|
whole thing via paste/lazyserver, assuming you don't have a
|
|
paste_local.ini, the asset serving should be done for you.
|
|
|
|
|
|
Configuring where things go
|
|
---------------------------
|
|
|
|
By default, MediaGoblin's install directory for themes is
|
|
``./user_dev/themes/`` (relative to the MediaGoblin checkout or base
|
|
config file.) However, you can change this location easily with the
|
|
``theme_install_dir`` setting in the ``[mediagoblin]`` section.
|
|
|
|
For example::
|
|
|
|
[mediagoblin]
|
|
# ... other parameters go here ...
|
|
theme_install_dir = /path/to/themes/
|
|
|
|
Other variables you may consider setting:
|
|
|
|
`theme_web_path`
|
|
When theme-specific assets are specified, this is where MediaGoblin
|
|
will set the URLs. By default this is ``"/theme_static/"`` so in
|
|
the case that your theme was trying to access its file
|
|
``"images/shiny_button.png"`` MediaGoblin would link
|
|
to ``/theme_static/images/shiny_button.png``.
|
|
|
|
`theme_linked_assets_dir`
|
|
Your web server needs to serve the theme files out of some directory,
|
|
and MediaGoblin will symlink the current theme's assets here. See
|
|
the "Link the assets" step in :ref:`theming-installing-section`.
|
|
|
|
|
|
Making a theme
|
|
==============
|
|
|
|
Okay, so a theme layout is pretty simple. Let's assume we're making a
|
|
theme for an instance about hedgehogs! We'll call this the
|
|
"hedgehogified" theme.
|
|
|
|
Change to where your ``theme_install_dir`` is set to (by default,
|
|
``./user_dev/themes/`` ... make those directories or otherwise adjust
|
|
if necessary)::
|
|
|
|
hedgehogified/
|
|
|- theme.cfg # configuration file for this theme
|
|
|- templates/ # override templates
|
|
| '- mediagoblin/
|
|
| |- base.html # overriding mediagoblin/base.html
|
|
| '- root.html # overriding mediagoblin/root.html
|
|
'- assets/
|
|
| '- images/
|
|
| | |- im_a_hedgehog.png # hedgehog-containing image used by theme
|
|
| | '- custom_logo.png # your theme's custom logo
|
|
| '- css/
|
|
| '- hedgehog.css # your site's hedgehog-specific CSS
|
|
|- README.txt # Optionally, a readme file (not required)
|
|
|- AGPLv3.txt # AGPL license file for your theme. (good practice)
|
|
'- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!]
|
|
|
|
|
|
The top level directory of your theme should be the symbolic name for
|
|
your theme. This is the name that users will use to refer to activate
|
|
your theme.
|
|
|
|
.. Note::
|
|
|
|
It's important to note that templates based on MediaGoblin's code
|
|
should be released as AGPLv3 (or later), like MediaGoblin's code
|
|
itself. However, all the rest of your assets are up to you. In this
|
|
case, we are waiving our copyright for images and CSS into the public
|
|
domain via CC0 (as MediaGoblin does) but do what's appropriate to you.
|
|
|
|
|
|
The config file
|
|
===============
|
|
|
|
The config file is not presently strictly required, though it is nice to have.
|
|
Only a few things need to go in here::
|
|
|
|
[theme]
|
|
name = Hedgehog-ification
|
|
description = For hedgehog lovers ONLY
|
|
licensing = AGPLv3 or later templates; assets (images/CSS) waived under CC0 1.0
|
|
|
|
The name and description fields here are to give users an idea of what
|
|
your theme is about. For the moment, we don't have any listing
|
|
directories or admin interface, so this probably isn't useful, but
|
|
feel free to set it in anticipation of a more glorious future.
|
|
|
|
Licensing field is likewise a textual description of the stuff here;
|
|
it's recommended that you preserve the "AGPLv3 or later templates" and
|
|
specify whatever is appropriate to your assets.
|
|
|
|
|
|
Templates
|
|
---------
|
|
|
|
Your template directory is where you can put any override and custom
|
|
templates for MediaGoblin.
|
|
|
|
These follow the general MediaGoblin theming layout, which means that
|
|
the MediaGoblin core templates are all kept under the ``./mediagoblin/``
|
|
prefix directory.
|
|
|
|
You can copy files right out of MediaGoblin core and modify them in
|
|
this matter if you wish.
|
|
|
|
To fit with best licensing form, you should either preserve the
|
|
MediaGoblin copyright header borrowing from a MediaGoblin template, or
|
|
you may include one like the following::
|
|
|
|
{#
|
|
# [YOUR THEME], a MediaGoblin theme
|
|
# Copyright (C) [YEAR] [YOUR NAME]
|
|
#
|
|
# This program is free software: you can redistribute it and/or modify
|
|
# it under the terms of the GNU Affero General Public License as published by
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU Affero General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU Affero General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
#}
|
|
|
|
|
|
Assets
|
|
------
|
|
|
|
Put any files, such as images, CSS, etc, that are specific to your
|
|
theme in here.
|
|
|
|
You can reference these in your templates like so::
|
|
|
|
<img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" />
|
|
|
|
This will tell MediaGoblin to reference this image from the current theme.
|
|
|
|
|
|
Licensing file(s)
|
|
-----------------
|
|
|
|
You should include AGPLv3.txt with your theme as this is required for
|
|
the assets. You can copy this from ``mediagoblin/licenses/``.
|
|
|
|
In the above example, we also use CC0 to waive our copyrights to
|
|
images and CSS, so we also included CC0_1.0.txt
|
|
|
|
|
|
A README.txt file
|
|
-----------------
|
|
|
|
A README file is not strictly required, but probably a good idea. You
|
|
can put whatever in here, but restating the license choice clearly is
|
|
probably a good idea.
|
|
|
|
|
|
Simple theming by adding CSS
|
|
----------------------------
|
|
|
|
Many themes won't require anything other than the ability to override
|
|
some of MediaGoblin's core CSS. Thankfully, doing so is easy if you
|
|
combine the above steps!
|
|
|
|
In your theme, do the following (make sure you make the necessary
|
|
directories and cd to your theme's directory first)::
|
|
|
|
$ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/
|
|
|
|
Great, now open that file and add something like this at the end::
|
|
|
|
<link rel="stylesheet" type="text/css"
|
|
href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
|
|
|
|
You can name the CSS file whatever you like. Now make the directory
|
|
for ``assets/css/`` and add the file ``assets/css/theme.css``.
|
|
|
|
You can now put custom CSS files in here and any CSS you add will
|
|
override default MediaGoblin CSS.
|
|
|
|
|
|
Packaging it up!
|
|
----------------
|
|
|
|
Packaging a theme is really easy. It's just a matter of making an archive!
|
|
|
|
Change to the installed themes directory and run the following::
|
|
|
|
tar -cvfz yourtheme.tar.gz yourtheme
|
|
|
|
Where "yourtheme" is replaced with your theme name.
|
|
|
|
That's it!
|