html_toc 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7fe0bd1ed85bd6019fdc3989a0f54f8bfb9d1560
-  data.tar.gz: 0e172e14bc8e9422d117a203451c4ce71363eab2
+  metadata.gz: 8a29233f8816b3ee12494fea882d296d3541315f
+  data.tar.gz: 1ef8af28f0c1c7ffd80f07dd344abad4a63da1a9
 SHA512:
-  metadata.gz: 4717de16883ae3c3100b75e1c41e536c5b7b5d71017eb9099844c12cca80cd72e3fc331a42d4b41dc85028871fb96687df8ca79bab324df1242f489026d80dab
-  data.tar.gz: d71ebf5f843cde92e66e270638d6bd365fb638f2d4296adafa2ca56ecc8d177201cce3b81772155d9b804d18ce90ab995324cbbb2b5f2400002f3936d3caa69b
+  metadata.gz: 9ce2bc271cc049d832a6ac0c5ce2104f4cd7703de9b5a71884f67272f81d2316746e69d0dfc4021c6e74d31cc9e9295cbff81f2c62d61c58fb6433655aac4717
+  data.tar.gz: 05aa67dec91573dab6b1ac296589f6ddb4bf838bdab2156a4c900d089c24d37d96f669956f5c6fab229d39a329bca1a0c0742db47c464b3f7dd87eb9a873f7ca

data/README.md

