Versions: Serious & Fun & Grotesque & Downloads

Add1toCOBOL.Lua - a library for Soupault Plugins


Return to Navigation

Add1toCOBOL.Lua is a third party library that provides useful plugins, widget settings, variables and functions for Soupault projects and Soupault plugins. The ADD1.Plugins demonstrate how to use the Add1toCOBOL.Lua library in your own plugins. The Add1toCOBOL.Lua website is:

http://soupault.add1tocobol.com/add1tocobol-lua/.

Soupault is a static website management tool based on HTML element tree rewriting. It includes the ability to process plugins written in Lua to extend its capabilities. The Soupault website is https://soupault.neocities.org/. The Lua website is https://www.lua.org/.

This document will not elaborate on Soupault or Lua concepts. We presume you already know how to use Soupault and Lua if you are about to create plugins for Soupault. If you do not know how to use these then read their websites to learn more. This document will focus on Add1toCOBOL.Lua usage.

ADD1.Features


Return to Navigation

Add1toCOBOL.Lua adds the following features to Soupault:

ADD1.Plugins for Soupault Widgets:

ADD1.Settings for Soupault Widgets:

ADD1.Variables for Soupault Plugins:

ADD1.Functions for Soupault Plugins:

ADD1.Terminology


Return to Navigation

ADD1.Version


Return to Navigation

This library is so new that we are not even giving it a version number yet.

ADD1.Installation


Return to Navigation

The Add1toCOBOL.Lua library is a single zip file for all operating systems. Currently all Add1toCOBOL.Lua features are Operating System agnostic and should work on all operating systems. We will note if any specific features require specific operating systems in the future.

To install Add1toCOBOL.Lua for your project:

Download the latest version directly at http://soupault.add1tocobol.com/add1tocobol-lua/downloads/add1tocobol-lua.zip. You can access other versions at http://soupault.add1tocobol.com/add1tocobol-lua/downloads/.

Unzip add1tocobol-lua.zip into your project's plugin directory which is usually:
YourProject/plugins/

This will populate all the needed Add1toCOBOL.Lua files into the directory:
YourProject/plugins/add1tocobol/

Edit the plugins_dir= setting of the [settings] section of the soupault.conf file for your project to add "plugins/add1tocobol" as one of the options. For instance:

[settings]
  # Gives the plugins we will use
  plugin_dirs = [ "plugins",
                  "plugins/soupault",
                  "plugins/add1tocobol",
                  "plugins/yourplugins"]

The plugin_dirs option is very important or else you won't be able to use Add1COBOL.Lua plugins, widget settings, variables or functions. This is necessary for all features.

That's it, you are finished with the installation. To learn how to use the Plugins, Widget Settings, Variables and Functions in your own projects read those sections. You can use any of the Plugins, without making your own plugins.

ADD1.Setup


Return to Navigation

In this document we will presume a standard Soupault project setup with a standard Add1toCOBOL.Lua library setup. This includes all standard directories such as site/ build/ plugins/ templates/ and so on. Adjust the settings provided to meet your setup if it is non-standard.

The soupault executable is run from the main directory of your project. A typical Soupault/Add1toCOBOL.Lua project tree might look something like this:

.mainProjectDirectory
+-- build
|   +-- fun
|   |   +-- index.html
|   |   +-- movies.html
|   |   +-- skydiving
|   |   |   +-- index.html
|   |   |   +-- logo.jpg
|   |   +-- swimming.html
|   +-- images
|   |   +-- logo.jpg
|   |   +-- map.jpg
|   |   +-- news
|   |       +-- logo.jpg
|   |       +-- map.jpg
|   +-- index.html
|   +-- news
|       +-- index.html
|       +-- sports.html
|       +-- weather.html
+-- plugins
|   +-- add1tocobol
|   |   +-- add1tocobol.lua
|   |   +-- colorize-characters.lua
|   |   +-- colorize-elements.lua
|   |   +-- colorize-words.lua
|   |   +-- do-code.lua
|   |   +-- insert-html.lua
|   |   +-- README.md
|   |   +-- todo.txt
|   |   +-- tree-image-file.lua
|   |   +-- tree-image-src.lua
|   |   +-- tree-template-include.lua
|   +-- soupault
|       +-- escape-html.lua
|       +-- git-timestamp.lua
|       +-- inline-include.lua
|       +-- insert-if.lua
|       +-- quick-links.lua
|       +-- reading-time.lua
|       +-- section-link-highlight.lua
|       +-- site-url.lua
|       +-- source-link.lua
+-- site
|   +-- fun
|   |   +-- index.html
|   |   +-- movies.html
|   |   +-- skydiving
|   |   |   +-- index.html
|   |   |   +-- logo.jpg
|   |   +-- swimming.html
|   +-- images
|   |   +-- logo.jpg
|   |   +-- map.jpg
|   |   +-- news
|   |       +-- logo.jpg
|   |       +-- map.jpg
|   +-- index.html
|   +-- news
|       +-- index.html
|       +-- sports.html
|       +-- weather.html
+-- soupault.conf
+-- templates
    +-- footer.html
    +-- header.html
    +-- main.html
    +-- news
        +-- footer.html
        +-- header.html
        +-- main.html

If you are already familiar with Soupault, then this tree structure should be easy to understand. There are special applications in Add1toCOBOL.Lua for the directories: plugins/, templates/ and site/images/.

plugins/


Return to Navigation

Our plugins/ directory has plugins grouped by provider. We store the standard Soupault plugins in:

plugins/soupault/

While the Add1toCOBOL.Lua plugins and library are stored in:

plugins/add1tocobol/

This setup was created in order to prevent conflicts with identically named files from different providers. Nevertheless, identically named files even in different directories will cause conflicts in the plugins and widget sections of soupault.conf. But, at least this structure keeps us from accidentally overwriting each others' plugins.

Additionally, this structure is forward thinking to a time when plugins might have some kind of namespacing. You can place more plugins directly in plugins/ or in subdirectories such as plugins/myplugins/ etc.

templates/


Return to Navigation

The directory templates/ is a special default directory to Add1toCOBOL.Lua. We have plugins that will search this for particular template files. If you are using a different directory to store your templates, then you will need to change a widget setting for any widgets using those plugins.

site/images/


Return to Navigation

The directory site/images is a special default directory to Add1toCOBOL.Lua. We have plugins that will search this for particular image files. If you are using a different directory to store your images, then you will need to change a widget setting for any widgets using those plugins.

ADD1.Plugins & ADD1.Widgets


Return to Navigation

Add1toCOBOL.Lua has several plugins. We provide an example for each ADD1.Plugin. See the examples we provide to get started.

ADD1.Plugins can be used in any Soupault project without the need to understand how to make a plugin. Just follow the standard Soupault method of creating a widget in soupault.conf:

[widgets.something]
  widget = "plugin-name"
  setting = "value"

We have special widget settings that are used in all of these plugins in a standardized way. They are all explained in the ADD1.Settings section. Some common Soupault widget settings such as page=, page_exclude= and others are applied by Soupault by all widgets that use those settings.

The most important ADD1.Setting to know about for now is the selectors= ADD1.setting. It is a replacement for the standard Soupault selector= setting. The selectors= setting allows you to use a comma separated list of css selectors and the widget will process all of them, rather than just one selector. It is used in all of our plugins. Should any in the future not use the setting we will note it in that plugin's documentation.

The ADD1.Plugins are:

For each plugin we will show the minimum necessary code in the widget area to activate the plugin. We will explain what t he widget does, show the results. Then go into more detail if warranted.

Each plugin can be used for multiple widgets as is usual with Soupault. The selectors we use are examples only and you can apply any selectors list you want to your widget. You can also use more widget settings than we have in the example. So let's see how all of these work.

