Difference between revisions of "Date field"

From EPrints Documentation
Jump to: navigation, search
m (Additional Properties)
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{reference}}
 
 
{{fieldtypes}}
 
{{fieldtypes}}
  
== Inherritance ==
 
 
* [[Metadata]]
 
** [[Date field]]
 
  
 
== Description ==
 
== Description ==
 +
This field is used to store a single date. Internally EPrints always uses ISO standard notation for dates, it avoids confusion. This is <tt>YYYY-MM-DD</tt>.
  
This field is used to store a single date. Internally EPrints always uses ISO standard notation for dates, it avoids confusion. This is YYYY-MM-DD.
+
In bibliographies sometimes exact dates of publication (or other events) are not known. EPrints allows you to store month and year values in date fields. <tt>YYYY</tt> or <tt>YYYY-MM</tt>.
  
In bibliographies sometimes exact dates of publication (or other events) are not known. EPrints allows you to store month and year values in date fields. YYYY or YYYY-MM.
+
In the database EPrints actually uses 3 integer fields to store the date, rather than a built in date field. This is because of the need to allow <tt>NULL</tt> in month and day if the date is just <tt>1998</tt>.
  
In the database EPrints actually uses 3 integer fields to store the date, rather than a built in date field. This is because of the need to allow "NULL" in month and day if the date is just "1998".
+
== Inheritance ==
 
+
* [[Metadata]]
== Properties ==
+
** [[Date field]]
  
 +
== Additional Properties ==
 
{| border="1" cellpadding="3" cellspacing="0"
 
{| border="1" cellpadding="3" cellspacing="0"
| name || default || description
+
! Name !! Default Value !! Required !! Description !! Notes
 +
|-
 +
| '''input_style''' || <tt>long</tt> || NO || Whether to render the date inpit fields using longer or shorter month labels. || Can be <tt>short</tt> or <tt>long</tt>. The former is useful if you have limited width in your input form, especially if you are using a date field in a [[Compound field]].
 
|-
 
|-
| '''min_resolution''' || day || One of day|month|year. If set to "day" then values of YYYY or YYYY-MM will cause a validation error. If set to "month" then values of YYYY will cause a validation error. If set to "year" then day, month or year resolutions are allowed.
+
| '''min_resolution''' || <tt>day</tt> || NO || The minimum resoltion of date that must be entered.  Can be <tt>day</tt>, <tt>month</tt> or <tt>year</tt>. || If set to <tt>day</tt> then values of <tt>YYYY</tt> or <tt>YYYY-MM</tt> will cause a validation error. If set to <tt>month</tt> then values of <tt>YYYY</tt> will cause a validation error. If set to <tt>year</tt> then day, month or year resolutions are allowed.
 
|-
 
|-
| '''render_res''' || day || One of day|month|year. If set to "year" then the dates 1998-10-01, 1998-10 and 1998 would all be rendered as "1998". This is not too useful in configuring the field, but can be set as a print option inside citation files.
+
| '''render_res''' || <tt>day</tt> || NO || The resolution to render the date stored by this field. Can be <tt>day</tt>, <tt>month</tt> or <tt>year</tt>. || If set to <tt>year</tt> then the dates <tt>1998-10-01</tt>, <tt>1998-10</tt> and <tt>1998</tt> would all be rendered as <tt>1998</tt>. This is not too useful in configuring the field, but can be set as a print option inside citation files.
 
|-
 
|-
| '''render_style''' || long || One of short|long. If "long" then you'll see "8 September 1998". If "short" then "08 Sep 1998".
+
| '''render_style''' || <tt>long</tt> || NO || The resolution to render the date stored by this field. Can be <tt>short</tt>, <tt>long</tt> or<tt>dow</tt>. || If <tt>long</tt> then you'll see <tt>8 September 1998</tt>. If <tt>short</tt> then <tt>08 Sep 1998</tt>.  <tt>dow</tt> would render <tt>Tuesday 8 September 1998</tt>.
 
|}
 
|}
  
 +
== Required Phrases ==
 +