@@ -0,0 +1,73 @@
+**Travis CI:** ![Latest test](https://travis-ci.org/GGadow/html_toc.svg?branch=master)
+
+#HtmlToc
+
+HtmlToc is a Ruby module that post-processes an HTML document to built a table of contents and insert it at a specified location. It takes in the source text of the page, and returns the modified text.
+
+##About
+
+The gem consists of a single module, <span style="color:#009900;">HtmlToc</span>, which exposes a single public method, <span style="color:#009900;">process</span>. 
+
+<span style="color:#009900;">#process</span> starts by performing a case-insensitive search for a token, **\[\[toc\]\]**. If no token is found, the unmodified source text is return. 
+
+If the token is found, <span style="color:#009900;">#process</span> scans for header tags falling within a provided range; if the header does not already have an id attribute, one is added. If no matching headers are found, the token is removed and the modified source text is returned.
+
+If headers are found, a link is generated for each matching header. The link text is taken from the header text, and the link's href points to the header's id. Each link wrapped in a div tag; the div is given a class name that matches is level relative to the search range. The link divs are wrapped in a few more divs with unique ids to create the table of contents. Lastly, the table of contents replaces the token and the modified source is returned. The classes and id allow the page to be styled in accordance with the website's design context. The resulting table of contents might look like this:
+
+<div style="border:solid 1px #000000;margin-left:1em;">
+
+&lt;div id='__toc'&gt;<br/>
+&nbsp;&nbsp;&lt;div id='__toc_header'&gt;Contents&lt;/div&gt;<br/>
+&nbsp;&nbsp;&lt;div id='__toc_content' style='display:block'&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#id__1'&gt;1 First (1<sup>st</sup>) major header&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__5'&gt;1.1 Minor header 1&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__11'&gt;1.1.1 Detail the first&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_1'&gt;1.1.2 Detail the second&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_2'&gt;1.2 Minor header 2&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_1'&gt;&lt;a href='#already_here_3'&gt;2 Second major header&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#id__2'&gt;2.1 Minor header 3&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#id__12'&gt;2.1.1 Detail the third&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_3'&gt;&lt;a href='#already_here_4'&gt;2.1.2 Detail the fourth&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;div class='__toc_level_2'&gt;&lt;a href='#already_here_5'&gt;2.2 Minor header 4&lt;/a&gt;&lt;/div&gt;<br/>
+&nbsp;&nbsp;&lt;/div&gt;<br/>
+&lt;/div&gt;
+
+</div>
+
+##Use
+
+**<span style="color:#009900;">HtmlToc.process</span> source:, h_tags: Range.new(2, 6), show_toggle: false, use_numbers: false**
+
+>**source** is a string holding the HTML source.
+
+>**h_tags** is a range of integers giving the indexes of the header tags that will be used to the table of contents. The method iterates through it to build the regular expression <span style="color:#800000;">/&lt;h#{x}(?: .\*?)?&gt;(.\*?)&lt;\/h#{x}&gt;/</span>. 
+
+>**show_toggle** flags whether or not to include a toggle button in the table of contents header. The span is programmed to call a Javascript method, ShowHideToc(). The implementing script is *not* included: it must be supplied by the programmer.
+
+>**use_numbers** flags whether or not the links will have outlining numbers. 
+
+##CSS
+
+These classes and ids are used by <span style="color:#009900;">HtmlToc</span> in the table of contents.
+
+>**#__toc** - The outer frame div.
+
+>**#__toc_header** - The header div.
+
+>**#__toc_content** - The contents div.
+
+>**#__toc_toggle** - The span containing the toggle.
+
+>**.__toc_level_x** - Used on the divs holding the links, with x ranging from 1 to 6. These are applied as the header tags are found, so using the default *h_tags*, __toc_level_1 will be associated with h2 tags, __toc_level_2 with h3 tags, and so on.
+
+
+##Additional files
+
+See **sample/html_toc.css** for an example of how to style the table of contents.<br/>
+See **sample/html_toc.js** for the Javascript to toggle visibility of the table of contents.
+
+##Change log
+
+**1.1** - Added keyword arguments.
+**1.0** - Initial deployment.
+

data/lib/html_toc.rb

@@ -3,7 +3,7 @@ require 'rexml/document'
 module HtmlToc
 
 	#Primary method call
-	def self.process source, h_tags=Range.new(2, 6), show_toggle=false, use_numbers=false
+	def self.process(source:, h_tags: Range.new(2, 6), show_toggle: false, use_numbers: false)
 
 		#Search regex for {{toc}}
 		token = /\[\[[tT][oO][cC]\]\]/

data/sample/html_toc.css

@@ -0,0 +1,43 @@
+div.__toc_level_1 {
+}
+
+div.__toc_level_2 {
+	padding-left:1em;
+}
+
+div.__toc_level_3 {
+	padding-left:2em;
+}
+
+div.__toc_level_4 {
+	padding-left:3em;
+}
+
+div.__toc_level_5 {
+	padding-left:4em;
+}
+
+div.__toc_level_6 {
+	padding-left:5em;
+}
+
+#__toc {
+	display:inline-block;
+	padding:0.5em;
+	border:solid 1px #AAAAAA;
+	background-color:#EEEEEE;
+}
+
+#__toc_content {
+	padding-top:0.75em;
+}
+        
+#__toc_header {
+	font-weight:bold;
+}
+
+#__toc_toggle {
+	cursor:pointer;
+	font-size:0.8em;
+	font-weight:normal;
+}

data/sample/html_toc.js

@@ -0,0 +1,8 @@
+var TOCState = 'block';
+
+function ShowHideToc() {
+    TOCState = (TOCState == 'none') ? 'block' : 'none';
+    var newText = (TOCState == 'none') ? 'Show' : 'Hide';
+    document.getElementById('__toc_toggle').innerHTML = newText;
+    document.getElementById('__toc_content').style.display = TOCState;
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html_toc
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Gregory Gadow
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-09 00:00:00.000000000 Z
+date: 2014-12-12 00:00:00.000000000 Z
 dependencies: []
 description: "This gem is intended to be used in Rails pre-processing, after the page
   has been generated but before it is delivered to the requestor. \n\nIt does a case-insensitive
@@ -24,9 +24,15 @@ description: "This gem is intended to be used in Rails pre-processing, after the
 email: gpg@gregory-gadow.net
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- sample/html_toc.css
+- sample/html_toc.js
 files:
+- README.md
 - lib/html_toc.rb
+- sample/html_toc.css
+- sample/html_toc.js
 homepage: https://github.com/GGadow/html_toc
 licenses:
 - MIT
@@ -39,7 +45,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -50,5 +56,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Generate and Insert a Table of Contents into a HTML Document
+summary: Generate and insert a table of contents into a HTML document
 test_files: []