add-class.lua


Return to Navigation

[widgets.classy]
  widget = "add-class"
  selectors = "p"
  class = "quiz"

The add-class.lua plugin adds a class to every matching element element.

The class widget sets the class "quiz" to all P elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<p class="quiz">
  This is a paragraph
</p>
<p class="quiz">
  This is another paragraph
</p>

add-style.lua


Return to Navigation

[widgets.stylish]
  widget = "add-style"
  selectors = "p"
  style = "font-size: 39em;"

The add-style.lua plugin adds a style to every matching element element.

The stylish widget sets the style "font-size: 39em;" to all P elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<p style="font-size: 39em;">
  This is a paragraph
</p>
<p style="font-size: 39em;">
  This is another paragraph
</p>

block-maker.lua needs written


Return to Navigation

needs written

colorize-backgrounds.lua


Return to Navigation

[widgets.weird-backgrounds]
  widget = "colorize-backgrounds"
  selectors = "p"

The colorize-backgrounds.lua plugin sets the style attribute of every matching element's background to a random color. Use rejected="r,g,b" to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

The weird-backgrounds widget sets a random background color to all P elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<p style="background: rgb(99, 103, 40);">
  This is a paragraph
</p>
<p style="background: rgb(248, 133, 216);">
  This is another paragraph
</p>

colorize-characters.lua


Return to Navigation

[widgets.colorize-headers]
  widget = "colorize-characters"
  selectors = "h1,h2,h3,h4,h5,h6"

The colorize-characters.lua plugin wraps every character of all matching elements with a span element. Then it sets the style attribute of each of those span elements to a random color. It ignores spaces. Use rejected="r,g,b" to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

The colorize-headers widget sets a random color to all the characters of all the H1-H6 elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<h2>Buddy!</h2>

After HTML:

<h1>
  <span style="color: rgb(99, 103, 40);">H</span>
  <span style="color: rgb(248, 133, 216);">O</span>
  <span style="color: rgb(186, 215, 20);">M</span>
  <span style="color: rgb(45, 35, 100);">E</span>
</h1>
<h2>
  <span style="color: rgb(155, 4, 62);">B</span>
  <span style="color: rgb(35, 205, 40);">u</span>
  <span style="color: rgb(102, 33, 27);">d</span>
  <span style="color: rgb(255, 55, 131);">d</span>
  <span style="color: rgb(214, 156, 75);">y</span>
  <span style="color: rgb(163, 134, 126);">!</span>
</h2>

colorize-elements.lua


Return to Navigation

[widgets.colorize-paragraphs]
  widget = "colorize-elements"
  selectors = "p"

The colorize-elements.lua plugin sets the style attribute of every matching element to a random color. Use rejected="r,g,b" to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

The colorize-paragraphs widget sets a random color to all P elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<p style="color: rgb(99, 103, 40);">
  This is a paragraph
</p>
<p style="color: rgb(248, 133, 216);">
  This is another paragraph
</p>

colorize-words.lua


Return to Navigation

[widgets.colorize-firstparagraph]
  widget = "colorize-words"
  selectors = "h1 + p,h2 + p,h3 + p,h4 + p,h5 + p,h6 + p"

The colorize-words.lua plugin wraps every word of all matching elements with a span element. Then it sets the style attribute of each of those span elements to a random color. The word separator is one or more spaces. Other than that it ignores spaces. Use rejected="r,g,b" to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

The colorize-firstparagraph widget sets every word of all each P that immediately follows an H1-H6 element to different random colors. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>
<h2>Not Home</h2>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<p style="color: rgb(99, 103, 40);">
  This is a paragraph
</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<p style="color: rgb(248, 133, 216);">
  This is paragraph
</p>
<p>This is another paragraph</p>

content-to-class.lua needs written


Return to Navigation

needs written

delete-elements.lua needs written


Return to Navigation

needs written

do-code.lua


Return to Navigation

[widgets.red-headings]
  widget = "do-code"
  selectors = "h1,h2,h3,h4,h5,h6"
  luacode = 'HTML.set_attribute(element,"style","color:red")'

The do-code.lua plugin performs whatever Lua code is in the luacode="" widget setting for every matched element.

The red-headings widget sets all the H1-H6 elements to the color red. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<p>This is paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1 style="color:red;">HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2 style="color:red;">Not Home</h2>
<p>This is paragraph</p>
<p>This is another paragraph</p>

WARNING: Be very careful with this plugin.

We created this plugin mostly as a way to test an idea before we went through the full process of creating a plugin. It can also be used for situations where we just want to do something simple like changing the color of an element, which is what we do here in our example.

The text in the luacode= setting can be any Lua code, including full access to Soupault's config array, HTML.Module, Regex.Module, Plugin.Model, Sys.Module, ADD1.Variables, ADD1.Functions, your functions, your arrays, your variables, and so on. The full power of Lua is at your fingertips, including commands that could delete files so be very careful.

The luacode= widget setting should be surrounded by single quotes rather than double quotes in case you want to use quotes in your code. Doing it the reverse way will result no effect at all or an error.

include-tag.lua needs written


Return to Navigation

needs written

insert-html.lua


Return to Navigation

[widgets.add-hr-to-h2]
  widget = "insert-html"
  selectors = "h1,h2"
  html = "<hr>"

The insert-html.lua plugin inserts the contents of the html= widget setting in matching elements.

The add-hr-to-h2 widget places an HR element after all the H1 and H2 elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<p>This is paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<hr>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<hr>
<p>This is paragraph</p>
<p>This is another paragraph</p>

insert-html-if.lua NEEDS CORRECTED


Return to Navigation

needs corrected just straight copied from insert-html.lua so not correct yet...

[widgets.add-hr-to-h2]
  widget = "insert-html"
  selectors = "h1,h2"
  html = "<hr>"

The insert-html.lua plugin inserts the contents of the html= widget setting in matching elements.

The add-hr-to-h2 widget places an HR element after all the H1 and H2 elements. It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

<h1>HOME</h1>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<p>This is paragraph</p>
<p>This is another paragraph</p>

After HTML:

<h1>HOME</h1>
<hr>
<p>This is a paragraph</p>
<p>This is another paragraph</p>

<h2>Not Home</h2>
<hr>
<p>This is paragraph</p>
<p>This is another paragraph</p>

pre-me.lua needs corrected


Return to Navigation

[widgets.pre-me]
  widget    = "pre-me"

CORRECT THIS documentation because it does take selectors now and so on...

The pre-me.lua plugin converts all HTML in PRE elements to HTML entities in matching elements. It takes no settings at all even selectors. It processes all PRE elements in your document.

Before HTML:

Just imagine your PRE elements have HTML in them...

After HTML:

Now imagine all that HTML is HTML entities instead...

LOOK it is gonna be really hard for me to show the code because my pre-me.lua is going to try to convert my example into HTML entities and i am not smart enough to figure out how to do the example. Ok! Jeez get over yerself!!!!!

File Tree Search Explained


Return to Navigation

The concepts in this section apply to multiple plugins and functions so we are only going to explain them once, here. The plugins and functions are:

The Add1toCOBOL.lua library includes a few plugins and a function to search for a specific file using the path.to.file as a guide for where to search. Once the most appropriate file is found one of three things will happen.

  1. For a function, the file's full path will be returned to the function.

  2. For template plugins, the file's contents will be included into the html tree.

  3. For image plugins, the file's path will be set as the src= attribute of an img element.

The point is to give you maximum flexibility with minimal effort in deciding which files will be used in various parts of your site.

For instance you might want all sections under staff/ to share the same banner.jpg so that each staff member inherits that same image. But each section under news, news/weather, news/sports, news/sports/basketball, news/sports/football to have separate banner images emphasizing that section of the news.

