Placeholder syntax

From refbase

Contents

This page explains the placeholder syntax used by refbase-0.9.0 or greater:

Introduction

refbase offers a flexible placeholder syntax that can be used to:

  • automatically rename uploaded files according to a specific file naming scheme
  • move uploaded files into automatically created sub-directories (which can be named based on the record's bibliographic information)
  • cite records using custom text citation strings
  • automatically generate custom cite keys on export
  • auto-generate URLs for each record based on the record's bibliographic information

General syntax rules

  • Placeholders start with '<' and end with '>' and the actual placeholder name is enclosed with colons (':'). Examples:
<:serial:>
<:firstAuthor:>
<:secondAuthor:>
<:year:>
<:title:>
<:volume:>
<:startPage:>
  • You can use literal text between placeholders. Example:
record-<:serial:>_<:firstAuthor:>_<:year:>
  • The placeholder syntax allows for prefix & suffix strings which will only get included if a given placeholder isn't empty. An optional prefix can be inserted between the opening angle bracket ('<') and the first colon (':'). Examples:
<vol:volume:>
<p:startPage:>
<:firstAuthor:><&:secondAuthor:>
An optional suffix can be inserted between the second colon (':') and the closing angle bracket ('>'). Example:
<:serial:_>
  • You're allowed to use any characters between (or within) placeholders except the delimiters '<', '>' and ':'.
  • Some placeholders allow for options (written in brackets). Placeholder options specify, for example, how many words/items will be extracted from a given field. Examples:
    • extract first two words from title field: <:title[2]:>
    • extract first three items from keywords field: <:keywords[3]:>
    • extract last item from keywords field: <:keywords[-1]:>
  • All options can be ommitted in which case default options will be applied. For more info about supported options and their default values, please see the syntax descriptions for the individual placeholders below.

Here's an extended example that includes all of the above mentioned features:

 <:serial:>_<:year[2]:_><vol:volume:><no:issue:><p:startPage:>
           ^       ^  ^  ^^^          ^^         ^
           1       2  3  4            5          6

Explanations:

  • 1: literal string '_' (text between placeholders)
  • 2: option '2' specifies that a two-digit year format shall be used
  • 3: suffix '_' (only printed when year field isn't empty)
  • 4: prefix 'vol' (only printed when volume field isn't empty)
  • 5: prefix 'no' (only printed when issue field isn't empty)
  • 6: prefix 'p' (only printed when pages field contains a number)

Supported placeholders

Below is a list of all supported placeholders including syntax rules and examples. Notes:

  • The placeholder string as well as the actual sample output is displayed in typewriter text.
  • In placeholder strings, the terms opt1, opt2 and opt3 indicate variable values that you're supposed to fill in. The term (opt2) indicates an optional option that may be ommitted.
  • The given output examples are mostly based on this record and this record.

serial

Description: Prints the record's unique database serial number from the serial field.

Basic syntax: <:serial:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:serial:> 6946

authors

Description: Prints last name(s) from the author field according to the given options.

Basic syntax: <:authors:>

Options syntax: <:authors[opt1|opt2|opt3]:>

Notes:

  • Options syntax:
    • opt1: Number that indicates how many authors shall be used from the author field before the string in opt3 is used.
      • You can specify '0' in order to always print all authors connected by the string given in opt2 (ignoring opt3).
      • Leaving the first option empty (as in <:authors[|opt2|opt3]:>) causes the raw author string to be returned without any modification (ignoring opt2 and opt3).
    • opt2: String that's used to connect individual author names (from first author up to the number of authors given in opt1).
    • opt3: String that's appended to the first author's last name if the record's number of authors exceeds the number given in opt1.
  • If no options are given, <:authors[2|+|_etal]:> will be used by default.
  • Default options for this placeholder are set by variable $extractDetailsAuthorsDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:authors:> one author: Gosselin, two authors: Gosselin+Levasseur, three or more authors: Gosselin_etal
<:authors[2|+|_etal]:> one author: Gosselin, two authors: Gosselin+Levasseur, three or more authors: Gosselin_etal
<:authors[2| & | and others]:> one author: Gosselin, two authors: Gosselin & Levasseur, three or more authors: Gosselin and others
<:authors[3| and | et al.]:> one author: Gosselin, two (or three) authors: Gosselin and Levasseur( and Wheeler), four or more authors: Gosselin et al.
<:authors[0| & | et al.]:> Gosselin & Levasseur & Wheeler & Horner & Booth
<:authors[| & | et al.]:> Gosselin, M; Levasseur, M; Wheeler, PA; Horner, RA; Booth, BC

firstAuthor

Description: Prints the first author listed in the author field.

Basic syntax: <:firstAuthor:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:firstAuthor:> Gosselin

secondAuthor

Description: Prints the second author listed in the author field.

Basic syntax: <:secondAuthor:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:secondAuthor:> Levasseur

title

Description: Prints words from the title field.

Basic syntax: <:title:>

Options syntax: <:title[opt1|(opt2)]:>

Notes:

  • Options syntax:
    • opt1: Number of words (i.e., strings delimited by spaces) from the title field.
      • A positive number ('x') extracts x words from the beginning of the title string.
      • A negative number ('-x') extracts x words from the end of the title string.
      • You can specify '0' in order to always print all words from the record's title.
      • Leaving the first option empty (as in <:title[|opt2]:>) causes the raw title string to be returned without any modification (ignoring opt2).
    • opt2 (optional): String that's used to connect individual words from the title. If this option is ommitted, words will be connected without any delimiter.
  • If no options are given, <:title[1]:> will be used by default, i.e., only the first word from title will be used.
  • Default options for this placeholder are set by variable $extractDetailsTitleDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:title:> New
<:title[1]:> New
<:title[2]:> Newmeasurements
<:title[2|-]:> New-measurements
<:title[-2|-]:> Arctic-Ocean
<:title[4|_]:> New_measurements_of_phytoplankton
<:title[0|_]:> New_measurements_of_phytoplankton_and_ice_algal_production_in_the_Arctic_Ocean
<:title[|_]:> New measurements of phytoplankton and ice algal production in the Arctic Ocean

year

Description: Prints the year from the year field.

Basic syntax: <:year:>

Options syntax: <:year[opt1]:>

Notes:

  • Options syntax:
    • opt1: Number that specifies whether the year is returned in two-digit ('2') or four-digit ('4') format.
  • If no options are given (or anything else than '2' or '4' is given), <:year[4]:> will be used by default, i.e., the year will be printed in four-digit format.
  • Default options for this placeholder are set by variable $extractDetailsYearDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:year:> 1997
<:year[4]:> 1997
<:year[2]:> 97

publication

Description: Prints words from the publication field.

Basic syntax: <:publication:>

Options syntax: <:publication[opt1|(opt2)]:>

Notes:

  • Options syntax:
    • opt1: Number of words (i.e., strings delimited by spaces) from the publication field.
      • A positive number ('x') extracts x words from the beginning of the publication string.
      • A negative number ('-x') extracts x words from the end of the publication string.
      • You can specify '0' in order to always print all words from the record's publication name.
      • Leaving the first option empty (as in <:publication[|opt2]:>) causes the raw publication string to be returned without any modification (ignoring opt2).
    • opt2 (optional): String that's used to connect individual words from the publication string. If this option is ommitted, words will be connected without any delimiter.
  • If no options are given, <:publication[3]:> will be used by default, i.e., only the first three words from the publication name will be used.
  • Default options for this placeholder are set by variable $extractDetailsPublicationDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:publication:> JournalofMarine
<:publication[3]:> JournalofMarine
<:publication[2]:> Journalof
<:publication[2|_]:> Journal_of
<:publication[-2|_]:> Marine_Systems
<:publication[0|_]:> Journal_of_Marine_Systems
<:publication[|_]:> Journal of Marine Systems

abbrevJournal

Description: Prints words from the abbrevJournal field.

Basic syntax: <:abbrevJournal:>

Options syntax: <:abbrevJournal[opt1|(opt2)]:>

Notes:

  • Options syntax:
    • opt1: Number of words (i.e., strings delimited by spaces) from the abbrevJournal field.
      • A positive number ('x') extracts x words from the beginning of the abbreviated journal string.
      • A negative number ('-x') extracts x words from the end of the abbreviated journal string.
      • You can specify '0' in order to always print all words from the record's abbreviated journal name.
      • Leaving the first option empty (as in <:abbrevJournal[|opt2]:>) causes the raw abbreviated journal string to be returned without any modification (ignoring opt2).
    • opt2 (optional): String that's used to connect individual words from the abbreviated journal string. If this option is ommitted, words will be connected without any delimiter.
  • If no options are given, <:abbrevJournal[3]:> will be used by default, i.e., only the first three words from the abbreviated journal name will be used.
  • Default options for this placeholder are set by variable $extractDetailsAbbrevJournalDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:abbrevJournal:> JMarSyst
<:abbrevJournal[3]:> JMarSyst
<:abbrevJournal[2]:> JMar
<:abbrevJournal[2|_]:> J_Mar
<:abbrevJournal[-2|_]:> Mar_Syst
<:abbrevJournal[0|_]:> J_Mar_Syst
<:abbrevJournal[|_]:> J Mar Syst

volume

Description: Prints contents from the volume field.

Basic syntax: <:volume:>

Options syntax: (none)

Examples:

Placeholder string Output examples
<:volume:> 44, 56A

issue

Description: Prints contents from the issue field.

Basic syntax: <:issue:>

Options syntax: (none)

Examples:

Placeholder string Output examples
<:issue:> 8, C3, 1-4

pages

Description: Prints contents from the pages field.

Basic syntax: <:pages:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:pages:> 1623-1644

startPage

Description: Prints first number from the pages field.

Basic syntax: <:startPage:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:startPage:> 1623

endPage

Description: Prints last number from the pages field.

Basic syntax: <:endPage:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:endPage:> 1644

keywords

Description:

Basic syntax: <:keywords:>

Options syntax: <:keywords[opt1]:>

Notes:

Examples:

Placeholder string Output example
<:keywords:>

issn

Description: Prints contents from the issn field.

Basic syntax: <:issn:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:issn:> 0967-0645

isbn

Description: Prints contents from the isbn field.

Basic syntax: <:isbn:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:isbn:> 0-632-05808-0

issn_isbn

Description: Prints contents from the issn or isbn field.

Basic syntax: <:issn_isbn:>

Options syntax: (none)

Notes:

  • If both, an ISSN and ISBN number are present, the ISSN number will be preferred.

Examples:

Placeholder string Output example
<:issn_isbn:> 0967-0645
<:issn_isbn:> 0-632-05808-0

area

Description:

Basic syntax: <:area:>

Options syntax: <:area[opt1]:>

Notes:

Examples:

Placeholder string Output example
<:area:>

notes

Description: Prints words from the notes field.

Basic syntax: <:notes:>

Options syntax: <:notes[opt1|(opt2)]:>

Notes:

  • Options syntax:
    • opt1: Number of words (i.e., strings delimited by spaces) from the notes field.
      • A positive number ('x') extracts x words from the beginning of the notes string.
      • A negative number ('-x') extracts x words from the end of the notes string.
      • You can specify '0' in order to always print all words from the record's notes field.
      • Leaving the first option empty (as in <:notes[|opt2]:>) causes the raw notes string to be returned without any modification (ignoring opt2).
    • opt2 (optional): String that's used to connect individual words from the notes string. If this option is ommitted, words will be connected without any delimiter.
  • If no options are given, <:notes[1]:> will be used by default, i.e., only the first word from the notes field will be used.
  • Default options for this placeholder are set by variable $extractDetailsNotesDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:notes:> Summary
<:notes[1]:> Summary
<:notes[2]:> Summaryof
<:notes[2|_]:> Summary_of
<:notes[-2|_]:> dissertation_thesis
<:notes[0|_]:> Summary_of_dissertation_thesis
<:notes[|_]:> Summary of dissertation thesis

userKeys

Description:

Basic syntax: <:userKeys:>

Options syntax: <:userKeys[opt1]:>

Notes:

Examples:

Placeholder string Output example
<:userKeys:>

citeKey

Description: Prints contents from the cite_key field.

Basic syntax: <:citeKey:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:citeKey:> Gosselin_etal1997

doi

Description: Prints contents from the doi field.

Basic syntax: <:doi:>

Options syntax: (none)

Examples:

Placeholder string Output example
<:doi:> 10.1016/S0022-0981(03)00321-6

recordIdentifier

Description: Prints contents from the cite_key or serial field.

Basic syntax: <:recordIdentifier:>

Options syntax: (none)

Notes:

  • If available, the user-specific cite key will be preferred, otherwise the record's serial number will be used as unique record identifier.

Examples:

Placeholder string Output example
<:recordIdentifier:> Gosselin_etal1997
<:recordIdentifier:> 6946

randomNumber

Description: Generates a random number taken from the range given in the options.

Basic syntax: <:randomNumber:>

Options syntax: <:randomNumber[opt1|opt2]:>

Notes:

  • Options syntax:
    • opt1: Number which defines the minimum random number.
    • opt2: Number which defines the maximum random number.
  • You can leave both options empty (as in <:randomNumber[|]:>) to use the maximum possible range.
  • If no options are given, <:randomNumber[0|99999]:> will be used by default, i.e., a random number between 0 and 99999 will be generated.
  • Default options for this placeholder are set by variable $extractDetailsRandomNumberDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:randomNumber:> 12345
<:randomNumber[100|999]:> 456
<:randomNumber[1000|9999]:> 7890
<:randomNumber[|]:> 609299654

Application-specific notes and examples

Directory names

Notes:

  • You can specify a naming scheme for auto-generated sub-directories in variable $dirNamingScheme in ini.inc.php.
  • Use slashes ('/' or '\') to separate between multiple sub-directories.
  • After expansion of placeholders, further string processing may be applied to generate the final directory name. This is controlled by variables in ini.inc.php:
    • Handling of any non-ASCII chars will be controlled by variable $handleNonASCIIChars.
    • Unwanted characters can be excluded with the help of variable $allowedDirNameCharacters.
    • Variable $changeCaseInDirNames controls if (and what) case transformations will be applied to the auto-generated directory names.

Examples:

Placeholder string Output example
<:firstAuthor:>/<:year:> Gosselin/1997
<:abbrevJournal:> JMarSyst

File names

Notes:

  • You can specify how uploaded files will be renamed in variable $fileNamingScheme in ini.inc.php.
  • Existing file extensions will be kept untouched by this naming scheme (i.e., the existing file name extension will be appended to the newly generated file name). However, file uploads will be blocked if the file name ends with .exe, .com, .bat, .zip, .php, .phps, .php3 or .cgi.
  • It is strongly recommended to always include the <:serial:> placeholder in your file naming scheme. This ensures truly unique file names, otherwise you'll risk files already on the server getting overwritten by newly uploaded files (which got assigned the same name).
  • You may want to include the <:randomNumber:> placeholder in your file naming scheme so that auto-generated file names cannot be guessed easily.
  • After expansion of placeholders, further string processing may be applied to generate the final file name. This is controlled by variables in ini.inc.php:
    • Handling of any non-ASCII chars will be controlled by variable $handleNonASCIIChars.
    • Unwanted characters can be excluded with the help of variable $allowedFileNameCharacters.
    • Variable $changeCaseInFileNames controls if (and what) case transformations will be applied to the auto-generated file names.

Examples:

Placeholder string Output example
<:serial:>_<:firstAuthor:><:year:><_:randomNumber:> 6946_Gosselin1997_22460
<:serial:>_<:authors:><:year:> one author: 6946_Gosselin1997, two authors: 6946_Gosselin+Levasseur1997, three or more authors: 6946_Gosselin_etal1997
<:firstAuthor:><_:year:><_:abbrevJournal:><_vol:volume:><_p:startPage:>_<:serial:> Granskog_2005_JMarSyst_vol53_p187_23958

Text citations

Notes:

  • Currently, the following placeholders are not available in text citations:
    • keywords
    • issn
    • area
    • notes
    • userKeys

Examples:

Placeholder string Output example
<:authors[2| & | et al.]:>< :year:>< {:recordIdentifier:}> one author: Gosselin 1997 {Gosselin1997}, two authors: Gosselin & Levasseur 1997 {Gosselin+Levasseur1997}, three or more authors: Gosselin et al. 1997 {Gosselin++1997}
<:authors[2| and | and others]:>< :year:>< {:serial:}> one author: Gosselin 1997 {6946}, two authors: Gosselin and Levasseur 1997 {6946}, three or more authors: Gosselin and others 1997 {6946}

Cite keys

Notes:

  • User-specific options in the refbase web interface allow you to customize the behaviour of cite-key generation on export.
  • The default cite key format used for auto-generation of cite keys can be changed in variable $defaultCiteKeyFormat in ini.inc.php.
  • Handling of any non-ASCII chars will be controlled by variable $handleNonASCIICharsInCiteKeysDefault in ini.inc.php.

Examples:

Placeholder string Output example
<:firstAuthor:><:year:> Gosselin1997
<:authors:><:year:> one author: Gosselin1997, two authors: Gosselin+Levasseur1997, three or more authors: Gosselin_etal1997
<:authors[2|+|++]:><:year:><:title:> one author: Gosselin1997New, two authors: Gosselin+Levasseur1997New, three or more authors: Gosselin++1997New

URLs

Example for an OpenURL resolver (using CrossRef):

http://www.crossref.org/openurl?aulast=<:firstAuthor:>&title=<:publication[|]:>&volume=<:volume:>&issue=<:issue:>&spage=<:startPage:>&date=<:year:>


Example for an ISBN resolver (using isbn.nu):

http://isbn.nu/<:isbn:>