seagull documentation - read the docsseagull documentation, release 1.0.dev1 seagull is an...

25
Seagull Documentation Release 1.0.dev1 Hajime Yamasaki Vukelic <[email protected]> August 21, 2016

Upload: others

Post on 20-Feb-2020

68 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull DocumentationRelease 1.0.dev1

Hajime Yamasaki Vukelic <[email protected]>

August 21, 2016

Page 2: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General
Page 3: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Contents

1 Guide contents 31.1 Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Installing Seagull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3 First steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4 Customizing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.5 Customizing the styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.6 Customizing the templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

i

Page 4: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

ii

Page 5: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General PublicLicense.

This guide explains how to start, customize, and deploy Seagull in a production environment. Since Seagull is rela-tively simple in design, most of the space will be spent on the customization aspect. The guide is written in the tutorialstyle to ease new users into the matter, but basic knowledge of Python, HTML, and CSS will definitely go a long waytowards making the reading experience much easier.

Contents 1

Page 6: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

2 Contents

Page 7: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

CHAPTER 1

Guide contents

1.1 Software requirements

In order to run Seagull on your machine, you will need to have a bunch of programs installed that Seagull depends on.Some of these programs are for running Seagull itself, some are for developing the skins. This section is divided intosubsections so you can skip the parts you do not need at this time. You must, however, cover the Basics section.

1.1.1 Basics

At absolute minimum you will need to have Python 3.5 or newer installed. Seagull specifically uses features that werenewly introduced in Python 3.5, so older versions will not work (not even older versions in the 3.x series).

If you are on Linux, you should use your distro’s package manager to install Python. In some distributions (e.g., ArchLinux), the default python package is Python 3.x. On other distros, default is usually Python 2.x so the Python 3.xwill use a package named python3 or something along those lines.

Windows and Mac users can peruse the download page on python.org.

Once Python is installed, check that you have the correct version. Run the following command in the command line(command prompt):

> python --versionPython 3.5.2

In some instances, you may need to refer to Python 3.5 as python3 or even python3.5 in the command line:

> python3 --versionPython 3.5.2

Throughout the rest of the guide, when you see python in the command examples, you will use the command namethat worked for you, be it python or python3 (and the same applies to pip as you will see later on).

Note: If your Linux distro does not ship the latest and greatest version, you will need to figure out a way to get thelatest version. For older releases of Ubuntu, for example, follow this advice. Debian has Python 3.5 in the unstablebranch. If you are going to eventually deploy Seagull yourself, it would probably be worthwhile to explore theseupgrades now.

If your Python install does not come with pip, the Python package manager, you will also need to install pip. Theversion of the pip package is not critical for using Seagull but asking for its version is a good way to test if it’sinstalled:

3

Page 8: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

> pip --versionpip 8.1.2 from ..... (python 3.5)

Make sure that it says ‘python 3.5’ in the result. If it says something like ‘python 2.7’ or any version other than 3.5,then you probably installed pip for the wrong version of Python. For example, on Linux, pip for Python 3.5 would bein a package named python3-pip or something similar. In some cases, the command itself may be different (e.g.,pip3 instead of pip).

1.1.2 Software needed for skin development

If you intend to customize the built-in skins (but not strictly required if you just want to create a completely new skin),you will also need:

• NodeJS and NPM for CoffeeScript support (see this guide)

• Ruby and Ruby Gems for Compass support (see this guide)

To verify the installs:

> npm --version3.10.3

> gem --version2.5.1

Exact versions are not really important here. Once you have NodeJS, NPM, Ruby, and Ruby Gems installed, you willneed to install CoffeeScript and Compass. To install CoffeeScript with NPM, run this command:

> npm install --global coffee-script

Next install Compass using Ruby Gem:

> gem install compass

You probably want to verify that these tools were installed correctly:

> coffee --versionCoffeeScript version 1.10.0

> compass --versionCompass 1.0.3 (Polaris)Copyright (c) 2008-2016 Chris EppsteinReleased under the MIT License.Compass is charityware.Please make a tax deductable donation for a worthy cause: http://umdf.org/compass

1.1.3 Tools for working on the documentation