You might want the same footer.html template to be used throughout the site but desire header.html and nav.html templates to be different in different sections of your website.

There are two things that are needed for the search. A path to search and a file to search for. Depending on the plugin, either of these might be obtained automatically or with a widget setting. Each plugin will detail how it knows what to search for. You just need to know that we are looking for a path to search and a file to search for.

Some plugins search one path, some plugins search two paths. Image altering plugins search site/path.to.file and site/images/path.to.file. Template plugins search templates/path.to.file.

File is the file you are searching for, not the file being processed. For templates, the file being searched will always be in the file= widget setting. With images, depending on the plugin, the file being searched for might be in the file= widget setting. Or the file being searched for might be taken from the src= attribute of the specific img element that is being processed.

For instance, let's say the file the file being processed is site/news/sports/football.html. An image we are searching for is banner.jpg. A template we are search for is header.html. The following two lists show the the directories and files we are searching for and the order they will be searched.

For banner.jpg this is the search list:

  1. site/news/sports/banner.jpg
  2. site/news/banner.jpg
  3. site/banner.jpg
  4. site/images/news/sports/banner.jpg
  5. site/images/news/banner.jpg
  6. site/images/banner.jpg

If at any point the banner.jpg is found, the search stops and that location is put in the img src= attribute. If no banner.jpg is found then no change is made.

For header.html template this is the search list:

  1. templates/news/sports/header.html
  2. templates/news/header.html
  3. templates/header.html

If at any point the header.html is found, the search stops and the contents of that file are included in HTML tree. If no header.html is found then no change is made.

So let's say your website contains sections news/, staff/, faq/, staff/ and shopping/. And you want different headers for news/, staff/ but the same header for the rest of your site. Just create templates/headers.html, templates/news/headers.html and templates/staff/headers.html.

The same concept applies for images. Using banner images just create site/images/banner.jpg, site/images/news/banner.jpg, site/images/staff/banners.jpg.

The plugins that use this feature are next in the documentation. The functions that use this feature are in the ADD1.Functions section.

tree-image-file.lua


Return to Navigation

[widgets.banner-image]
   widget    = "tree-image-file"
   file      = "banner.jpg"
   selectors = "img.banner"
   images    = "assets/images"  

The tree-image-file.lua plugin searches directories for files matching the widget setting file= and if it finds any then it alters the src attribute of matching img elements.

The banner-image widget sets the src attribute of all img elements with a class of "banner" to the most appropriate banner.jpg in the file tree. We set the widget setting images= to "assets/images" so that is what will searched. If we do not set it to anything then "images" is what will be searched since "images" is the default.

The example shows four separate files in the before and after for clarity. Notice how none of the img elements have a src attribute until we process this plugin. Also notice how sports and football both use "/news/sports/banner.jpg". Also notice that some of the src= attributes are altered to use the /images/ directory and some are not.

It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

file:site/news/index.html
<h1>HOME</h1>
<p><img class="banner"></p>

file:site/news/weather/index.html
<h1>HOME</h1>
<p><img class="banner"></p>

file:site/news/sports/index.html
<h1>HOME</h1>
<p><img class="banner"></p>

file:site/news/sports/football/index.html
<h1>HOME</h1>
<p><img class="banner"></p>

After HTML:

file:site/news/index.html
<h1>HOME</h1>
<p><img class="banner" src="/images/news/banner.jpg"></p>

file:site/news/weather/index.html
<h1>HOME</h1>
<p><img class="banner" src="/images/news/weather/banner.jpg"></p>

file:site/news/sports/index.html
<h1>HOME</h1>
<p><img class="banner" src="/news/sports/banner.jpg"></p>

file:site/news/sports/football/index.html
<h1>HOME</h1>
<p><img class="banner" src="/news/sports/banner.jpg"></p>

This plugin is almost identical to tree-image-src but uses the same search filename for all the matching elements taken from the file= widget setting. If you want to search for files based on the src= attribute of each particular img element itself, then see the directions for the tree-image-src.lua plugin.

Note: We do not validate that the element is an img. So this plugin could add src to any other element that matches in selectors=.

tree-image-src.lua


Return to Navigation

[widgets.tree-all-my-images]
  widget    = "tree-image-src"
  selectors = "img"
  images = "images"

The tree-image-src.lua plugin searches directories for any files matching an img element's src= attribute. If it finds any it alters the src attribute of that img element. This is useful when you want to have different images depending on where you are in the site.

The tree-all-my-images widget sets the src attribute of all img elements to the most appropriate in the file tree matching it's src= attribute. We set the widget setting images= to "images" so that is what will searched. If we do not set it to anything then "images" is still what will be searched since "images" is the default.

The example shows four separate files in the before and after for clarity. Notice how the src is set based on the original src of the img element. Also notice how sports and football each use different locations for "champs.jpg". It modifies this before html snippet, turning it into this after html snippet.

Before HTML:

file:site/news/index.html
<h1>HOME</h1>
<p><img src="banner.jpg"></p>

file:site/news/weather/index.html
<h1>HOME</h1>
<p><img src="banner.jpg"></p>

file:site/news/sports/basketball/index.html
<h1>HOME</h1>
<p><img src="champs.jpg"></p>

file:site/news/sports/football/index.html
<h1>HOME</h1>
<p><img src="champs.jpg"></p>

After HTML:

file:site/news/index.html
<h1>HOME</h1>
<p><img src="/banner.jpg"></p>

file:site/news/weather/index.html
<h1>HOME</h1>
<p><img src="/news/weather/banner.jpg"></p>

file:site/news/sports/basketball/index.html
<h1>HOME</h1>
<p><img src="/news/basketball/champs.jpg"></p>

file:site/news/sports/football/index.html
<h1>HOME</h1>
<p><img src="/news/sports/football/champs.jpg"></p>

This plugin is almost identical to tree-image-file.lua but uses different search filenames for all the matching elements based on the src= attribute of each img element. If you want to search for files based on the file= widget setting, then see the directions for tree-image-file.lua plugin.

Note: We do not validate that the element is an img. So this plugin could change the src any other element that matches in selectors= and has a src=.

tree-template-include.lua


Return to Navigation

[widgets.copyright]
  widget = "tree-template-include"
  file = "copyright.html"
  selectors = "#copyright"
  templates = "templates"

The tree-template-include.lua plugin searches the templates directory and subdirectories for templates matching the file= widget setting. If it finds any it inserts the contents of that file in matching elements. This is extremely useful to allow different header.html, footer.html, menu.html and other templates depending on where you are in the site.

The copyright widget searches for the most appropriate copyright.html in the file tree. Then it includes that file unchanged into the selector. We set the widget setting templates= to "templates" so that is what will searched. If we do not set it to anything then "templates" is still what will be searched since "templates" is the default.

We give to different examples. The first is site/news/football/index.html and the second site/news/weather/index.html

templates/copyright.html:

<p class="copyright">Website Copyright!</p>

templates/news/sports/copyright.html:

<p class="copyright">Sports Copyright!</p>

Before HTML for site/news/weather.html:

<h1>Weather</h1>
<p>Expect Rain</p>

<div id="copyright"></div>

Before HTML for site/news/sports/football.html:

<h1>Football!</h1>
<p>Cleveland Indians vs Cleveland Cavaliers!</p>

<div id="copyright"></div>

After HTML for site/news/weather.html:

<h1>Weather</h1>
<p>Expect Rain</p>

<div id="copyright">
  <p class="copyright">Website Copyright!</p>
</div>

After HTML for site/news/sports/football.html:

<h1>Football!</h1>
<p>Cleveland Indians vs Cleveland Cavaliers!</p>