No additional phrases beyond the [[Metadata#Required_Phrases|standard metadata field phrases]].
  
== Required Phrases ==
+
== Database ==
 +
Date fields are stored in the database as:
 +
 
 +
fieldname_year SMALLINT(6)
 +
fieldname_month SMALLINT(6)
 +
fieldname_day SMALLINT(6)
 +
 
 +
If a date only has a year value then it would be stored as 1998,NULL,NULL
 +
 
 +
== API ==
 +
See [[API:EPrints/MetaField/Date|API page]].
 +
 
 +
Date values are represented in the API as scalars containing ISO encoded dates. eg.
 +
 
 +
"1976"
 +
"1976-02"
 +
"1976-02-02"
 +
 
 +
=== Searching ===
 +
Date fields can be searched as either single values or ranges. Searching for <tt>2006><tt> will also match <tt>2006-12-25</tt>. You can search for <tt>2000-</tt> to search dates in or after 2000. Or <tt>2000-12-2003-01</tt> for December 2000 through January 2003.
  
None.
+
== Examples ==
 +
Most basic example.
 +
{
 +
    name => 'acceptance_date',
 +
    type => 'date',
 +
}
 +
Set minimum resolution to which the date must be specified is at least a <tt>month</tt>.
 +
{
 +
    name => 'moratorium_date',
 +
    type => 'date',
 +
    min_resolution => 'month',
 +
}
 +
Set resolution to render to the <tt>month</tt>, set rendering style to <tt>short</tt> (e.g. Feb 2023).
 +
{
 +
    name => 'publication_date',
 +
    type => 'date',
 +
    render_res => 'month',
 +
    render_style => short',
 +
}

Latest revision as of 07:15, 25 April 2023

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


Metadata Fields: Arclanguage - Base64 - Bigint - Boolean - Compound - Counter - Dataobjref - Date - Decimal - Email - Fields - Float - Id - Idci - Image - Int - Itemref - Keywords - Langid - Longtext - Longtext_counter - Multilang - Multipart - Name - Namedset - Pagerange - Recaptcha - Relation - Search - Secret - Set - Storable - Subject - Subobject - Text - Time - Timestamp - Url - Uuid


Description

This field is used to store a single date. Internally EPrints always uses ISO standard notation for dates, it avoids confusion. This is YYYY-MM-DD.

In bibliographies sometimes exact dates of publication (or other events) are not known. EPrints allows you to store month and year values in date fields. YYYY or YYYY-MM.

In the database EPrints actually uses 3 integer fields to store the date, rather than a built in date field. This is because of the need to allow NULL in month and day if the date is just 1998.

Inheritance

Additional Properties

Name Default Value Required Description Notes
input_style long NO Whether to render the date inpit fields using longer or shorter month labels. Can be short or long. The former is useful if you have limited width in your input form, especially if you are using a date field in a Compound field.
min_resolution day NO The minimum resoltion of date that must be entered. Can be day, month or year. If set to day then values of YYYY or YYYY-MM will cause a validation error. If set to month then values of YYYY will cause a validation error. If set to year then day, month or year resolutions are allowed.
render_res day NO The resolution to render the date stored by this field. Can be day, month or year. If set to year then the dates 1998-10-01, 1998-10 and 1998 would all be rendered as 1998. This is not too useful in configuring the field, but can be set as a print option inside citation files.
render_style long NO The resolution to render the date stored by this field. Can be short, long ordow. If long then you'll see 8 September 1998. If short then 08 Sep 1998. dow would render Tuesday 8 September 1998.

Required Phrases

No additional phrases beyond the standard metadata field phrases.

Database

Date fields are stored in the database as:

fieldname_year SMALLINT(6)
fieldname_month SMALLINT(6)
fieldname_day SMALLINT(6)

If a date only has a year value then it would be stored as 1998,NULL,NULL

API

See API page.

Date values are represented in the API as scalars containing ISO encoded dates. eg.

"1976"
"1976-02"
"1976-02-02"

Searching

Date fields can be searched as either single values or ranges. Searching for 2006> will also match 2006-12-25. You can search for 2000- to search dates in or after 2000. Or 2000-12-2003-01 for December 2000 through January 2003.

Examples

Most basic example.

{
    name => 'acceptance_date',
    type => 'date',
}

Set minimum resolution to which the date must be specified is at least a month.

{
    name => 'moratorium_date',
    type => 'date',
    min_resolution => 'month',
}

Set resolution to render to the month, set rendering style to short (e.g. Feb 2023).

{
   name => 'publication_date', 
   type => 'date', 
   render_res => 'month', 
   render_style => short',
}