cyberweb 0.6.17 → 0.7.9

data/doc/README.gen

@@ -416,11 +416,18 @@ Note that **Cyberweb.set_path()** is a shorter alias to this method;
 may be useful in IRB. Otherwise I recommend to use the longer 
 method name instead, as it is more explicit.
 
+For many users this API may be fairly irrelevant or even cumbersome.
+In that case you should consider uploading some of your images to a
+remote server and then simply link towards these images rather
+than having to deal with paths to local images being a nuisance. I do
+that with some of my files, e. g. referring to a FTP site. In the
+long run, though, this situation will eventually improve.
+
 ## Images
 
-If an image is not existing, but used within the Cyberweb
-framework, then a a red border and a red text will be
-displayed around that (non-existing) image.
+If an image is not existing, but used within the Cyberweb framework,
+then a a red border and a red text will be displayed around that
+(non-existing) image.
 
 This way, the user is being encouraged to fix the problem at hand.
 
@@ -429,11 +436,13 @@ fix/change this.
 
 This is why the red warning or warnings in general, can be reduced
 or disabled - have a look at the configuration file for this.
+Personally I prefer a red warning, but others may not want to
+have this.
 
-If warnings are set to verbose, then the web_object project will
-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.
+If <b>warnings</b> are set to verbose, then the <b>cyberweb project</b>
+will display the notification mentioned above for all images that
+were not found. If it is set to normal or lower than that, the
+cyberweb project will <b>not</b> display that warning.
 
 ## Greek letters
 
@@ -447,13 +456,6 @@ the following command:
 
     Cyberweb.show_greek_letters
 