<div id="copyright">
  <p class="copyright">Sports Copyright!</p>
</div>

The uses for this are endless. You can have different language sections. This is a real world case I am using this plugin for right now. You could have footers with different contact information depending on the area of the site. And more.

It basically allows you to handcraft your site now without requiring separate main.html templates for different areas of your site and without having to do independent file.html in different use cases...

To be honest when I said the uses are endless that is not entirely true. For instance it's not going to do squat to phuq'ng help me seduce Isabel Merced. More's the pity.

ADD1.Settings


Return to Navigation

Soupault widget settings are placed in your soupault.conf file and passed from Soupault to the plugin called by the widget.

In the examples for ADD1.Plugins and ADD1.Widgets we provided the minimum widget settings to make each ADD1.Plugin and Add1.Widget work. But there are more widget settings in two categories.

First, there are Soupault widget settings. Soupault has several widget settings that apply across all widgets such as page= and page_exclude=. The Soupault widgets that apply to all widgets will generally work on our widgets as well. For their usage see the Soupault documentation.

Second, we have created special widget settings for the Add1toCOBOL.Lua library. These widget settings are used in a consistent way in all our of plugins. The plugins you create using these settings will provide the same results if you use the ADD1.Variables and ADD1.Functions in your plugins.

Here, we explain what each widget setting is, what it does, what its defaults to and what its ADD1.Variable companion is in ADD1.Plugins Lua code.

The ADD1.Settings are:

Action ADD1.Setting


Return to Navigation

action = any of:

Action determines what action a widget will perform on an element. It is based on the Soupault HTML functions library. These actions are:

If action is not set then the default, append_child, will be set automatically by the Add1toCOBOL.Lua library.

ADD1.action variable contains the value of the action widget setting for use in any plugin or function.

Selectors ADD1.Setting


Return to Navigation

selectors = "multiple valid comma separated selectors"

eg.

selectors = "p,div.content"

NO DEFAULT

The selectors widget setting is identical to Soupault's selector widget setting except that it processes multiple comma separated css selectors. You write your css selectors exactly as you normally would in a typical css file. So all of these are valid:


selectors = "h1,h2"
selectors = "p, article, article.news, div.news"
selectors = "h1,p#heading,heading"
selectors = "div#content,div#header,div#footer"
selectors = "img,p.logo"

And so on.

All selectors and elements matching those selectors will be processed based on the next two widget settings, selectors_apply and elements_apply.

Note, selectors widget setting does not have a default. If you put nothing in, you will get nothing back.

ADD1.selectors variable contains an array of all the values of the selectors widget setting for use in any plugin or function.

ADD1.selectorsCount variable contains a count of all of the values in ADD1.selectors variable for use in any plugin or function.

ADD1.selectorsIndex variable will be initialized to 1.

Selectors Apply and Elements Apply ADD1.Settings


Return to Navigation

selectors_apply = "all" (default) or "first"

elements_apply = "all" (default) or "first"

The two widget settings selectors_apply and elements_apply work together to determine which elements a widget will process from those that match the values in the selectors widget setting.

Both allow only the two values "first" and "all". The default for both is "all". If either is not set, then it's value will be "all". Any value other than "first" will result in "all" as well. Thus, below when we say "all" we mean any value other than "first" explicitly.

Now we will show the four different cases. For all four cases we will use a pseudo widget that adds class="yes" to matched elements. We will also use this pseudo HTML for the four case example results.


h1
h2
h1
h2

Case 1 Both All.


Return to Navigation

If both are "all" then every matched element of every matched selector will be processed. Notice in the result that all H1 and H2 elements have been modified.


[widgets.both-all]
  widget          = "pseudo-plugin"
  selectors       = "h1,h2"
  selectors_apply = "all"
  elements_apply  = "all" 
  alter_class     = "yes"

-- results:
h1 class="yes"
h2 class="yes"
h1 class="yes"
h2 class="yes"

Case 2 selectors_apply all, elements_apply first.


Return to Navigation

If selectors_apply = "all" and elements_apply = "first" then only the first matched element of a selector will be processed even if there are multiple matching elements of that selector. Then the next selector will be checked to see if it has matching elements and if it does only the first one will be processed, even if there are other matching elements for that selector. And so on.

Notice that indeed an H1 and an H2 is changed but only the first in each.


[widgets.selectors-all-elements-first]
  widget          = "pseudo-plugin"
  selectors       = "h1,h2"
  selectors_apply = "all"
  elements_apply  = "first" 
  alter_class     = "yes"

-- results:

h1 class="yes"
h2 class="yes"
h1
h2

Case 3 selectors_apply first, elements_apply all


Return to Navigation

If selectors_apply = "first" and elements_apply = "all" then only the first selector that has matching elements will be processed even if there are other selectors with matching elements. But all the matching elements of that first selector will be processed.

Notice that all H1 elements are changed but no H2 elements are changed.


[widgets.selectors-first-elements-all]
  widget          = "pseudo-plugin"
  selectors       = "h1,h2"
  selectors_apply = "first"
  elements_apply  = "all" 
  alter_class     = "yes"

-- results:
h1 class="yes"
h2
h1 class="yes"
h2

Case 4 Both First


Return to Navigation

If selectors_apply = "first" and elements_apply = "first" then only the first selector that has matching elements will be processed even if there are other selectors with matching elements. Further, only the first matching element of that selector will be processed even if there are other matching elements for that selector.

Lastly notice that only the first H1 is changed.


[widgets.selectors-first-elements-first]
  widget          = "pseudo-plugin"
  selectors       = "h1,h2"
  selectors_apply = "first"
  elements_apply  = "first" 
  alter_class     = "yes"

-- results:
h1 class="yes"
h2
h1
h2

ADD1.selectorsApply variable contains the value of the selectors_apply widget setting for use in any plugin or function.

ADD1.elementsApply variable contains the value of the elements_apply widget setting for use in any plugin or function.

Raw ADD1.Setting


Return to Navigation

raw = ""(default) or "raw"

The raw= widget setting has only two values, raw="raw" and raw="anything that isn't raw". If the value is "raw" then html code within the content is turned into html entities. Otherwise the content is left as html elements. The default for raw is not set. So by default all content is left as html elements and not converted to html entities.

Example:


[widgets.raw]
  widget = "somewidget"
  raw = "raw"
  html = "<h1>Test Raw</h1>"

  -- html results:
&lt;h1&gt;Test Raw&lt;/h1&gt;

[widgets.notraw]
  widget = "somewidget"
  raw = ""
  html = "<h1>Test Raw</h1>"

  -- html results:
<h1>Test Raw</h1>

[widgets.notrawer]
  widget = "somewidget"
  html = "<h1>Test Raw</h1>"

  -- since raw is not set then
  -- raw is not = "raw" so
  -- html code is not converted to
  -- html entities
  -- html results:
<h1>Test Raw</h1>

ADD1.raw variable contains the value of the raw widget setting for use in any plugin or function.

Directory ADD1.Settings


Return to Navigation

images = "images" (default) or "anything else"

plugins = "plugins" (default) or "anything else"

templates = "templates" (default) or "anything else"

There are three directory widget settings that create ADD1.variables; images, plugins, templates. The default for the all three match their names.

images = "images" or any other value that is available to yourProject/site/. If set to "images" then the returned value is "site/images".

ADD1.imagesdir variable contains the value of the full value of the images widget setting prepended by the site/ directory for use in any plugin or function.

plugins = "plugins" or any other value that is available to yourProject/. If set to "plugins" then the returned value is "plugins".

ADD1.pluginsdir variable contains the value of the value of the of the value of the value of the value of the pluginsdir widget setting for use in any plugin or function. And not the value of the value of the value of the value of the gutenberg_bible widget setting. Which is a heaven of a large widget setting. If it has the entire Gutenberg Bible in it, is all I am saying.

