Slides

Imprint

Contents of this Page

1   Aim

The objective is the creation of web pages featuring a large picture or YouTube video in the centre, outfitted with buttons on the left and right sides for transiting to the next or previous slide. The central element shall feature a description text, stretching exactly over the width of the central content. The buttons shall be equally high as the element in the centre. When hovering 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 labelling.

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

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

.. container:: slide

    ((Button to the Left))

    ((The Photo or the Video))

    ((Button to the Right))

The text for a picture in the section ((The Photo or the Video)) shall be therein:

.. figure:: ((Raster Image))

    ((Picture Caption))

YouTube videos can be embedded utilising a HTML iframe element. Therefore, for a video shall be written in the ((The Photo or the Video)) section:

.. container:: youtube

    ((YouTube Embedding iframe))

    ((Description of the Video))

For the Buttons shall be written:

.. container:: ((Button Class))

    ((Button Text))

For the transition to the next slide, the ((Button Text)) of an according active button consists typically of a link with an unicode arrow as text content. Compared to this, inactive buttons contain their text directly without a surrounding link element.

Ideally, the ((Button Class)) for active and inactive Buttons is the same, and the different functionalities originate from the different elements of the button container (link with text or pure text). It is however acceptable when there are two classes: One for active buttons and another for inactive ones.

In this way it follows for a slide featuring a figure:

.. container:: slide

    .. container:: ((Button Class))

        ((Button Text))

    .. figure:: ((Raster Image))

        ((Picture Caption))

    .. container:: ((Button Class))

        ((Button Text))

and when using a YouTube video:

.. container:: slide

    .. container:: ((Button Class))

        ((Button Text))

    .. container:: youtube

        ((YouTube Embedding iframe))

        ((Description of the Video))

    .. container:: ((Button Class))

        ((Button Text))

2   Styles for the Various Elements

2.1   The slide Container

To enclose in the HTML result the contents of the slide by a div element, it is written as ReST code:

.. container:: slide

The buttons and the image or video of a slide 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.slide {
    display: flex;
    justify-content: center;
}

This turns the div.slide into a flex container (display: flex), and justify-content: center places the child elements directly next to each other, altogether horizontally centred.

2.2   Pictures

Figures, 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 slides;
  • the headline of the page as well as the description need a little bit of space.

The figures shall be described in the ReST code by an unmodified .. figure:: directive, as described in the Aim:

.. figure:: ((Raster Image))

    ((Figure Caption))

The tailoring for the purposes of a slide shall be achieved entirely by enclosing the figure by the div.slide container.

From a ReST figure it results as HTML outcome (shown here abbreviated w.r.t. the attributes):

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

A proper style for such figures is:

div.slide > div.figure {
    width: 160ex;
}
div.slide > div.figure > img {
    width: 100%;
}

This CSS code is sufficient for pictures all showing the same aspect ratio. When more choices are required, using the figwidth option for the ReST figure is 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: 160ex style for div.slide > div.figure can in this situation remain, it will be overridden by the :figwidth: option. In this way, the setting width: 160ex 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   YouTube Videos

Each YouTube video features an ID independent from its name, which appears in the URLs of the video, e.g. in https://youtube.com/watch?v=((ID)). In order to embed a YouTube Video in a web page, the following HTML code can be used:

<iframe
 src="https://www.youtube.com/embed/((ID))"
 title="YouTube video player"
 frameborder="0"
 allow="accelerometer; autoplay; clipboard-write; encrypted-media;
        gyroscope; picture-in-picture; web-share"
 allowfullscreen>
</iframe>

This raw HTML snippet is included by utilising the raw directive:

.. raw:: html

    <iframe
     src="https://www.youtube.com/embed/((ID))"
     ((...))>
    </iframe>

The analogue to the figure is thus, refining the draft from the Aim:

.. container:: youtube

    .. raw:: html

        <iframe
         src="https://www.youtube.com/embed/((ID))"
         ((...))>
        </iframe>

    ((Description of the Video))

Such Slides are then formatted by the following styles:

div.slide > div.youtube {
    width: 160ex;
    margin-left: 2em;
    margin-right: 2em;
}
div.slide > div.youtube > iframe {
    width: 160ex;
    height: 90ex;
}
div.slide > div.youtube > p {
    font-style: italic;
}

Here, the div.youtube element and also the iframe within it are formatted by width: 160ex; the iframe element additionally by height: 90ex. The width and height figures need to be given explicitly for the iframe element. Because both width as well as height need to be specified, no values like 80% can be used as width, because there is no corresponding styling method for the height. The aspect ratio of the numbers given in the stylesheet is appropriate for 16:9 videos.

