cyberweb 0.6.17 → 0.7.9

data/lib/cyberweb/web_object/images.rb

@@ -10,182 +10,11 @@ module Cyberweb
 
 class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
 
-  # ========================================================================= #
-  # === draggable_image
-  #
-  # Example code how to tap into this method:
-  #
-  #   draggable_image 'STD/USB_CONNECTION_DEVICE.png',
-  #                   'mar1em bblack1 mars3em'
-  #
-  # It may be more convenient to use the alias name dimg().
-  # ========================================================================= #
-  def draggable_image(
-      url       = '',
-      css_class = :empty_string_or_global_css_rules_for_images, 
-      the_id    = '',
-      css_style = '',
-      alt_text  = '',
-      &block
-    )
-    if the_id and the_id.empty?
-      the_id = (
-                'drag_'+
-                 File.basename(url.to_s).
-                 downcase.
-                 delete_suffix(
-                   File.extname(url.to_s)
-                 )
-               ).tr('.','_')
-    end
-    if the_id and !the_id.empty? and !the_id.start_with?('drag_')
-      the_id = the_id.dup
-      the_id.prepend('drag_')
-    end
-    if uses_sinatra? # Handle sinatra first.
-      draggable_img_base64(url, css_class, css_style)
-    else
-      img(url, css_class, the_id, css_style, alt_text) { :draggable_attribute }
-    end
-  end; alias draggable_img draggable_image # === draggable_img
-       alias dimg          draggable_image # === dimg
-       alias dimage        draggable_image # === dimage
-
-  # ========================================================================= #
-  # === return_path_to_the_images_directory
-  # ========================================================================= #
-  def return_path_to_the_images_directory(
-      path_to_use = relative_path?
-    )
-    return "#{path_to_use}data/"\
-           "#{return_name_of_the_images_directory}/"
-  end
-
-  # ========================================================================= #
-  # === images_css
-  #
-  # This method allows the user to set the same CSS rules for all
-  # images used on a given WebObject.
-  # ========================================================================= #
-  def images_css(i)
-    @internal_hash[:global_CSS_rules_for_all_images] = i
-  end
-
-  # ========================================================================= #
-  # === img_nbr
-  #
-  # The fourth argument, called css_style, used to default to
-  # "border-width:1px", but in May 2021 it was realized that this
-  # will conflict with e. g. a css class such as "bblack3". In
-  # this case we would want to use a border width of 3px, but
-  # this would be ignored due to the default. Thus, the default
-  # was removed.
-  #
-  # In October 2022 the second argument to this method was changed to
-  # a Symbol. 
-  # ========================================================================= #
-  def img_nbr(
-      url       = 'RPG/YINYANG.png',
-      css_class = :empty_string_or_global_css_rules_for_images, 
-      the_id    = '',
-      css_style = '' # Empty default since May 2021 - see above for an explanation.
-    )
-    img(
-      url,
-      css_class, 
-      the_id,
-      css_style
-    )
-    br
-  end; alias img_br img_nbr # === img_br
-       alias imgbr  img_nbr # === imgbr
-
-  # ========================================================================= #
-  # === img                                              (img tag, image tag)
-  #
-  # Keep in mind that this method has to remain quite flexible. It has
-  # to be able to work with input such as this:
-  #
-  #  img(
-  #    this_image.sub(Regexp.quote('/home/x/data/images/'),''),
-  #    css_class: 'bblack3',
-  #    width:  '528',
-  #    height: '340',
-  #    alt:    File.basename(this_image.delete_suffix(File.extname(this_image)))
-  #  )
-  #
-  # ========================================================================= #
-  def img(
-      url       = 'RPG/YINYANG.png',
-      css_class = :empty_string_or_global_css_rules_for_images,
-      the_id    = '',
-      css_style = '',
-      alt_text  = '',
-      &block
-    )
-    # ======================================================================= #
-    # First we should obtain the corresponding <img> tag. This will be
-    # delegated towards sg() which is an abbreviated name for
-    # string_image():
-    # ======================================================================= #
-    content = sg(
-      url, css_class, the_id, css_style, alt_text
-    )
-    # ======================================================================= #
-    # === Handle blocks given to this method next
-    # ======================================================================= #
-    if block_given?
-      yielded = yield
-      # ===================================================================== #
-      # === Handle Hashes next
-      # ===================================================================== #
-      if yielded.is_a? Hash
-        # =================================================================== #
-        # === :draggable_attribute
-        # =================================================================== #
-        if yielded.has_key? :draggable_attribute
-          content = content.dup
-          content[-1,0] = ' draggable="true"'
-        end
-        # =================================================================== #
-        # === :usemap
-        # =================================================================== #
-        if yielded.has_key? :usemap
-          content = content.dup
-          content[-1,0] = ' usemap="'+yielded[:usemap].to_s+'"' 
-        end
-      # ===================================================================== #
-      # === Handle Symbols next
-      # ===================================================================== #
-      elsif yielded.is_a? Symbol
-        case yielded # case tag
-        # =================================================================== #
-        # === :draggable_attribute
-        # =================================================================== #
-        when :draggable_attribute,
-             :drag
-          content = content.dup
-          content[-1,0] = ' draggable="true"'
-        end
-      end
-    end
-    addnl(
-      content
-    )
-  end; alias ig img # === ig
-
-  # ========================================================================= #
-  # === images_css_rules?
-  # ========================================================================= #
-  def images_css_rules?
-    @internal_hash[:global_CSS_rules_for_all_images]
-  end
-
   # ========================================================================= #
   # === simpler_string_image                                         (sg tag)
   #