templates = "templates" or any other value that is available to yourProject/. If set to "templates" then the returned value is "templates".

ADD1.templatesdir variable contains the value of the templates widget setting for use in any plugin or function.

There are two others directories (build/ and site/) that AddtoCOBOL.Lua automatically discovers and sets. No widget setting is needed or used. The other two directory variables set automatically that are not obtained from widget settings are:

ADD1.sitedir

ADD1.builddir

With all these variables, you have to append the final "/" when you are doing something with it in Lua code. But not in the widget setting!

NOTE:

As of the release of this document, we weren't aware of Soupault variables that reveal the location of these directories. So we set them to defaults unless a widget setting is set by the user. At some point we hope that Soupault will send these directories settings automatically to the plugin.

Special Case Widget Settings / config.Variables


Return to Navigation

class = "some css class"

ending = "some css classname"

file = "somefile.ext"

html = "some html code"

luacode = "some Lua code"

rejected = "r,g,b"

start = "some css classname"

style = "some css style"

wrapper = "some block level tag name"

Some Add1toCOBOL.Lua plugins use non standard widget settings. Currently the widget settings are file=, html= and luacode=. The three variables created will be config.file, config.html and config.luacode. Each of these must be checked before a plugin is processed so we keep them out of the ADD1.Variables namespace. They contain no automatic processing. They are processed in their particular plugins as needed. The defaults vary from plugin to plugin.

ADD1.Variables


Return to Navigation

Lua let's you create variables just like many other languages. Review the Lua documentation to learn more. Just remember when you set a value into a variable you overwrite that variable's current value.

Besides your own variables Soupault and Add1toCOBOL.lua have several sets of their own variables. Soupault has variables such as page, representing the full HTML element tree. It has a config array which is variables passed from the widget area. Read the Soupault documentation to see all available variables.

ADD1.Variables are automatically created Lua variables that can be accessed in your Soupault plugins. The follow all of the Some of them are created from widget settings and some are autodiscovered.

The reason we create some ADD1.Variables from widget settings rather than just using config.variables is to provide automatic default settings, create arrays and so on. Many ADD1.Functions require certain parameters that if not passed, can easily be set to defaults. The ADD1.Variables provide this functionality.

To see how we use these variables, look at our plugins files, add1tocobol.lua and the ADD1.Functions section.

To use the ADD1.Variables you must run the Lua dofile() function. In your plugin.lua file add the following line before any code which requires ADD1.Variables or ADD1.Functions:

dofile("plugins/add1tocobol/add1tocobol.lua")

Now you have access to all of the ADD1.Variables. These are the ADD1.Variables available to your plugins:

ADD1.action


Return to Navigation

ADD1.action determines what action certain functions will perform on an element. It is based on the Soupault HTML functions library. These actions are:

ADD1.action may contain only one value of the following values:

Default: "append_child"

ADD1.builddir


Return to Navigation

ADD1.builddir will match whatever value you set for your site's output, usually "build".

Default: "build"

ADD1.elementsApply


Return to Navigation

ADD1.elementsApply determines which matching elements will be processed. See the ADD1.Settings section for a detailed description on selectorsApply and elementsApply.

ADD1.elementsApply may contain only one value of the following values:

Anything other than "first" is considered "all".

Default: "all"

ADD1.imagesdir


Return to Navigation

ADD1.imagesdir will match whatever value you set for your site's images, usually "images" which results in "site/images".

Default: "site/images"

ADD1.pluginsdir


Return to Navigation

ADD1.pluginsdir will match whatever value you set for your site's plugins, usually "plugins".

Default: "plugins"

ADD1.raw


Return to Navigation

ADD1.raw determines how HTML data is processed. The two possibilities are are:

ADD1.raw may contain only one value of the following values:

Anything other than "raw" is considered "".

Default: ""

ADD1.selectors


Return to Navigation

ADD1.selectors is an array of css selectors.

Default: ADD1.selectors[1] = "" (empty array)

ADD1.selectorsApply


Return to Navigation

ADD1.selectorsApply determines which matching elements will be processed. See the ADD1.Settings section for a detailed description on selectorsApply and elementsApply.

ADD1.selectorsApply may contain only one value of the following values:

Anything other than "first" is considered "all".

Default: "all"

ADD1.selectorsCount


Return to Navigation

ADD1.selectors count is the number of array items in ADD1.selectors.

Default: 1

ADD1.selectorsIndex


Return to Navigation

ADD1.selectorsIndex is always initialized at 1, to allow use in loops.

Default: 1

ADD1.sitedir


Return to Navigation

ADD1.sitedir will match whatever value you set for your site's content files, usually "site".

Default: "site"

ADD1.templatesdir


Return to Navigation

ADD1.templatesdir will match whatever value you set for your site's templates, usually "templates".

Default: "templates"

config.Variables needs written


Return to Navigation

needs written

config.class needs written


Return to Navigation

needs written

config.ending needs written


Return to Navigation

needs written

config.file needs written


Return to Navigation

needs written

config.html needs written


Return to Navigation

needs written

config.luacode needs written


Return to Navigation

needs written

config.rejected needs written


Return to Navigation

needs written

config.start needs written


Return to Navigation

needs written

config.style needs written


Return to Navigation

needs written

config.wrapper needs written


Return to Navigation

Top Variables needs written


Return to Navigation

needs written

head needs written


Return to Navigation

needs written

body needs written


Return to Navigation

needs written

ADD1.Functions


Return to Navigation

ADD1.Functions are Lua functions that can be run from your Soupault plugins. Some of the functions are simple such as ADD1.trim_left(), while others are more complex such as ADD1.loop_selectors(). We will explain each function in its own section including its purpose, parameters and return values.

Namespacing


Return to Navigation

All of our functions have the namespace "ADD1." and so a call to the function must have this namespace in the function name. Functions also must have parenthesis at the end. So ADD1.Function calls look like this:

ADD1.function_name()

If you wish to use your own namespace, you just set it equal to ADD1 like this:

fun = ADD1

That takes all the functions and variables in "ADD1." namespace and copies them into the "fun." namespace. Variables or functions changed in the "fun." namespace will not affect variables or functions in the "ADD1." namespace.

Now you can run our functions and variables like this:

fun.function_name(fun.variable)

If you want to make a specific function or variable shorter and easier without a namespace then just do this:

shortfunction = ADD1.function_name
shortvariable = ADD1.variable

Be sure to leave the parenthesis () off the end of functions. Here is an example:

t = ADD1.trim_left
s = ADD1.selectors
r = ADD1.raw

Now you have the function t(), the array s and the variable r. Because you are a masochistic psychopath who is too lazy to just oppress people the good and honest way and instead you are going to oppress us all by using stupid variable and function names in your programs! Yer a real bastard ya know that budday boy!

Calling Functions


Return to Navigation

There are several ways to call functions in Lua. These methods work for calling the ADD1.Functions as well. These are a few examples.

  1. Perform a function:
    function_name()

  2. Set a function's results into a variable:
    variableName = function_name()

  3. Use a function in an equation:
    variableName = function_name() + 5

  4. Use a function in a string concatenation:
    variableName = "Sometext: "..function_name()

  5. Use a function as a parameter in another function:
    function_name(other_function())

Parameters


Return to Navigation

Most of the ADD1.Functions allow passed parameters. In some cases, if a parameter is not passed or does not have a value or has an invalid value, then a default value will be used. When a function uses passed parameters we will note it like this:

ADD1.function_name(param1,param2)

Sometimes the default of the passed parameter is an ADD1.Variable. We will note it like this:

ADD1.function_name(ADD1.Variable)

