Updated documentation. Added demos and source.

EatonCiaran · Jul 10, 2021 · ccb84da · ccb84da
1 parent 96c2822
commit ccb84da
Show file tree

Hide file tree

Showing 6 changed files with 1,138 additions and 676 deletions.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,2 +1,71 @@
-# jquery-console
-A jQuery plugin to provide a non-interactive console.
+# jQuery Console
+
+## Overview
+
+The jQuery Console plugin allows you to easily create a non-interactive console within a page.
+
+
+## Compatibility
+* Known to work with jQuery v3.x.x
+
+---
+
+## Usage
+
+Initialise the console by attaching it to a `div` tag. `options` is optional.
+
+````javascript
+let options = { msgDirection: "up" };
+let myConsole = $("div").console(options);
+````
+
+Log messages with the `log` method.
+
+````javascript
+myConsole.log("message");
+````
+
+## Options
+
+### history
+Integer to set how many messages to retain. Default: `10000`.
+
+### msgDirection
+String to denote whether messages are appended to the top or bottom. Default: `"down"`
+* `"down"`: append to the bottom
+* `"up"`: append to the top
+
+### showTimestamp
+Boolean flag indicating whether the timestamp the message was logged should be shown. Default: `true`
+
+### timeout
+Integer to set how long in milliseconds until messages are deleted. Setting to `0` results in no timeout. Default: `0`
+
+---
+
+## Utility Methods
+
+### log
+Logs message to the assigned console. Takes 2 parameters:
+* `msg`: String representing the message to be logged. Required.
+* `level`: Can either be an integer or string representing the desired visual style. Default: `6`
+
+| Integer | String        |
+| ------- | ------------- |
+| `0`     | `"emergency"` |
+| `1`     | `"alert"`     |
+| `2`     | `"critical"`  |
+| `3`     | `"error"`     |
+| `4`     | `"warning"`   |
+| `5`     | `"notice"`    |
+| `6`     | `"info"`      |
+| `7`     | `"debug"`     |
+
+
+---
+
+## License
+
+This project is under the GPLv3:
+
+* [GNU General Public License v3](LICENSE)
diff --git a/demos/css/main.css b/demos/css/main.css
@@ -0,0 +1,45 @@
+body {
+  background: #fff none repeat scroll 0 0;
+  font-family: Tahoma,Calibri,Verdana,Geneva,sans-serif;
+  font-size: 0.9em;
+  max-width: 1100px;
+  min-width: 800px;
+  margin: 0 auto;
+  text-align: center;
+}
+h2 {
+  font-size: 0.8em;
+  text-align: left;
+}
+p {
+  text-align: justify;
+}
+
+form label {
+  display: inline-block;
+  text-align: right;
+  vertical-align: top;
+  width: 10%;
+}
+form textarea {
+  box-sizing: border-box;
+  font-family: monospace;
+  font-size: 90%;
+  width: 80%;
+}
+form #submit {
+  font-size: 1em;
+  margin-top: 10px;
+}
+
+.leftpanel {
+  display: inline-block;
+  float: left;
+  padding-right: 1em;
+  text-align: left;
+  width: 25%;
+}
+.rightpanel {
+  display: inline-block;
+  width: 70%;
+}
diff --git a/demos/index.html b/demos/index.html
@@ -0,0 +1,117 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+
+    <link rel="stylesheet" href="./css/main.css" type="text/css" />
+    <link rel="stylesheet" href="../src/jquery.console.css" type="text/css" />
+
+    <title>jQuery Console Plugin</title>
+</head>
+
+<body>
+    <header>
+        <div id="header">
+            <h1>jQuery Console Plugin</h1>
+        </div>
+    </header>
+
+    <noscript>
+        This page requires Javascript. You're seeing this message as you have Javascript disabled.
+    </noscript>
+
+    <main>
+        <h2>New messages placed at the top</h2>
+        <div class="console1"></div>
+
+        <h2>New messages placed at the bottom and limited history of 15 messages</h2>
+        <div class="console2"></div>
+
+        <h2>No timestamp and messages timeout after 3 seconds</h2>
+        <div class="console3"></div>
+    </main>
+
+    <script language="javascript" type="text/javascript" src="https://code.jquery.com/jquery-3.0.0.min.js"></script>
+    <script language="javascript" type="text/javascript" src="../src/jquery.console.js"></script>
+
+    <script type="text/javascript">
+        $(document).ready(function () {
+            // Init the consoles
+            let con1 = $(".console1").console({ msgDirection: "up" });
+            let con2 = $(".console2").console({ history: 15 });
+            let con3 = $(".console3").console({ msgDirection: "up", showTimestamp: false, timeout: 3000 });
+
+            // Sample messages to show off the different log levels
+            let long_txt = "This is very long alert message. This is very long alert message. This is very long alert message. "
+                + "This is very long alert message. This is very long alert message. This is very long alert message. "
+                + "This is very long alert message. This is very long alert message. This is very long alert message.";
+            let msgs = [
+                { txt: "This is a debug message.", level: 7 },
+                { txt: "This is an info message.", level: 6 },
+                { txt: "This is a notice message.", level: 5 },
+                { txt: "This is a warning message.", level: "warning" },    // can use choose using str or int
+                { txt: "This is an error message.", level: 3 },
+                { txt: "This is a critical message.", level: 2 },
+                { txt: "This is an alert message.", level: 1 },
+                { txt: "This is an emergency message.", level: 0 },
+                { txt: "This is a default message." },                      // no level needs to be provided
+                { txt: long_txt, level: 1 }
+            ];
+
+            // Generator implementation of writing a message every second from the message array
+            function* get_message() {
+                let index = 0;
+                while (true) {
+                    let msg = msgs[index];
+                    index = (index + 1) % msgs.length;  // inc index but cycle back to the start if at the end of the list
+                    yield msg;
+                }
+            }
+            let msg_generator = get_message();
+
+            function writeMessage() {
+                let msg = msg_generator.next().value;
+                if ("level" in msg) {
+                    con1.log(msg["txt"], msg["level"]);
+                    con2.log(msg["txt"], msg["level"]);
+                    con3.log(msg["txt"], msg["level"]);
+                }
+                else {
+                    con1.log(msg["txt"]);
+                    con2.log(msg["txt"]);
+                    con3.log(msg["txt"]);
+                }
+            }
+            let tid = setInterval(writeMessage, 1000);
+
+
+            /* 
+            TODO: Decide if generator or closure implementation is easier to understand and maintain.
+
+            // Closure implementation of writing a message every second from the message array
+            const writeMessage = (function () {
+                let index = 0;
+                return function () {
+                    let msg = msgs[index];
+                    if ("level" in msg) {
+                        con1.log(msg["txt"], msg["level"]);
+                        con2.log(msg["txt"], msg["level"]);
+                        con3.log(msg["txt"], msg["level"]);
+                    }
+                    else {
+                        con1.log(msg["txt"]);
+                        con2.log(msg["txt"]);
+                        con3.log(msg["txt"]);
+                    }
+                    index = (index + 1) % msgs.length;
+                    return index;
+                }
+            })();
+            let tid = setInterval(writeMessage, 1000);
+            */
+        });
+    </script>
+</body>
+
+</html>
diff --git a/src/jquery.console.css b/src/jquery.console.css
@@ -0,0 +1,63 @@
+.jquery-console {
+    border: 1px solid #444;
+    height: 10em;
+    overflow-y: scroll;
+    margin: 1em;
+}
+
+.jquery-console-entry {
+    text-align: left;
+    color: #444;
+    padding: 0 0.5em 0 0.5em;
+}
+
+.jquery-console-msg {
+    display: inline-block;
+    word-break: break-all;
+    text-align: left;
+    width: 100%;
+}
+
+.jquery-console-msg-nots {
+    float: left;
+    width: 90%;
+}
+
+.jquery-console-timestamp {
+    display: inline-block;
+    text-align: right;
+    width: 10%;
+}
+
+.jquery-console-lvl-debug {
+    color: #D2D2D2;
+}
+
+.jquery-console-lvl-info {
+    color: #444444;
+}
+
+.jquery-console-lvl-notice {
+    color: #009300;
+}
+
+.jquery-console-lvl-warning {
+    color: #009393;
+}
+
+.jquery-console-lvl-error {
+    color: #00007F;
+}
+
+.jquery-console-lvl-critical {
+    color: #FC7F00;
+}
+
+.jquery-console-lvl-alert {
+    color: #7F0000;
+}
+
+.jquery-console-lvl-emergency {
+    background-color: #000000;
+    color: #FFFFFF;
+}