README

scetch

scetch is yet another templating library for vanilla http(s) and express. It differs from the rest because it taught me how the express rendering/middleware engine works, and is also really, really, really simple to use. I really mean DEAD SIMPLE.

Why scetch and not sketch? Honestly, I don't know. I think I wanted it to be different?

Can you condense regexes like a pro? If so, then feel free to chonk down these regexes for super stonks on speed!

Installation

npm install --save scetch

Quick Start

Consider this as your __dirname/views/home.sce

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>scetch - the newest templating engine!</title>
</head>
<body>
    <p>You requested [[url]]</p>
    <p>The time is [[time]]</p>
</body>
</html>

Vanila HTTP(S)

In your server.js:

const http = require('http');
const router = require('./router');
const scetch = require('scetch')();

router.get('/callback-*', (req, res) => {
    scetch.engine('home',{
        url: req.url,
        time: new Date().toLocaleString()
    }, (data) => {
      res.write(data).end();
    });
});
router.get('/promise-*', async function (req, res) => {
    res.write(await scetch.engine('home', {
        url: req.url,
        time: new Date().toLocaleString()
    })).end();
});

Express

In your app.js:

const express = require('express');
const scetch = require('scetch')();

let app = express();
app.set('views', 'views'); // registers './views' as the folder holding all the scetch template files
app.engine('sce', scetch.engine); // 'sce' registers the file extension, scetch.engine is the actual engine!
app.set('view engine', 'sce'); // tells express to look for '*.sce' files when rendering

app.get('/*', (req,res) => {
    res.render('home', {
        url: req.url,
        time: new Date().toLocaleString()
    });
});

`sce` How To

scetch offers a variety of handlebar-like expressions to make your templates easy to manage:

Options
Variables
Partials
Conditionals
Loops
Components

These expressions are found using Regular Expressions, therefore, scetch is pretty flexible about what you can put in - it even doesn't care for spaces, so add as many as you want!

Options

scetch has a couple of options that you can use to override the default settings of how you expect it to function. This list is by no means exhaustive, and it can even change with any update - fair warning.

The following are the default settings, and can be changed by modifying the values.

const scetch = require("scetch")({
    root: path.join(__dirname, 'views'),
    ext: ".sce",
    nonceName: "nonce"
});

Variables

Usage: [[ variableName ]] or [[ object.value ]]
Regex: /\[\[[^=]*? *([^\[\]\s]+?) *\]\]/gi

Variables are inserted within the scetch engine by swapping the placeholder with the variable passed from the express route. What you'll notice is that you can also use dot notation for objects! Depth for dot notation is relatively shallow, and it's probably best that you stray from it when using loops - this is what caused my hair to fall out last night! Otherwise, I guess it works well -- I haven't really tested it too hard... ~~This allows for extra complexity which you might not get from another templating engine!~~ <== That is completely a guess and has no evidence.

To access elements of an array through this tag, you can use dot notation as well! This makes things like [[ array.0.id ]] possible!

Partials

Usage: [[i= location/to/partial ]]
Regex: /\[\[i= *(.+?) *\]\]/gi

Partials are synonymous with includes (yeah, just like PHP includes... almost...). You can specify a portion of your HTML (the whole head tag for example), and then add in [[i=partial/head]] into your template, and your whole head tag will be inserted!

Conditionals

Usage:
- If: [[?= "js eval expression" ]]
- Else If: [[3= "another js eval expression" ]]
- Else: [[3= ]] (else if with no expression)
- End If: [[?==]]
Regexes:
- If: /\[\[\?= *([^\s=].*?) *\]\]/gi
- Else (If): /\[\[3= *(.*?) *\]\]/gi
- End If: "[[?==]]" (straight up string matching)

Conditionals provide you with a way to control the flow of your rendered views. You can show or hide content on the server side to make sure the end user does (not) see what they're (not) supposed to!

Loops

