mckay.utilities.general
Class HTMLWriter

java.lang.Object
  extended by mckay.utilities.general.HTMLWriter

public class HTMLWriter
extends java.lang.Object

Static methods for generating HTML files, either via a DataOutputStream or a StringBuffer.

An HTML file is typically created using the startNewHTMLFile method, which returns a DataOutputStream file or a StringBuffer which can be used by various methods to write to the file/buffer. When all contents have been added, then the endHTMLFile method should be used to end the file.

A frames base interface consisiting of multiple files can be generated using the startNewFramesPage and the addFrame methods.

It can be appropriate to pre-process text passed to the methods of this class with the convertSpecialCharacters method, as this replaces special characters such as ampersands with the appropriate HTML tags.


Constructor Summary
HTMLWriter()
           
 
Method Summary
static java.io.DataOutputStream addFrame(java.lang.String new_file_title, java.io.File directory, java.io.DataOutputStream contents_file_stream)
          Adds a new HTML page to a frames-based interface, as prepared with the startNewFramesPage method.
static void addHorizontalRule(java.io.DataOutputStream writer)
          Writes a a horizontal rule to the given file.
static void addHorizontalRule(java.lang.StringBuffer writer)
          Writes a a horizontal rule to the given StringBuffer.
static java.lang.String[][] addLineBreaksToArray(java.lang.String[][] to_process)
          Returns an array consisting of the given array but with the second dimension projected into one entry separated by
tags.
static void addList(java.lang.String[] list, boolean numbered, java.io.DataOutputStream writer)
          Writes the given list as a formatted HTML lsit to the given file.
static void addList(java.lang.String[] list, boolean numbered, java.lang.StringBuffer writer)
          Writes the given list as a formatted HTML lsit to the given StringBuffer.
static void addParagraph(java.lang.String paragraph, java.io.DataOutputStream writer)
          Writes the given paragraph as formatted HTML to the given file.
static void addParagraph(java.lang.String paragraph, java.lang.StringBuffer writer)
          Writes the given paragraph as formatted HTML to the given StringBuffer.
static void addTable(java.lang.String[][] table, java.lang.String[] column_headings, boolean bold_first_column, java.lang.StringBuffer writer)
          Writes the given table as formatted HTML to the given StringBuffer.
static void addTable(java.lang.String[][] table, java.lang.String[] column_headings, java.io.DataOutputStream writer)
          Writes the given table as formatted HTML to the given file.
static void addTableHighlightingHighestInRow(java.lang.String[][] table, java.lang.String[] column_headings, boolean bold_first_column, java.lang.StringBuffer writer)
          Writes the given table as formatted HTML to the given StringBuffer.
static java.lang.String convertSpecialCharacters(java.lang.String to_convert)
          Converts HTML escape characters in the given text to HTML encoding in order to make it HTML consistent.
static java.lang.String[] convertSpecialCharacters(java.lang.String[] to_convert)
          Converts HTML escape characters in the entries of the given array to HTML encoding in order to make it HTML consistent.
static void endHTMLFile(java.io.DataOutputStream writer, boolean include_text)
          Ends the HTML file referred to by the given DataOutputStream by writing a horizontal rule followed by a link to the anchor at the top of the page followed by the final HTML closing tags.
static void endHTMLFile(java.lang.StringBuffer writer, boolean include_text)
          Ends the HTML file referred to by the given StringBuffer by writing a horizontal rule followed by a link to the anchor at the top of the page followed by the final HTML closing tags.
static java.lang.String getContentsFramePath(java.lang.String root_path)
          Get the path of the left frame holding links to the frames that is created by the startNewFramesPage method.
static java.lang.String getDefaultPageFramePath(java.lang.String root_path, java.lang.String title_page_title)
          Get the path of the default page for the right frame that is created by the startNewFramesPage method.
static java.lang.String getFrameSubdirectoryPath(java.lang.String root_path)
          Get the path of the subdirectory that is created by the startNewFramesPage method.
static java.io.DataOutputStream[] startNewFramesPage(java.lang.String root_path, java.lang.String root_title, int left_frame_size, java.lang.String title_page_title, java.io.File[] sub_directory_dummy)
          Prepares the creation of a frame-based interface consisting of one frame on the left and one on the right (named, respectively, "left" and "right").
static java.lang.StringBuffer startNewHTMLFile(java.lang.String background_colour, java.lang.String text_colour, java.lang.String document_title, boolean include_text)
          Creates the beginning of the contents for a new HTML file.
