html_tags 0.1.183

data/doc/README.gen

@@ -0,0 +1,256 @@
+DEFAULT_HEADER
+
+## Introduction to the HtmlTags gem
+
+<img src="https://i.imgur.com/A1MaV0i.png" style="margin: 1em">
+
+The <b>HtmlTags gem</b> is a somewhat small gem that will try to
+<b>autogenerate Strings</b> put into methods resembling the
+available HTML tags.
+
+Let's next have a look at a specific example supporting this statement.
+
+Take the following method call in Ruby:
+
+    span('foo')
+
+So, we call the method span() and pass the String 'foo' into it. The
+method .span() can be found as part of the HtmlTags gem.
+
+This will be expanded towards the following String:
+
+    <span>foo</span>
+
+In other words: the HtmlTags gem can be used to autogenerate 
+HTML code.
+
+This functionality is then made available to other projects, which
+can tap into that functionality, in particular the gem <b>cyberweb</b>.
+I use the latter gem for my custom cgi/sinatra/rails projects.
+
+The code that was part in the html_tags gem originally used to
+be part of the <b>cyberweb</b> gem in the past, until <b>html_tags</b>
+became a standalone gem, in the year <b>2013</b>.
+
+## Goals and Objectives for the HtmlTags gem
+
+The HtmlTags gem has various goals, some of which are more important
+than others.
+
+In no particular order, here are the different goals for this gem:
+
+    - Provide a way to generate all valid HTML tags, in particular for HTML5.
+    - Provide useful documentation as to how to use this project.
+    - Make the code as consistent as possible, unless the specific HTML tag at hand requires a different treatment
+    - Make the HtmlTags as self-contained as possible, e. g. no external dependencies.
+    - Make the HtmlTags as useful as possible, by also providing helper code unrelated to HTML-tags itself.
+    - Document the HTML that is supported by the gem. 
+
+## New ideas (playground for new ideas)
+
+We could replace code elements such as:
+
+    <button onclick="show_source()">Click me</button>
+
+With:
+
+    button.text('Click me').onclick('show_source')
+
+Or perhaps simple:
+
+    button('Click me').on_clicked {
+      show_source
+    }
+
+This is currently not implemented, though. Need to think more about
+it first.
+
+## Using HTML headers
+
+The following example shows how to use the <b>h1 tag</b> via
+HtmlTags:
+
+    HtmlTags.h1('Hello world!') # => "<h1>\nHello world!\n</h1>"
+
+You can include the module HtmlTags. Then you can just type <b>h1()</b>
+directly.
+
+Another example, this time for the <b>div tag</b>:
+
+    name = 'Joe'
+    puts HtmlTags.div("Hello, #{name}!") # => <div>Hello, Joe!</div>
+
+## HtmlTags.a
+
+The HTML <b>a</b> tag is for hyperlinks; typically it contains a 
+**href** entry.
+
+You can pass in a Hash, too, including a few supported JavaScript
+functions.
+
+Example for the latter:
+
+    onclick: 'change_the_colour_to()'
+
+Note that you still have to write the function somewhere and pull it
+into the .html file (or .cgi file or whatever else you are using).
+
+I added support for this in <b>October 2021</b>, as I needed to have clickable
+links that change colour upon being clicked. I used that to memorize
+which links I clicked, without having to depend on CSS.
+
+## Objectified HTML Tags
+
+This is mostly for clarification. An objectified HTML tag is
+a HTML tag that can be used like an object.
+
+Example:
+
+    Span.new('Hello world!') # => <span>Hello world!</span>
+
+The html_tags gem currently does not support this, but support for this
+may be added in the future, depending on whether that use case turns
+out to be sufficiently useful.
+
+## How to use HtmlTags.span()
+
+The span-tag in HTML creates something like this:
+
+    <span>Hello world!</span>
+
+To attach a CSS class to this, in HTML, one can use something such
+as:
+
+    <span class="padl1em">Hello world!</span>
+
+This is simple HTML.
+
+The html_tags gem also allows these use cases.
+
+For instance, consider the following:
+
+    e HtmlTags.span('Hey there')
+
+This is equivalent to the first variant shown before.
+
+The actual output will be:
+
+    <span>
+    Hey there</span>
+
+So there is a newline after the starting span-tag. The
+reason as to this is that I feel that, for readability,
+it is better to have a newline show up if you want to
+do a view-source action on the resulting .html file.
+
+Not everyone may want this, so we may need to have to
+add a toggle to strip newlines there. But for the time
+being this has to suffice.
+
+## How to use HtmlTags.a()
+
+Usage example for how to use <b>HtmlTags.a()</b>:
+
+    HtmlTags.a(
+      remote_url: remote_url,
+      text:       title?.to_s,
+      css_style: 'font-weight: bold; color: darkblue'
+    )
+
+## The structure of opening and closing tags
+
+This subsection just shows a tiny bit of the structure behind
+opening and closing tags.
+
+Consider a HTML a tag such as:
+
+    <a>
+
+This has three components: <b><</b>, <b>a</b> and <b>></b>.
+
+These <b>three components</b> are, in order, called:
+
+- opening bracket
+- element ID
+- closing bracket
+
+The closing tag, that is:
+
+    </a>
+
+Has one more component, the /, also called the forward slash
+(unsurprisingly so).
+
+Note that an opening tag can contain attributes.
+
+## The bdo tag
+
+<b>bdo</b> stands for <b>bi-directional override</b>.
+
+The purpose of the bdo tag in HTML is to specify the text direction
+or to override the current text direction. This is important
+for languages such as <b>Arabic</b> or <b>Hebrew</b>.
+
+Personally I do not really need this tag, but in the event that
+other users of the <b>html_tag</b> gem need support for the bdo-tag,
+support for it has been added to the html_tag gem in <b>June 2023</b>.
+
+The <b>bdo tag</b> has a special attribute called <b>dir</b> - an
+abbreviation standing for <b>direction</b>.
+
+The dir attribute specifies the direction in which the text will
+be displayed.
+
+Only two values are permissive for the dir attribute:
+
+(1) <b>ltr</b>: It means left to right. The text inside the bdo tag will
+be rendered from left to right. This is the default value.
+
+(2) <b>rtl</b>: It means right to left. The text inside the bdo tag
+will be rendered from right to left.
+
+Note that you can use the CSS class rtl-lang instead, so I am not
+sure why that HTML tag is necessary.
+
+At any rate, an invocation example follows:
+
+    HtmlTags.bdo()
+
+## Working with HTML tables
+
+You can use <b>HtmlTags.table</b> to create a String that represents
+a HTML table. In January 2024 this functionality was extended a bit,
+in that you can pass an Array to this method, via the block form.
+That Array will be used as content for the HTML table at hand.
+
+Usage example is this API:
+
+    puts HtmlTags.table(nil,'mars1em','test_table','border:1px solid rand') {
+      %w( abc def ghi jkl )
+    }
+
+This would generate the following String:
+
+    <table class="mars1em" id="test_table" style="border:1px solid rand">
+    <tr><td>
+    abc</td><td>
+    def</td></tr><tr><td>
+    ghi</td><td>
+    jkl</td></tr>
+    </table>
+
+Quite convenient, isn't it?
+
+## Available HTML tags
+
+The following HTML tags are valid, in <b>HTML5</b>:
+
+DISPLAY_THIS_FILE /home/x/programming/ruby/src/html_tags/lib/html_tags/yaml/available_html_tags.yml
+
+In the long run the HtmlTags project should offer support
+for <b>all</b> these HTML tags. This applies mostly to HTML5-tags
+though; for instance, the <b>acronym tag</b> is no longer valid
+in HTML5, and will thus not be supported by the html_tags
+project.
+
+ADD_EMAIL

