| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| file_renaming [2024/08/10 07:22] – dstillman | file_renaming [2025/04/16 11:47] (current) – Fixed a small copy-paste error tnajdek |
|---|
| ===== Attachment Title vs. Filename ====== | ===== Attachment Title vs. Filename ====== |
| |
| Attachments have two separate names: the attachment title shown in the items list and the filename of the file on disk. | See [[kb:attachment_title_vs_filename|Attachment Titles vs. Filenames]]. |
| |
| The parent item row already displays metadata such as the title and authors, and since files are generally renamed using that same metadata, Zotero doesn't show the filename directly in the items list. Instead, it uses simpler attachment titles such as "PDF" or "Ebook" for the first file of a given type or includes additional information about the source of the file (e.g., "ScienceDirect Full Text PDF" for a file saved from ScienceDirect, or "Accepted Version" or "Submitted Version" for [[/blog/improved-pdf-retrieval-with-unpaywall-integration/|open-access files]]). These separate titles avoid cluttering the items list with duplicate metadata and prevent parent items from being unnecessarily expanded when searching for titles or creators. | |
| |
| Subsequent files added to an item from the filesystem will still get titles named after the filename (without the file extension), since those are likely to be supplementary files and the filename may be informative. | |
| |
| You can view and change the title and filename by clicking on the attachment and looking in the item pane. | |
| |
| ==== Attachment Title Handling in Zotero 7 ==== | |
| |
| Zotero 7 makes a couple changes to how attachment titles are handled: | |
| |
| - When dragging a file from the filesystem or creating a parent item, Zotero now sets the title of the first attachment of a given type to "PDF", "EPUB", etc., instead of setting the title based on the filename. | |
| - Prior to Zotero 7, the attachment title was unnecessarily changed to the filename when manually running Rename File from Parent Metadata, which was a bug that led many people to believe that files weren't automatically renamed and it was necessary to run Rename File from Parent Metadata on every new attachment. The title is no longer changed, and titles remain as "PDF", "ScienceDirect Full Text PDF", or whatever they were set to previously. | |
| |
| People who were using ZotFile (which also set the title to the filename) or who were unnecessarily running Rename File from Parent Metadata on every attachment might be used to seeing filenames in the items list, but we'd encourage people to give the new behavior a try. | |
| |
| If you'd like to convert existing attachments to use "PDF" titles for consistency, you can select all items in the items list, go to Tools → Developer → Run JavaScript, and run this code: | |
| |
| <code javascript> | |
| var items = ZoteroPane.getSelectedItems(); | |
| for (let item of items) { | |
| if (!item.isRegularItem()) continue; | |
| let attachment = await item.getBestAttachment(); | |
| if (!attachment) continue; | |
| let title = attachment.getField('title'); | |
| if (title.endsWith('.pdf')) { | |
| attachment.setField('title', 'PDF'); | |
| await attachment.saveTx(); | |
| } | |
| } | |
| </code> | |
| |
| This will go through the primary attachment of every selected item and convert the title of any that ends in ".pdf" to just "PDF". | |
| |
| You should test with a smaller number of selected items first to make sure it's doing what you expect. | |
| ===== Customizing the Filename Format ====== | ===== Customizing the Filename Format ====== |
| |
| ''Lee et al. - 2023 - The First Room-Temperature Ambient-Pressure Superconductor.pdf'' | ''Lee et al. - 2023 - The First Room-Temperature Ambient-Pressure Superconductor.pdf'' |
| |
| While Zotero has always renamed files automatically, Zotero 7, currently in [[https://forums.zotero.org/discussion/105094/announcing-the-zotero-7-beta/p1|beta]], introduces a new, powerful syntax for customizing filenames. The default format can be customized from the General pane of the Zotero settings. | While Zotero has always renamed files automatically, Zotero 7 introduces a new, powerful syntax for customizing filenames. The default format can be customized from the General pane of the Zotero settings. |
| |
| This is the default template string: | This is the default template string: |
| ^ Variable ^ Description ^ | ^ Variable ^ Description ^ |
| | ''authors'' | Parent item's principal creators (depending on the item type these are authors or artists but not editors or other contributors). | | | ''authors'' | Parent item's principal creators (depending on the item type these are authors or artists but not editors or other contributors). | |
| | | ''authorsCount'' | The number of the parent item's principal creators. //(Zotero 7.1)// | |
| | ''editors'' | Parent item's editors. | | | ''editors'' | Parent item's editors. | |
| | | ''editorsCount'' | The number of parent item's editors. //(Zotero 7.1)// | |
| | ''creators'' | All parent item's creators. | | | ''creators'' | All parent item's creators. | |
| | ''firstCreator'' | Parent item's creator (1–2 authors or editors). | | | ''creatorsCount'' | The total number of all parent item's creators. //(Zotero 7.1)// | |
| | ''itemType'' | Parent item type. | | | ''firstCreator'' | Parent item's creator (1–2 authors or editors), same as the value of the "Creator" column. | |
| | | ''itemType'' | Parent item type. Complete list of recognized item types can be found [[https://api.zotero.org/itemTypes|here]] | |
| | ''attachmentTitle'' | The title of the attachment that is being renamed or created |' | | ''attachmentTitle'' | The title of the attachment that is being renamed or created |' |
| | ''year'' | Year, extracted from parent item's date field. | | | ''year'' | Year, extracted from parent item's date field. | |
| | ''regexOpts'' | All | 'i' | Defines [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags|flags]] to use when matching using regular expressions (see ''replaceFrom''). For example, ''%%{{ title replaceFrom="\s+" regexOpts="g" }}%%'' is substituted with the parent item's title with all white space removed (without ''regexOpts'', only the first white space would be removed). | | | ''regexOpts'' | All | 'i' | Defines [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags|flags]] to use when matching using regular expressions (see ''replaceFrom''). For example, ''%%{{ title replaceFrom="\s+" regexOpts="g" }}%%'' is substituted with the parent item's title with all white space removed (without ''regexOpts'', only the first white space would be removed). | |
| | ''match'' | All | | Use a regular expression to test for a matching string in the variable. This parameter is useful in conditions and it cannot be used with any other parameters, except for ''regexOpts''. For example, the following template will only return the parent item's URL if the URL's domain name is zotero.org: ''%%{{ if {{ url match="^https?://zotero.org.*?$" }} }}{{ url }}{{ endif }}%%''. | | | ''match'' | All | | Use a regular expression to test for a matching string in the variable. This parameter is useful in conditions and it cannot be used with any other parameters, except for ''regexOpts''. For example, the following template will only return the parent item's URL if the URL's domain name is zotero.org: ''%%{{ if {{ url match="^https?://zotero.org.*?$" }} }}{{ url }}{{ endif }}%%''. | |
| | ''max'' | ''authors'', ''editors'', ''creators'' | | Limits number of creators to use, e.g., ''%%{{ editors max="1" }}%%'' will be replaced with first editor of parent's item. It can be configured with ''regexOpts'' parameter. | | | ''max'' | ''authors'', ''editors'', ''creators'' | | Limits number of creators to use, e.g., ''%%{{ editors max="1" }}%%'' will be replaced with first editor of parent's item. | |
| | ''name'' | ''authors'', ''editors'', ''creators'' | ''family'' | Customizes how creator name appears in the filename, with the following accepted options: ''family-given'' will use full name of the creator, beginning with family (last) name of the creator, ''given-family'' also uses full name but inverts the order, and options ''given'' and ''family'' will only use part of the parent item's creator's name. | | | ''name'' | ''authors'', ''editors'', ''creators'' | ''family'' | Customizes how creator name appears in the filename, with the following accepted options: ''family-given'' will use full name of the creator, beginning with family (last) name of the creator, ''given-family'' also uses full name but inverts the order, and options ''given'' and ''family'' will only use part of the parent item's creator's name. | |
| | ''name-part-separator'' | ''authors'', ''editors'', ''creators'' | '' ''(single space character) | Defines what characters to use to separate given and family name, especially useful when combined with ''initialize''. | | | ''name-part-separator'' | ''authors'', ''editors'', ''creators'' | '' ''(single space character) | Defines what characters to use to separate given and family name, especially useful when combined with ''initialize''. | |
| A year of publication, followed by a hyphen-separated list of authors, followed by a title truncated at 30 characters: | A year of publication, followed by a hyphen-separated list of authors, followed by a title truncated at 30 characters: |
| |
| Template: ''%%{{ year suffix="-" }}{{ authors name="family-given" initialize="given" initialize="-" join="-" suffix="-" case="hyphen" }}{{ title truncate="30" case="hyphen" }}%%'' | Template: |
| | <code>{{ year suffix="-" }} |
| | {{ authors name="family-given" initialize="given" initialize="-" join="-" suffix="-" case="hyphen" }} |
| | {{ title truncate="30" case="hyphen" }} |
| | </code> |
| |
| Filename: ''2023-lee-sukbae-kim-ji-hoon-kwon-young-wan-the-first-room-temperature-amb.pdf'' | Filename: ''2023-lee-sukbae-kim-ji-hoon-kwon-young-wan-the-first-room-temperature-amb.pdf'' |
| Anything not included inside a ''%%{{%%'' bracket is copied to the filename literally: | Anything not included inside a ''%%{{%%'' bracket is copied to the filename literally: |
| |
| Template: ''%%{{ itemType localize="true" }} from {{ year }} by {{ authors max="1" name="given-family" initialize="given" }}%%'' | Template: |
| | <code>{{ itemType localize="true" }} from {{ year }} by {{ authors max="1" name="given-family" initialize="given" }} |
| | </code> |
| |
| Filename: ''Preprint from 2023 by S. Lee.pdf'' | Filename: ''Preprint from 2023 by S. Lee.pdf'' |
| {{ title }} | {{ title }} |
| {{ endif }}</code> | {{ endif }}</code> |
| | |
| | As of Zotero 7.1, it's possible to compare numeric values like ''authorsCount'' using relational operators such as ''<'', ''%%<=%%'', ''>'', and ''>=''. For example, the following template checks the number of authors: if there are two or more, it uses the first author's name followed by et al.; if there are one or two authors, it includes all their names in the filename. |
| | |
| | <code> |
| | {{ if {{ authorsCount > 2 }} }} |
| | {{ authors max="1" suffix=" et al" }} |
| | {{ else }} |
| | {{ authors join=" & " }} |
| | {{ endif }} |
| | </code> |
| |
| It's possible to use regular expressions to match values and change the behavior of the template. For example, the following template preserves common attachment names (such as "Full Text"), but for attachments with non-matching titles, it uses the standard Zotero filename template: | It's possible to use regular expressions to match values and change the behavior of the template. For example, the following template preserves common attachment names (such as "Full Text"), but for attachments with non-matching titles, it uses the standard Zotero filename template: |
| * ''websiteTitle'' | * ''websiteTitle'' |
| * ''websiteType'' | * ''websiteType'' |
| |
Upgrade Storage