File renaming documentation incomplete & inconsistent

langisjor

Since the upgrade to Zotero 7, I've been finding that the file renaming documentation (https://www.zotero.org/support/file_renaming) is incomplete and inconsistent, and I'm wondering if and how this could be improved? My question is not a request to try to accommodate every specific file renaming scenario one might have, but to improve the documentation of the base behaviors of the file renaming behavior.

A few examples of what I mean:

- The documentation for `firstCreator` doesn't describe the complete behavior of this variable. For example, only the first creator's last name is output, if there are two creators they're joined by ' and ', and if there are more than two creators the suffix ' et al.' is added. (This may not be the expected behavior, I'm simply describing what I would hope the documentation would include.) It's also not clear if and how this variable can be modified with various parameters.

- `year` is listed as a variable in the initial table of variables, but then isn't included in the Complete List of Fields at the bottom of the page.

- What is the complete list of `itemType` options as recognized by the file renaming process? Ostensibly it's the complete set of item types that Zotero supports, but then how are the variables named? For example, does "Audio Recording" become "audioRecording" or "audiorecording" or "audio-recording"? This documentation detail would seem to apply to other variables such as `audioFileType`, `letterType`, `mapType`, 'presentationType`, etc.

- Similar to the above, `itemType` is mentioned as a variable in the example about using conditionals, but then it isn't listed in the Complete List of Fields.

- What other conditional expressions can be used? Is there a string conditional such as `if empty`, or would this type of expression need to be done with regEx?

These are just a few of the examples I've encountered with the existing documentation being somewhat incomplete when trying to work through some specific file renaming attempts.

tnajdek

The documentation for `firstCreator` doesn't describe the complete behavior of this variable

The logic for creating the `firstCreator` is the same as for the "Creator" column. We will add a note about this to the documentation.

`year` is listed as a variable in the initial table of variables, but then isn't included in the Complete List of Fields at the bottom of the page.

That's intentional. There is a list of variables that the renaming system recognizes, and the last entry in that table is "Any item field," which you can find at the bottom of this page. The list at the end consists of fields that an item can have and that the renaming system recognizes as variables. Otherwise, the table of variables would be very long, and the second column would be repeated for most of the rows.

What is the complete list of `itemType` options as recognized by the file renaming process?

We will add a list (or a link) to the documentation.

For example, does "Audio Recording" become "audioRecording" or "audiorecording" or "audio-recording"?

It becomes "audioRecording". It can also become "Audio Recording" if the localise attribute is used. The latter is language-specific, so it might become something else if your Zotero is not in English.

What other conditional expressions can be used

The only conditionals supported are equal ('==') and not equal (!=.). Additionally it's possible to use `match` to check a value against a regular expression.

There have been a few more complex templates posted on this forum that we might add to the documentation. We’re also planning to add some new features based on the feedback we’ve received on this feature so far.

langisjor

Thanks for the attention to this. Really appreciate it.

jademsquires

Hi, I have a follow-up question regarding the firstCreator behavior.

On a different post, the poster stated that {{ firstCreator join=", " }} doesn't work because join [only] works for authors, editors, and creators. ref: https://forums.zotero.org/discussion/117442/filename-renaming-with-multiple-authors/p1

However, the documentation (and comment from @tnajdek - above) advise that "The logic for creating the `firstCreator` is the same as for the "Creator" column."

Q1: This reads to me, at first glance, that any *variable* that can be used for creators can also be used for firstCreator; is this a misread on my part? Or is the key part of what you're saying that the logic for CREATING the *parameter* itself is the same (i.e. what it's doing on the back-end to parse/pull the author/editor information in the background)? But NOT that firstCreator can be acted upon by the same variables as Creators?

I'm asking because the creators variable allows for many parameters to be implemented (ex. join) that don't work with firstCreator, which I was disappointed by.

I tested this myself because I expected it to work and it did not.

Here is what I currently have vs what I'm trying to achieve:

Current Filename Template: {{ firstCreator join="-" suffix="-" }}{{ year suffix="-" }}{{ title truncate="100" case="pascal" }}

What is currently showing: Doe and Smith-2018-ExampleTitleExampleSubtitle.pdf

What I want to show: Doe-Smith-2018-ExampleTitleExampleSubtitle.pdf (for 2 authors, at least)

But it seems like if you use firstCreator, you are stuck with the Surname1 and Surname2 format, unless you want to do significantly more conditional work in your coding.

This has been mentioned as an issue/on a wishlist item/request many times:
https://forums.zotero.org/discussion/comment/484145
https://forums.zotero.org/discussion/comment/440865#Comment_440865
https://forums.zotero.org/discussion/comment/470873/#Comment_470873
https://forums.zotero.org/discussion/comment/471001/#Comment_471001
https://forums.zotero.org/discussion/comment/472890#Comment_472890
https://forums.zotero.org/discussion/comment/472409#Comment_472409

Q2: Is this a bigger ask that I'm imagining? If it is, since this has been a recurring question in forums, could y'all simply include the exact coding workaround to achieve this (just the replacement of the "and" in firstCreator output) on the file renaming documentation page?

I have combed through the related forum posts that I could find, and it seems like most of the workarounds involve customizing authors, but what if you want the customizations to apply to both authors and editors- then, would you use regular creators and not use firstCreator at all?

The go-to workaround seems to be from @tnajdek here: https://forums.zotero.org/discussion/comment/472761/#Comment_472761

From that, I'm using:
{{ if {{ authors match="[^,]+,[^,]+,[^,]+" }} }}
{{ authors max="1" suffix=" et al" }}
{{ else }}
{{ authors join="-" suffix="-"}}
{{ year suffix="-" }}
{{ title truncate="100" case="pascal" }}

This includes more than just changing Surname1 and Surname2 to Surname1-Surname2, but I actually DO also want it to do what that original poster wanted (list all authors if there are 2 or less, and use the first-author et al. format if there are 3 or more), so that was fine as-is.

Q3: If I *didn't* also want the 3+ author et al adjustment, and rather *just* wanted the code to apply firstCreator rules (without using firstCreator, so show the first 1-2 author/editors, surname only) but with the hyphen joining those with 2 author/editors instead of the 'and,' what would that code look like?

Q4: If I wanted the code from @tnajdek above to pull authors OR editors, depending on which was applicable to the citation in question, could I simply sub creators for authors in the exact same code? i.e. -
{{ if {{ creators match="[^,]+,[^,]+,[^,]+" }} }}
{{ creators max="1" suffix=" et al" }}
{{ else }}
{{ creators join="-" suffix="-"}}
{{ year suffix="-" }}
{{ title truncate="100" case="pascal" }}

(that would hinge on the creators pulling either the authors or the editors, depending on which category applies to any given citation, which is what I would expect based on my read of the documentation, but please correct me if I'm wrong!)

Q5: Also, I'm not a programmer, so I'm not quite sure *exactly* what the if statement at the beginning is conveying, i.e. {{ if {{ authors match="[^,]+,[^,]+,[^,]+" }} }} Does it limit the application of the authors' variables to situations where authors are listed with commas in the original formatting, or...? I just want to make sure any citation that I have in my library would meet the criteria for this filename format to apply correctly.

Thanks in advance! I've tried to be as precise in my wording as possible, but please let me know if any part needs clarification.

tnajdek

1. It’s the latter. The documentation specifies exactly which parameters can be used with which variables.The logic for firstCreator is the same as the “Creator” column in terms of how the value is determined, but that does not mean all creator-related parameters apply to firstCreator.
2. The recommended approach is to build the template to match your requirements. In Zotero 7.0.16 we introduced authorsCount, editorsCount, and creatorsCount, so the older regex-based workaround from forum posts is no longer necessary.
3. If you simply want up to two creators, joined by a hyphen, you can use:{{ creators max="2" join="-" }}
max="2" limits the output to the first two creators, and join="-" sets the delimiter (it won’t be used if there is only one creator).
4. Yes, that’s correct. You can also nest this inside a broader if/else block if you want different behaviour depending on item type.
5. The {{ if {{ authors match="[^,]+,[^,]+,[^,]+" }} }} construct was a regular-expression workaround to detect three or more authors by counting comma-separated names. Since Zotero 7.0.16 provides authorsCount (and related count variables), that workaround is no longer needed.