Add reference to hx-preserve to the example at "Preserving File Inputs after Form Errors"

[Matt544]

Description

I have added a second approach to preserving file inputs after form errors (in the example at file-upload-input.md), using hx-preserve.

The approach currently suggested requires a restructuring of the form that will not always be feasible or convenient. I have found that adding hx-preserve to the file input causes the expected behavior: the user does not have to choose a file again before re-submitting the form.

The approach is:

<form method="POST" id="binaryForm" enctype="multipart/form-data" hx-swap="outerHTML" hx-target="#binaryForm">
    <input hx-preserve id="someId" type="file" name="binaryFile">
    <button type="submit">Submit</button>
</form>

I feel this change is necessary because the current version of file-upload-input.md leaves the impression that there is no htmx attribute that can preserve the file input's value if the input is within the area that htmx will swap. I'm a little embarrassed to say that this is the conclusion I drew when I saw the current version of file-upload-input.md and I charged ahead and made an extension that moved my input out of the swap zone and put it back after the swap. My bad. But it might help others to point out that hx-preserve is available for this use case.

Testing

My own testing on the hx-preserve approach shows it can acheive the following behaviour:

• if the form has errors and is returned, the original file input choice is preserved and the form can be successfully re-submitted.

• if the file field has errors on it, they will be displayed provided that hx-preserve was placed in the input only and not the errors element (e.g. ol.errorlist)

• if you want the file upload input to return without the user's chosen file because the field was invalid, you can manage that on the server side by omitting the hx-preserve attribute when the field has errors. (For example, if the user chooses an invalid file type, you may want the file field to come back with no value so the user is forced to make another choice.)

Checklist

• [x] I have read the contribution guidelines
• [x] I have targeted this PR against the correct branch (master for website changes, dev for source changes)
  • I have tried to target the master branch. Sorry if that didn't work!
• [x] This is either a bugfix, a documentation update, or a new feature that has been explicitly approved via an issue
• [ ] I ran the test suite locally (npm run test) and verified that it succeeded
  • Nope. This PR address documentation only, under www.

[alexpetros]

Your testing is so good, I wonder if maybe it would help to include some of that in the documentation as well? This bit especially:

if the file field has errors on it, they will be displayed provided that hx-preserve was placed in the input only and not the errors element (e.g. ol.errorlist)

if you want the file upload input to return without the user's chosen file because the field was invalid, you can manage that on the server side by omitting the hx-preserve attribute when the field has errors.

[Telroshan]

Hey @Matt544 , are you still interested in this change? If so, what do you think of alex's suggestion above? Thanks!

[Matt544]

Greetings @Telroshan , thanks for the nudge. And thanks @alexpetros for the initial feedback. Sorry for going awol there: various poor excuses apply.

I agree with Alex's suggestion. I have made changes to my pull request branch to reflect the suggestion. I'm not totally clear on the process for updating a pull request (this is my first time trying to contribute to an open source project). My branch 'pr_branch' contains the changes. Please let me know if I should do anything more.

Thanks.

[Telroshan]

Hey @Matt544, first of all no worries at all about the delay, look how long it took me to get back to this PR in the first place!

Thanks for your first open source contribution then 😄

In these cases you should rebase and not merge, in fact you can already see the issue of merging above ; the PR now has 533 files changed which makes it hard (if not impossible) to identify the diff of that very PR, i.e. what actual changes it brings compared to the latest branch, thus hard for us to review.

If you can't manage to rebase and have only your commits in the PR diff (i.e. without bringing along the ~250 other commits), there's always the last resort of closing this PR and opening a new one starting fresh from the latest commit (call it dirty but hey, it works). I am myself a git-cmd ignorant and happy GitHub Desktop user, so I won't be able to help much with the commands, I just click buttons (devs deserve good UIs too!)

[Matt544]

I think I have managed the rebase, thanks for the advice on that.

Note: I did "manual" testing of the suggested approach of using hx-preserve by creating a basic django site and using the htmx cdn for version 2.0.4, which I believe is the current latest. I confirmed that the functionality still works as described in my pull request.

Just let me know if I can do anything else to assist.

Cheers.

[Telroshan]

Thanks!