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.
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.
The figure, consisting of picture and picture legend, shall be displayed smaller than the viewport width:
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.
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.
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; }
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.
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))
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.
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|_.
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.