Usage:
- For: [[f= counter 0:10 ]] or [[f= number 0:2:10 ]] (step 2 each time) (excludes upper boundary)
- For Each: [[e= newVar in array ]] (newVar is a variable, not an index!)
- While: [[w= jsBoolEvalExpression() ]] (executed on entry)
- End Loop: [[?==]] (I know, it's the end if! 😮)
Regexes:
- For: /\[\[f= *(\w+?) *(\d+):(?:(\d+):)?(\d+) *\]\]/gi
- For Each: /\[\[e= *(\w+) *in *(\S+) *\]\]/gi
- While: /\[\[w= *(\S.*?) *\]\]/gi
- End Loop: "[[?==]]" (I know, it's the end if! 😮)

Loops allow you to duplicate certain pieces of your template so you can create multiples! The counter loop is inclusive of start, and exclusive of end, so looping from 0 to 10 will provide 0 through 9 (or 10 values).

Also, if you want to use the number counter to reference an array element from a variable passed in, you can use dot notation and variable substitution, like [[ array.[[counter]] ]]. scetch handles this by substituting the value for the counter in during the loop, and then substituting the whole variable just before finishing up! (Take note that this is only required because of variable name dependency.)

What you might also notice, is that the end loop tag is identical to the end if - this is intentional, because the last open if/for/while will be closed using the end loop/if!

Components

Usage:
- Prepare component: [[l= location/to/component ]] - Places a script object before the closing </body> tag.
- Inject component server-side: [[c= location/to/component || obj=obj.variable literal="literal strings" escaped="\"escaped\" values too" ]]
- Inject component client-side: js: scetch.insert(target, [position], scetchComponent, data)
Regexes:
- Prepare: \[\[l= *(.+?) *\]\]
- Injection:
  - Whole Capture: /\[\[c= *([^ ]+?)(?: *\|\| *(.+?))? *\]\]/gi
  - Variables Capture: /(\w+)=("[^"\\]*(?:\\.[^"\\]*)*"|(?:\w+\.*)+)/gi
  - RegExr: https://regexr.com/5bimv and https://regexr.com/5biqb

Components in scetch allow you to render partials both statically and dynamically! You can render the partial before sending data to the client by using c=, allowing you to, for example, add multiple rows of todos! Then if the client wants a new todo, the global scetch object can insert one on your command! By calling scetch.insert($(".todos"), "beforeend", scetch.comps.todo), you can add a new todo component before the closing tag of the todo list!

The scetch.comps object literally holds the string data of the scetch components. Therefore you can add partials that you don't even load! Simply swap out the scetch component you want to use for valid HTML and, scetch's your engine, it's in!

The only limitation to using the client-side injection is that you only have access to applying variables. You don't get loops, you don't get conditions, you don't get nothin' but variables.

Your web app doesn't allow inline scripts? No worries! Nonce use is available to help secure your web apps! One package (also written by TheBrenny) that can help become a middleware to ExpressJS is nonce-express.

Alternatively, nonces can be set by setting a variable during in the object passed to res.render or scetch.engine.

See also! scetch.insert is more-or-less a wrapper for insertAdjacentHTML. Go there to understand the arguments!

scetch to Mona Lisa

scetch's processing flow isn't fully matured yet, and is subject to change at any time. This may break your environment, so be careful when it comes to updating scetch! Here's the current flow:

engine(filepath, variables, cb)
- Read data in filepath
- "Process Data"
  - Apply Partials
  - Apply Component Injections
  - Apply Variables
  - Apply Logic (recursively calls "Process Data" for some things)
- Apply Variables (as a safety measure)
- Apply Component Load Scripts
- Return the processed data!

A cool idea would be to make this processing flow more modular, and let you users take control of it, but we'll see what happens... I gotta give scetch a real canvas first!

Contributing

Pull requests are warmly welcomed. For major changes, please open an issue first to discuss what you would like to change.

~~Please make sure to update tests as appropriate.~~ Yeah.... We'll get to testing one day... Maybe you could sort it out? 🙏

Final Words

This is literally just a passion project for no other reason than to build and maintain a project that I can use in my life! I've used it in a number of projects already, and plan to continue using it for more!

If you feel like adopting scetch, please be aware of the risks associated with a library that's just for fun!

License

MIT

Usage no npm install needed!