Documentation on Writing Extensions

[benvcutilli]

Hi, not sure if Issues is where this belongs, so I apologize ahead of time.

I am new to HTMX. I started using it (really enjoy the declarative simplicity), but have found at least one scenario in which writing an extension is the only way to solve the issue in the way that makes sense for the code/request-response patterns I'm using. What I've found on the subject is pretty terse, so I don't really know the expectations on how the extension is to be implemented. For example, it isn't clear which APIs to try to stick to (such as the htmx object vs. the Web API; bypassing HTMX might result in state inconsistencies, I don't know). Also, the names and parameters of the methods on the object that we create to define the extensions, for me at least, aren't self-describing enough to know what code goes where. A Google search didn't turn up much of anything, and I feel as though reading and understanding the interactions of all 4000+ lines of HTMX code is kinda an unreasonable strategy. I also took a look at response-targets, but felt that I didn't understand the core of HTMX anywhere close to well enough to know what was going on there.

Is there anything more in-depth but simultaneously more accessible out there that I could look at? Appreciate the help.

[MichaelWest22]

Yeah there is not a lot of detailed documentation on how to develop htmx extensions. However I've found them quite easy to develop and test. read the main readme https://github.com/bigskysoftware/htmx-extensions carefully first and look at the list of functions you can override in your extension at the bottom. There is no clear explanation for each of them giving you an description or example or return type doco sorry. I would instead recommend you look at https://github.com/bigskysoftware/htmx-extensions/tree/main/src and find examples of extensions that implement each of the functions to find how to use them. Most of the extensions you will find are very simple and easy to understand how they work. Most of the functions are very simple to work out how they work when you see the code for the other examples and the only one that is more complicated is the onEvent() one and for this one I would study https://htmx.org/events/ to learn how events listeners work in htmx.

But the best way to learn how to write the extensions I've found is to download a copy of the un-minified htmx.js into your local test app folder so you can link to this in your head instead of the external static minified version. Then you can add breakpoints in your browser dev tools and make changes to the htmx.js file (and your htmx-cust-ext.js) if required to add custom logging or tweaks so you can learn how it handles each request and step though the code. You may find to start with you can just modify htmx.js directly to test out getting it to do what you want first once you have debugged and found the lines involved. You can then look in the code close to this for a htmx event you can listen to to override or a call to the extension integration so you know how to write your extension. You never need to read all 4000 lines at once this way and the htmx source is super simple to read, understand and debug. Adding htmx.logAll() to the end your htmx.js copy or running this in console each time is useful to learn the events htmx fires. You