data/html_tags.gemspec

@@ -0,0 +1,48 @@
+# =========================================================================== #
+# Gemspec for Project HtmlTags.
+# =========================================================================== #
+require 'html_tags/version/version.rb'
+require 'roebe/toplevel_methods/misc.rb'
+
+Gem::Specification.new { |s|
+
+  s.name    = 'html_tags'
+  s.version = HtmlTags::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+    This library is called html_tags.
+
+    Its fundamental core idea is to collect all valid html tags into
+    a single project, and then make this data available to other
+    projects.
+
+    Other ideas are to autogenerate closing tags (helper
+    methods), and of course to generate string representations
+    of these html tags. This can then be used by other 
+    web-projects.
+
+    A simple usage example follows:
+
+      require 'html_tags'
+      HtmlTags.p 'hello world!' # => "<p>\nhello world!\n</p>"
+
+  EOF
+
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+  s.extra_rdoc_files = %w()
+
+  s.authors   = ['Robert A. Heiler']
+  s.email     = Roebe.email?
+  s.files     = Dir['**/*']
+  s.files    << 'USAGE.md'
+  s.license   = 'MIT'
+  s.homepage  = 'https://rubygems.org/gems/html_tags'
+
+  s.required_ruby_version     = '>= '+Roebe.third_most_stable_version_of_ruby
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+}

