![](\"img/logo.png\"){kind=logo}
\n\n
![\"no](\"https://img.shields.io/badge/dependencies-none-blue.svg\"){kind=icon}
\n![\"build](\"https://travis-ci.org/adambertrandberger/l.svg?branch=master\")
\n\n\n\n![\"l\"](\"img/l.png\")
makes it easy.\nFor your client-side apps, you will be free from the chains that are the DOM API. No longer will you have verbose calls like `document.createElement`\nbinding you to your keyboard. With your new found freedom you can focus on describing HTML in a natural way. For your webservers, you can use the same \nliberating abstractions offered by to generate HTML.\n\nTry it out online [here](http://idiocode.com/projects/l/try.html)!\n\n:\n```javascript\nl(() => div(\nh1('Example'),\ndiv(p('First'), hr, p('Second'), span(span(span('Nesting is easy.')))),\nsection(header(h1('HTML 5 is supported too!')),\ndiv('Properties can be set', { style: { color: 'red' }}),\ndiv('Attributes can be set too!', { class: 'wow' }))\n)\n);\n```\n\nHTML:\n```html\nFirst
\nSecond
\nNesting is easy.\n works in Node.js too! Install with `npm install l-html`, then import using `require`:\n\n```javascript\nconst l = require('l-html')\n```\n\n## Test\n has `mocha` tests that verify that the code works as expected. If you want to run the tests, run:\n\n```\ngit clone https://github.com/adambertrandberger/l\nnpm install\nnpm test\n```\n\nThis is an optional step. You should only do it if you want to verify everything works for yourself. But, reading some of these tests is a good supplement to the tutorial below. \n\n## Getting Started\nAfter importing in your environment, there will be one new variable called `l` that you can use. \nEverything we go over in the following sections describes what you can do with this object.\n\n## Generating Elements\nThere are multiple ways to generate HTML through the `l` object. \nThe most straightforward way is to create a tag by calling the tag name using the dot operator on the `l` object.\n\n```javascript\nl.div()\n// \n\nl.section()\n// \n```\n\nThe `l` object has a function like this for every valid HTML tag.\n\nYou may be saying \"what about custom HTML elements?\". You're right, the HTML spec allows for custom tag names and so does . \nIf you want to generate a custom HTML tag, you can make it by calling `l` as a function:\n\n```javascript\nl('customtag')\n// will try to guess if the value should be set as an attribute, or a property on the node.\nIf you want to force a value to be a property or attribute explicitly you can use the reserved key `attrs` for attributes\nand `props` for properties:\n\n```javascript\nl.textarea({ value: 'My value' })\n// \n\nl.textarea({ props: { value: 'My value' }})\n// \n```\n\nNotice how inferred that `value` was an attribute, but when told to use it as a property it will be assigned to the node \nas a property. This results in the HTML not containing the potentially long `value` attribute, but it is still shown in the HTML. \n\n\nYou can mix these two arguments (the string and object) to make the syntax more compact:\n```javascript\nl.div('This is the text', { style: { color: 'red' }})\n// Function\nYou know how we have been saying `l.div()` and `l.span()`? With the `l` _dot_? That isn't what the example code looks like is it? In the example code we didn't \nhave to type `l` _dot_. To get the pretty code you see in the examples, you have to use functions. An function is a shortcut so that you \ncan skip typing `l.` all the time. Everything works the same as before. All the arguments are the same, its just easier to type.\nThe main advantage is that you can feel like you're typing actual HTML instead of using a library.\n\n```javascript\nl(() => div(span('Feels more like writing HTML'), br, span('Pretty cool')))\n\nl.div(() => span('You use it anywhere'), () => l.br, () => l.span('Yeah'))\n```\n\nThere is a performance overhead that comes with using functions. If you are using this to create a \nmission-critical page that would benefit from being a couple of milliseconds faster, you can skip using functions, or even look into using `l.import`. But, everyone else will be able enjoy the\ncleaner interface.\n\nA nice trait of functions is that they don't clobber variables in the outer or global scope:\n\n```javascript\nvar a = \"Can't touch this\";\nl(() => a('What are you talking about', { href: '#' }))\n// What are you talking about\nconsole.log(a === \"Can't touch this\");\n```\n\nSee how inside of the function, `a` changed its value from being `\"Can't touch this\"` to being a function that creates an anchor tag? Even better,\nthe `a` defined in the outer scope is untouched. You can think of any tag name as a reserved keyword inside of an function.\nIf you need to close a variable over an function, you should make sure it isn't the name of an HTML tag, as it will not\nbe visible inside of the function.\n\n#### Functions and Variable Scopes\nYou might be wondering exactly which variables functions are capable of accessing. Due to implementation problems, functions \naren't able to keep the same properties that exist in Javascript functions. They do not capture local variables as Javascript's closures do. This means\nthe following code will _not_ work:\n\n```\n// Does NOT work:\nfunction myFunc() {\nconst thing = 12;\nconsole.log(() => div(thing));\n}\n\nmyFunc(); // throws \"ReferenceError: thing is not defined\"\n```\n\nTo look on the bright-side, this is good because it means that no local variables (variables defined in functions) will get clobbered with names of the element generators in the \n functions. But it would be nice to access local variables from within an function.\nIn the next section we will take a look at `l.with`, which is a way to pass arguments to functions.\n\nWhile they can't access local variables, they _can_ access all global variables:\n\n```\n// DOES work\nconst thing = 12;\nfunction myFunc() {\nconsole.log(() => div(thing));\n}\n\nmyFunc(); // functions to be able to render different HTML based off different objects, we need a way of passing\ninformation to the functions. In the next section we will show the solution to this: `l.with`.\n\n## Passing Arguments to Functions\nBecause aren't closures, we need some way of passing variables into function if we ever want to render HTML based on some input data.\n\n`l.with` lets this happen. `l.with` is just like calling `l` as a function (`l(...)`), except it takes a required object as its first argument.\n\nAll of the fields in that object will be available inside of the function. Take a look:\n\n```\nconst person = { age: 23, name: 'Dave' },\n animal = { type: 'birdy', talk: () => 'tweet' };\nl.with({ person, animal }, () => div('You are: ', person.age, ' years old.', span(animal.talk()))); // function any additional parameters. The object you give `l.with` automagically includes them in the\nscope. If you only needed the \"person\" and didn't want to have to type \"person\" all the time you can just pass in the \"person\" directly too:\n\n```\nconst person = { age: 23, name: 'Dave' };\nl.with(person, () => div('You are: ', age, ' years old.')); // supports a way of appending children to existing DOM nodes. When you use `l` as a function, as we have done Generating Elements,\nyou can pass `l` an existing DOM node, and it will append any nodes that are given after it to that node.\n\n```javascript\nl(document.body, () => div(\"I've been appended!\"))\n// ... makes sense of whatever mess you give it. So try to give it your own mess\nand see what it gives you back.\n\n## What's Next?\nTry mixing in Javascript with to render your objects for you:\n\n```javascript\nclass Profile {\nconstructor(name, age, phoneNumber) {\nthis.name = name;\nthis.age = age;\nthis.phoneNumber = phoneNumber;\n}\n\neditAge(e) {\nalert('Call me at ' + this.phoneNumber);\n}\n\nrender(parent) {\nreturn l(parent, l.with(this, () => div(\nh1(`Welcome, ${name}!`),\nul(li(`Age: ${age}`), \nli(`Phone Number: ${phoneNumber}`, { onclick: editAge })\n),\n)));\n}\n}\n```\n\nThis way you can generate an HTML page for any person's profile. No Virtual DOM needed!\n\nMake a game in Javascript, make a webserver, make visualizations, do anything you could do in normal Javascript and HTML, but enjoy it more.\n\n## A Note on the Performance of Functions\nEverytime you use an function, Javascript's `eval(...)` function is called. The function you supply\nis actually converted to a string, then, among other things, a bunch of `var` declarations for each tag name are prepended to that string and fed into an `eval(...)`.\n\nPopular opinion is to think that this is massively inefficient. From my tests, it is a bit inefficient, but still very usable even in production environments. Using `eval` allows the library to be even more flexible \nbecuase it can use intermediate objects for HTML elements. Down the road additional helper functions and optimizations could be written that takes advantage of this. For example, when interfacing with the DOM, there are optimizations \nfor calls which are made in succession intermediate objects allow us to be lazy about DOM node generation and allow us to do some optimizations around that. Element generator functions couldn't do this because\nthere is no way to say \"whenever a tag generator completes, and the stack is empty, convert the result to a DOM node\". Well... there is a way, but it includes using `Function.prototype.caller` which is widely\nunderstood to be on the docket for removal from most Javascript implementations.\n\nAn optimization like this can still be done manually; however,\nrequiring a manual step from the programmers though. It would look like this: `l.dom(l.div, l.span, l.div(l.div()));`. But then, the whole library would have to be used this way.\nbut I'm not willing to make users have to worry about when the intermedate HTML element objects are turned into DOM nodes. At that point, I turn to my opinion that the programmers time\nis not worth that small of an efficiency gain. This is why the option to use an `eval` based approach may be a good thing rather than a bad thing. There is no doubt about the weakened performance\nat the moment though. I did a test on my macbook, and I was able to create ~500 DOM nodes (a `div` with 500 `span` children) in 0.025 milliseconds using element generators (`l.div()` and `l.span()`).\nI tried the same experiment using functions and was able to make 500 DOM nodes in 3.88 milliseconds. These tests were done in Google Chrome, not on Node.js.\nI assume the running times will be different on Node.js based on how a fake DOM is used in that environment. \n\nKeep in mind this is a lot of DOM nodes. 500 nodes is enough for making most web pages. When this number becomes unusable is when you are using the library for a game that requires 60FPS updates and has > 10,000 DOM nodes (since every frame must take less than 16.66ms).\nPerhaps a large n-body particle simulation would greatly benefit from skipping functions all together and just going with element generators.\n\nThe conclusion I take away from these results is to use functions whenever performance doesn't matter. Rendering a webpage, and even frequent re-rendering of a \nwebpage is a good use for functions because it will save programmer time. For tasks that are extremely time sensitive (such as rendering animation frames) or for\nextremely large webpages (>10,000 DOM nodes), use element generators, or `l.import`.\n\n## But I want high performance, and functions!\nWe can do that. But you are going to have to sacrifice for a little good ol' fashioned namespace pollution:\n\n```\nl.import();\n\ndiv(span(span()), 'it works!')\n```\n\nThere is `l.import` for this need. The function takes an object to import the element generators into (defaults to `window`), and a boolean which indicates whether to clobber existing variables or not (defaults to `false`, as in \"don't clobber\").\n\nThis isn't a horrible choice if you really like the function syntax, but want the performance. Although, it has potential to cause some nasty variable overriding issues. I figured I would keep it in the library for those who don't care about namespace pollution :).\n\n## On the use of `eval` instead of `with`\n\nA question I forsee from a small number of people is \"why not use the `with` statement instead of building up your own variable declarations in the string that is eval'd?\". Well, the Javascript community has effectively killed\nthe `with` statement. Javascript running in `strict mode` doesn't pass the parsing step if it finds a `with` statement. Many tools are hard coded to only use `strict mode` for\ntheir build processes. This means if I wanted to use the latest transpilers and bundlers, like babel and webpack, I couldn't use the `with` statement.\n\nI'm sure before the first question is asked most people would say \"why were you even considering using the `with` statement?!\". The dynamic nature of functions required me to do some namespace hacking.\n\n## Related Libraries\nThe idea of generating HTML in programming languages is old. It has been (almost famously) re-invented in lisps many times. [spinneret](https://github.com/ruricolist/spinneret), for example, is a library for generating HTML5. \nProgramming languages like [prolog](http://www.swi-prolog.org/pldoc/man?section=htmlwrite), python, and c have done it too. However, these programming languages don't run directly in the browser like Javascript does. \nThose libraries are created for web servers or static page generation. No offense to server-side programming, especially because supports that. But, having access to the DOM allows \nnodes to be created dynamically and for making interactive HTML. Seeing as Javascript can run in the browser like this, and be used for a webserver it is a natural fit for such a library.\n\nThe browser already has the capability of generating HTML through a builtin interface: the DOM. \nI've used the DOM enough to know how time consuming it is to use. Take a look at how messy it is to generate ` and inspired my work:\n- [jaml](http://edspencer.github.io/jaml/) - Has the same interface as functions, but only generates HTML strings. It seems like it was inspired from MVC style HTML templates like that of Ruby on Rails or Django.\n- [http/html_write](http://www.swi-prolog.org/pldoc/man?section=htmlwrite) - A prolog library for generating HTML. Identical interface as JAML and functions.\n- [crel](https://github.com/KoryNunn/crel) - More lightweight than with some interface differences (the constructor handles attributes/properties differently). Doesn't have an function equivalent.\n- [laconic](https://github.com/joestelmach/laconic) - Similar to crel (crel says this was its inspiration).\n- [RE:DOM](https://redom.js.org/) - Has much in common with , but doesn't have a function equivalent, and focuses more on providing features for web components and updating the DOM.\n\n## License\n\nCopyright 2019 Adam Bertrand Berger\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n## TODO:\n- Add a way to print a pretty html string\n- Rename Element to Node and Node to NodeProperties (and make a new Element class and TextNode class)\n- Make website\n- Add try-out-online page\n- Create example apps\n- why does doing `l.div` vs `l.div()` have such a large performance impact\n- figure out why Proxy isn't being used in the browser for the `l` object\n","readmeFilename":"README.md"}