-## Javascript-support in the Cyberweb project
-
-Have a look at the subdirectory called **javascript/**.
-
-If a new javascript-component is added, it should be registered
-in one of the .rb files in said directory.
-
 ## Commandline usage
 
 A commandline program exists, at <b>bin/cyberweb</b>.
@@ -881,18 +883,6 @@ useful for short header-entries, such as "Goals" or
 functionality purely exists due to convenience - I wanted
 to quickly generate the default id entry for a sitemap. 
 
-## JavaScript clock
-
-If you wish to display a small JavaScript "clock" that just
-shows the time, you could use this:
-
-    display_clock('pad1em') { :larger_font_size }
-
-The block argument just increases the font-size a bit; it can
-be omitted of course, as can all arguments, too:
-
-    display_clock
-
 ## Redirecting to another page
 
 You can combine BeautifulUrl, and Cyberweb, to redirect
@@ -1836,19 +1826,6 @@ To do this, try:
       e('This text should now be editable.') { :editable }
     }
 
-## Specify javascript files
-
-You can specify a specific javascript file via:
-    
-    w.javascript_file = '../../CODE/JS/FADER.js'
-    w.javascript_file = :fader
-  
-As you can see, both a string version giving the full path, and a
-Symbol shortcut, will work - provided that the Symbol was registered.
-
-I recommend to use the Symbol version for two reasons: first, it is
-less to type. Second, it is trivial to change the path lateron.
-
 ## Configuration
 
 All meaningful options that can be configured, can be configured
@@ -2380,32 +2357,6 @@ Valid cursors include:
     not-allowed
     no-drop
 
-## Removing child elements in JavaScript
-
-An element can be removed via JavaScript by issueing:
-
-    this.parentNode.removeChild(this)
-
-## Default parameters to functions in JavaScript
-
-You can use default values to functions in JavaScript.
-
-Example:
-
-    function multiply(a, b = 1) {
-      return a * b;
-    }
-
-    console.log(multiply(5, 2));
-    console.log(multiply(5));
-
-Alternatively you could also use || inside of the function
-body, to simulate default values.
-
-It may then look like this inside of a function:
-
-    bar = bar || "Default Value";
-
 ## Using language-specific files as content of a webpage
 
 The typical way how I describe the main content of a web-page
@@ -2815,44 +2766,6 @@ Example in HTML:
 
     <img src='foobar.jpg' loading='lazy' alt='Alternative Text'>
 
-## JavaScript for-in and for-of loops:
-
-Just examples for each:
-
-    for (const key in {a: 1, b: 2}) {
-      console.log(key);
-    }
-    // a, b
-
-    for (const value of [1,2,3,4,5]) {
-      console.log(value);
-    }
-    // 1, 2, 3, 4, 5
-
-## Data Types in JavaScript (ECMAScript)
-
-There are six simple data types:
-
-    Undefined
-    Null
-    Boolean
-    Number
-    String
-    Symbol
-
-## How to use the typeof() operator in JavaScript
-
-The typeof operator is called like this:
-
-    let x = "some string";
-    typeof(x)  # "string"
-    typeof(95) # "number"
-
-Note that the () for typeof() could be omitted, as typeof is
-an operator and not a function - but it seems simpler to use
-the () just as it is used for other functions in JavaScript
-as well.
-
 ## CSS zoom-on-hover effect
 
 This can be done like this:
@@ -4224,8 +4137,8 @@ More specifically what these **four values** mean:
 
     drop-shadow(offset-x offset-y blur-radius color)
 
-If you make use of the **cyberweb** project then you
-can use the following API:
+If you make use of the **cyberweb** project then you can use
+the following API, to generate a drop shadow:
 
     generate_drop_shadow :red, :default, 'drop_shadow_red'
     div('drop_shadow_red') {
@@ -4424,8 +4337,8 @@ remember that you also get a lot of flexibility that way.
 
 ## The method images_css() in class Cyberweb::WebObject
 
-Sometimes you have several images and may want to apply the
-same CSS rules to all of them.
+Sometimes you may have several images and may want to apply
+the same CSS rules to all of them.
 
 For instance, I use the CSS class <b>bblack1</b> which is
 equivalent to:
@@ -4446,6 +4359,10 @@ for a demo in this regard. (Not all images work; some of them
 are only available on my home system, but the other images
 should work.) 
 
+Do note that since as of November 2022, when images_css is
+used then it will <b>always</b> be appended to every 
+image tag. So only use it if you really need this functionality.
+
 ## links.md
 
 If a file called <b>links.md</b> exists in the current working directory
@@ -4657,6 +4574,258 @@ showcasing this functionality.
 
 <img src="https://i.imgur.com/k5wFnwn.png" style="margin: 1em">
 
+## class Cyberweb::ObtainCssRules
+
+<b>class Cyberweb::ObtainCssRules</b> was added to quickly fetch the
+CSS rule shortcut.
+
+For instance, the cyberweb gem comes with many custom CSS classes
+defined. I use these for different project.
+
+One such CSS rule is this:
+
+    .mars1em {
+      margin-left: 1em;
+      margin-right: 1em;
+    }
+
+Now: sometimes I can not use these custom CSS rules, even though I
+want to.
+
+<b>class Cyberweb::ObtainCssRules</b> fills that use case.
+
+We can tell this class to fetch the body of the CSS rule at
+<b>.mars1em</b>. This will then be automatically expanded
+onto the corresponding "margin-left" and "margin-right"
+entries.
+
+To require this class do:
+
+    require 'cyberweb/utility_scripts/obtain_css_rules.rb'
+
+Furthermore, this class was also added to automatically
+make use of various shortcuts.
+
+Let me demonstrate how I use this specifically.
+
+In the file pidgin.rb, which is part of the roebe gem,
+I use the following:
+
+    default_template1 '
+
+    p.default {
+      .mars1em;
+    }
+
+    '
+
+What does the above mean?
+
+It means that the p-tag (in HTML), if it makes use of the
+CSS class called default, will use the CSS rules defined
+in the .mars1em CSS class' body.
+
+So, it is <b>exactly</b> identical to the following:
+
+    p.default {
+      margin-left:  1em;
+      margin-right: 1em;
+    }
+
+This is a bit similar to less and SASS and similar
+shortcut-tools.
+
+Within the web-app, for class WebObject, I may then
+create these paragraphs via:
+
+    p_default {
+      e 'Hello world!'
+    }
+
+Note that the above does not work 100% reliably; I
+added this in <b>November 2022</b> in part to try it out.
+
+At some later point in time this may be improved,
+so use with care. I recommend to be very strict when
+using the above functionality; the less complexity,
+the better usually (unless you can write more succinct
+and more expressive code, perhaps; but even then it
+is a trade-off ultimately).
+
+## Returning all images from a remote website
+
+If you ever have a use case that you wish to return all
+images found on a remote website, consider using the
+following API:
+
+    x = Cyberweb.return_all_images_from_this_webpage('https://www.projectaon.org/en/xhtml/lw/02fotw/sect166.htm', true)
+
+This would yield the following Array:
+
+    [
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/title.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrtpl.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrtp.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrtpr.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrl.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/ill10.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrr.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrbtl.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrbt.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/brdrbtr.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/left.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/toc.png",
+      "https://www.projectaon.org/en/xhtml/lw/02fotw/right.png"
+    ]
+
+## JavaScript support in the cyberweb project
+
+### JavaScript for-in and for-of loops:
+
+Just examples for each:
+
+    for (const key in {a: 1, b: 2}) {
+      console.log(key);
+    }
+    // a, b
+
+    for (const value of [1,2,3,4,5]) {
+      console.log(value);
+    }
+    // 1, 2, 3, 4, 5
+
+### Javascript-support in the Cyberweb project
+
+Have a look at the subdirectory called **javascript/**.
+
+If a new javascript-component is added, it should be registered
+in one of the .rb files in said directory.
+
+### Data Types in JavaScript (ECMAScript)
+
+There are six simple data types:
+
+    Undefined
+    Null
+    Boolean
+    Number
+    String
+    Symbol
+
+### How to use the typeof() operator in JavaScript
+
+The typeof operator is called like this:
+
+    let x = "some string";
+    typeof(x)  # "string"
+    typeof(95) # "number"
+
+Note that the () for typeof() could be omitted, as typeof is
+an operator and not a function - but it seems simpler to use
+the () just as it is used for other functions in JavaScript
+as well.
+
+### JavaScript clock
+
+If you wish to display a small JavaScript "clock" that just
+shows the time, you could use this:
+
+    display_clock('pad1em') { :larger_font_size }
+
+The block argument just increases the font-size a bit; it can
+be omitted of course, as can all arguments, too:
+
+    display_clock
+
+### Specify JavaScript files
+
+You can specify a specific javascript file via:
+    
+    w.javascript_file = '../../CODE/JS/FADER.js'
+    w.javascript_file = :fader
+  
+As you can see, both a string version giving the full path, and a
+Symbol shortcut, will work - provided that the Symbol was registered.
+
+I recommend to use the Symbol version for two reasons: first, it is
+less to type. Second, it is trivial to change the path lateron.
+
+### Removing child elements in JavaScript
+
+An element can be removed via JavaScript by issueing:
+
+    this.parentNode.removeChild(this)
+
+### Default parameters to functions in JavaScript
+
+You can use default values to functions in JavaScript.
+
+Example:
+
+    function multiply(a, b = 1) {
+      return a * b;
+    }
+
+    console.log(multiply(5, 2));
+    console.log(multiply(5));
+
+Alternatively you could also use || inside of the function
+body, to simulate default values.
+
+It may then look like this inside of a function:
+
+    bar = bar || "Default Value";
+
+### JavaScript's document.getElementById()
+
+You can use JavaScript's document.getElementById() to modify
+values programmatically.
+
+Example showcasing this:
+
+    function foobar() {
+      document.getElementById("set_on_value_changed").value = "44";
+    }
+
+All you need to know is the ID of the target element.
+
+### Does order matter for JavaScript?
+
+Script tags that are used in a webpage are executed in the order they
+appear. So, if you look at the following JavaScript code:
+
+    <script>
+    var x = 42;
+    </script>
+
+    <script>
+    alert(x); // Will alert '3';
+    </script>
+
+Then first the variable x will be set, to the value of <b>42</b>.
+
+Note that this also applies to when you load external .js files - first
+in, first to be evaluated. So order does indeed matter.
+
+The reason I noted this down here was in the event that I may forgot
+why I decided to load some .js files before others.
+
+There is, however had, also a practical consideration here: if you
+have some external .js files that take a while to load, it may be
+best to put them near the end of the page, or at the least after
+other .js files were already loaded, as it may otherwise slow
+down the loading of the webpage. This is the reason why some
+webpages recommend to put JavaScript script-tags shortly before
+the closing </body> tag rather than in the <head> section of 
+the given HTML code at hand.
+
+You can also use the async keyword; this means that the loading of
+the webpage will continue.
+
+Example:
+
+    <script src="path/foobar.js" async></script>
+
 ## Useful quotes when designing websites and web-apps
 
 The following subsection collects a few <b>interesting statements</b> -