For the width of the description at the bottom side of the video, the width style of the div.youtube element is sufficient. Following the style of docutils figures, the caption is formatted with font-style: italic, and to the left as well as to the right of the div.youtube element 2em are left as space.

2.4   Active Buttons

Active buttons use a link, coded by an a element with a certain text. The text can be an arrow. The text of an active button is contained inside of the a element. To make these contents of an active button accessible for styling by CSS, it is enclosed by a container:

.. container:: activebutton

    ((Link))

The a element shall stretch over the entire height of the content in the centre of the slide. This can be obtained by:

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

    text-align: center;
    width: 2.5em;
}
div.slide > 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 centre the text inside of the a element (the link text) also 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.

2.5   Inactive Buttons

Inactive buttons consist of pure text, typically a (striked-through) unicode arrow. One can write:

.. container:: inactivebutton

    ((Text))

Such a button can be implemented by the following CSS code:

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

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

In this way, the inactivebutton section is declared by display: grid as a grid container, for which per grid-template-columns: auto and grid-template-rows: auto exactly one colum and one row are created.

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.

3   The Entire Style Sheet

The styles for the body of a slide run all in all:

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

div.slide > div.figure {
    width: 160ex;
}
div.slide > div.figure > img {
    width: 100%;
}

div.slide > div.youtube {
    width: 160ex;
    margin-left: 2em;
    margin-right: 2em;
}
div.slide > div.youtube > iframe {
    width: 160ex;
    height: 90ex;
}
div.slide > div.youtube > p {
    font-style: italic;
}

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

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

    color: inherit;
    text-decoration: inherit;
}

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

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

4   Patterns of Application

With the styles developed, the structures of the Aim can be implemented concretely.

4.1   Slide with a Picture

The ReST source of a slide with a picture is structured in the following manner (in this example the link to the left is inactive, while the one to the right is active):

.. container:: slide

    .. container:: inactivebutton

        ((to the left))

    .. figure:: ((image))

        ((image caption))

    .. container:: activebutton

        ((link to the target))

The HTML structure of this slide is in its essential parts (docutils adds here some more classes and attributes more, which however are of no relevance here):

<div class="slide">
    <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>

4.2   Slide with a YouTube Video

A slide with a YouTube video can be created from the following ReST source (here with inactive button to the left and active button to the right):

.. container:: slide

    .. container:: inactivebutton

        ((to the left))

    .. container:: youtube

        .. raw:: html

            <iframe
             src="https://www.youtube.com/embed/((ID))"
             title="YouTube video player"
             frameborder="0"
             allow="accelerometer; autoplay; clipboard-write; encrypted-media;
                    gyroscope; picture-in-picture; web-share"
             allowfullscreen>
            </iframe>

        ((video description))

    .. container:: activebutton

        ((link to the target))

The resulting HTML structure can be outlined as (with especially the iframe abridged):

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

    <div class="youtube">
        <iframe src="https://www.youtube.com/embed/((ID))"></iframe>
        <p>((video description))</p>
    </div>

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

5   Examples

5.1   Custom Styles

The CSS rules developed in this section are specific for demonstrating the styles given in The Entire Style Sheet.

5.1.1   The Colour of the Page Background

To display the picture or the video on black background with white text colour, the following CSS is appropriate:

body {
    background: black;
    color: white;
}

5.1.2   Hovering Active Buttons

To tailor the background of the link element in an active button when hovering it with the mouse, one can write:

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

5.1.3   Links Pointing Back to the Source Article

The slide page needs a link pointing back to the article, to which the slide belongs. For this, the subheading of the page (not to be confused with the caption of the picture or video) 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. For this, one can write:

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

text-decoration: inherit inhibits for links in subtitles (selected by h2 > a) underlining. text-decoration: revert reverts this declaration (of the author Stylesheet) for such links when hovering them with the mouse, such that the respective links can be displayed again with underlining, according to the browser and user stylesheets. The colour of the link text is inherited always from the surrounding element (color: inherit).

5.1.4   Summary

This results in total for the custom styles used here:

slides-custom.css
body {
    background: black;
    color: white;
}

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

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

5.2   Labelling of the Buttons

The following symbols may be used for the buttons:

Link Replacement Symbol Display
Link to the next slide |nextslide| |srarr| →
Link to the previous slide |prevslide| |slarr| ←
Inactive link to the next slide |no-nextslide| |nrarr| ↛
Inactive link to the previous slide |no-prevslide| |nlarr| ↚
Link back to the superordinate page |return| |slarr| ←

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

Slides.rst
.. |nextslide| replace:: |srarr|
.. |prevslide| replace:: |slarr|

.. |no-nextslide| replace:: |nrarr|
.. |no-prevslide| 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 Slides.rst and use the replacements for designing the slides. The symbols originate from the isoamsa.txt standard docutils definition file, included by:

.. include:: <isoamsa.txt>

5.3   Headlines

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 slide 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 slides it is useful to utilise for the title line 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 slide. In pages referencing the slide, a "local alias" can be defined.

In our example there are two slides with stamps 2024-03-29_1105 and 2024-03-29_1133, carrying the titles Starship before the Mun and YouTube Example, respectively. The substitutions in Articles.rst thus run:

.. |2024-03-29_1105| replace:: Starship before the Mun
.. _2024-03-29_1105: 2024-03-29_1105.html

.. |2024-03-29_1133| replace:: YouTube Example
.. _2024-03-29_1133: 2024-03-29_1133.html

5.4   Backreferences

The page, which is backreferred to from the slide, can be an individual page or the last page of the corresponding article. In the former case, one uses the name of the particular HTML page, in the latter case the article's stamp link is used instead.

In our case the article carries the stamp 2023-02-09_2009. A backreference to the last page of this article would therefore run 2023-02-09_2009_. The examples provided here however belong specifically to the present version of the article, which is therefore also the target of the backreferences in the slides.

5.5   Results

We are assuming here that a picture 01-009.png and a YouTube video with ID onsVKidGqTQ exist. Both are in 16:9 aspect. The picture is in our case made available as 2023-02-09_2009/2024-03-29_1103/01-009.png.

The slides created in this example, resulting in page stamp files 2024-03-29_1105.rst and 2024-03-29_1133.rst in the Compound directory, have the following content:

2024-03-29_1105.rst
.. include:: Slides.rst
.. include:: <isoamsa.txt>

.. :Blox:`slides.css`

.. |subheading| replace:: |return| To the Article
.. _subheading: 2024-03-29_1100.html

.. _nextslide: 2024-03-29_1133.html


|2024-03-29_1105|
#################

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

.. container:: slide

    .. container:: inactivebutton

        |no-prevslide|

    .. figure:: 2023-02-09_2009/2024-03-29_1103/01-009.png

        The starship, as it approaches Mun.

    .. container:: activebutton

        |nextslide|_
2024-03-29_1133.rst
.. include:: Slides.rst
.. include:: <isoamsa.txt>

.. :Blox:`slides.css`

.. |subheading| replace:: |return| To the Article
.. _subheading: 2024-03-29_1100.html

.. _prevslide: 2024-03-29_1105.html


|2024-03-29_1133|
#################

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

.. container:: slide

    .. container:: activebutton

        |prevslide|_

    .. container:: youtube

        .. raw:: html

            <iframe
             src="https://www.youtube.com/embed/onsVKidGqTQ"
             title="YouTube video player"
             frameborder="0"
             allow="accelerometer; autoplay; clipboard-write; encrypted-media;
                    gyroscope; picture-in-picture; web-share"
             allowfullscreen>
            </iframe>

        Angle of departure 60 degrees, unlocking of the parachute in the
        highest path point.  Full forward control stick pressure in the
        ascending branch.  The maximum height reached is above the release
        height of the parachute.  The velocity in the height of this
        threshold is small enough to permit releasing the parachute.
        Inflation and landing according to plan.  Approximately above the
        coast switching to height above ground.

    .. container:: inactivebutton

        |no-nextslide|

The resulting slides are:

For the links shown here, the titles and the targets are inserted automatically per |2024-03-29_1105|_ and |2024-03-29_1133|_.

6   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 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 or video. 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 central content 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 a element then occupies the entire vertical space reserved for it.

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.

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

The a element as a:hover is attributed (by the custom style sheet) 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.

Using width: 160ex for the div.figure element places the picture together with the caption using up less then the full viewport width. Within this div section the picture img element is then rendered with exactly the same width (width: 100%). 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 160ex for the width of the picture or video is appropriate to display 16:9 material 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 measure 160ex has been chosen such, that at least the central element fits on screen vertically when the page is not watched full-screen. Would one want to show in addition the titleing and the description outside of full-screen mode, the required size reduction of the picture or video would be too strong.