If you wish to hack at this guide, you will need to install Sphinx and the ReadTheDocs theme for Sphinx:

> pip install sphinx sphinx-rtd-theme

To verify that Sphinx was installed:

> sphinx-build --versionSphinx (sphinx-build) 1.4.5

4 Chapter 1. Guide contents

Page 9: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

1.1.4 Tools for working with the source code

The Seagull source code can always be browsed through on GitHub, so making a local copy of the source code andtracking it is not strictly necessary. If you still wish to give it a try, here are the tools you will need:

• Git

• virtualenvwrapper

1.2 Installing Seagull

Once all the prerequisites are satisfied (see :doc:requirements), you can install Seagull itself.

1.2.1 Install from GitHub

To install Seagull on your computer as a package (as opposed to creating a local copy of the source, that is), you caninstall directly from the GitHub repository of the project:

> pip install https://github.com/foxbunny/seagull/archive/master.zip

If you need to know where it got installed, run the following command:

> python -c 'import seagull; print(seagull.__appdir__)'/usr/lib/python3.5/site-packages/seagull# or on Windows: c:\python35\lib\site-packages\seagull

1.2.2 Clone the source code

If you installed the tools for working with the source code in the :doc:requirements section, you now get a chance toput them to use. First you will need to clone the Git repository:

> git clone https://github.com/foxbunny/seagull.gitCloning into 'seagull'...remote: Counting objects: 418, done.remote: Compressing objects: 100% (194/194), done.emote: Total 418 (delta 226), reused 377 (delta 185), pack-reused 0Receiving objects: 73% (306/418), 556.00 KiB | 260.00 KiB/sReceiving objects: 100% (418/418), 613.73 KiB | 260.00 KiB/s, done.Resolving deltas: 100% (226/226), done.Checking connectivity... done.> cd seagull> mkvirtualenv seagullUsing base prefix '<path to python>'New python executable in <path to copy of python>Installing setuptools, pip, wheel...done.> pip install -e .Obtaining file://<path to cloned repository>Collecting bottle==0.12.9 (from seagull==1.0.dev1)Collecting bottle-streamline==1.0 (from seagull==1.0.dev1)Collecting confloader==1.1 (from seagull==1.0.dev1)........

Later if you wish to update the source code do:

1.2. Installing Seagull 5

Page 10: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

> git reset --hard HEAD> git pull origin master

Note: If you wish to learn more about Git, there is plenty of material on the Git homepage, in the documentationsection, including introductory videos.

1.2.3 Verifying the install

To verify that seagull was installed correctly, you can run this command:

> seagull --version1.0.dev1

1.3 First steps

In this section, we’ll take Seagull for a quick step, and do some fairly basic ‘customization’, simply by manipulatingthe gallery folder.

1.3.1 Ignition!

Let’s quickly start up Seagull and see what that does. In your console, type:

> seagullStarting SeagullRegistering SIGINT handlerRegistering SIGTERM handlerPreparing application to runAdded JS bundle: app.jsAdded CSS bundle: app.cssQuitting, no gallery directory '/tmp/seagull-gallery'

So that was a bit underwhelming. It’s missing a gallery folder at its default location, which is/tmp/seagull-gallery (or C:\tmp\seagull-gallery on Windows). Thankfully, this is easy to fix. Let’screate the folder where it wants it and try again:

> seagullStarting SeagullRegistering SIGINT handlerRegistering SIGTERM handlerPreparing application to runAdded JS bundle: app.jsAdded CSS bundle: app.cssSetting up index for /tmp/seagull-gallerySorting itemsAdded 0 items to the indexRoute gallery:main mapped to /Route gallery:image mapped to /gallery/<path:path>Route gallery:reindex mapped to /reindex/<token>Route app:static mapped to /static/<path:path>Server started on http://0.0.0.0:8080/Server started on http://0.0.0.0:8080/

6 Chapter 1. Guide contents

Page 11: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

Now that’s more like it. It does say ‘Server started’ twice, but it’s only starting once. It’s a bug. To access Seagull,let’s open our favorite browser (Firefox, of course) and browse to localhost:8080.

To stop the gallery app, press Ctrl-C in the console where you started it....Server started on http://0.0.0.0:8080/Server started on http://0.0.0.0:8080/Server stopped

