Photo Flow

Downloads of the Blox Project | Downloads of the entire Site | Imprint

Contents of this Page

1   Aim

The objective is the creation of web pages featuring a large photograph in the centre, outfit with button on the left and right sides for transiting to the next or previous photo. When hoving the buttons with the mouse, these buttons shall change their background colour. The buttons shall be available also in a deactivated version; when hovering deactivated buttons with the mouse their background colour shall not change. The width of the buttons shall be larger than the text width of their labeling.

To reach these aims, CSS shall be used, employing flex and grid containers. Static tables shall be avoided.

The principle representation of such photo pages in their ReST sources shall be:

.. container:: photoflex

    ((Button to the Left))

    ((The Actual Photo))

    ((Button to the Right))

The text for ((The Actual Photo)) shall be therein:

.. figure:: ((Raster Image))

    ((Picture Caption))

For the Buttons shall be written:

.. container:: ((Button Class))

    ((Button Text))

Typically the ((Button Text)) consists either of a single unicode arrow or of a link with such an unicode arrow as text, pointing to the respective next photo. The links shall thereby be equally high as the image, such that they can be clicked in the entire photograph height.

Ideally, the ((Button Class)) for active and inactive Buttons is the same. It is however acceptable when there are two classes: One for active buttons, another for inactive ones.

2   Implementation

2.1   The photoflex Container

The buttons and the image of one photo flow page shall be placed horizontally next to each other. All of these shall be placed altogether in the viewport horizontally centred. This can be achieved by:

div.photoflex {
    display: flex;
    justify-content: center;
}

justify-content: center places the child elements thereby directly next to each other, altogether horizontally centred.

2.2   The figure

The figure, consisting of picture and picture legend, shall be displayed smaller than the viewport width:

  • Some space needs to be reserved for the buttons for switching between different pictures;
  • The headline of the page as well as the picture legend need a little bit of space.

A sufficient style for the figure is:

div.photoflex > div.figure {
    width: 80%;
}
div.photoflex > div.figure > img {
    width: 100%;
}

Docutils figures consist of several elements:

<div class="figure">
    <img />
    <p class="caption">
        ((caption))
    </p>
</div>

width: 80% for the div.figure element places the picture together with the caption using up 80% of the viewport width. Within this div section the picture is then rendered with exactly the same width. Would width: 100% for the img element be omitted, the picture would be scaled based on its native pixel count, leading to an improperly large display.

The choice of 80% for the width of the div.figure element is appropriate to display 16:9 pictures on a 16:9 screen, given that the web page is watched in full screen mode. Without the full screen mode, it is to assume that the page will vertically not be visible completely.

The CSS code above is sufficient for pictures showing all the same aspect ratio. When more choices are required, possibly using the figwidth option for the ReST figure might be an option, e.g. as:

.. figure:: ((picture))
    :figwidth: 50%

    ((caption))

which makes the picture and its caption occupy 50% of the viewport width. The width: 80% style for div.photoflex > div.figure can in this situation remain, it will be overridden by the :figwidth: option. In this way, the setting width: 80% in the stylesheet can be used as a default value, from which can be diverged as needed.

Observe that div.figure elements obtain by means of docutils a style margin-left: 2em; margin-right: 2em. This results in a certain distance between the actual picture and the buttons at its left and right sides.

2.3   Inactive Buttons

Inactive buttons consist of pure text, typically an unicode arrow. Such a button can be implemented by the following CSS code:

div.photoflex > div.inactivebutton {
    display: grid;
    grid-template-columns: auto;
    grid-template-rows: auto;
    align-items: center;

    text-align: center;
    width: 2.5em;
}

grid-template-columns: auto and grid-template-rows: auto create here exactly one column/row.

align-items: center and text-align: center place the text of the inactive button vertically (align-items: center) as well as horizontally (text-align: center) centred.

width: 2.5em set the width of the inactive button.

2.4   Active Buttons

Active buttons are a link. They are coded as an a element with a certain text. The text can be an arrow. Different from the situation of the inactive button the text of an active button is inside of such an a element. The a element shall stretch over the entire height of the picure. This can be obtained by:

div.photoflex > div.activebutton {
    display: flex;
    flex-direction: column;

    text-align: center;
    width: 2.5em;
}
div.photoflex > div.activebutton > a {
    display: grid;
    grid-template-columns: auto;
    grid-template-rows: auto;
    align-items: center;
    flex: auto;

    color: inherit;
    text-decoration: inherit;
}

The .activebutton section here becomes a vertical (flex-direction: column) flex container (display: flex). All text within the div.activebutton elements is shown horizontally centred (text-align: center), thus also the text of the link.

To generate the link with a certain (fixed) width, the div.activebutton is rendered with width: 2.5em.

Since the a element is set up with flex: auto, it stretches over the entire height of the div.activebutton containers. Observe here that this flex container is oriented in column direction (flex-direction: column).