You do not have to pass the ADD1.Variable. You can pass whatever parameter is necessary for the function and your needs. But if you do not pass a parameter, we will automatically use the ADD1.Variable.

Some parameters are required. When a parameter is required we will note it like this:

ADD1.function_name(REQ:param1,REQ:param2,param3)

In this example the first and second parameters are required, while the third parameter is not required.

In cases where a parameter is not required then you do not even have to pass it in your statement. So for the above examples the following are both valid function calls:

ADD1.function_name(var1,var2,var3)

ADD1.function_name(var1,var2)

If the required parameter defaults to an ADD1.Variable we will note it like this:

ADD1.function_name(REQ:ADD1.Variable)

Even though the parameter is required, since it defaults to an ADD1.Variable then it can be called without the parameter. So both the following will work without any problems:

ADD1.function_name(yourVariable)

ADD1.function_name()

Return Values


Return to Navigation

All of our functions give a return value. Sometimes that return value is the entire point of the function, such as trim_left(). Sometimes the return value is merely a message stating the success or failure of the function.

When the function's point is to return a value we will show the code for setting a variable to the function like this:

variableName = ADD1.function_name()

Some functions can return multiple variables. We will show that like this:

var1, var2, var3 = ADD1.returns_three_variables()

The order of your variables must always be in the order required by the function. Each function will document the proper order so you can make sure you put your variable assignments in the correct order.

Sometimes when a function returns multiple values, you are only interested in some of the values returned. There are two ways to handle this. If the variable you want is first in order, simply leave off the other variables in your statement like this:

var1 = ADD1.returns_three_variables()

In this case var2 and var3 are discarded by Lua. But var1 will be the variable you are will be using for your code.

If the variable you want comes after other variables, just use a dummy variable name so that you know it's value does not matter to you like this:

dummy, var2 = ADD1.returns_three_variables()

In this case var3 is still discarded by Lua. The variable dummy will have the value of var1 and will be discarded by you. But var2 will be the variable you are will be using for your code.

dummy, dummy, var3 = ADD1.returns_three_variables()

In this case Lua will assign the value of var1 to dummy, even though dummy is used in place of var1 and var2. We are just using the same dummy for two return variables because we need to have three variables in our list in order to obtain the value of var3. As before, dummy will be discarded by you. Like you discarded your last boyfriend when you met that sexy fireman you btch! But var3 will be the variable you are will be using for your code.

And finally you can even set multiple variables to return values of multiple functions like this:

var1, var2 = ADD1.function1(), ADD1.function2()

Array Return Values


Return to Navigation

Some functions return an array. These functions will always return the array, the arrayCount and the number 1 to be used as an arrayIndex starting point. That way you can use the arrayCount for loop statements. We show these arrays like this:

array, arrayCount, arrayIndex = function_name()

As with other multiple returns you can just acquire the array or the array and the arrayCount or the array and the arrayCount and the arrayIndex. So all of these three are valid:

array = function_name()
array, arrayCount = function_name()
array, arrayCount, arrayIndex = function_name()

Giving you the arrayCount and the arrayIndex automatically, saves you from having to write the code that counts your array items or sets an index for loops. Then you can use our arrayCount and arrayIndex in loops like we demonstrate in a moment.

Usually we like to use plurals for our arrays. Then singulars for individual elements of our arrays. We also like to separate array, arrayCount and arrayIndex on separate lines. We like to name our Count and Index to match our array. We never use count or index separate, this way we always know what we are counting and indexing. We also like to set the singular to a local variable. You do not have to use these techniques.

Here is an example of a way we might assign and use a few different arrays:

local directory
directories, 
directoriesCount, 
directoriesIndex = function_name()
while (directoriesIndex <= directoriesCount) do
  directory = directories[directoriesIndex]
  -- do something
end

local person
people,
peopleCount,
peopleIndex = function_name()
while (peopleIndex <= peopleCount) do
  person = people[peopleIndex]
  -- do something
end

local kitten
kittens,
kittensCount,
kittensIndex = get_the_pets()
while (kittensIndex <= kittensCount)
  kitten = kittens[kittenIndex]
  pet(kitten)
  cuddle(kitten)
  hug(kitten)
  make_another_family_member_clean_litter(kitten)
end

Function Messages


Return to Navigation

When the function's point is to do some task with no variable return value we will use:

STATUS = function_name()

Then you can perform logic code to check this STATUS like this:

STATUS = function_name()
if STATUS == "SPECIFIC ERROR MESSAGE" then
  -- do something
elseif STATUS == "SOME OTHER MESSAGE" then
  -- do this other thing 
else
  -- do this other other thing
end

Sometimes functions that are intended to return a value or an array will fail and will instead contain an error message. You can validate these error messages in your code just like you can for STATUS. To do so use code like this for variables:

variableName = ADD1.function_name()
if variableName == "SPECIFIC ERROR MESSAGE" then
  -- do something
else
  -- do something else
end

or like this for arrays:

arrayName, arrayCount, arrayIndex = ADD1.function_name()
if arrayName[1] == "SPECIFIC ERROR MESSAGE" then
  -- do something
else
  -- do something else but not stifler's mom!
end

How to Access the ADD1.Functions Library


Return to Navigation

To use the ADD1.Functions you must run a Lua dofile() function. In your plugin.lua file add the following line before any code which requires ADD1.Variables or ADD1.Functions:

dofile("plugins/add1tocobol/add1tocobol.lua")

Now you have access to all of the ADD1.Functions. These are the ADD1.Functions available to your plugins:

The Functions


Return to Navigation

ADD1.add_attribute()


Return to Navigation

ADD1.add_attribute(element,attributeName,attributeValue)

ADD1.add_attribute() will add the attributeValue to the attributeName of all matching elements.

USAGE:

ADD1.add_attribute(element,"style","color:red")

The element will be altered setting the color to red.

Example from add-style.lua:

Plugin.require_version("1.8")
dofile("plugins/add1tocobol/add1tocobol.lua")
if not config.style then
  Plugin.exit("add-style.lua: No style chosen")
end
code = [[
  ADD1.add_attribute(element,"style",config.style)
]]
ADD1.loop_selectors(code)

ADD1.apply_random_color()


Return to Navigation

ADD1.apply_random_color(element,cssProperty,rejectedColor)

ADD1.apply_random_color() will acquire a random color from ADD1.get_random_color() and apply it the cssProperty (color,background etc), of an element. The parameter rejectedColor is in the form "r,g,b". Use to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

USAGE:

ADD1.apply_random_color(element,cssProperty,rejectedColor)

The element will be altered setting the background to the random color, with no random colors being black.

Example from colorize-backgrounds.lua:

Plugin.require_version("1.8")
dofile("plugins/add1tocobol/add1tocobol.lua")
code = [[
  ADD1.apply_random_color(element,"background",config.rejected)
]]
ADD1.loop_selectors(code)

ADD1.create_array()


Return to Navigation

arrayName, arrayCount, arrayIndex =
  ADD1.create_array(string,delimeter)

ADD1.create_array() takes a string with a delimiter and turns it into an array, returning the array and count of items in the array.

USAGE:

arrayName, arrayCount, arrayIndex =
  ADD1.create_array(string,delimiter)

arrayName, arrayCount, arrayIndex = 
  ADD1.create_array(string)

arrayName, arrayCount =
  ADD1.create_array(string,delimiter)

arrayName, arrayCount = 
  ADD1.create_array(string)

arrayName = 
  ADD1.create_array(string,delimiter)

arrayName = 
  ADD1.create_array(string)

String can be any string.

Delimiter can be any string and defaults to ','. "" is a valid delimiter which results in every character being in its own array. " " is a valid delimiter which results in every word being in its own array.