For now let’s start it up again and keep it running while we fiddle with it.

1.3.2 Adding the cover

The screen looks deliciously dark, but I’m pretty sure not everyone enjoys dark. Let’s add a cover image. Pickany JPEG image that’s fairly large (say, 1600px by 1200px) and put it in the gallery folder. Rename the image to_cover.jpg.

Note: Only JPEG images are supported for covers at this time, and it will likely remain that way for foreeseablefuture. This can be fixed relatively easily through skinning, though.

Let’s reload the page.

1.3. First steps 7

Page 12: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

It already looks presentable. You will notice that the two bottom links don’t do much. This is because there are nophotos in the gallery.

1.3.3 Adding the photos

To add the photos to the gallery, we simply dump a bunch of JPEG, PNG, or GIF images into the gallery folder.

Let’s reload the page.

8 Chapter 1. Guide contents

Page 13: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

But wait. There are still no photos. This is because, unlike the cover page, the photos in the actual gallery need tobe reindexed before they will show up. It would be too CPU-intensive if we did this every time we load the page, sowe do it only as needed. To trigger the indexing, we use a magic URL: localhost:8080/reindex/reindex-now-1234 (thepart that says ‘reindex-now-1234’ is configurable, and we’ll get to that in the next section). Once we go to that page,we will see a message about gallery being rescanned.

After approximately 5 seconds, we are back in the main page. If we now scroll down or use the ‘gallery’ link, we willsee our photos.

1.3. First steps 9

Page 14: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

The photos are ordered in lexical order (or in plain English: alphabetically). All you need to do in order to change theimage order is to change the file names.

1.3.4 Adding the ‘About’ section

Seagull supports adding an ‘About’ section that appears right below the cover image on the start page. The aboutsection is written in Markdown, so it’s helpful to know its syntax. Let’s open up an editor and add some text for a shortabout section:

## Seagull photo gallery

Seagull photo gallery is an open-source photo gallery application.

We’ll save this file in our gallery folder and name it _about.mkd.

As with the photos, we need to reindex the gallery. Once the gallery is reindexed, and we reload the page, we seethat there is a new link in the menu, and that our text has been rendered as a section below the cover page just like

10 Chapter 1. Guide contents

Page 15: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

promised.

1.3.5 Changing the site metadata

There is one more thing that we can add using the gallery folder and that’s the site metadata. The metadata affect thefollowing:

• site title

• site description

• author name

• copyright year

• contact links section

This is done by adding a file named _about.info to the gallery folder. The structure of the file is best explainedusing an example:

title: Projectionsdescription: Hajime Yamasaki photo galleryauthor: Hajime Yamasakicopyright: 2011email: [email protected]: hayavuktwitter: foxbunnyflickr: foxbunnylinkedin: brankovukelicyoutube: UC7OFFqXeuvvlRIXGkK4jMsQ

The above example contains all the supported metadata and contact link information. The order does not matter, butthe names on the left have to be exactly as they appear there and must be all lower-case. For contact links, you alwaystype in the last portion of the profile address (the bit after the last slash: /) on the right-hand side.

Now, let’s save this file in our gallery folder as _about.info.

1.3. First steps 11

Page 16: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

After reindexing and reloading the page, the menu contains the contact link, the gallery title and description areupdated, and contact links section appears at the bottom of the page.

12 Chapter 1. Guide contents

Page 17: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

1.4 Customizing the configuration

Although there are many configuration settings in the default configuration file that comes with Seagull, we normallyonly need to change a few things. In this section, we will gloss over the process of creating a custom configurationfile, and change the password. Configuration will be covered in more detail in the deployment section later on.

1.4.1 Creating the custom configuration file

The seagull command we have been using has a shortcut for creating our own configuration file. Let’s try it:

> seagull custom-conf mygull.ini

Now let’s open the file in an editor. The contents look like this:

[config]

defaults =/usr/lib/python3.5/site-packages/seagull/seagull.ini

[seagull]

# Add your settings below this line

The part that says /usr/lib/python3.5/... is going to be different depending on what operating system youare on, and where Seagull is installed, but it always points to the default configuration file.

