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))
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.
Figures, consisting of picture and picture legend, shall be displayed smaller than the viewport width:
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.
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.
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.
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.
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; }
With the styles developed, the structures of the Aim can be implemented concretely.
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>
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>
The CSS rules developed in this section are specific for demonstrating the styles given in The Entire Style Sheet.
To display the picture or the video on black background with white text colour, the following CSS is appropriate:
body { background: black; color: white; }
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; }
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).
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; }
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>
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
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.
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|_.
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.