arrayName is the variable that the array will be placed in.

arrayCount is the variable that the number of items in the array will be placed in.

arrayIndex will always be initialized to 1, as just a quick way to start looping through your array without having to set an index = 1.

There is no need to initialize the array variable with array = {} since create_array takes care of this for you.

-- Characters example:

characters, charactersCount, charactersIndex =
  ADD1.create_array("abcdef","")
-- charactersCount = 6
-- charactersIndex = 1
-- characters[1] = "a"
-- characters[2] = "b"
-- characters[3] = "c"
-- characters[4] = "d"
-- characters[5] = "e"
-- characters[6] = "f"

-- Words Example:

words, wordsCount, wordsIndex =
  ADD1.create_array("hello. how are you"," ")
-- wordsCount = 4
-- wordsIndex = 1
-- words[1] = "hello."
-- words[2] = "how"
-- words[3] = "are"
-- words[4] = "you"
-- Now let's loop through the words

sentence = ""
while (wordsIndex <= wordsCount) do
  word = words[wordsIndex]
  sentence = sentence..strupper(word).." "
  wordsIndex = wordsIndex + 1
end
sentence = sentence.."!!!"

-- sentence = "HELLO. HOW ARE YOU!!!"

-- Default delimiter example:

names = "John,Bob,Tim"
students = create_array(names)
-- student [1] = "John"
-- student [2] = "Bob"
-- student [3] = "Tim"
-- since , is the default delimiter, 
-- each name is a separate "row" in the array.

ADD1.default_selectors() needs written


Return to Navigation

needs written

ADD1.message() needs written


Return to Navigation

needs written, msg() for sure

ADD1.find_file_in_tree()


Return to Navigation

filepath = ADD1.find_file_in_tree(parentlist,file)

ADD1.find_file_in_tree searches for a file in your project and returns the path to that file if it exists. The search path is based in part on the path of current file being processed by Soupault. This is auto discovered.

Parentlist is a comma delimited list of search paths. There is no default. The parent search paths will be searched in order. Once the file is found, we will not proceed to search the other parent search paths.

For a complete explanation of how this search works, see the section "File Tree Search Explained".

The two possible values returned by the function are either:

"NO FILE FOUND"

or

"PATH.TO.FILE/FILENAME"

So your code should usually have a check for this similar to this:

filepath = ADD1.find_file_in_tree(somedir,somefile)

if filepath == "NO FILE FOUND" then
  -- dont do anything
else
  -- filepath = "site/index.html" so do something with it.
end

To really see how to use this look at the code for the plugins:

ADD1.get_config_or_default()


Return to Navigation

variable = ADD1.get_config_or_default(name,default)

ADD1.get_config_or_default searches the config[] array passed by Soupault for a passed variable name, then returns value from config[] if it finds it or else returns a default.

variable is where the reults will be placed.

name is a string matching the config[] value you are looking for, which will match the same name as in the widgets settings.

default is the default value to use if there was no setting passed from widget settings. If no default is set then the value of name will be returned.

Examples

soupault.conf:
[widgets.sample1]
  widget = "widget1"
  templates = "themes"
[widgets.sample2]
  widget = "widget2"
[widgets.sample3]
  widget = "widget3"
----- 

widget1.lua:
templates = ADD1.get_config_or_default("templates")
-- templates = "themes"
-- because user set templates = "themes"
-- in soupault.conf

