|
| 1 | +[](https://htmx.org) |
| 2 | + |
| 3 | +*high power tools for HTML* |
| 4 | + |
| 5 | +[](https://htmx.org/discord) |
| 6 | +[](https://app.netlify.com/sites/htmx/deploys) |
| 7 | +[](https://bundlephobia.com/result?p=htmx.org) |
| 8 | +[](https://bundlephobia.com/result?p=htmx.org) |
| 9 | + |
| 10 | +## introduction |
| 11 | + |
| 12 | +htmx allows you to access [AJAX](https://htmx.org/docs#ajax), [CSS Transitions](https://htmx.org/docs#css_transitions), |
| 13 | +[WebSockets](https://htmx.org/docs#websockets) and [Server Sent Events](https://htmx.org/docs#sse) |
| 14 | +directly in HTML, using [attributes](https://htmx.org/reference#attributes), so you can build |
| 15 | +[modern user interfaces](https://htmx.org/examples) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and |
| 16 | +[power](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of hypertext |
| 17 | + |
| 18 | +htmx is small ([~14k min.gz'd](https://unpkg.com/htmx.org/dist/)), |
| 19 | +[dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json), |
| 20 | +[extendable](https://htmx.org/extensions) & |
| 21 | +IE11 compatible |
| 22 | + |
| 23 | +## motivation |
| 24 | + |
| 25 | +* Why should only `<a>` and `<form>` be able to make HTTP requests? |
| 26 | +* Why should only `click` & `submit` events trigger them? |
| 27 | +* Why should only GET & POST be available? |
| 28 | +* Why should you only be able to replace the *entire* screen? |
| 29 | + |
| 30 | +By removing these arbitrary constraints htmx completes HTML as a |
| 31 | +[hypertext](https://en.wikipedia.org/wiki/Hypertext) |
| 32 | + |
| 33 | +## quick start |
| 34 | + |
| 35 | +```html |
| 36 | + <script src="https://unpkg.com/htmx.org@1.9.1"></script> |
| 37 | + <!-- have a button POST a click via AJAX --> |
| 38 | + <button hx-post="/clicked" hx-swap="outerHTML"> |
| 39 | + Click Me |
| 40 | + </button> |
| 41 | +``` |
| 42 | + |
| 43 | +The [`hx-post`](https://htmx.org/attributes/hx-post) and [`hx-swap`](https://htmx.org/attributes/hx-swap) attributes tell htmx: |
| 44 | + |
| 45 | +> "When a user clicks on this button, issue an AJAX request to /clicked, and replace the entire button with the response" |
| 46 | +
|
| 47 | +htmx is the successor to [intercooler.js](http://intercoolerjs.org) |
| 48 | + |
| 49 | +### installing as a node package |
| 50 | + |
| 51 | +To install using npm: |
| 52 | + |
| 53 | +``` |
| 54 | +npm install htmx.org --save |
| 55 | +``` |
| 56 | + |
| 57 | +Note there is an old broken package called `htmx`. This is `htmx.org`. |
| 58 | + |
| 59 | +## website & docs |
| 60 | + |
| 61 | +* <https://htmx.org> |
| 62 | +* <https://htmx.org/docs> |
| 63 | + |
| 64 | +## contributing |
| 65 | + |
| 66 | +* please write code, including tests, in ES5 for [IE 11 compatibility](https://stackoverflow.com/questions/39902809/support-for-es6-in-internet-explorer-11) |
| 67 | +* please include test cases in [`/test`](https://github.com/bigskysoftware/htmx/tree/dev/test) and docs in [`/www`](https://github.com/bigskysoftware/htmx/tree/dev/www) |
| 68 | +* if you are adding a feature, consider doing it as an [extension](https://htmx.org/extensions) instead to |
| 69 | + keep the core htmx code tidy |
| 70 | +* development pull requests should be against the `dev` branch, docs fixes can be made directly against `master` |
| 71 | +* No time? Then [become a sponsor](https://github.com/sponsors/bigskysoftware#sponsors) |
| 72 | + |
| 73 | +### hacking guide |
| 74 | + |
| 75 | +To develop htmx locally, you will need to install the development dependencies. |
| 76 | + |
| 77 | +__Requires Node 15.__ |
| 78 | + |
| 79 | +Run: |
| 80 | + |
| 81 | +``` |
| 82 | +npm install |
| 83 | +``` |
| 84 | + |
| 85 | +Then, run a web server in the root. |
| 86 | + |
| 87 | +This is easiest with: |
| 88 | + |
| 89 | +``` |
| 90 | +npx serve |
| 91 | +``` |
| 92 | + |
| 93 | +You can then run the test suite by navigating to: |
| 94 | + |
| 95 | +<http://0.0.0.0:3000/test/> |
| 96 | + |
| 97 | +At this point you can modify `/src/htmx.js` to add features, and then add tests in the appropriate area under `/test`. |
| 98 | + |
| 99 | +* `/test/index.html` - the root test page from which all other tests are included |
| 100 | +* `/test/attributes` - attribute specific tests |
| 101 | +* `/test/core` - core functionality tests |
| 102 | +* `/test/core/regressions.js` - regression tests |
| 103 | +* `/test/ext` - extension tests |
| 104 | +* `/test/manual` - manual tests that cannot be automated |
| 105 | + |
| 106 | +htmx uses the [mocha](https://mochajs.org/) testing framework, the [chai](https://www.chaijs.com/) assertion framework |
| 107 | +and [sinon](https://sinonjs.org/releases/v9/fake-xhr-and-server/) to mock out AJAX requests. They are all OK. |
| 108 | + |
| 109 | +## haiku |
| 110 | + |
| 111 | +*javascript fatigue:<br/> |
| 112 | +longing for a hypertext<br/> |
| 113 | +already in hand* |
0 commit comments