Dollarsign - Native jQuery
A small library for native DOM selection and event binding. Wraps basic browser functionality into a more consistent API. Supports most of jQuery's basic API for event binding, DOM selection, and CSS/attribute manipulation.
Installation
Install Dollarsign with NPM:
$ npm install dollarsign --save
Or Yarn:
$ yarn add dollarsign
You can then import the $ factory function:
import $ from "dollarsign";
Usage
Use Dollarsign to select DOM elements and bind events:
import $ from "dollarsign";
$("#change-color").on("click", function (event) {
event.preventDefault();
$("h1").css({ color: "#ff000" });
});
<body>
<h1>I'm different!</h1>
<nav>
<a href="#" id="change-color">Change Color</a>
</nav>
</body>
Much of the jQuery API is provided, with some notable exceptions (like
$.ajax).
Programmatic Usage
You can also use the Dollarsign class on its own and build your own
factory function:
import { Dollarsign } from "dollarsign";
function $(selector) {
return new Dollarsign(document, selector);
}
Plugins
Plugins are similar to the jQuery implementation:
$.fn.plugin = function () {
this.each((element) => {
$(element).addClass("plugined");
});
};
$("#element").plugin();
$("#element").hasClass("plugined"); // => true
Testing Plugins
You can test your plugins in isolation by using a stripped-down build. Here's an example written in Jest:
import { foo } from "./foo";
import { $ } from "dollarsign/factory";
$.fn.foo = foo;
test("foo", () => {
expect($(document).foo()).toEqual("bar");
});
Roll Your Own
The plugin system is not only used for 3rd-party plugins, it's also how Dollarsign implements most of its functionality. This means you can leverage the relatively small size of Dollarsign's core functionality and "roll your own" build of the library, using tree-shaking and compile-time optimizations to get the smallest possible bundle size with the least amount of work.
To roll your own build of Dollarsign, import $ from the factory
module rather than the default:
import { $ } from "dollarsign/factory";
This gives you a "blank slate" Dollarsign object. You can still query for elements, but there's not much you can do with them. You'll need to import some functionality and apply them as plugins. For example, if you only wanted the event binding functionality, you might do:
import { $ } from "dollarsign/factory";
import { on, off, fire } from "dollarsign/events";
$.fn.on = on;
$.fn.off = off;
$.fn.fire = fire;
export default $;
Note that some parts of the standard set of plugins are dependent on one
another. For example, to use load(), you will need to also include the
following plugins (or at least reasonable facsimiles of them):
import { $ } from "dollarsign";
import { load } from "dollarsign/ajax";
import { html } from "dollarsign/dom";
$.fn.html = html;
$.fn.load = load;
API Documentation
For more information about what API methods are implemented, visit the documentation at https://tubbo.github.io/dollarsign
Development
To contribute to Dollarsign, download the Git repository:
$ git clone https://github.com/tubbo/dollarsign.git
$ cd dollarsign
Then, install dependencies:
$ yarn install
Make your changes to the .js files and run tests to make sure
everything still works (and write tests for new functionality!):
$ yarn test
We use Jest for our test runner, and [Babel][] to compile our
JavaScript to a format that Jest will understand. Since Jest does not
yet support ESModules syntax out of the box, we need to use babel-jest
here to transpile our syntax.
Static Analysis
We use Prettier for code formatting and ESLint for linting. These two tools help us ensure a consistent style and code quality.
Run lint checks to ensure your code matches our style guide:
$ yarn lint
If the checks flag anything, reformat your code:
$ yarn fmt
Contributing Documentation
After editing the JSDoc, ensure your documentation looks correctly by building it locally:
$ yarn docs
Then, open docs/index.html in your browser.