-  # This method has been added in September 2020 to specifically
-  # work around the problem that the older sg() has.
+  # This method has been added in September 2020 to specifically work
+  # around the problem that the older sg() has.
   #
   # The return-value of this method MUST always be a String; it may never
   # use addnl() directly. The whole idea is to build up a <img> tag
@@ -197,22 +26,28 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
       optional_the_id    = '',
       optional_css_style = '',
       alt_text           = '',
-      make_linebreak     = 0,
+      make_linebreak     =  0,
       something1         = '',
       something2         = '',
       hmmmmmmmmm         = '',
       javascript         = '',
       &block
     )
+    if optional_css_class and optional_css_class.is_a?(String) and
+       images_css_rules? and !images_css_rules?.empty?
+      optional_css_class += " #{images_css_rules?}"
+    end
     case optional_css_class
     # ======================================================================= #
     # === :empty_string_or_global_css_rules_for_images
+    #
+    # Make use of the global image CSS rules here.
     # ======================================================================= #
     when :empty_string_or_global_css_rules_for_images
-      if @internal_hash[:global_CSS_rules_for_all_images].nil?
+      if images_css_rules?.nil?
         optional_css_class = ''
       else
-        optional_css_class = @internal_hash[:global_CSS_rules_for_all_images]
+        optional_css_class = images_css_rules?
       end
     end
     yielded = nil # Dummy variable for later re-use.
@@ -299,6 +134,8 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
     case optional_the_id
     # ======================================================================= #
     # === :drag
