Style (CSS) and Eloquence (Languages)

EPrints has a rather complex hierachy of style sheets. You have eprints default styles which is then overwritten (where appropriate) by a local theme which is then overwritten in turn by your repositories local style sheets. Themes have been around since EPrints 3.0 but they are almost never used because very few people ever style more than one repository. Themes are a pack of style sheets, images, templates, static pages, and javascript which can completely change the look and feel of an EPrints repository. In EPrints 3.3 themes have been revisited and polished up so that they can be easily made into EPrints Bazaar packages.

In this tutorial we will focus on how to make your own theme which can be packaged for the EPrints Bazaar.

Creating the theme

You will need to start by creating your own theme directory. In this tutorial my theme name will be "abstract_flash" so the directory I will create for my theme is <eprints_root>/archives/<archive_name>/cfg/themes/abstract_flash/

Adding a style sheet

The first and easiest thing to do is create a new style sheet for our theme. In EPrints 3.2 the default template has been changed to make the things you can do with CSS styles much more powerful.

Create a stylesheet in your theme's directory: <eprints_root>/archives/<archive_name>/cfg/themes/abstract_flash/static/style/auto/y_abstract_flash.css

Try out some simple style rules to change the appearance of your EPrints template. If you aren't comfortable with CSS or you're just feeling lazy you can copy my code from the box below.

.ep_tm_archivetitle {
        display: block;
        padding: 10px;
        color: #D4FAE7;
}

.ep_tm_menu, .ep_tm_header {
        background: none repeat scroll 0 0 #525252;
}

.ep_tm_logo {
        display: none;
}

.ep_tm_menu li {
        padding: 20px;
        display: inline-block;
        border-top: 2px solid white;
}

.ep_tm_searchbar {
        background: none repeat scroll 0 0 #D4FAE7;
        border-top: 1px solid #525252;
        border-bottom: 1px solid #525252;
}

.ep_tm_key_tools li a {
        color:#525252;
}

body {
        margin: 0;
}

To enable your theme you will need to create file in cfg.d which tells EPrints which theme it should use. If you don't do this EPrints will use the default theme. I called my file cfg.d/x_abstract_flash.pl it contains this directive:

$c->{theme} = "abstract_flash";

Changing the template

Our theme can also contain a template. The template is the frame in which pages are displayed.

I suggest copying your template file from the lib directory lib/templates/default.xml. The template can go in either cfg/themes/abstract_flash/templates/default.xml or cfg/themes/abstract_flash/lang/[langid]/templates/default.xml (if you want a language specific template)

In this example I have moved the key tools bar so that it is a menu on the right of the screen. To do this you must edit your template and move the "login_status" pin from inside the search bar to below it. This exert shows what I have done:

 <table class="ep_tm_searchbar">
    <tr>
      <td> <!-- login_status pin was here--> </td>
      <td align="right" style="white-space: nowrap">
                <epc:pin ref="languages" />
        <form method="get" accept-charset="utf-8" action="{$config{http_cgiurl}}/search" style="display:inline">
          <input class="ep_tm_searchbarbox" size="20" type="text" name="q"/>
          <input class="ep_tm_searchbarbutton" value="Search" type="submit" name="_action_search"/>
          <input type="hidden" name="_action_search" value="Search"/>
          <input type="hidden" name="_order" value="bytitle"/>
          <input type="hidden" name="basic_srchtype" value="ALL"/>
          <input type="hidden" name="_satisfyall" value="ALL"/>
        </form>
      </td>
    </tr>
  </table>
</div>


<epc:pin ref="login_status"/>

You must reload your configuration for this change to take affect.

You should now find that login information is outside of the search search bar area. Now we apply some style rules to position it on the right and make it look slightly more attractive. The style rules i chose are below.

.ep_tm_key_tools {
        width: 200px;
        float: right;
        background: none repeat scroll 0 0 #D4FAE7;
        margin:0;
        border-left: 1px solid #525252;
        border-bottom: 1px solid #525252;
}

.ep_tm_key_tools li, .ep_tm_key_tools li:first-child {
        border:none;
        font-size: 110%;
        display: block;
        padding: 10px;
}

Adding Some Images

There are a number of reasons your might add images to a theme. Maybe you want a colourful background image or maybe you want to make EPrints icons fit in with the rest of your theme. In this example my goal the later although the mechanism works for the former.

I want to replace RSS feed icons. To do this I create the directory themes/abstract_flash/style/images/. In this directory I can add image files which I then reference in my style sheet. The RSS feed icon already exists in EPrints and is used in the default style sheet. To replace it I simply create a file of the same name (in this case feed-icon-14x14.png). I'm using this icon I found on Icon Finder http://www.iconfinder.com/icondetails/42454/16/

wget http://cdn1.iconfinder.com/data/icons/iconic/raster/16/rss.png -O feed-icon-14x14.png

When you refresh the page changes should be applied.

Packaging Your Theme

To package your theme simply remove the files you have created from the archive and package them in the same way you have in the earlier excises. If you have problems getting your style to revert back to the original delete the directory <eprintsroot>/archives/<archiveid>/html/style/ manually. This is a known bug which could be solved by using a prerm method. We should have fixed this before release.

Language Packs

Language packs allow you to easily add interfaces for different languages to your repository. There are quite a few translations of EPrints which already exist but now those translations can be easily installed through the bazaar.

To create a language pack you create a folder in <eprintsroot>archives/<archiveid>/cfg/lang/<languagecode>. Now copy the language specific elements of the repository configuration from <eprintsroot>/lib/lang into this folder. Now you must go through the pain staking process of translating all of those files into your chosen language. The phrase ids stay the same but the phrases should be changed. If you want to skip this step you can use the phrases and static files from one of the available EPrints translations available at http://files.eprints.org/view/type/translation.html

Again to enable your chosen language pack you must make a cfg.d file which adds your new language code to the languages array. This cfg.d file must be alphabetically later than languages.pl

$c->{languages} = push @{$c->{languages}}, "lang_code";

Now you should have a working language pack which you can switch between using the controls next to the search box.

To package this simply remove the files you have created from the archive and package them in the same way you have in the earlier excise. Remember to keep your package name unique.