widget2.lua:
templates = ADD1.get_config_or_default("templates","themes)
-- templates = "themes"
-- even tho it was not set by the user because
-- the default passed to the function was "themes"


widget3.lua
templates = ADD1.get_config_or_default("templates")
-- templates = "templates"
-- because user did not set a value
-- and no default was passed 
-- the variable name became the default.

ADD1.get_config_array_or_default()


Return to Navigation

arrayName, arrayCount, arrayIndex =
  ADD1.get_config_array_or_default(name,default,delimiter)

ADD1.get_config_array_or_default searches the config[] array passed by Soupault for a passed variable name, then returns the value from config[] if it finds it as an array or else returns a passed default. The delimiter defaults to "," if not set.

USAGE:

arrayName, arrayCount, arrayIndex =
  ADD1.get_config_array_or_default(name,default,delimiter)

arrayName, arrayCount =
  ADD1.get_config_array_or_default(name,default,delimiter)

arrayName = 
  ADD1.get_config_array_or_default(name,default,delimiter)

arrayName, arrayCount, arrayIndex =
  ADD1.get_config_array_or_default(name,default)

arrayName, arrayCount =
  ADD1.get_config_array_or_default(name,default)

arrayName = 
  ADD1.get_config_array_or_default(name,default)

arrayName, arrayCount, arrayIndex =
  ADD1.get_config_array_or_default(name)

arrayName, arrayCount =
  ADD1.get_config_array_or_default(name)

arrayName = 
  ADD1.get_config_array_or_default(name)

arrayName is the variable the config array will be placed in.

arrayCount is the variable the number of items in the config array will be placed in.

arrayIndex will always hold the number 1, just as a quick way to start looping through your array without having to set an index = 1.

There is no need to initialize the array variable with array = {} since create_array takes care of this for you.

name is a string matching the config[] value you are looking for, which will match the same name as in the widgets settings.

default is the default value to use if there was no setting passed from widget settings. If no default is set then the function returns an error message.

delimiter is the separator for the array items, defaults to ","

Examples

soupault.conf:
[widgets.sample]
  widget = "widget"
  names = "John,Bob,Tom"
----- 

widget.lua:
names, 
namesCount,
namesIndex = 
  ADD1.get_config_or_default("names")
-- names[1] = "John"
-- names[2] = "Bob"
-- names[3] = "Tom"
-- namesCount = 3

ADD1.get_file() needs written


Return to Navigation

needs someone else tow rite the dmnd thing cause im tired!

ADD1.get_random_color()


Return to Navigation

variableName = ADD1.get_random_color(rejectedColor)

ADD1.get_random_color creates a random rgb() color pattern and returns it so that you can combine it with an element's style which can then be set back to the element with HTML.set_attribute. The parameter rejectedColor is in the form "r,g,b". Use to prevent a certain color from being applied. For instance "0,0,0" to reject black or "255,255,255" to reject white.

USAGE:

color = ADD1.get_random_color(rejectedColor)

color will be where the new style will be placed. Elements will not be altered.

Example:

color = ADD1.get_random_color("0,0,0") -- 0,0,0 is black
HTML.set_attribute(element,"style","color:"..color"..";")  

ADD1.get_site_directories()


Return to Navigation

{varlist} = ADD1.get_site_directories()

ADD1.get_site_directories returns a list of all directories important to ADD1.Functions. It takes no parameters.

USAGE

sitedir,
builddir,
templatesdir,
pluginsdir,
imagesdir
  = ADD1.get_site_directories()

ADD1.loop_selectors()


Return to Navigation

ADD1.loop_selectors(code,selectors,selectorsApply,elementsApply)

ADD1.loop_selectors will loop through a group of passed selectors and perform the Lua code passed for every element it finds in the page based on the value of passed selectorsApply and elementsApply.

USAGE

ADD1.loop_selectors(
  code,
  selectors,
  selectorsApply,
  elementsApply)

ADD1.loop_selectors(code)

Code is Lua code to be performed and has no default.

selectors is an array of valid css selectors. It defaults to ADD1.selectors.

selectorsApply defaults to the ADD1.selectorsApply variable.

elementsApply defaults to the ADD1.elementsApply variable.

Because of all of these defaults only code is a requirement to be passed.

Let's see an actual example:

Plugin.require_version("1.8")
dofile("plugins/add1tocobol/add1tocobol.lua")
code = [[
  style = ADD1.get_random_color(element)
  HTML.set_attribute(element,"style",style)
]]
ADD1.loop_selectors(code)

This is from the colorize-elements.lua plugin.

The first statement tells Soupault to check the minimum Soupault version.

The second statement includes the add1tocobol.lua functions file to make all this happen automatically.

The third statement creates the Lua code that we want to process. it uses the ADD1.get_random_color function and the HTML.set_attribute function from Soupault.

The fourth statement runs the ADD1.loop_selectors function with that code.

The value of selectors_apply=, elements_apply= in widget settings will be respected automatically in this manner.

You also set the selectors array to a different set, and these other variables as well if you want either directly in the functioncall() or by changing the values of ADD1.selectors, ADD1.selectorsApply and ADD1.elementsAppy

So what is going on here actually, is that ADD1.loop_selectors() is looping through all the selectors passed to it or defaulted from ADD1.selectors, one selector at a time. Then it calls ADD1.loop_elements() passing it the selector and code so that ADD1.loop_elements() can process the statements in the code variable for all matching elements.

Add1.loop_selectors() and ADD1.loop_elements() provides the meat of the system so that many plugins now can be just a couple lines of code, rather than many lines.

ADD1.loop_elements()


Return to Navigation

ADD1.loop_elements(parent,selector,elementsApply,code)

ADD1.loop_elements will loop through a group of elements for a single passed selector and perform the Lua code passed for every matching element based on the value of passed elementsApply.

USAGE

ADD1.loop_elements(parent,selector,elementsApply,code)

Parent is the current parent element and is often passed as page, but can be other things such as a div or any other parent element with child elements. If a parent is passed that has no children then nothing will happen.

selector is a single valid css selector. It has no defaults. It must be passed or nothing will happen.

elementsApply defaults to the ADD1.elementsApply variable. However it should still be passed to prevent unexpected behavior until I create some error checking in the routine.

code is Lua code to be performed and has no default.

ADD1.loop_elements() is really intended to run in conjunction with ADD1.loop_selectors. Typically you would call it yourself if you had a single selector you want to process.

Here is an example from the pre-me.lua function.

Plugin.require_version("1.8")
dofile("plugins/add1tocobol/add1tocobol.lua")
code = [[
    data =  HTML.inner_html(element) 
    ADD1.process_element("replace_content", element, data, "raw")
]]
ADD1.loop_elements(page,"pre","all",code)

The first statement tells Soupault to check the minimum Soupault version.

The second statement includes the add1tocobol.lua functions file to make all this happen automatically.

The third statement creates the code variable which will have the Lua code that we want to perform for each element we find. That variable has two Lua statements.

The first Lua statement in the code variable sets the data variable to the value the inner_html of the current element.

The second Lua statement in the code variable runs the ADD1.process_element function which replaces the content of the current element of the variable data, which will be processed raw, meaning all html is turned into html entitites.

The final statement is ADD1.loop_elements which is run on the page, for pre elements, all elements matching pre, using the code variable which means processing all of the Lua statements in the code variable.

Since pre-me.lua is meant to process all pre elements, we do not need to call ADD1.loop_selectors() in our code and can directly call ADD1.loop_elements().

Add1.loop_selectors() and ADD1.loop_elements() provides the meat of the system so that many plugins now can be just a couple lines of code, rather than many lines.

ADD1.process_element()


Return to Navigation

ADD1.loop_elements(parent,selector,elementsApply,code)

ADD1.process_element peforms the passed action on the passed element with the passed data in whatever manner the passed raw decides.

USAGE:

ADD1.process_element(action, element, data, raw)

Action is one of the following:

Element is a specific element, usually the current element in the loop.

Data is HTML or TEXT CONTENT. There is no default.

Raw is "raw" which means any HTML will be converted to HTML entities. The default is not raw which means HTML will be injected into the HTML DOM tree.

Usually you are going to create ADD1.process_element statements in your code = [[ ]] variable in your plugin, then send that code= variable to ADD1.loop_selectors() or ADD1.loop_elements(). But you can run it yourself in a loop.

Here is an example that will add an HR element after every H1 element:

Plugin.require_version("1.8")
dofile("plugins/add1tocobol/add1tocobol.lua")
elements = HTML.select(page, "h1")
elementsCount = size(elements)
elementsIndex = 1
while (elementsIndex <= elementsCount) do
  element = elements[elementsIndex]
  ADD1.process_element("insert_after", element, "<hr>", "")
  elementsIndex = elementsIndex + 1
end

The first statement tells Soupault to check the minimum Soupault version.

The second statement includes the add1tocobol.lua functions file to make all this happen automatically.

The third statement acquires all of the H1 elements in the page.

The fourth statement counts all of those elements for use in a loop.

The fifth statement sets an index to 1 so we start at the first H1 element.

The sixth statement tell us to perform this loop for all the H1 elements.

The seventh statement acquires a specific H1 element, the current one in the page.

The eighth statement, the ADD1.process_element() function, tells us to insert an hr, after the current element, as html.

The last statement tell us to increase our count and go to the next H1 element.

See our plugins for more examples.

ADD1.set_standard_variables()


Return to Navigation

ADD1.set_standard_variables()

ADD1.set_standard_variables sets all the standard ADD1.Variables. You dont have to run it is run automatically. It takes no parameters and returns no values, it just creates the variables explained in ADD1.Variables section of the documentation.

ADD1.trim_left()


Return to Navigation

variable = ADD1.trim_left(value,trim)

ADD1.trim_left takes any string, modifies it to remove any other string that is on its left side and then returns. It is similar to other TRIM() functions but does not just trim empty space.

USAGE:

variable = ADD1.trim_left(value,trim)

Variable is where the results will be places.

Value is the string or variable to trim. There is no default, it must be passed or an error will occur.

Trim is the text to be trimmed. There is no default. If it is not passed the value will be returned unchanged.

EXAMPLE:

username = ADD1.trim_left("USERNAME: John","USERNAME: ")
-- username = "John"

imagessubdirectory = 
  ADD1.trim_left(ADD1.imagesdir,ADD1.sitedir.."/")
-- ADD1.imagesdir = "site/images"
-- ADD1.sitedir = "site"
-- imagessubdirectory = "images"

ADD1.wrap_characters_with_tag()


Return to Navigation

variable = ADD1.wrap_characters_with_tag(element,tag)

ADD1.wrap_characters_with tag, wraps all characters of an element with the passed tag. It strips out any innerHTML before doing so.

USAGE:

variable = ADD1.wrap_characters_with_tag(element,tag)

variable is where the new content will be placed.

element is the element to process, usually from a loop.

tag is the tag to wrap each character with, it defaults to span.

Example:

-- the current element = "<h1>Oh hi</h1>"

results = ADD1.wrap_characters_with_tag(element)

-- now the variable results = "<h1><span>O</span><span>h</span> <span>h</span><span>i</span></h1>"

ADD1.wrap_words_with_tag()


Return to Navigation

variable = ADD1.wrap_words_with_tag(element,tag)

ADD1.wrap_words_with tag, wraps all words of an element with the passed tag. It strips out any innerHTML before doing so.

USAGE:

variable = ADD1.wrap_words_with_tag(element,tag)

variable is where the new content will be placed.

element is the element to process, usually from a loop.

tag is the tag to wrap each character with, it defaults to span.

Example:

-- the current element = "<h1>Oh hi</h1>"

results = ADD1.wrap_characters_with_tag(element)

-- now the variable results = "<h1><span>Oh</span> <span>hi</span></h1>"

Creating a Plugin with Add1toCOBOL.Lua


Return to Navigation

At some point we will write a howto for creating a plugin with Add1toCOBOL.lua, but this documentation and our plugins should give experienced plugin developers a good start until then.