+    #
+    # "Rescue" a specific symbol here, called :drag.
     # ======================================================================= #
     when :drag
       optional_the_id = 'drag_'+File.basename(i).downcase.delete_suffix(
@@ -354,10 +191,22 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
         may_we_prepend_the_path = false
       end
     end
-    if may_we_prepend_the_path
+    # ======================================================================= #
+    # Next we prepend the path to the local directory. This is, however
+    # had, NOT the case if i begins with the substring 'http'.
+    # ======================================================================= #
+    if may_we_prepend_the_path and !i.start_with?('http')
       i = return_path_to_the_images_directory+
           i
     end
+    # ======================================================================= #
+    # Last but not least, we need to ensure that the ID is unique. If
+    # not then we will append some characters here.
+    # ======================================================================= #
+    if optional_the_id and !optional_the_id.empty? and is_a_duplicate_id?(optional_the_id)
+      optional_the_id = optional_the_id.dup if optional_the_id.frozen?
+      optional_the_id << '_'+random_alphabet_characters(10)
+    end
     return raw_image(
       i,
       optional_css_class,
@@ -371,6 +220,178 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
        alias simg       simpler_string_image # === simg
        alias sg         simpler_string_image # === sg
 
+  # ========================================================================= #
+  # === images_css
+  #
+  # This method allows the user to set the same CSS rules for all
+  # images used on a given WebObject.
+  # ========================================================================= #
+  def images_css(i)
+    @internal_hash[:global_CSS_rules_for_all_images] = i
+  end
+
+  # ========================================================================= #
+  # === images_css_rules?
+  # ========================================================================= #
+  def images_css_rules?
+    @internal_hash[:global_CSS_rules_for_all_images]
+  end
+
+  # ========================================================================= #
+  # === image                                            (img tag, image tag)
+  #
+  # This method can be used to integrate ("embed") an image into the
+  # local web-page at hand. This image can either be a local image,
+  # or a remote one.
+  #
+  # The corresponding HTML code that governs this is the <img> tag.
+  # The first argument, called `url`, will become src="".
+  #
+  # It should be kept in mind that this method has to remain quite flexible.
+  #
+  # It has to be able to work with input such as this:
+  #
+  #   img(
+  #     this_image.sub(Regexp.quote('/home/x/data/images/'),''),
+  #     css_class: 'bblack3',
+  #     width:  '528',
+  #     height: '340',
+  #     alt:    File.basename(this_image.delete_suffix(File.extname(this_image)))
+  #   )
+  #
+  # ========================================================================= #
+  def image(
+      url       = 'RPG/YINYANG.png',
+      css_class = :empty_string_or_global_css_rules_for_images,
+      the_id    = '',
+      css_style = '',
+      alt_text  = '',
+      &block
+    )
+    # ======================================================================= #
+    # === Delegate towards simpler_string_image()
+    #
+    # First we should obtain the corresponding <img> tag. This will be
+    # delegated towards sg() which is an abbreviated name for
+    # string_image():
+    # ======================================================================= #
+    content = sg(
+      url, css_class, the_id, css_style, alt_text
+    )
+    # ======================================================================= #
+    # === Handle blocks given to this method next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      # ===================================================================== #
+      # === Handle Hashes next
+      # ===================================================================== #
+      if yielded.is_a? Hash
+        # =================================================================== #
+        # === :draggable_attribute
+        # =================================================================== #
+        if yielded.has_key? :draggable_attribute
+          content = content.dup
+          content[-1,0] = ' draggable="true"'
+        end
+        # =================================================================== #
+        # === :usemap
+        # =================================================================== #
+        if yielded.has_key? :usemap
+          content = content.dup
+          content[-1,0] = ' usemap="'+yielded[:usemap].to_s+'"' 
+        end
+      # ===================================================================== #
+      # === Handle Symbols next
+      # ===================================================================== #
+      elsif yielded.is_a? Symbol
+        case yielded # case tag
+        # =================================================================== #
+        # === :draggable_attribute
+        # =================================================================== #
+        when :draggable_attribute,
+             :drag
+          content = content.dup
+          content[-1,0] = ' draggable="true"'
+        end
+      end
+    end
+    addnl(
+      content
+    )
+  end; alias img image # === img
+       alias ig  image # === ig
+
+  # ========================================================================= #
+  # === draggable_image
+  #
+  # Example code how to tap into this method:
+  #
+  #   draggable_image 'STD/USB_CONNECTION_DEVICE.png',
+  #                   'mar1em bblack1 mars3em'
+  #
+  # It may be more convenient to use the alias name dimg().
+  # ========================================================================= #
+  def draggable_image(
+      url       = '',
+      css_class = :empty_string_or_global_css_rules_for_images, 
+      the_id    = '',
+      css_style = '',
+      alt_text  = '',
+      &block
+    )
+    if the_id and the_id.empty?
+      the_id = (
+                'drag_'+
+                 File.basename(url.to_s).
+                 downcase.
+                 delete_suffix(
+                   File.extname(url.to_s)
+                 )
+               ).tr('.','_')
+    end
+    if the_id and !the_id.empty? and !the_id.start_with?('drag_')
+      the_id = the_id.dup
+      the_id.prepend('drag_')
+    end
+    if uses_sinatra? # Handle sinatra first.
+      draggable_img_base64(url, css_class, css_style)
+    else # delegate towards img() next.
+      img(url, css_class, the_id, css_style, alt_text) { :draggable_attribute }
+    end
+  end; alias draggable_img draggable_image # === draggable_img
+       alias dimg          draggable_image # === dimg
+       alias dimage        draggable_image # === dimage
+
+  # ========================================================================= #
+  # === img_nbr
+  #
+  # The fourth argument, called css_style, used to default to
+  # "border-width:1px", but in May 2021 it was realized that this
+  # will conflict with e. g. a css class such as "bblack3". In
+  # this case we would want to use a border width of 3px, but
+  # this would be ignored due to the default. Thus, the default
+  # was removed.
+  #
+  # In October 2022 the second argument to this method was changed to
+  # a Symbol. 
+  # ========================================================================= #
+  def img_nbr(
+      url       = 'RPG/YINYANG.png',
+      css_class = :empty_string_or_global_css_rules_for_images, 
+      the_id    = '',
+      css_style = '' # Empty default since May 2021 - see above for an explanation.
+    )
+    img(
+      url,
+      css_class, 
+      the_id,
+      css_style
+    )
+    br # And then the separate call towards br().
+  end; alias img_br img_nbr # === img_br
+       alias imgbr  img_nbr # === imgbr
+
   # ========================================================================= #
   # === remote_img
   #
@@ -429,7 +450,11 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
   # === raw_image
   #
   # The first argument to this method should be the path to the file at
-  # hand.
+  # hand. This can also be a remote image.
+  #
+  # Note that this method deliberately does NOT check whether the ID is
+  # unique or not. You have to solve this prior to calling this method
+  # if you wish to avoid duplicate IDs.
   # ========================================================================= #
   def raw_image(
       i                  = '',
@@ -720,4 +745,335 @@ class WebObject < ::Cyberweb::Base # === Cyberweb::WebObject
     )
   end
 
+  # ========================================================================= #
+  # === return_path_to_the_images_directory
+  # ========================================================================= #
+  def return_path_to_the_images_directory(
+      path_to_use = relative_path?
+    )
+    return "#{path_to_use}data/"\
+           "#{return_name_of_the_images_directory}/"
+  end
+
+  # ========================================================================= #
+  # === img_dir?
+  #
+  # This method refers to a local directory where images are kept.
+  #
+  # This is hardcoded for my home system, so it is fairly useless for other
+  # people.
+  # ========================================================================= #
+  def img_dir?
+    "#{server_base_directory?}"\
+    "data/"\
+    "#{return_name_of_the_images_directory}/"
+  end
+
+  # ========================================================================= #
+  # === return_this_base64_image
+  # ========================================================================= #
+  def return_this_base64_image(
+      i,
+      optional_css_class = '',
+      optional_css_id    = ''
+    )
+    return ::Cyberweb.return_this_base64_image(
+      i,
+      optional_css_class,
+      optional_css_id
+    )
+  end
+
+  # ========================================================================= #
+  # === display_all_images
+  #
+  # Use this when you just want to display all images.
+  #
+  # The first argument should be the location towards the
+  # directory that holds all images.
+  # ========================================================================= #
+  def display_all_images(
+      dir          = ::Cyberweb.return_pwd,
+      optional_css = 'bblack1'
+    )
+    if dir.is_a? Hash
+      dir = dir.delete(:from) if dir.has_key? :from
+    end
+    if dir.include? '$'
+      dir = ConvertGlobalEnv[dir]
+    end
+    unless Dir.exist? dir
+      e 'It seems as if the directory at `'+dir+'` does not exist.'
+    end
+    all_the_images = get_images_from(dir)
+    all_the_images.each {|file|
+      file = rds(file)
+      h3 file, 'slateblue'
+      imgbr(
+        file,
+        optional_css
+      )
+    }
+  end; alias display_images_from display_all_images # === display_images_from
+       alias display_images      display_all_images # === display_images
+
+  # ========================================================================= #
+  # === do_use_in_dir_images
+  # ========================================================================= #
+  def do_use_in_dir_images
+    @config['use_in_dir_images'] = true
+    # ======================================================================= #
+    # Also keep track of the new path.
+    # ======================================================================= #
+    ::Cyberweb.set_path_to_images('')
+  end; alias use_in_dir_images do_use_in_dir_images # === use_in_dir_images
+
+  # ========================================================================= #
+  # === base64_image
+  #
+  # This is distinct to other base64-related images within the Cyberweb
+  # project. It will simply, and directly, add the given data.
+  # ========================================================================= #
+  def base64_image(
+      i, image_type_to_use = :infer
+    )
+    addnl(
+      return_base64_image(i, image_type_to_use)
+    )
+  end
+
+  # ========================================================================= #
+  # === return_base64_image
+  # ========================================================================= #
+  def return_base64_image(
+      i,
+      image_type_to_use  = :infer,
+      optional_css_class = '',
+      optional_the_id    = '',
+      optional_css_style = ''
+    )
+    case image_type_to_use
+    # ======================================================================= #
+    # === :infer
+    # ======================================================================= #
+    when :infer
+      image_type_to_use = File.extname(i)
+      if image_type_to_use.empty?
+        image_type_to_use = 'png' # Rescue in this case.
+      end
+    end
+    _ = '<img src="data:image/'+
+        image_type_to_use.to_s.delete('.')+
+        ';base64,'+i+'"'.dup
+    if optional_css_class
+      _ << css_class_or_no_class(optional_css_class)
+    end
+    if optional_the_id
+      _ << id_or_no_id(optional_the_id)
+    end
+    if optional_css_style
+      _ << css_style_or_no_style(optional_css_style)
+    end
+    _ << '>'
+    return _
+  end
+
+  # ========================================================================= #
+  # === local_image_or_remote_image
+  #
+  # This method can be used to add a substitute image in the event that
+  # a local image could not be found. Otherwise it behaves exactly like
+  # image() does.
+  # ========================================================================= #
+  def local_image_or_remote_image(
+      local_image             = '',
+      remote_image_substitute = '', # This one should be the remote URL.
+      optional_css_class      = '',
+      optional_the_id         = '',
+      optional_css_style      = '',
+      alt_text                = '',
+      &block
+    )
+    # ======================================================================= #
+    # We first have to decide whether the image exists or whether it does
+    # not exist, at the specified location. If it exists then we can use
+    # the regular img() call; otherwise we have to use the second argument
+    # to this method.
+    # ======================================================================= #
+    assumed_path = rds(
+      path_to_the_image_directory?+
+      local_image
+    )
+    if File.exist?(assumed_path) and !local_image.empty?
+      img(
+        local_image,
+        optional_css_class,
+        optional_the_id,
+        optional_css_style,
+        alt_text,
+        &block
+      )
+    else
+      # ===================================================================== #
+      # else we use a remote URL or a rescue URL anyway.
+      # ===================================================================== #
+      remote_img(
+        remote_image_substitute,
+        {
+          css_class: optional_css_class,
+          id:        optional_the_id,
+          css_style: optional_css_style
+        },
+        &block
+        # alt_text is currently not handled here.
+      )
+    end
+  end
+
+  # ========================================================================= #
+  # === embed_this_image
+  # ========================================================================= #
+  def embed_this_image(
+      i                  = 'lyxandras-das-Dorf-Nadorp.jpg',
+      optional_css_class = 'bblack1',
+      optional_the_id    = ''
+    )
+    addnl(
+      ::Cyberweb.embed_this_image(i, optional_css_class, optional_the_id)
+    )
+  end
+
+  # ========================================================================= #
+  # === relative_background_image
+  #
+  # We have to build the proper path, e. g.:
+  #
+  #   url(data/images/WALLPAPERS/TheCalling_AnimeWallpaper.jpg);
+  #
+  # ========================================================================= #
+  def relative_background_image(this_image)
+    _ = ('../' * n_steps_to_the_base_directory?) + 
+        "#{name_of_img_dir?}".dup
+    _ << this_image
+    background_image = "background-image: url(#{_});" # The string to append.
+    # ======================================================================= #
+    # Next, add some default assumptions here. No repeat is ok to
+    # use, centered background position - not sure.
+    #   background-position: center;
+    # ======================================================================= #
+    add_this_css_style(
+      'body {
+         '+background_image+'
+         background-repeat: no-repeat;
+       }'
+    )
+  end
+
+  # ========================================================================= #
+  # === background_image=
+  #
+  # Use this method to set the background image for a page.
+  #
+  #   body {background-image: url("../IMG/");}'
+  #
+  # Since as of December 2011, if you pass an argument such as 'NJOY/#RAND'
+  # then we use this as instruction to fetch a random entry from this
+  # directory.
+  #
+  # Usage Example:
+  #
+  #   w.background_image = 'NJOY/#RAND'
+  #
+  # ========================================================================= #
+  def background_image=(
+      i = '/blaaa/foo.png'
+    )
+    _ = "#{name_of_img_dir?}/".dup # Hardcoded for now. Yes, I am aware that this sucks.
+    if i.to_s.downcase.include? '#rand' # Then get path given. Example: w.background_image = 'NJOY/#RAND'
+      first_part = i.split('#').first
+      _ << first_part
+      _ << get_files_from(::Cyberweb.path_to_images?).sample.to_s
+    else
+      case i
+      when :random
+        _ << Dir[::Cyberweb.path_to_images?+'NJOY/*'].sample.
+             sub(/\/home\/x\/DATA\/IMG\//, '')
+      else
+        _ << i
+      end
+    end
+    background_img = "background-image: url(#{::Cyberweb.path_to_images?}#{_});" # The string to append.
+    # ======================================================================= #
+    # Next, add some default assumptions here. No repeat is ok to
+    # use, centered background position - not sure.
+    #   background-position: center;
+    # ======================================================================= #
+    add_this_css_style(
+      'body {
+         '+background_img+'
+         background-repeat: no-repeat;
+       }'
+    )
+  end; alias body_background_image background_image= # === body_background_image
+       alias background_image      background_image= # === background_image
+
+  # ========================================================================= #
+  # === return_the_registered_base64_images
+  # ========================================================================= #
+  def return_the_registered_base64_images
+    ::Cyberweb.base64_images
+  end
+
+  # ========================================================================= #
+  # === disable_webimages
+  #
+  # We wont use the webimages if we use this method here.
+  # ========================================================================= #
+  def disable_webimages
+    ::Cyberweb.config?['use_webimages'] = false
+  end
+
+  # ========================================================================= #
+  # === get_images
+  #
+  # This method will obtain all files from all subdirectories there as
+  # well.
+  # ========================================================================= #
+  def get_images(
+      from_this_dir = return_pwd
+    )
+    Dir["#{from_this_dir}/**/**"].select {|entry|
+      ::Cyberweb.is_an_image?(entry)
+    }
+  end; alias get_images_from        get_images # === get_images_from
+       alias return_all_images_from get_images # === return_all_images_from
+
+  # ========================================================================= #
+  # === done_image
+  # ========================================================================= #
+  def done_image
+    sg(:done, 'marr10px')
+  end
+
+  # ========================================================================= #
+  # === draggable_string_image
+  # ========================================================================= #
+  def draggable_string_image(
+      url       = '',
+      css_class = '', 
+      the_id    = '',
+      css_style = '',
+      alt_text  = '',
+      &block
+    )
+    if the_id and the_id.empty?
+      the_id = 'drag_'+File.basename(url).downcase.delete_suffix(File.extname(url))
+    end
+    if the_id and !the_id.empty? and !the_id.start_with?('drag_')
+      the_id = the_id.dup
+      the_id.prepend('drag_')
+    end
+    string_img(url, css_class, the_id, css_style, alt_text) { :draggable_attribute }
+  end
+
 end; end