cyberweb 0.4.174

data/lib/cyberweb/web_object/images.rb

@@ -0,0 +1,693 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'cyberweb/web_object/images.rb'
+# =========================================================================== #
+require 'cyberweb/base/base.rb'
+
+module Cyberweb
+
+class WebObject < Base # === Cyberweb::WebObject
+
+  require 'cyberweb/requires/require_web_images.rb'
+
+  # ========================================================================= #
+  # === drag_local_image_or_remote_image
+  #
+  # As local_image_or_remote_image(), but with the default id argument to
+  # refer to :drag.
+  # ========================================================================= #
+  def drag_local_image_or_remote_image(
+      local_image             = '',
+      remote_image_substitute = '', # This one should be the remote URL.
+      optional_css_class      = '',
+      optional_the_id         = :drag,
+      optional_css_style      = '',
+      alt_text                = '',
+      &block
+    )
+    local_image_or_remote_image(
+      local_image,
+      remote_image_substitute,
+      optional_css_class,
+      optional_the_id,
+      optional_css_style
+    ) { :drag }
+  end; alias dlocal_image_or_remote_image drag_local_image_or_remote_image # === dlocal_image_or_remote_image
+       alias dimg2                        drag_local_image_or_remote_image # === dimg2
+
+  # ========================================================================= #
+  # === 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
+      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
+
+  # ========================================================================= #
+  # === remote_img
+  #
+  # This method can be used to "embed" a remote image in a given
+  # web-application.
+  #
+  # Usage example:
+  #
+  #   embed_remote_image('https://i.imgur.com/jYBEnjr.png', css_class: 'bblack2 mar4px', id: 'drag_ferkellampe')
+  #
+  # ========================================================================= #
+  def remote_img(
+      i             = 'http://mikesrpgcenter.com/krondor/maps/timirianya.html',
+      optional_hash = {},
+      &block
+    )
+    # ======================================================================= #
+    # === Handle blocks first
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      # ===================================================================== #
+      # === Handle Hashes next
+      # ===================================================================== #
+      if yielded.is_a? Hash
+        optional_hash.merge!(yielded) # And push them onto the main Hash here.
+      end
+    end
+    addnl(
+      HtmlTags.img(i) { optional_hash }
+    )
+  end; alias embed_remote_image remote_img # === embed_remote_image
+       alias remote_image       remote_img # === remote_image
+
+  # ========================================================================= #
+  # === raw_image
+  #
+  # The first argument to this method should be the path to the file at
+  # hand.
+  # ========================================================================= #
+  def raw_image(
+      i                  = '',
+      optional_css_class = '',
+      optional_the_id    = '',
+      optional_css_style = '',
+      alt_text           = ''
+    )
+    return '<img src="'+i+'"'+
+           css_class_or_no_class(optional_css_class)+
+           id_or_no_id(optional_the_id, i)+
+           css_style_or_no_style(optional_css_style)+
+           alt_text_or_no_alt_text(alt_text)+'>'
+  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.
+  #
+  # 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
+  # through it; sg is short for string_image().
+  # ========================================================================= #
+  def simpler_string_image(
+      i                  = :random, # This is the path - or a Symbol denoting that a path should be used.
+      optional_css_class = '',
+      optional_the_id    = '',
+      optional_css_style = '',
+      alt_text           = '',
+      make_linebreak     = 0,
+      something1         = '',
+      something2         = '',
+      hmmmmmmmmm         = '',
+      javascript         = '',
+      &block
+    )
+    if i.is_a? Symbol
+      i = ::Cyberweb.image_url(i) # This has the path.
+    end
+    # ======================================================================= #
+    # === Handle Hashes next
+    #
+    # We must be careful here, depending on which symbol is passed to the
+    # method.
+    # ======================================================================= #
+    if optional_css_class.is_a? Hash
+      # ===================================================================== #
+      # === :id
+      # ===================================================================== #
+      if optional_css_class.has_key? :id
+        optional_the_id = optional_css_class.delete(:id)
+      # ===================================================================== #
+      # === :the_id
+      # ===================================================================== #
+      elsif optional_css_class.has_key? :the_id
+        optional_the_id = optional_css_class.delete(:the_id)
+      end
+      # ===================================================================== #
+      # === :css_style
+      # ===================================================================== #
+      if optional_css_class.has_key? :css_style
+        optional_css_style = optional_css_class.delete(:css_style)
+      end
+      # ===================================================================== #
+      # === :content
+      # ===================================================================== #
+      if optional_css_class.has_key? :content
+        i = optional_css_class.delete(:content)
+      end
+      # ===================================================================== #
+      # === :css
+      # ===================================================================== #
+      if optional_css_class.has_key? :css
+        optional_css_class = optional_css_class.delete(:css)
+      # ===================================================================== #
+      # === :css_class
+      # ===================================================================== #
+      elsif optional_css_class.has_key? :css_class
+        optional_css_class = optional_css_class.delete(:css_class)
+      end
+    end
+    i = i.to_s
+    may_we_prepend_the_path = true
+    case optional_the_id
+    # ======================================================================= #
+    # === :drag
+    # ======================================================================= #
+    when :drag
+      optional_the_id = 'drag_'+File.basename(i).downcase.delete_suffix(
+        File.extname(i)
+      ).tr('.','_')
+    end
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :draggable
+      # ===================================================================== #
+      when :drag
+        optional_the_id = 'drag_'+File.basename(i).downcase.delete_suffix(
+          File.extname(i)
+        ).tr('.','_')
+      # ===================================================================== #
+      # === :draggable_attribute
+      # ===================================================================== #
+      when :draggable_attribute
+        i = i.dup
+        i[-1,0] = ' draggable="true"'
+      # ===================================================================== #
+      # === :prepend_only_to_the_images_real_directory
+      # ===================================================================== #
+      when :prepend_only_to_the_images_real_directory
+        i.prepend(relative_path?.dup)
+        may_we_prepend_the_path = false
+      # ===================================================================== #
+      # === :do_not_prepend_anything
+      # ===================================================================== #
+      when :do_not_prepend_anything
+        may_we_prepend_the_path = false
+      end
+    end
+    if may_we_prepend_the_path
+      i = return_path_to_the_images_directory+
+          i
+    end
+    return raw_image(
+      i, optional_css_class, optional_the_id, optional_css_style, alt_text
+    )
+  end; alias sg         simpler_string_image # === sg
+       alias simg       simpler_string_image # === simg
+       alias string_img simpler_string_image # === string_img
+
+  # ========================================================================= #
+  # === img                                              (img tag, image tag)
+  # ========================================================================= #
+  def img(
+      url       = 'RPG/YINYANG.png',
+      css_class = '', 
+      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
+
+  # ========================================================================= #
+  # === 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 = '', 
+      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_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
+
+  # ========================================================================= #
+  # === add_this_base64_image
+  # ========================================================================= #
+  def add_this_base64_image(
+      i,
+      optional_css_class = '',
+      optional_css_id    = ''
+    )
+    addnl(
+      return_this_base64_image(
+        i,
+        optional_css_class,
+        optional_css_id
+      )
+    )
+  end
+
+  # ========================================================================= #
+  # === display_the_registered_base64_images
+  # ========================================================================= #
+  def display_the_registered_base64_images
+    return_the_registered_base64_images.each {|this_base64_image|
+      add_this_base64_image(this_base64_image)
+    }
+  end
+
+  # ========================================================================= #
+  # === draggable_image_nbr
+  # ========================================================================= #
+  def draggable_image_nbr(
+      url       = '',
+      css_class = '', 
+      the_id    = '',
+      css_style = '',
+      alt_text  = '',
+      &block
+    )
+    draggable_image(
+      url,
+      css_class, 
+      the_id,
+      css_style,
+      alt_text,
+      &block
+    )
+    br
+  end
+
+  # ========================================================================= #
+  # === img_dir?
+  # ========================================================================= #
+  def img_dir?
+    Cyberweb.server_base_directory?+
+    'data/'+
+    return_name_of_the_images_directory+'/'
+  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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === in_dir_image
+  #
+  # This will use an image from the current working directory.
+  #
+  # The first argument to it should be the target file path of your local
+  # file system.
+  # ========================================================================= #
+  def in_dir_image(
+      path,
+      optional_css_class = '',
+      optional_id        = :drag,
+      optional_css_style = ''
+    )
+    addnl HtmlTags.img(
+      path, optional_css_class, optional_id, optional_css_style
+    )
+    javascript_drag_and_drop(optional_id) if optional_id == :drag
+  end; alias indir_img  in_dir_image # === indir_img
+       alias img_in_dir in_dir_image # === img_in_dir
+
+  # ========================================================================= #
+  # === return_absolute_image
+  # ========================================================================= #
+  def return_absolute_image(
+      remote_url,
+      css_class = '',
+      the_id    = '',
+      css_style = ''
+    )
+    register_this_id(the_id)
+    return ::Cyberweb.string_absolute_img(
+               remote_url,
+               css_class,
+               the_id,
+               css_style
+             )
+  end
+
+  # ========================================================================= #
+  # === enable_drag_all_images
+  #
+  # We enable a configuration option through this method call here.
+  #
+  # Note that we will also automatically enable jquery in this case,
+  # as otherwise we could not drag the image in question around,
+  # which would sort of defeat the points of having this method
+  # in the first place - or it would require of you to manually
+  # enable jquery, which seems superfluous.
+  # ========================================================================= #
+  def enable_drag_all_images
+    do_use_jquery unless use_jquery?
+    @config['drag_all_images'] = true
+  end; alias drag_all_images              enable_drag_all_images # === drag_all_images
+       alias drag_everything              enable_drag_all_images # === drag_everything
+       alias do_drag_all_images           enable_drag_all_images # === do_drag_all_image
+       alias do_enable_drag_all_images    enable_drag_all_images # === do_enable_drag_all_image
+       alias drag_everything              enable_drag_all_images # === drag_everything
+       alias all_images_will_be_draggable enable_drag_all_images # === all_images_will_be_draggable
+       alias enable_dragging              enable_drag_all_images # === enable_dragging
+       alias enable_drag_and_drop         enable_drag_all_images # === enable_drag_and_drop
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === absolute_image
+  # ========================================================================= #
+  def absolute_image(
+      remote_url,
+      css_class = '',
+      the_id    = '',
+      css_style = ''
+    )
+    register_this_id(the_id)
+    result = string_absolute_img(
+               remote_url,
+               css_class,
+               the_id,
+               css_style
+             )
+    addnl(result)
+    return result
+  end; alias absolute_img absolute_image # === absolute_img
+
+  # ========================================================================= #
+  # === return_the_registered_base64_images
+  # ========================================================================= #
+  def return_the_registered_base64_images
+    ::Cyberweb.base64_images
+  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_image?(entry)
+    }
+  end; alias get_images_from get_images # === get_images_from
+
+  # ========================================================================= #
+  # === return_name_of_the_images_directory
+  #
+  # This method must always return the name of the default images directory,
+  # without any trailing '/'.
+  # ========================================================================= #
+  def return_name_of_the_images_directory
+    'images'
+  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
+
+end; end