Note: Any setting that appears in the default configuration file can be overridden by your custom configuration file.You just need to make sure the appropriate section header exists in both (e.g., [seagull] in the above example) andthat the setting you want to override is under the correct section.

1.4. Customizing the configuration 13

Page 18: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

1.4.2 Changing the password

We’ll use this opportunity to change the reindex password. The comment in the default configuration file says that thispassword must be URL-friendly. To keep it simple, we’ll take this to mean that we can only use letters and numbersand dashes (in reality, there are many more characters that can be used, but discussing the full set of rules about whatcan and cannot be used in an URL is outside the scope of this tutorial).

[seagull]

# Reindexing password: asked for when using the reindex page, must be# URL-friendlypassword = my-new-password

We can also change the gallery folder path using the gallery_dir setting, but I’ll leave that to you to play with. :-)

Note: When modifying the settings, it’s good practice to copy the comments from the default configuration file soyou can remember what the setting does when you come back to it later.

1.5 Customizing the styling

Styling and layout is defined by skins. Skins are folders with standardized structure, that contain static assets, sourcecode (if you use transpiled languages like Compass and/or CoffeeScript), and (optionally) templates.

In this section, we’ll take a look at setting up a skin folder, and lightly touching up the default skin.

1.5.1 Creating the skin folder

To create a skin folder, we’ll use the custom-skin command.

> seagull custom-skin myskinCreated skin in 'myskin'

What this option does is it creates a copy of the default skin at the specified path (in our case it’s myskin).

1.5.2 Skin folder structure

Before going into the modification, let’s take a look at the generated folder.

There are three folders inside the shiny new skin folder:

• assets - contains the (compiled) static assets

• src - contains the Compass and/or CoffeeScript sources

• templates - contains any HTML templates

The assets folder

If you intend to work with raw CSS and JavaScript, you will work in the assets folder. Otherwise, this folder willcontain files generated by Compass and CoffeeScript. Regardless of your approach, there is one important file in thedirectory that you may want to modify: bundles.conf.

The bundles file looks like this:

14 Chapter 1. Guide contents

Page 19: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

app.js:main

app.css:main

Each line that starts with a filename followed by a colon is a bundle. This file contains two bundles: app.js andapp.css. You can have any number of bundles but that depends on how your template is constructed. The defaulttemplate uses only those two bundles. Bundles cannot be nested, by the way.

The names after the bundle line, until the next bundle line, are paths of the JavaScript and CSS files that should be inthe bundle. They don’t have an extension because the extension is picked up from the bundle name. The file paths arelooked up in the assets/js folder for .js bundles, and assets/css folder for .css bundles.

Let’s say we have files menu.js and hero.js that we wish to combine into the app.js bundle. To do this, wewould copy the two files into the skin’s assets/js folder, and have this in the bundles file:

app.js:menuhero

The bundle is created with the contents ordered exactly as specified, so if the loading order matters for your files, youshould make sure they are listed in the correct order.

Similarly, for CSS, you can combine multiple files with something like:

app.css:menuherofooter

If one of the files is in a subdirectory (e.g., assets/css/footer/copyright.css), then the bundle might looklike this:

app.css:menuherofooter/copyright

Note: Slashes are always forward regardless of the operating system.

The src folder

The src folder has two subfolders: coffee and scss. They contain the CoffeeScript and Compass sources, respec-tively. You can completely omit this folder if you don’t intend to use these fantastic technologies. Sure, not everyonecan handle awesome. :-)

The templates folder

The templates folder contains templates. It starts off with a file named .empty (which can be safely removed),and it should contain templates that you wish to override. The default templates are located where seagull is installed(or cloned), in a folder named default_templates. We’ll discuss modifying templates a bit later.

1.5. Customizing the styling 15

Page 20: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

1.5.3 Setting the new skin

We’ll now go back to our configuration file, mygull.ini, and edit it to use our new skin:

[seagull]

...

# The skin to useskin = myskin

# Directory that contains additional skinsextra_skins = .

The skin setting selects myskin as the skin we want to use. The extra_skns points to a folder in which themyskin folder can be found. We say . to make seagull look in the directory where we start it.

Let’s try out the new settings:

> seagull --conf mygull.iniStarting SeagullRegistering SIGINT handlerRegistering SIGTERM handlerPreparing application to runUsing skin 'myskin'Setting up index for /tmp/seagull-galleryOmitted /tmp/seagull-gallery/index.html from galleryOmitted /tmp/seagull-gallery/page2.html from galleryOmitted /tmp/seagull-gallery/_about.mkd from galleryOmitted /tmp/seagull-gallery/_contact.info from galleryOmitted /tmp/seagull-gallery/_cover.jpg from galleryOmitted /tmp/seagull-gallery/_static from gallerySorting itemsAdded 11 items to the indexAdded JS bundle: app.jsAdded CSS bundle: app.cssRoute gallery:main mapped to /Route gallery:image mapped to /gallery/<path:path>Route gallery:reindex mapped to /reindex/<token>Route app:static mapped to /static/<path:path>Server started on http://0.0.0.0:8080/Server started on http://0.0.0.0:8080/

You will notice that this time seagull says Using skin ’myskin’ to let us know that the new skin is being used.Reloading the gallery page does not do anything yet, though, because myskin is still unmodified.

1.5.4 Editing CSS and JavaScript directly

If you wish to work with CSS and JavaScript directly, you can skip to the next section after reading this heading. Ialso won’t talk about directly editing CSS and JavaScript at length as I believe readers who choose this option will bemore than capable of figuring things out on their own.

The only thing I am going to note is that, if you are editing the code directly, you will probably find the bundles fileessential to your workflow. The bundles file combines and minifies listed assets into singular files (bundles), and alsotakes care of cache busting.

Note: Cache-busting in Seagull is performed by the webassets library it uses. You can read more about the technical

16 Chapter 1. Guide contents

Page 21: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

details of how it works in the webassets documentation.

1.5.5 Starting the code compilers

The code compilers compile Compass and CoffeeScript code and dumps the compiled versions of CSS and JavaScriptinto the assets folder. If you’ve never used Compass before, don’t worry. It’s just CSS with additional bells andwhistles, and if you followed the installation guide closely, you’ll have everything you need for a pleasant developmentexperience.

Before we start hacking at the Compass code, we’ll start the watching compiler. The watching compiler will monitorthe files and will recompile the code as soon as changes are detected.

Note: It is recommended that you keep seagull running in one console, and start the watcher in another one so thatyou can preview the changes immediately.

Enough talk, let’s start the watcher:

> seagull watch --skin-path myskinstarting watchersusing skin in '/path/to/myskin'12:59:26 PM - compiled /path/to/myskin/src/coffee/main.coffee>>> Compass is watching for changes. Press Ctrl-C to Stop.

Note: The python setup.py portion of the command can be replaced with ./setup.py on Linux and Mac,or setup on Windows.

Depending on your computer speed, the output may take a while to appear, and the console prompt may appear beforethe last line of the example output is printed on your screen. The watcher is not fully started until you see the >>>Compass line.

1.5.6 Editing the Compass code

Now we are ready to start customizing the skin. We first want to get rid of the animation on the title and description,because they don’t work so well for our long-ish title.

The top portion of the page (the one that has the cover image) is called a ‘hero’ area, and the code for it is found insrc/scss/_hero.scss. In that file, find and remove the following lines:

.title {...@include transform(translateX(0)); <-- this@include animation(6s ease-out fly-in); <-- and this

}

.description {...@include transform(translateX(0)); <-- this@include animation(8s ease-out fly-in); <-- also, this

}

Once the file is saved, we should see the change in the console where the watchers are running.

1.5. Customizing the styling 17

Page 22: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

modified myskin/src/scss/_hero.scsswrite myskin/assets/css/main.css

Refreshing the page, we see that the animation is no longer there. Good. Now I want the title and subtitle to be at thetop of the page, and left-aligned. The modified portions now look like this:

.title {position: relative;z-index: 1;font-size: 400%;line-height: 100%;padding: 2rem 2rem 1rem;...

.description {position: relative;z-index: 1;white-space: nowrap;padding: 0 2rem;...

1.5.7 Stopping the watchers

Now that we are satisfied with the changes we can stop the watchers.

It’s important to note that the watcher is now running in the background. You can type additional commands in thesame console, for example. Simply closing the console may not stop them, so let’s see how to stop the watcherproperly:

> seagull stop-watchersstopping watchers

That’s it. Now the watchers are stopped.

18 Chapter 1. Guide contents

Page 23: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

1.6 Customizing the templates

Due to the pages’ simple structure, even just using CSS, a lot of customization ca be made. But in some cases,modifying the template can be the only way to achieve something.

In this section, we’ll modify our Projections gallery to have the about text appear in the hero area as a column on theright instead of in a strip at the bottom of the page. This will require a change in both the templates and the stylesheet,so let’s fire up the watchers again.

1.6.1 The tour of the templates

Before we start hacking at templates, I will give you a brief tour of what each template does. First lets locate thetemplates:

> seagull templates/usr/lib/python3.5/site-packages/seagull/skins/seagull/templates/usr/lib/python3.5/site-packages/seagull/default_templates

The first path is always the skin’s template folder, and the second one is the one we are interested in: the defaulttemplates folder. This folder contains the following files:

• _contact.mako

• _images.mako

• _paging.mako

• base.mako

• main.mako

• reset.mako

Note: All templates are written for the Mako template engine. If you want to seriously hack at the templates, youshould be familiar with Python and HTML, and, of course, the Mako syntax rules.

These are not all different pages. There are actually only two different page templates: reset.mako (which we don’treally care about) and main.mako which is applied to all gallery pages. The other templates are support (partial) andbase templates.

The base.mako template provides the outer shell for all the pages. It contains the common bits like the docstring,HTML tag, footer, and so on.

The main.mako is the template that glues together the base and the inner bits and pieces such as the contact list,about section, the image list, and the pager.

_contact.mako contains fragments for the contact list.

_images.mako contains fragments for the gallery’s image list.

_paging.mako contains fragments for the pager at the bottom of the page.

1.6.2 Modifying the hero layout

Now let’s modify the hero layout according to our original plan. First we will copy the main.mako from the defaulttemplates folder to our skin’s templates folder.

When we optn the file in our editor, we see the following bit:

1.6. Customizing the templates 19

Page 24: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

%if pager.is_first and metadata.about:<section id="about" class="about">${metadata.about | n,unicode}</section>

%endif

In Mako parlance, this says that the about section is only shown on the first page and when the about metadata isavailable. We want this whole block to move into the hero area, so we’ll cut it and paste it just below the description....

${metadata.description}</p>

%if pager.is_first and metadata.about:<section id="about" class="about">

....

Template changes are applied immediately, so we can reload the page and see the results right away.

Of course, without assistance from some CSS we cannot make our layout happen. We’ll start the watcher and editsrc/scss/_about.scss in our skin folder to adjust the about section layout.

.about {display: block;position: fixed;right: 0;top: 0;bottom: 0;width: 40%;@include box-sizing(border-box);z-index: 1;background: transparentize($light-grey, 0.2);padding: 2rem;color: $dark-grey;

}

We’ll let the watchers recompile the stylesheet and preview our result.

20 Chapter 1. Guide contents

Page 25: Seagull Documentation - Read the DocsSeagull Documentation, Release 1.0.dev1 Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General

Seagull Documentation, Release 1.0.dev1

We’ll just make one more adjustment, and hide the about link in the navigation menu when we are on the first page.The part of the main.mako template that deals with this is:

<nav id="navigation" class="navigation">....%if metadata.about:

<a href="${prefix}#about">About</a>%endif...

</nav>

Right now, it only checks that there is about metadata, and shows the link in that case. We also want to hide it on thefirst page, because the about information is already shown at the top. Therefore, we edit the link to look like this:

%if not pager.is_first and metadata.about:

The above line will work correctly, but it’s a little ambiguous. Is it saying ‘not first page and not metadata.about’ or‘not (first page and metadata.about)’? There is a better way to express this thought:

%if page.has_prev and metadata.about:

If we are not the the first page, then there are previous pages, so this gives us the same result.

You’ll forgive me for leaving unfixed styling issues in interest of brevity, and let me conclude this section at this point.:-)

1.6. Customizing the templates 21