data/lib/html_tags/array_registered_html_tags.rb

@@ -0,0 +1,126 @@
+module HtmlTags # require 'html_tags/array_registered_html_tags.rb'
+
+  # ========================================================================= #
+  # === ARRAY_REGISTERED_HTML_TAGS
+  #
+  # Please also add to this array whenever you add a new html tag.
+  #
+  # Sort alphabetically.
+  #
+  # For references, look at the periodic table for HTML tags to find out
+  # which ones are available:
+  #
+  #     https://developer.mozilla.org/en-US/docs/Web/HTML/Element
+  #     https://developer.mozilla.org/de/docs/Web/HTML/Element
+  #
+  # In January 2014 it stated that 107 Elements are known. However, the
+  # mozilla reference in March 2015 listed 136 HTML elements.
+  #
+  # <b> is no longer valid in HTML5 it seems.
+  # ========================================================================= #
+  ARRAY_REGISTERED_HTML_TAGS = %w(
+
+a
+abbr
+audio
+
+b
+blockquote
+body
+br
+button
+
+canvas
+
+div
+dd
+dl
+dt
+
+fieldset
+figure
+form
+
+head
+html
+h1
+h2
+h3
+h4
+h5
+h6
+hr
+
+i
+img
+input
+
+label
+legend
+li
+
+nav
+
+object
+
+p
+pre
+
+q
+
+span
+strong
+style
+
+table
+tbody
+td
+textarea
+th
+thead
+tr
+
+ul
+
+  )#+ # The following elements I did not yet think about much at all
+      # We may add these one after the other eventually though.
+   # %w(
+   #   html head span title # meta rt base rp link noscript
+   #   style script dfn abbr q cite em time var samp i b
+   #   sub sup small strong mark ruby ins del bdi bdo s
+   #   kbd wbr code br hr figcaption figure p ol ul li
+   #   div pre blockquote fieldset metr legend
+   #   label input textarea form select opgroup option
+   #   output button body aside address datalist keygen
+   #   progress h1 h2 h3 h4 h5 h6 section header nav
+   #   article footer hgroup col colgroup caption menu
+   #   command summary details table tr td th tbody thead
+   #   tfoot img area map embed object param source iframe
+   #   canvas track audio video
+   #)
+
+  # ========================================================================= #
+  # === ARRAY_TAGS_WITHOUT_CLOSING_TAG
+  #
+  # The following array keeps track of which tags have no closing tag.
+  # Please sort alphabetically.
+  # ========================================================================= #
+  # The <img> tag is no longer a part of the above Array since as
+  # of June 2016.
+  # ========================================================================= #
+  ARRAY_TAGS_WITHOUT_CLOSING_TAG = %w(
+
+    br
+
+  )
+
+  # ========================================================================= #
+  # === registered_html_tags?
+  #
+  # Feedback all registered HTML tags next.
+  # ========================================================================= #
+  def registered_html_tags?
+    Kernel.p ARRAY_REGISTERED_HTML_TAGS 
+  end
+
+end

data/lib/html_tags/autoinclude.rb

@@ -0,0 +1,2 @@
+require 'html_tags'
+include HtmlTags

data/lib/html_tags/autoinclude_base_module.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'html_tags'
+
+include HtmlTags::BaseModule

data/lib/html_tags/base/README.md

@@ -0,0 +1,3 @@
+Code in this directory can be used to subclass from a HtmlTags::Base
+class that may allow you to make use of the registered html-tags in
+this project.

data/lib/html_tags/base/base.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'html_tags/base/base.rb'
+# =========================================================================== #
+module HtmlTags
+
+class Base
+
+end; end