cyberweb 0.5.225 → 0.6.17

data/README.md

@@ -2,9 +2,9 @@
 [![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
 [![Gem Version](https://badge.fury.io/rb/cyberweb.svg)](https://badge.fury.io/rb/cyberweb)
 
-This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">17.10.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">17:36:14</span> o'clock.
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">01.11.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">19:17:06</span> o'clock.
 
-<img src="https://i.imgur.com/aNpDmmz.png" style="margin-left: 1.2em">
+<img src="https://i.imgur.com/aC4YzSk.png" style="margin-left: 1.2em">
 
 ## The (slightly convoluted) History of the Cyberweb project
 
@@ -35,23 +35,31 @@ the following:
     div {
     }
 
-In PHP this is not easily possible, because the syntax is more rigid,
-so ruby is better in this regard - more flexibility in this regard.
-
-During that **transition phase**, from **php** to **ruby**, the project
-was renamed several times - first to **web_foundation**, then to
-**cybersprawl**, then to **Cyberweb**, then to **web_object** and
-then back to **Cyberweb** again. I think the name **Cyberweb** 
-is best among these alternatives. While **web_object** is the
-more technically correct and accurate term, as everything related
-to the www is handled via that object (or such objects), I prefer the
-name **Cyberweb** in general for the whole project - it sounds
-rather futuristic. The name **WebObject** is a good name too,
-though, as we attempt to describe a particular "web-page" as a
-"web-object", with specific functionality, basically.
+In PHP this is not easily possible, because the syntax is more rigid.
+Thus, at the least in regards to the syntax, ruby is better than 
+PHP - more flexibility syntax-wise is available to ruby users than
+is for PHP users. This flexibility helps a <b>lot</b> when writing
+more dynamic, and more succint, code.
+
+During that **transition phase**, from **php** to **ruby**, the cyberweb
+project was renamed several times as well - first to **web_foundation**,
+then to **cybersprawl**, then to **Cyberweb**, then to **web_object** and
+then back to **Cyberweb** again.
+
+I think the name **Cyberweb** is the best choice best among these alternatives.
+While **web_object** is the more technically correct and accurate term, as
+everything related to the www is handled via that object (or such objects),
+I prefer the name **Cyberweb** in general for the whole project - it sounds
+rather futuristic. The name **WebObject** is a good name too, though, as
+we attempt to describe a particular "web-page" as a "web-object", with
+specific functionality, basically. The WebObject not only describes the
+raw HTML code or combines it with CSS, but it can be thought of as a 
+higher hierarchy abstraction. In principle we could generate a .pdf
+file from a WebObject too, so the functionality is not limited to
+"merely" HTML or CSS only.
 
 **class WebObject** was originally the very main class I was
-using in PHP to describe my local knowledge base, an "app" where
+using in PHP to describe my <b>local knowledge base</b>, an "app" where
 I kept useful information bits about linux, and ruby, and other 
 parts together. The code for this project in PHP was simpler, and
 also uglier though, and less flexible. (Actually the name was
@@ -193,7 +201,7 @@ hopefully more "modern" as well, as I work on improving the documentation
 in the next step (no possibility to have more users without **high
 quality documentation**).
 
-Since June 2021 two new goals were added to this project:
+Since <b>June 2021</b> two new goals were added to this project:
 
 - It will contain documentation in regards to useful CSS knowledge.
 - It will contain documentation in regards to useful JavaScript knowledge.
@@ -208,24 +216,171 @@ presented (and presentable) in a single project as well. This means
 that there may be pure CSS, pure HTML and pure JavaScript 
 examples distributed within the Cyberweb project as well.
 
-## Features
+## Features of the Cyberweb project
 
-For a more complete documentation of the above features, please check
-out the file FEATURES.
+The cyberweb project attempts to address multiple different use
+cases, so it is difficult to provide an overview over its
+features; in part also due to its fuzzy history.
 
-- You can select various different default CSS templates. They will be
-  stored in the CSS/ directory by default. To use them, pass a symbol
-  to the method invocation for css_style=(). They are numbered in
-  succession, so template1, template2 etc..
+However had, this subsection will at the least try to name <b>some</b>
+of its features - keep in mind that ultimately it is about the
+use cases <b>you</b> may have that matter more.
+
+In no particular order, the cyberweb gem attempts to solve these
+problems:
+
+- Provide support for rack, sinatra and .cgi files for "out of the
+box" working with web-related technology in general.
+
+- Provide numerous helper methods in various classes (most importantly
+in Cyberweb::Base) to help build web-applications.
+
+- Be able to generate standalone .html files.
+
+- Provide a unified DSL over web-related use cases.
+
+- Support CSS-related aspects, including auto-generation of
+CSS code and re-using CSS templates.
+
+- Aim to provide a webmin-clone.
+
+- Aim to provide a wiki.
+
+- Aim to provide a webforum.
+
+And many more use cases that are somehow related to these goals.
+
+Not all of these use cases currently work fully; the cyberweb gem
+in many ways is also there to help me experiment with different
+ideas, and try to see what could be done to make these work.
+
+A word about "CSS templates": you can select various different default
+CSS templates. They will be stored in the <b>cascading_style_sheets/</b>
+directory by default. To use them, pass a symbol to the method
+invocation for css_style=(). They are numbered in succession, so
+template1, template2 etc..
 
 Example for this on the main w object:
  
-   w.css_style = :template1
+    w.css_style = :template1
  
 This will default to the template1.
- 
+
+Alternatively since October 2022 you can simply use this, if you work
+with a WebObject:
+
+    template1 '
+      # your CSS rules go in here
+    '
+
+This will pull in the first template (template1) and then add the
+CSS rules towards that.
+
 Currently the way to add new templates is to expand the case menu.
 
+## Adapting the cyberweb gem to your use cases
+
+Presently it may be a bit difficult to adjust the cyberweb gem to
+your use cases. The primary reason for this is that the cyberweb
+gem was originally started to support my use cases, as well as
+making available images that I have collected over many years.
+So that explaines why the method img(), for instance, is defaulting
+to a fairly weird use case, which means that it may not work for
+your use cases initially. In the long run I intend to remedy this
+situation, but for the time being, you have to accept that some
+parts of the cyberweb gem are not useful for you.
+
+Nonetheless, I decided to add this subsection to document some
+things, and provide some help to new users, until eventually
+the situation improves so that people can just install the gam
+and "it will work", as-is.
+
+Without further ado, let's clarify some things here next.
+
+The cyberweb gem needs access to a temporary directory.
+
+On Linux this is typically <b>/tmp/</b>. The cyberweb gem may
+create a subdirectory there, called cyberweb/, and then copy
+some files into that subdirectory - in particular JavaScript
+.js files.
+
+To query the base directory in use you can call this method:
+
+    Cyberweb.temp_directory?
+
+If you want to use another temporary directory then you can
+use this method:
+
+    Cyberweb.set_temp_directory('/opt/')
+
+You need to make the permission bits on that directory
+possibly to be modified, such as /tmp/ on Linux normally
+is able to be modified by <b>group and user nobody</b> (or,
+the user that runs the webserver; in my case this is typically
+lighty, as I use lighttpd as my primary webserver).
+
+The code for this functionality can be found here:
+
+    cyberweb/toplevel_methods/temp_directory.rb
+
+Or the direct require command:
+
+    require 'cyberweb/toplevel_methods/temp_directory.rb'
+
+This is a very important first step to do, to adjust
+the temp directory to your use case.
+
+I may add more code support for this step in the future;
+for now (October 2022) I just wanted to document this,
+so people know where to look for changes in this regard.
+
+## Include the cyberweb project on a website
+
+To include the cyberweb project on a website, in your .cgi script
+for instance, do use this line:
+
+    require 'cyberweb/autoinclude'
+
+You can then populate the @web_object object, which resides in the
+main Cyberweb-namespace, and which is also aliased through a
+convenience method called w(). If you autoinclude Cyberweb
+then you can use the w() method directly.
+
+This allows you to describe a webpage, such as by issuing the 
+following code:
+
+    w {
+      title 'My first homepage'
+      body_css 'mar1em'
+      h2 'Hello World!'
+      use_jquery
+    }
+
+Note that this should happen on separate lines - the description
+here for the gem does not replace newlines with the html <br> tag.
+
+Inside **w {}** you can issue special instructions, such as use_jquery
+or disable_webimages. The former allows us to use jquery, the latter
+disables webimages. (Webimages are small icons that I find myself
+to use a lot. If you wish to use these images, have a look at
+
+  http://shevegen.square7.ch/STD.tar.xz
+
+)
+
+## Proper (default) order of arguments to many methods in the Cyberweb project
+
+The Cyberweb project uses quite a few methods that have more than 4
+or 5 parameters.
+
+The typical order for these methods is the following:
+
+(**1**) the content belonging to the tag at hand
+(**2**) the css class that is to be used for that tag (defaults to class WebTag)
+(**3**) the id to that HTML element (optional)
+(**4**) the css style for that tag (optional)
+(**5**) javascript code to that tag (optional)
+
 ## CSS templates
 
 CSS templates can be designated by assigning to a symbol, such as
@@ -283,19 +438,6 @@ display the above notification for images not found. If it is set
 to normal or lower than that, the web_object project will not
 display that warning.
 
-## Proper (default) order of arguments to many methods in the Cyberweb project
-
-The Cyberweb project uses quite a few methods that have more than 4
-or 5 parameters.
-
-The typical order for these methods is the following:
-
-(**1**) the content belonging to the tag at hand
-(**2**) the css class that is to be used for that tag (defaults to class WebTag)
-(**3**) the id to that HTML element (optional)
-(**4**) the css style for that tag (optional)
-(**5**) javascript code to that tag (optional)
-
 ## Greek letters
 
 The old greek letters are specified via shortcuts such as <b>&sigma;</b>
@@ -308,18 +450,6 @@ the following command:
 
     Cyberweb.show_greek_letters
 
-## SVG
-
-If you wish to make use of SVG it is recommended to install the
-**svg_paradise** project. Then, you can use it through Cyberweb
-such as in the following case:
-
-    ee Cyberweb.circle
-
-This will output a SVG circle. Do note that this can be customized;
-simply have a look for the SVG Paradise project for more
-documentation pertaining to this part.
-
 ## Javascript-support in the Cyberweb project
 
 Have a look at the subdirectory called **javascript/**.
@@ -364,40 +494,6 @@ Since as of **April 2019**, the old .cgi approach will be extended;
 while .cgi will be always supported in the Cyberweb project, an
 approach similar to **sinatra** will eventually be adopted as well.
 
-## Include the cyberweb project on a website
-
-To include the cyberweb project on a website, in your .cgi script
-for instance, do use this line:
-
-    require 'cyberweb/autoinclude'
-
-You can then populate the @web_object object, which resides in the
-main Cyberweb-namespace, and which is also aliased through a
-convenience method called w(). If you autoinclude Cyberweb
-then you can use the w() method directly.
-
-This allows you to describe a webpage, such as by issuing the 
-following code:
-
-    w {
-      title 'My first homepage'
-      body_css 'mar1em'
-      h2 'Hello World!'
-      use_jquery
-    }
-
-Note that this should happen on separate lines - the description
-here for the gem does not replace newlines with the html <br> tag.
-
-Inside **w {}** you can issue special instructions, such as use_jquery
-or disable_webimages. The former allows us to use jquery, the latter
-disables webimages. (Webimages are small icons that I find myself
-to use a lot. If you wish to use these images, have a look at
-
-  http://shevegen.square7.ch/STD.tar.xz
-
-)
-
 ## Configuration - and editing the configuration file (which is a yaml file)
 
 Keep in mind that you can modify a lot of the configuration that
@@ -539,7 +635,43 @@ I sometimes use the pre-tag, and display numbers in a table-fashion,
 for where it may be useful to use a monospaced font, so that the
 alignment of the text is easier.
 
-## Setting a title on a webobject
+## The WebObject (Cyberweb::WebObject)
+
+The following subsection will contain information pertaining to
+the most important class of this gem: <b>WebObject</b>.
+
+This is the primary class that is used for describing a 
+web-application (or, in oldschool parlance, a HTML object
+or HTML page).
+
+## Setting the date-of-creation for a web-app based on WebObject
+
+Since as of **October 2021** you can use:
+
+    created_when '20.08.2021'
+
+To **indicate when the webpage at hand has been created**. This will then
+add a meta-element to the page, which is roughly equivalent to:
+
+    <meta name="DCTERMS.created" scheme="DCTERMS.ISO8601" content="2010-03-17T13:31:50"/>
+
+I am not sure whether this is super-useful or not, but I wanted
+to add a method that keeps track of the creation-time of 
+web-apps based on web_object, which is the main reason why
+this functionality was added. At the least it helps me remember
+when a web-app was created.
+
+### Default hyperlinks
+
+The default styling for a-tags in HTML is to start with
+text-decoration: none, and upon a <b>hover</b> event
+change towards text-decoration: underline.
+
+Since this is so commonly used, the method
+<b>.default_hyperlink_behaviour()</b> can be used
+to add the CSS rules for this, as-is.
+
+### Setting a title on a webobject
 
 You can set a title on the default webobject via:
 
@@ -910,7 +1042,7 @@ Normal text usually equates to a font-weight value of
 <b>400</b> whereas bold text equals to a value of
 <b>700</b>.
 
-## Caret cursor in CSS
+## Caret cursor in CSS and cursors in general
 
 You can style the colour of the cursor that appears in an
 input-field.
@@ -933,6 +1065,14 @@ This may then look like this:
 
 The relevant part is the red cursor in the ~middle in that input field.
 
+If you have a use case for a web-page having some different cursor,
+you can use this for a given Cyberweb::WebObject:
+
+    cursor :wait        # signals that the program is busy.
+    cursor :help        # signals that help-information is available.
+    cursor :crosshair   # signals that a selection is possible/needed.
+    cursor :grab        # signals that this element can be grabbed via the mouse/pointer device.
+
 ## CSS helper code and how it relates to the Cyberweb project
 
 This subsection attempts to detail how the **cyberweb** project
@@ -2277,23 +2417,27 @@ is via:
     doc {
     }
 
-This **doc** refers to document and is ultimately just a <div>
-tag. So I put my web-applications into a big <div> tag
+This **doc** refers to document and is ultimately just a &lt;div>
+tag. So I put my web-applications into a big &lt;div> tag
 ultimately.
 
-Since late 2020 I am also using language variants such as:
+Since as of late <b>2020</b> I am also using language variants such
+as:
 
     english {
     }
+
     # or
+
     german {
     }
 
-To denote a webpage in german, or in english. Not as 
-replacement for doc {}, but as the start point in
-general.
+The latter is used for denoting that this webpage is written
+in german, and the former is used when the webpage is written in
+english. This is not a replacement for doc {}, but is the starting
+point I use for describe a web-object in general.
 
-In June 2021 this was extended in that I added the method
+In <b>June 2021</b> this was extended in that I added the method
 called:
 
     doc_skeleton
@@ -2301,20 +2445,22 @@ called:
 The word <b>skeleton</b> refers to a separate file, the
 skeleton of the web-application.
 
-Say that you have five called index.rb, index.cgi,
+Say that you have <b>five</b> files called index.rb, index.cgi,
 index.sinatra, index_english.md and index.german.md.
 
 This allows us to read in either the english or the german
-language.
+language, as-is.
 
 To let the cyberweb project guess on its own, consider
 using a variant via the following Symbol:
 
     doc_skeleton(:english_or_german)
 
-This currently defaults to german. You can pass ?use_english
-or ?english to the .cgi page to overrule this and force
-the web-application to view the english content instead.
+This currently defaults to <b>german</b>. You can pass <b>?use_english</b>
+or <b>?english</b> to the .cgi page to overrule this and force
+the web-application to view the english content instead. That way
+the user can change languages, as-is. A bit cumbersome for now,
+but possible.
 
 In order for this to work, the corresponding .md file must
 exist, e. g. **index_english.md** or **index_german.md**.
@@ -2323,12 +2469,12 @@ Note that this is currently (June 2021) quite experimental,
 but I wanted to add the feature that we can offer different
 languages. In the long run I may adapt this approach, to
 make it easier to use different languages on any given 
-weba-application, but for now I only use this in the
-**roebe** gem. For example, luft.cfg under **roebe/www/luft/**
+web-application, but for now I only use this in the
+**roebe** gem. For example, <b>luft.cfg</b> under **roebe/www/luft/**
 will show this. It may not work on your home system,
-though, as it is catered to my home setup. But it shows
-how this could be done in theory. So, who knows - in the
-long run I may integrate this as a 'default' feature.
+though, as it is catered to my home setup currently. But it
+shows how this could be done in theory. So, who knows - in
+the long run I may integrate this as a 'default' feature.
 
 Note that **?use_german** will work as well, to force
 the **_german.md** file to be read.
@@ -2799,82 +2945,6 @@ You can add content via CSS like this:
 I don't think this is too overly useful when you can dynamically
 generate the web-app as-is, though.
 
-## Cyberweb::HtmlTemplate
-
-class **Cyberweb::HtmlTemplate** can be used to fill it with HTML
-specific content.
-
-Let's show a specific example how this may be used:
-
-    require 'cyberweb/requires/require_the_html_template.rb' # This is the recommended way to require class HtmlTemplate.
-
-    Cyberweb::HtmlTemplate[
-      title: 'Status',
-      body:  '<pre style="font-size:150%">'+
-             ::EnvironmentInformation.return_the_most_important_info+
-               '</pre>'
-    ].to_s
-
-This would represent a "full" HTML page, as a String.
-
-It is possible, since as of **18.06.2021**, to pass **CSS classes**
-into this, via:
-
-    css_classes:
-
-For example, passing 'darkblue' to that key means that the CSS
-class 'darkblue' will be made available, which ultimately comes
-down to <b>color: darkblue</b>.
-
-I needed this functionality to pull in only the CSS classes
-that I use on a particular page generated by class
-Cyberweb::HtmlTemplate.
-
-Various additional entries are available. For example, if
-you want to modify the css-style in use for the body tag
-then you can simply use the following variant:
-
-    body_css_style: 'background-color:#DFD1FF'
-
-In the long run the goal here is to extend class HtmlTemplate
-in such a way that all html-generation used within the
-Cyberweb project can be handled by it.
-
-You can also pass ad-hoc CSS style into it. Example:
-
-    Cyberweb::HtmlTemplate[
-      body:  _, # The content of <body> goes in here.
-      css_style: '
-        img {
-          border: 8px solid #black;
-          padding: 2px;
-        }
-        ' # and ^^^ there you can put your CSS rules into class HtmlTemplate
-    ].to_s
-
-You can also pass in some ad-hoc javascript code via:
-
-    javascript_code:
-
-All this does is add the proper &lbrack;script> tag to it.
-
-You can also specifically add jquery support for the HtmlTemplate.
-The following example shows how this can be done:
-
-    html_template = Cyberweb::HtmlTemplate[
-      title:      'This is a test-page,
-      body:       HtmlTags.p('Another test.','','','font-size:1.8em'),
-      use_jquery: true
-    ].to_s
-
-    puts html_template
-
-Typing <b>Cyberweb::HtmlTemplate[]</b> is quite cumbersome, though. Since
-as of October 2022 a simpler toplevel API is available:
-
-    Cyberweb.html_template
-    Cyberweb.html_template(body_content) # The String you pass here will be the body of the HTML page.
-
 ## Embed youtube videos and videos in general
 
 You can embed youtube videos, thanks to the MultimediaParadise
@@ -3116,23 +3186,6 @@ local file, if said remote website contains german umlauts.
 
 In fact this was precisely the reason why that method was added.
 
-## Setting the date-of-creation for a web-app based on WebObject
-
-Since as of **October 2021** you can use:
-
-    created_when '20.08.2021'
-
-To **indicate when the webpage at hand has been created**. This will then
-add a meta-element to the page, which is roughly equivalent to:
-
-    <meta name="DCTERMS.created" scheme="DCTERMS.ISO8601" content="2010-03-17T13:31:50"/>
-
-I am not sure whether this is super-useful or not, but I wanted
-to add a method that keeps track of the creation-time of 
-web-apps based on web_object, which is the main reason why
-this functionality was added. At the least it helps me remember
-when a web-app was created.
-
 ## autogenerated_system_settings.yml
 
 The file <b>cyberweb/yaml/autogenerated_system_settings.yml</b> is created
@@ -3840,46 +3893,6 @@ Including the namespace for <b>Cyberweb::Objectified::Mask</b> is
 done mostly for convenience, so that the user does not have to
 manually include this module.
 
-## Drawing a coloured circle via CSS
-
-You can draw a circle via CSS.
-
-Let's first show the CSS rules for this:
-
-    div.circle {
-      width: 300px;
-      height: 300px;
-      background: #2762e9;
-      border-radius: 50%;
-    }
-
-Next you can use HTML to draw the circle:
-
-   <div class="circle"></div>
-
-That's it.
-
-I found this to be simple and potentially useful, so I added
-an API to the cyberweb project to support this.
-
-The API goes like this:
-
-    Cyberweb.draw_circle()
-    Cyberweb.draw_circle(width: 200)
-    Cyberweb.draw_circle(width: 200, height: 500)
-    Cyberweb.draw_circle(width: 200, height: 500, background_color: :steelblue)
-    Cyberweb.draw_circle(width: 200, height: 500, background_color: :steelblue, border_radius: '30%')
-
-Pass a Hash to the method. Note that this will return the CSS rule
-as-is, as well as return the div-tag String. Cyberweb::BaseModule
-will directly embed this if you use <b>draw_circle()</b>.
-
-Here is a partial screenshot showing three such examples; only the
-second example has a border-radius of 50%. See also the example
-<b>cyberweb/examples/advanced/draw_circle/draw_circle.cgi</b>.
-
-<img src="https://i.imgur.com/k5wFnwn.png" style="margin: 1em">
-
 ## JQuery
 
 The Cyberweb framework/toolset favours the use of jquery. Presently,
@@ -4460,6 +4473,193 @@ The general syntax goes like this:
     @keyframes name_here {
     }
 
+## module Cyberweb::JqueryModule
+
+<b>module Cyberweb::JqueryModule</b> is used to enable or disable support
+for jquery. Not all classes in the cyberweb gem make use of this module
+right now - notably class <b>Cyberweb::WebObject</b> does not use this
+module as of yet. This is planned at some later time in the future, as
+some code has to be re-written, in order to make use of this new
+module.
+
+The only class that uses module <b>Cyberweb::JqueryModule</b> right
+now is <b>class Cyberweb::HtmlTemplate</b>.
+
+## CSS Borders
+
+CSS supports different borders.
+
+You can control various different aspects here, such as the
+width of the border, or the style of the border.
+
+The available <b>border-style properties</b> are as follows:
+
+    dotted - Defines a dotted border.
+    dashed - Defines a dashed border.
+    solid  - Defines a solid border.
+    double - Defines a double border.
+    groove - Defines a 3D grooved border. This effect depends on the border-color value.
+    ridge  - Defines a 3D ridged border. This effect depends on the border-color value.
+    inset  - Defines a 3D inset border. This effect depends on the border-color value.
+    outset - Defines a 3D outset border. This effect depends on the border-color value.
+    none   - Defines no border.
+    hidden - Defines a hidden border.
+
+The following paragraph shows how you can use this:
+
+    p.dotted {border-style: dotted;}
+    p.dashed {border-style: dashed;}
+    p.solid  {border-style: solid; }
+    p.double {border-style: double;}
+    p.groove {border-style: groove;}
+    p.ridge  {border-style: ridge; }
+    p.inset  {border-style: inset; }
+    p.outset {border-style: outset;}
+    p.none   {border-style: none;  }
+    p.hidden {border-style: hidden;}
+    p.mix    {border-style: dotted dashed solid double;}
+
+Interestingly enough, if you do not specify a color for
+the border via border-color then this will default to <b>black</b>.
+
+## Cyberweb::HtmlTemplate
+
+class **Cyberweb::HtmlTemplate** can be used to fill it with HTML
+specific content.
+
+Let's show a specific example how this may be used:
+
+    require 'cyberweb/requires/require_the_html_template.rb' # This is the recommended way to require class HtmlTemplate.
+
+    Cyberweb::HtmlTemplate[
+      title: 'Status',
+      body:  '<pre style="font-size:150%">'+
+             ::EnvironmentInformation.return_the_most_important_info+
+               '</pre>'
+    ].to_s
+
+This would represent a "full" HTML page, as a String.
+
+It is possible, since as of **18.06.2021**, to pass **CSS classes**
+into this, via:
+
+    css_classes:
+
+For example, passing 'darkblue' to that key means that the CSS
+class 'darkblue' will be made available, which ultimately comes
+down to <b>color: darkblue</b>.
+
+I needed this functionality to pull in only the CSS classes
+that I use on a particular page generated by class
+Cyberweb::HtmlTemplate.
+
+Various additional entries are available. For example, if
+you want to modify the css-style in use for the body tag
+then you can simply use the following variant:
+
+    body_css_style: 'background-color:#DFD1FF'
+
+In the long run the goal here is to extend class HtmlTemplate
+in such a way that all html-generation used within the
+Cyberweb project can be handled by it.
+
+You can also pass ad-hoc CSS style into it. Example:
+
+    Cyberweb::HtmlTemplate[
+      body:  _, # The content of <body> goes in here.
+      css_style: '
+        img {
+          border: 8px solid #black;
+          padding: 2px;
+        }
+        ' # and ^^^ there you can put your CSS rules into class HtmlTemplate
+    ].to_s
+
+You can also pass in some ad-hoc javascript code via:
+
+    javascript_code:
+
+All this does is add the proper &lbrack;script> tag to it.
+
+You can also specifically add jquery support for the HtmlTemplate.
+The following example shows how this can be done:
+
+    html_template = Cyberweb::HtmlTemplate[
+      title:      'This is a test-page,
+      body:       HtmlTags.p('Another test.','','','font-size:1.8em'),
+      use_jquery: true
+    ].to_s
+
+    puts html_template
+
+You can also pass in a favicon to use such as shown in the following
+example:
+
+    Cyberweb::HtmlTemplate[
+      title: 'Current Time',
+      body:  '<b>'+Roebe::Time.hh_mm_ss+' '+Roebe::Time.dd_mm_yyyy+'</b>',
+      favicon: BeautifulUrl[:time_favicon]
+    ].to_s
+
+Typing <b>Cyberweb::HtmlTemplate[]</b> is quite cumbersome, though. Since
+as of October 2022 a simpler toplevel API is available:
+
+    Cyberweb.html_template
+    Cyberweb.html_template(body_content) # The String you pass here will be the body of the HTML page.
+
+## SVG
+
+If you wish to make use of SVG it is recommended to install the
+**svg_paradise** project. Then, you can use it through Cyberweb
+such as in the following case:
+
+    ee Cyberweb.circle
+
+This will output a SVG circle. Do note that this can be customized;
+simply have a look for the SVG Paradise project for more
+documentation pertaining to this part.
+
+## Drawing a coloured circle via CSS
+
+You can draw a circle via <b>CSS</b>.
+
+Let's first show the pure CSS rules for this functionality:
+
+    div.circle {
+      width: 300px;
+      height: 300px;
+      background: #2762e9;
+      border-radius: 50%;
+    }
+
+Next you can use HTML to actually "draw" the circle, as-is:
+
+   <div class="circle"></div>
+
+That's it.
+
+I found this to be simple and potentially useful, so I added
+an API to the cyberweb project to support this.
+
+The toplevel API goes like this:
+
+    Cyberweb.draw_circle()
+    Cyberweb.draw_circle(width: 200)
+    Cyberweb.draw_circle(width: 200, height: 500)
+    Cyberweb.draw_circle(width: 200, height: 500, background_color: :steelblue)
+    Cyberweb.draw_circle(width: 200, height: 500, background_color: :steelblue, border_radius: '30%')
+
+Pass a <b>Hash</b> into the method. Note that this will return the CSS
+rule as-is, as well as return the div-tag String. <b>Cyberweb::BaseModule</b>
+will directly embed this if you use the method <b>draw_circle()</b>. 
+
+Here is a partial screenshot showing three such examples; only the
+second example has a border-radius of <b>50%</b>. See also the 
+distributed example at <b>cyberweb/examples/advanced/draw_circle/draw_circle.cgi</b>
+showcasing this functionality.
+
+<img src="https://i.imgur.com/k5wFnwn.png" style="margin: 1em">
+
 ## Useful quotes when designing websites and web-apps
 
 The following subsection collects a few <b>interesting statements</b> -