To center the text inside of the a element (the link text) vertically in the a element, the a element is formatted as display: grid using align-items: center (this property refers to the vertical alignment of the grid's child elements). The a element contains exactly one column (grid-template-columns: auto) as well as exactly one row (grid-template-rows: auto). The text written directly inside of the a element makes up automatically the (only) subordinate element of the a element. Thus, the text of the link is displayed horizontally and vertically centred, while the a element itself has the desired size.

Different from link elements in the continuous text the text of the link shall be shown in the same way as ordinary text; thus styles color: inherit and text-decoration: inherit are employed.

To tailor the background of the link element when hovering it with the mouse, one finally can write:

div.photoflex > div.activebutton > a:hover {
    background: #333;
}

2.5   Design of the Entire Page

To display the image for example on black background with white text colour, the following CSS is appropriate:

body {
    background: black;
    color: white;
}

The photo flow page needs a link pointing back to the page from which the photo flow page has been reached. For example, the subheading of the page can be used. In this case, the link shall possibly be rendered unobstrusively without the link-typical underlining and also in the ordinary text colour, while hovering the link text shall restore the underlining as a hint. All in all, one can write:

h2 > a {
    color: inherit;
    text-decoration: inherit;
}
h2 > a:hover {
    text-decoration: revert;
}

text-decoration: revert thereby reverts the CSS code of the author stage (here text-decoration: inherit), such that typically the respective link will be displayed again with underlining, according to the results of the browser and user stage.

2.6   Summary

The HTML structure of a photo flow page is in its essential parts (in this example the link to the left is inactive, while the one to the right is active):

<div class="photoflex">
    <div class="inactivebutton">
        ((to the left))
    </div>

    <div class="figure">
        <img src="((image))" />
        <p class="caption">
            ((figure caption))
        </p>
    </div>

    <div class="activebutton">
        <a href="((target))">
            ((to the right))
        </a>
    </div>
</div>

docutils adds some more classes and attributes, which however are of no relevance here.

The CSS markup runs entirely:

photoflex.css
div.photoflex {
    display: flex;
    justify-content: center;
}

div.photoflex > div.figure {
    width: 80%;
}
div.photoflex > div.figure > img {
    width: 100%;
}

div.photoflex > div.inactivebutton {
    display: grid;
    grid-template-columns: auto;
    grid-template-rows: auto;
    align-items: center;

    text-align: center;
    width: 2.5em;
}

div.photoflex > div.activebutton {
    display: flex;
    flex-direction: column;

    text-align: center;
    width: 2.5em;
}
div.photoflex > div.activebutton > a {
    display: grid;
    grid-template-columns: auto;
    grid-template-rows: auto;
    align-items: center;
    flex: auto;

    color: inherit;
    text-decoration: inherit;
}
div.photoflex > div.activebutton > a:hover {
    background: #333;
}

body {
    background: black;
    color: white;
}

h2 > a {
    color: inherit;
    text-decoration: inherit;
}
h2 > a:hover {
    text-decoration: revert;
}

The ReST code for generating the HTML shown above is:

.. container:: photoflex

    .. container:: inactivebutton

        ((to the left))

    .. figure:: ((image))

        ((image caption))

    .. container:: activebutton

        ((link to the target))

3   Deploying and Using the CSS File

The CSS file photoflex.css can be placed in the project's Sources/Supp/Common directory. It can then be included by writing an inclusion statement in the appropriate .blox file in that directory, e.g. Universal.blox:

Photo Flow Styles /css/ : photoflex.css ::

The purpose tag /css/ declares the file as a file used for CSS inclusions, and it will be included in the HTML result of all files processes by blox-rst2html which depend on (or use) this CSS file. The dependency can e.g. be stated in the ReST source file of pages using the photo flex styles by placing a blox dependency tag inside of it:

.. :Blox:`<-- photoflex.css`

For docutils, this is an ordinary ReST comment, while the Blox compiler will pick it up as a dependency tag, telling that the ReST file processed depends on (or uses) the file photoflex.css. Because the purpose of photoflex.css is "css", it will be included as a style sheet.

4   Example of Application

The following symbols may be used for the buttons:

Link Replacement Symbols Display
Link to the next picture |nextp| |srarr| →
Link to the previous picture |prevp| |slarr| ←
Inactive link to the next picture |no-nextp| |nrarr| ↛
Inactive link to the previous picture |no-prevp| |nlarr| ↚
Link back to the superordinate page |return| |slarr| ←

For access to these symbols, one can create a resource file, called here Photoflex.rst:

Photoflex.rst
.. |nextp| replace:: |srarr|
.. |prevp| replace:: |slarr|

.. |no-nextp| replace:: |nrarr|
.. |no-prevp| replace:: |nlarr|

.. |return| replace:: |slarr|

This file is placed expediently in the Supp/Common directory, from where it will be available for all languages. One can then include Photoflex.rst and use the replacements for designing the photoflex page. The symbols originate from the isoamsa.txt standard docutils definition file, included by:

.. include:: <isoamsa.txt>

The p in e.g. |nextp| serves for the distinction from the replacement |next|, which is used for versioning pages. This distinction isn't strictly neccessary, when photo flow pages are never versioned.

For versioned articles usually the title of the respective page is distinct from the link name, which is used to link the current version of the article in question. The latter one should coincide with the title of the last version of that article. However, since during the evolution of an article the title can vary from version to version, and because the actual choice for a given page possibly should not be amended later, it is not useful to use the ReST substitution inserting the current title in the headline of such a page. Things are different for photo flow pages: These are part of an article and contain only little versionable content; they don't feature a release date and their content can change as time goes by. Because of this, for photo flow pages it is useful to utilise the substitution used also elsewhere when referencing the page.

The substitution is defined in Articles.rst. As replacement name can e.g. be chosen the stamp used for the photo flow page. In pages referencing the photo flow page, a "local alias" can be defined.

In our example there are two photo flow pages with stamps 2023-04-08_1825 and 2023-10-31_1743, carrying the titles Starship before the Mun and Strongly Inclinated Orbit, respectively. The substitutions in Articles.rst thus run:

.. |2023-04-08_1825| replace:: Starship before the Mun
.. _2023-04-08_1825: 2023-04-08_1825.html

.. |2023-10-31_1743| replace:: Strongly Inclinated Orbit
.. _2023-10-31_1743: 2023-10-31_1743.html

The page, from which the photo flow shall be accessible, carries in this example here the article stamp 2023-02-09_2009. References back from the individual photo pages to this main page shall always refer to the last version of this including article, using 2023-02-09_2009_. This link always points to the last version of the article. In case that the page referenced changes, the Articles.rst file will be modified accordingly, and this will result in the recompilation of the entire project; in this way also the article referenced from the photo flow pages will be updated automatically.

We are assuming here that two pictures 01-009.png and 01-012.png exist, which are screen shots with a 16:9 aspect. These can be placed in the Article Supp directory and be transferred via bxsupp into the Supp directory of the project. They are then available for pages of the project as 2023-02-09_2009/01-009.png and 2023-02-09_2009/01-012.png.

The photo flow pages created in this example, resulting in page stamp files 2023-04-08_1825.rst and 2023-10-31_1743.rst in the Compound directory, have the following content:

2023-04-08_1825.rst
.. include:: Articles.rst
.. include:: Photoflex.rst
.. include:: <isoamsa.txt>

.. :Blox:`photoflex.css`

-de-
.. |subheading| replace:: |return| Zum Artikel
-en-
.. |subheading| replace:: |return| To the Article
-all-
.. _subheading: 2023-02-09_2012.html

.. _nextp: 2023-10-31_1743.html


|2023-04-08_1825|
#################

|subheading|_
*************

.. container:: photoflex

    .. container:: inactivebutton

        |no-prevp|

    .. figure:: 2023-02-09_2009/2023-12-06_1930/01-009.png

        -de-
        Das Raumschiff, wie es gerade auf den Mun zufliegt.
        -en-
        The starship, as it approaches Mun.
        -all-

    .. container:: activebutton

        |nextp|_
2023-10-31_1743.rst
.. include:: Articles.rst
.. include:: Photoflex.rst
.. include:: <isoamsa.txt>

.. :Blox:`photoflex.css`

-de-
.. |subheading| replace:: |return| Zum Artikel
-en-
.. |subheading| replace:: |return| To the Article
-all-
.. _subheading: 2023-02-09_2012.html

.. _prevp: 2023-04-08_1825.html


|2023-10-31_1743|
#################

|subheading|_
*************

.. container:: photoflex

    .. container:: activebutton

        |prevp|_

    .. figure:: 2023-02-09_2009/2023-12-06_1930/01-012.png

        -de-
        Ansicht der gegenüber der Ekliptik stark geneigten Bahn des
        Raumschiffs.
        -en-
        Depiction of the starship's orbit, which is strongly inclinated
        with respect to the ecliptic.
        -all-

    .. container:: inactivebutton

        |no-nextp|

The resulting photo flow pages are:

For the links shown here, the titles and the targets are inserted automatically per |2023-04-08_1825|_ and |2023-10-31_1743|_.

5   Discussion

In the div.inactivebutton section there is no subordinate element except the "anonymous" element comprised of the text of the inactive button. It is therefore impossible to associate to this text a flex: auto style, like it is happening for the div.activebutton > a element. Because of this reason, for div.inactivebutton display: grid is is applied with align-items: center. This then positions the text of the inactive button vertically in the centre of the button element.

When applying the same style now to a button whose text is comprised by an a element, then this anchor won't extend vertically over the entire height of the space aside of the picture. Instead, this link will be shown only in its natural height (vertically centred). The aim, that the link shall cover the whole height of the picture then isn't met.

To format the a element as intended, therefore display: flex; flex-direction: column is applied to the div.activebutton section, together with flex: auto for the a anchor contained within the button. The entire a element then occupies the requested vertical space.

Inside of the a link then the contained pure link text is formatted in the same way as the text of the inactive button. The grid styles for div.inactivebutton and for div.activebutton > a therefore are identical.

The a element as a:hover is attributed the style background: #333, such that the background colour changes when hovering as projected. It is required, that the a element has the required height, such that the user can click the link in the entire height. It is therefore not sufficient to just apply the background: #333 style to div.activebutton:hover.

It is thus not possible to use the same CSS class for both the active and the inactive button.