Add configurable field separator

This commit is contained in:
Alan Grainger
2026-10-19 17:33:47 +13:00
parent a620d0b3ae
commit ac34a03482
8 changed files with 118 additions and 32 deletions
+32 -7
View File
@@ -103,17 +103,42 @@ reason for the delay is explained in [When do uploads appear](/visitor-uploads#w
**Type:** `bool` · **Default:** `true`
Whether the upload page has an optional "Your name" field. The name goes into each stored filename between the prefix
and the original name, followed by a comma, so `IMG_0042.jpg` from Jane Smith is stored as
`ipp_upload_jane-smith,IMG_0042.jpg`. A file sent without a name is stored as `ipp_upload_IMG_0042.jpg`, with no
comma. The visitor's browser remembers the name for the next share on the same install. With `false`, the field is
not shown and a name sent anyway is ignored.
and the original name, followed by the [`fieldSeparator`](#fieldseparator), so `IMG_0042.jpg` from Jane Smith is
stored as `ipp_upload_jane-smith,IMG_0042.jpg`. A file sent without a name is stored as `ipp_upload_IMG_0042.jpg`,
with no separator. The visitor's browser remembers the name for the next share on the same install. With `false`, the
field is not shown and a name sent anyway is ignored.
The name is stored as a slug: lower case, letters and digits in any script, and a hyphen for anything else, at most 32
characters. A comma in the visitor's own filename is removed, so the comma always marks the end of the name. A
filename that already carries the prefix gets neither the prefix nor the name again. The name is the visitor's own
claim; IPP cannot check it. For what to do with it, see
characters. A filename that already carries the prefix gets neither the prefix nor the name again. The name is the
visitor's own claim; IPP cannot check it. For what to do with it, see
[Find each visitor's uploads](/tag-and-review-uploads#find-each-visitors-uploads).
### `fieldSeparator`
**Type:** `string` · **Default:** `","`
The characters that end each visitor field in a stored filename, between the field and the original name, as in
`ipp_upload_jane-smith,IMG_0042.jpg`. The visitor's name is the only field today. The separator is removed from the
visitor's own filename, so it always marks the end of a field. A file sent with no fields has no separator at all.
A comma reads naturally, but some people name their photos with one, as in `Venice, Italy.jpg`, and that comma is
lost. If your visitors do, set `"^"`: it is never written by a camera or a phone, and almost never by a person.
```json
{
"ipp": {
"upload": {
"fieldSeparator": "^"
}
}
}
```
Any punctuation that is legal in a filename works, with one or more characters. A letter, digit, hyphen, dot, space
or a character that is illegal in a filename (`/ ? < > \ : * | "`) is not accepted, and the default is used instead.
Changing it later leaves the files already stored with the old one. How the filename is read back is explained in
[The separator](/tag-and-review-uploads#the-separator).
### `notifyUrl`
**Type:** `string` · **Default:** `""`
+10 -9
View File
@@ -39,20 +39,21 @@ The comma matters: without it, `ipp_upload_jane` would also match `jane-smith` a
visitor typed, made lower case with hyphens for spaces and punctuation. A visitor who leaves the field empty is stored
with the prefix alone and no comma. A visitor can type any name, so treat it as a label, not proof.
### Why a comma
### The separator
The filename is `<prefix><fields><original>`, where each field is followed by a comma. The separator had to be one
that a visitor's own filename never keeps, so that a stem with no comma has no fields, and otherwise the last comma
The filename is `<prefix><fields><original>`, where each field is followed by the separator. The separator has to be
one that a visitor's own filename never keeps, so that a stem without it has no fields, and otherwise the last one
ends them. An underscore cannot do that: `ipp_upload_photo_1.jpg` would read as a visitor called `photo`. A tilde
was ruled out because Android names an edited photo `IMG_1234~2.jpg`. A comma is typeable, legal on every file
system, never written by a camera or a phone, and only rarely by a person. When a visitor's filename does contain
one, it is removed.
was ruled out because Android names an edited photo `IMG_1234~2.jpg`. The default comma is typeable, legal on every
file system, never written by a camera or a phone, and reads naturally. When a visitor's filename does contain one,
as in `Venice, Italy.jpg`, it is removed. If your visitors name their photos that way, set
[`upload.fieldSeparator`](/config/upload-service#fieldseparator) to `^`, which almost nobody types in a filename.
The fields are positional so that more can be added later, such as an event code the owner hands out. A new field
goes on the end, an empty one is written empty, and a file with no fields at all has no comma. So a future
goes on the end, an empty one is written empty, and a file with no fields at all has no separator. So a future
`ipp_upload_jane-smith,34,IMG_0042.jpg` and `ipp_upload_,34,IMG_0042.jpg` would sit beside today's names, and a
script that splits on the comma reads all of them: the last piece is the original filename, the rest are the fields
in order.
script that splits on the separator reads all of them: the last piece is the original filename, the rest are the
fields in order.
## Review uploads before they appear