Covers examples of frequent cross-cutting concerns.

Name
Concepts
Parent
Iteration
Filled

Domain Model

Diagram

Elements of the Domain

Table: Domain Model
NameShort Description
Anchor
Html element to create →Links. Contain link-targets in the form <a href="link-target">
Cross reference
Link from one part of the document to another part within the same document. A special form of →internal-link, with a →link-target in the same document.
Finding
Description of a problem found by one →Checker within the →Html Page.
Html Element
HTML pages (documents) are made up by HTML elements, .e.g. <a href="link target">, <img src="image.png"> and others. See the W3-Consortium.
HTML Page
A single chunk of HTML, mostly regarded as a single file. Shall comply to standard HTML syntax. Minimal requirement: Our HTML parser can successfully parse this page. Contains →Html Elements. Also called html document.
id
Identifier for a specific part of a document, e.g. <h2 id="#someHeader">. Often used to describe →link targets.
Link to another section of the same page or to another page of the same domain. Also called local link.
Any a reference in the →html page that lets you display or activate another part of this document (internal ink) or another document, image or resource (can be either →internal (local) or →external link). Every link leads from the link source to the link target.
The target of any →link, e.g. heading or any other a part of a html document, any internal or external resource (identified by URI). Expressed by →id.
local resource
Local file, either other html files or other filetypes (e.g. pdf, docx).
Run Result
The overall results of checking a number of pages (at least one page).
Single Page Result
A collection of all checks of a single → HTML Page.
URI
Universal Resource Identifier. Defined in RFC-2396. The ultimate source of truth concerning link syntax and semantic.

Gradle Plugin Concept and Development

Description

You should definitely read the original [Gradle User Guide] on custom plugin development.

To enable the required Gradle integration, we implement a lean wrapper as described in the Gradle user guide.

class HtmlSanityCheckPlugin implements Plugin<Project> {
  void apply(Project project) {
    project.task('htmlSanityCheck',
            type: HtmlSanityCheckTask,
            group: 'Check')
  }
}

Directory Structure and Required Files

|-htmlSanityCheck
   |  |-src
   |  |  |-main
   |  |  |  |-org
   |  |  |  |  |-aim42
   |  |  |  |  |  |-htmlsanitycheck
   |  |  |  |  |  |  | ...
   |  |  |  |  |  |  |-HtmlSanityCheckPlugin.groovy (1)
   |  |  |  |  |  |  |-HtmlSanityCheckTask.groovy
   |  |  |  |-resources
   |  |  |  |  |-META-INF                           (2)                     
   |  |  |  |  |  |-gradle-plugins
   |  |  |  |  |  |  |-htmlSanityCheck.properties   (3)
   |  |  |-test
   |  |  |  |-org
   |  |  |  |  |-aim42
   |  |  |  |  |  |-htmlsanitycheck
   |  |  |  |  |  |  | ...
   |  |  |  |  |  |  |-HtmlSanityCheckPluginTest
   |
  1. the actual plugin code: HtmlSanityCheckPlugin and HtmlSanityCheckTask groovy files
  2. Gradle expects plugin properties in META-INF
  3. Property file containing the name of the actual implementation class:

Passing Parameters From Buildfile to Plugin

To be done

Building the Plugin

The plugin code itself is built with Gradle.

Uploading to Public Archives

To be done

Further Information on Creating Gradle Plugins

Although writing plugins is described in the Gradle user guide, a clearly explained sample is given in a Code4Reference tutorial.

Flexible Checking Algorithms

Description

Failed to render macro

Reason: Invalid scheme for URL. Supported schemes are: [http, https, ftp, ftps, mailto, nntp, news, irc]

We achieve that by defining the skeleton of the checking algorithm in one operation, deferring the specific checking algorithm steps to subclasses.

 

The invariant steps are implemented in the abstract base class, while the variant checking algorithms have to be provided by the subclasses.

/**
 * template method for performing a single type of checks
 * on the given @see HtmlPage.
 *
 * Prerequisite: pageToCheck has been successfully parsed,
 * prior to constructing this Checker instance.
 */
 public CheckingResultsCollector performCheck() {
    // assert prerequisite
    assert pageToCheck != null
    initResults()
    return check() // execute the actual checking algorithm
 }

Context

Elements

Name Short Description
abstract class, used in form of the template-pattern. Shall be subclassed for all checking algorithms.
checks if referenced local image files exist
checks if cross references (links referenced within the page) exist
checks if any id has multiple definitions

Flexible Reporting

Description

HtmlSC allows for different output formats:

  • formats (HTML and text) and

  • destinations (file and console)

The reporting subsystem uses the template method pattern to allow different output formats (e.g. Console and HTML). The overall structure of reports is always the same:

Graphical clients can use the API of the reporting subsystem to display reports in arbitrary formats.

The (generic and abstract) reporting is implemented in the abstract Reporter class as follows:

/**
 * main entry point for reporting - to be called when a report is requested
 * Uses template-method to delegate concrete implementations to subclasses
*/
    public void reportFindings() {
        initReport()               (1)
        reportOverallSummary()     (2)
        reportAllPages()           (3)
        closeReport()              (4)
    }
//
    private void reportAllPages() {
        pageResults.each { pageResult ->
            reportPageSummary( pageResult )  (5)
            pageResult.singleCheckResults.each { resultForOneCheck ->
               reportSingleCheckSummary( resultForOneCheck )    (6)
               reportSingleCheckDetails( resultForOneCheck )    (7)
               reportPageFooter()                               (8)
        }
    }
  1. initialize the report, e.g. create and open the file, copy css-, javascript and image files.
  2. create the overall summary, with the overall success percentage and a list of all checked pages with their success rate.
  3. iterate over all pages
  4. write report footer - in HTML report also create back-to-top-link
  5. for a single page, report the nr of checks and problems plus the success rate
  6. for every singleCheck on that page, report a summary and
  7. all detailed findings for a singleCheck.
  8. for every checked page, create a footer, pagebreak or similar to graphically distringuish pages between each other.

Styling the Reporting Output

Description

  • The HtmlReporter explicitly generates css classes together with the html elements, based upon css styling re-used from the Gradle JUnit plugin.

  • Stylesheets, a minimized version of JQuery javascript library plus some icons are copied at report-generation time from the jar-file to the report output directory.

  • Styling the back-to-top arror/button is done as a combination of JavaScript plus some css styling, as described in http://www.webtipblog.com/adding-scroll-top-button-website/.

Attributions

Credits for the arrow-icon https://www.iconfinder.com/icons/118743/arrow_up_icon