static java.io.DataOutputStream startNewHTMLFile(java.lang.String path, java.lang.String background_colour, java.lang.String text_colour, boolean can_erase, java.lang.String document_title, boolean include_text)
          Creates a new HTML file at the given path and gives it a header that includes the given document title and a body tag that sets the text and background to the specified colours.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HTMLWriter

public HTMLWriter()
Method Detail

convertSpecialCharacters

public static java.lang.String convertSpecialCharacters(java.lang.String to_convert)
Converts HTML escape characters in the given text to HTML encoding in order to make it HTML consistent.

The escape characters converted are:

  • <
  • >
  • "
  • '
  • \
  • &

    Parameters:
    to_convert - The text to convert. IMPORTANT: This text must not include HTML tags, as they will be converted out of HTML.
    Returns:
    The encoded text.

  • convertSpecialCharacters

    public static java.lang.String[] convertSpecialCharacters(java.lang.String[] to_convert)
    Converts HTML escape characters in the entries of the given array to HTML encoding in order to make it HTML consistent.

    The escape characters converted are:

  • <
  • >
  • "
  • '
  • \
  • &

    Parameters:
    to_convert - The text to convert. IMPORTANT: This text must not include HTML tags, as they will be converted out of HTML.
    Returns:
    The array of encoded text.

  • startNewHTMLFile

    public static java.io.DataOutputStream startNewHTMLFile(java.lang.String path,
                                                            java.lang.String background_colour,
                                                            java.lang.String text_colour,
                                                            boolean can_erase,
                                                            java.lang.String document_title,
                                                            boolean include_text)
    Creates a new HTML file at the given path and gives it a header that includes the given document title and a body tag that sets the text and background to the specified colours. If the include_text parameter is true, then an anchor at the top of the page named "Top" and a large blue title at the top of the page that corresponds to the given document_title parameter are also added. Returns, in either case, a DataOutputStream that can be used to write further code to the HTML file.

    If the file at the given path already exists and the can_erase parameter is false, then the user is presented with a dialog box asking if it should be overwritten.

    If the file cannot be written to, then the user is given an error message saying so, and null is returned.

    Parameters:
    path - The path at which the HTML file is to be saved.
    background_colour - The hex code for the background colour. (e.g. #e4e4e4 for grey, #000000 for black and #FFFFFF for white).
    text_colour - The hex code for the text colour. (e.g. #e4e4e4 for grey, #000000 for black and #FFFFFF for white).
    can_erase - Whether or not the file should be automatically overwritten if it already exists.
    document_title - The title to assign to the document in the HTML header and to write at the top of the page.
    include_text - Whether or not to include the anchor and the title at the top of the page.
    Returns:
    Returns a DataOutputStream that can be used to write to the file at the given path. Null is returned if there is a problem.

    startNewHTMLFile

    public static java.lang.StringBuffer startNewHTMLFile(java.lang.String background_colour,
                                                          java.lang.String text_colour,
                                                          java.lang.String document_title,
                                                          boolean include_text)
    Creates the beginning of the contents for a new HTML file. Gives it a header that includes the given document title and a body tag that sets the text and background to the specified colours. If the include_text parameter is true, then an anchor at the top of the page named "Top" and a large blue title at the top of the page that corresponds to the given document_title parameter are also added. Returns, in either case, a StringBuffer to which further HTML code can then be written.

    Parameters:
    background_colour - The hex code for the background colour. (e.g. #e4e4e4 for grey, #000000 for black and #FFFFFF for white).
    text_colour - The hex code for the text colour. (e.g. #e4e4e4 for grey, #000000 for black and #FFFFFF for white).
    document_title - The title to assign to the document in the HTML header and to write at the top of the page.
    include_text - Whether or not to include the anchor and the title at the top of the page.
    Returns:
    Returns a StringBuffer that contains the generated HTML and to which further HTML may be written.

    endHTMLFile

    public static void endHTMLFile(java.io.DataOutputStream writer,
                                   boolean include_text)
                            throws java.io.IOException
    Ends the HTML file referred to by the given DataOutputStream by writing a horizontal rule followed by a link to the anchor at the top of the page followed by the final HTML closing tags.

    The writer DataOutputStream is also closed.

    Parameters:
    writer - Refers to the HTML file to write to.
    include_text - Whether or not to include the anchor link and the horizontal rule.
    Throws:
    java.io.IOException - An exception is thrown if a problem occurs during writing.

    endHTMLFile

    public static void endHTMLFile(java.lang.StringBuffer writer,
                                   boolean include_text)
    Ends the HTML file referred to by the given StringBuffer by writing a horizontal rule followed by a link to the anchor at the top of the page followed by the final HTML closing tags.

    Parameters:
    writer - Refers to the HTML file to write to.
    include_text - Whether or not to include the anchor link and the horizontal rule.

    addParagraph

    public static void addParagraph(java.lang.String paragraph,
                                    java.io.DataOutputStream writer)
                             throws java.io.IOException
    Writes the given paragraph as formatted HTML to the given file.

    Parameters:
    paragraph - The paragraph to wrap in HTML tags and write.
    writer - Refers to the HTML file to write to.
    Throws:
    java.io.IOException - Throws an exception if cannot write.

    addParagraph

    public static void addParagraph(java.lang.String paragraph,
                                    java.lang.StringBuffer writer)
    Writes the given paragraph as formatted HTML to the given StringBuffer.

    Parameters:
    paragraph - The paragraph to wrap in HTML tags and write.
    writer - Refers to the StringBuffer to write to.

    addHorizontalRule

    public static void addHorizontalRule(java.io.DataOutputStream writer)
                                  throws java.io.IOException
    Writes a a horizontal rule to the given file.

    Parameters:
    writer - Refers to the HTML file to write to.
    Throws:
    java.io.IOException - Throws an exception if cannot write.

    addHorizontalRule

    public static void addHorizontalRule(java.lang.StringBuffer writer)
    Writes a a horizontal rule to the given StringBuffer.

    Parameters:
    writer - Refers to the StringBuffer to write to.

    addList

    public static void addList(java.lang.String[] list,
                               boolean numbered,
                               java.io.DataOutputStream writer)
                        throws java.io.IOException
    Writes the given list as a formatted HTML lsit to the given file.

    Parameters:
    list - The list to write. Each entry corresponds to a different item in the list.
    numbered - Whether or not the list should be numbered.
    writer - Refers to the HTML file to write to.
    Throws:
    java.io.IOException - Throws an exception if cannot write.

    addList

    public static void addList(java.lang.String[] list,
                               boolean numbered,
                               java.lang.StringBuffer writer)
    Writes the given list as a formatted HTML lsit to the given StringBuffer.

    Parameters:
    list - The list to write. Each entry corresponds to a different item in the list.
    numbered - Whether or not the list should be numbered.
    writer - Refers to the StringBuffer to write to.

    addTable

    public static void addTable(java.lang.String[][] table,
                                java.lang.String[] column_headings,
                                java.io.DataOutputStream writer)
                         throws java.io.IOException
    Writes the given table as formatted HTML to the given file.

    Parameters:
    table - The table to wrap in HTML tags and write. The first dimension indicates rows and the second indicates columns.
    column_headings - An optional row of headings to place in the first row. Ignored if null.
    writer - Refers to the HTML file to write to.
    Throws:
    java.io.IOException - Throws an exception if cannot write.

    addTable

    public static void addTable(java.lang.String[][] table,
                                java.lang.String[] column_headings,
                                boolean bold_first_column,
                                java.lang.StringBuffer writer)
    Writes the given table as formatted HTML to the given StringBuffer.

    Parameters:
    table - The table to wrap in HTML tags and write. The first dimension indicates rows and the second indicates columns.
    column_headings - An optional row of headings to place in the first row. Ignored if null.
    bold_first_column - Whether or not the entries of the first column should be in bold.
    writer - Refers to the StringBuffer to write to.

    addTableHighlightingHighestInRow

    public static void addTableHighlightingHighestInRow(java.lang.String[][] table,
                                                        java.lang.String[] column_headings,
                                                        boolean bold_first_column,
                                                        java.lang.StringBuffer writer)
    Writes the given table as formatted HTML to the given StringBuffer.

    Italicizes and bolds the highest value in each row. IMPORTANT: Note that this assumes that each entry in the table is a number (except for those entries in the first column, if bold_first_column is set to true). Rows not containing any numbers are written without any italicizations/bolds.

    Parameters:
    table - The table to wrap in HTML tags and write. The first dimension indicates rows and the second indicates columns.
    column_headings - An optional row of headings to place in the first row. Ignored if null.
    bold_first_column - Whether or not the entries of the first column should be in bold. If this is true then the first column is considered to hold labels and is not considered as a candidate for holding the highest value in the row.
    writer - Refers to the StringBuffer to write to.

    startNewFramesPage

    public static java.io.DataOutputStream[] startNewFramesPage(java.lang.String root_path,
                                                                java.lang.String root_title,
                                                                int left_frame_size,
                                                                java.lang.String title_page_title,
                                                                java.io.File[] sub_directory_dummy)
                                                         throws java.lang.Exception
    Prepares the creation of a frame-based interface consisting of one frame on the left and one on the right (named, respectively, "left" and "right"). The left frame holds a list of links that can be loaded into the right frame.

    This method automatically creates a root file that defines the frame settings. This file is saved at the path specified in the root_path parameter.

    A sub-directory is also created with the same name as the root file, but with no extension and "_documents" appended to the name. This sub-directory is meant to eventually hold each of the HTML pages that will be referred to in the left frame. IMPORTANT: If this sub-directory already exists, then it and all of its contents are erased and/or overwritten. A pointer to the new sub-directory is stored in the first entry of the given sub_directory_dummy parameter.

    A contents file is created in this sub-directory. This file will eventually hold links to the right frame. For now, it is initialized as an HTML file using the startNewHTMLFile method, and a DataOutputStream to it is returned in the first entry of the returned array. A heading is also created for this contents file that is the same asthe root_title parameter, and a link named "Home" is created for the default page that is loaded in the right frame.

    A reference is also created in the root file to this default pages so that it will be loaded into the right frame. This reference points to a file created in the sub-directory with a file name provided by the title_page_title parameter (with the extension ".html" added). This method initializes this file as an HTML file using the startNewHTMLFile method and returns DataOutputStream for it in the second entry of the returned array.

    Once this method is called, further pages that can be loaded into the right frame can be added (along with auto-updates to the contents links) using the addFrame method. The default page that is generated here can be updated using the miscellaneous methods of this class.

    Parameters:
    root_path - The path at which the root HTML file for the the frames is to be saved.
    root_title - The title to assign to the root file in the HTML header. Also used as the heading of the list of contents in the left frame.
    left_frame_size - The percentage of the frames (1 to 99) to be assigned to the left frame.
    title_page_title - The name to assign to the default page that will load in the right frame.
    sub_directory_dummy - A dummy File[] of size 1. The contents of this array are ignored, and the first entry will be overwritten with a link to the sub-directory that will be created.
    Returns:
    Returns two DataOutputStreams that can be used to write to. The one in entry 0 is the contents file that is displayed in the left frame, and the one in entry 1 is the page that loads by default in the right frame. Null is returned if there is a problem.
    Throws:
    java.lang.Exception - An exception is thrown if any errors occur.

    addFrame

    public static java.io.DataOutputStream addFrame(java.lang.String new_file_title,
                                                    java.io.File directory,
                                                    java.io.DataOutputStream contents_file_stream)
                                             throws java.lang.Exception
    Adds a new HTML page to a frames-based interface, as prepared with the startNewFramesPage method. This method adds a page that can be loaded into the right frame (se up using the startNewHTMLFile method), and adds a link to it on the contents page in the left frame.

    Parameters:
    new_file_title - The title of the new file. This is stored in the HTML header and is written in large blue type at the top of the page.
    directory - The directory where the new file is to be saved. Is typically the same directory that the sub_directory_dummy parameter of the startNewHTMLFile method is filled with.
    contents_file_stream - A stream to the contents frame. A link will be added to this frame that links to the new file prepared by this method.
    Returns:
    A stream to the new file that has been created.
    Throws:
    java.lang.Exception - Throws an exception if a problem occurs.

    getFrameSubdirectoryPath

    public static java.lang.String getFrameSubdirectoryPath(java.lang.String root_path)
                                                     throws java.lang.Exception
    Get the path of the subdirectory that is created by the startNewFramesPage method.

    Parameters:
    root_path - The path of the root frame file.
    Returns:
    The path of the subdirectory.
    Throws:
    java.lang.Exception - Throws an exception if the root path is invalid.

    getContentsFramePath

    public static java.lang.String getContentsFramePath(java.lang.String root_path)
                                                 throws java.lang.Exception
    Get the path of the left frame holding links to the frames that is created by the startNewFramesPage method.

    Parameters:
    root_path - The path of the root frame file.
    Returns:
    The path of the contents file.
    Throws:
    java.lang.Exception - Throws an exception if the root path is invalid.

    getDefaultPageFramePath

    public static java.lang.String getDefaultPageFramePath(java.lang.String root_path,
                                                           java.lang.String title_page_title)
                                                    throws java.lang.Exception
    Get the path of the default page for the right frame that is created by the startNewFramesPage method.

    Parameters:
    root_path - The path of the root frame file.
    title_page_title - The title of the default page.
    Returns:
    The path of the subdirectory.
    Throws:
    java.lang.Exception - Throws an exception if the root path is invalid.

    addLineBreaksToArray

    public static java.lang.String[][] addLineBreaksToArray(java.lang.String[][] to_process)
    Returns an array consisting of the given array but with the second dimension projected into one entry separated by
    tags. The convertSpecialCharacters method is also called on each element.

    Parameters:
    to_process - The array to project to [n][1] size with line breaks.
    Returns:
    The new array.