Difference between revisions of "Boolean field"

From EPrints Documentation
Jump to: navigation, search
(menu style)
m (Additional Properties)
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
* [[Metadata]]
+
{{fieldtypes}}
** [[Boolean field]]
+
 
  
 
== Description ==
 
== Description ==
 
 
Describes a simple yes/no value. Unless the field has the ''required'' property set, it can actually have a third setting of unset. This can be useful as it distinguishes between a "False" and a "don't know/haven't filled this in yet". For example when asking if a paper is refereed, this is a boolean field. However it's not required as often someone isn't sure, and does not want to click "no" when that's not necessarily true.
 
Describes a simple yes/no value. Unless the field has the ''required'' property set, it can actually have a third setting of unset. This can be useful as it distinguishes between a "False" and a "don't know/haven't filled this in yet". For example when asking if a paper is refereed, this is a boolean field. However it's not required as often someone isn't sure, and does not want to click "no" when that's not necessarily true.
  
== Properties ==
+
== Inheritance ==
 +
* [[Metadata]]
 +
** [[Boolean 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>checkbox</tt> || NO || This controls how the field is rendered in input forms.  May be one of <tt>menu</tt>, <tt>radio</tt> or <tt>checkbox</tt>. ||
 +
|-
 +
| '''input_rows''' || n/a || NO || Number of rows for select box in input form. || Only applicable if <tt>input_style => 'menu'</tt>.  If so, must be configured within field definition.
 +
|-
 +
| '''false_first''' || <tt>0</tt> || NO || Whether the false option should appear before the true option. ||  
 
|-
 
|-
| '''input_style''' || checkbox || May be one of (menu<nowiki>|</nowiki>radio<nowiki>|</nowiki>checkbox). This controls how the field is rendered in input forms.
 
 
"checkbox" gives just a single HTML checkbox which can be ticked or not. It looks a bit rubbish, and does not provide a way to indicate an "unset" value.
 
 
"menu" gives an HTML "select" menu with two or three options. The third is "unspecified" and only available if the field is not a required field.
 
 
"radio" gives an HTML radio buttons interface. It renders an html phrase with the true and false radio buttons placed in the phrase using pins. If the field is not required then a third radio button for "unspecified" appears below this.
 
 
 
|}
 
|}
  
 
== Required Phrases ==
 
== Required Phrases ==
 +
In addition to the [[Metadata#Required_Phrases|standard metadata field phrases]]:
  
 
=== menu style ===
 
=== menu style ===
Line 27: Line 28:
 
If you use input_style=>"menu" then you need two phrases of the type:
 
If you use input_style=>"menu" then you need two phrases of the type:
  
  '''datasetid''' + "_fieldopt_" + '''fieldname''' + "_TRUE"
+
  ''datasetid'' + "_fieldopt_" + ''fieldname'' + "_TRUE"
  '''datasetid''' + "_fieldopt_" + '''fieldname''' + "_FALSE"
+
  ''datasetid'' + "_fieldopt_" + ''fieldname'' + "_FALSE"
  
 
These control the display of the items in the menu.
 
These control the display of the items in the menu.
Line 36: Line 37:
 
     <epp:phrase id="eprint_fieldopt_myboolean_TRUE">Certainly!</epp:phrase>
 
     <epp:phrase id="eprint_fieldopt_myboolean_TRUE">Certainly!</epp:phrase>
 
     <epp:phrase id="eprint_fieldopt_myboolean_FALSE">No way!</epp:phrase>
 
     <epp:phrase id="eprint_fieldopt_myboolean_FALSE">No way!</epp:phrase>
 +
 +
==== optional phrase to replace 'UNSPECIFIED' text ====
 +
To overwrite the default 'UNSPECIFIED' option displayed when a boolean field is not required, a phrase with an underscore at the end can be used:
 +
 +
''datasetid'' + "_fieldopt_" + ''fieldname'' + "_"
 +
 +
Example:
 +
 +
    <epp:phrase id="eprint_fieldopt_myboolean_">Don't know.</epp:phrase>
  
 
=== radio style ===
 
=== radio style ===
Line 41: Line 51:
 
This uses a single phrase with two pins in it to indicate the locations of the radio buttons. The phrase id is:
 
This uses a single phrase with two pins in it to indicate the locations of the radio buttons. The phrase id is:
  
  '''datasetid''' + "_radio_" + '''fieldname'''
+
  ''datasetid'' + "_radio_" + ''fieldname''
  
 
We suggest placing a <label> element around the radio button and it's title - as well as being good practice, this also means that in some browsers clicking on the text will select the button.
 
We suggest placing a <label> element around the radio button and it's title - as well as being good practice, this also means that in some browsers clicking on the text will select the button.
Line 48: Line 58:
  
 
     <epp:phrase id="eprint_radio_myboolean"><label><epc:pin name="true"/>Yes, I like cheese.</label><br/><label><epc:pin name="false"/>No, cheese is bad.</label></epp:phrase>
 
     <epp:phrase id="eprint_radio_myboolean"><label><epc:pin name="true"/>Yes, I like cheese.</label><br/><label><epc:pin name="false"/>No, cheese is bad.</label></epp:phrase>
 +
 +
== Database ==
 +
Boolean fields are stored in the database as
 +
fieldname VARCHAR(5)
 +
 +
== API ==
 +
See [[API:EPrints/MetaField/Boolean|API page]].
 +
 +
In the code these fields are stored as strings containing <tt>TRUE</tt>, <tt>FALSE</tt> or <tt>undef</tt> if they are not set.
 +
 +
== Examples ==
 +
Most basic example.  Display a checkbox as this is the default.
 +
{
 +
    name => "no_request_email_button",
 +
    type => "boolean",
 +
}
 +
Display as radio group of options.  Allows <tt>TRUE</tt>, <tt>FALSE</tt> and <tt>UNSPECIFIED</tt> but phrases uses will determine labelling of options displaye.
 +
{
 +
    name => 'refereed',
 +
    type => 'boolean',
 +
    input_style => 'radio',
 +
},
 +
Display as drop down list of options.  Allows only <tt>TRUE</tt> or <tt>FALSE</tt> as <tt>required</tt> is set to true.
 +
{
 +
    name => 'is_artwork',
 +
    type => 'boolean',
 +
    required => 1,
 +
    input_style => 'menu',
 +
},

Revision as of 20:42, 11 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 - Recaptcha3 - Relation - Search - Secret - Set - Storable - Subject - Subobject - Text - Time - Timestamp - Url - Uuid


Description

Describes a simple yes/no value. Unless the field has the required property set, it can actually have a third setting of unset. This can be useful as it distinguishes between a "False" and a "don't know/haven't filled this in yet". For example when asking if a paper is refereed, this is a boolean field. However it's not required as often someone isn't sure, and does not want to click "no" when that's not necessarily true.

Inheritance

Additional Properties

Name Default Value Required Description Notes
input_style checkbox NO This controls how the field is rendered in input forms. May be one of menu, radio or checkbox.
input_rows n/a NO Number of rows for select box in input form. Only applicable if input_style => 'menu'. If so, must be configured within field definition.
false_first 0 NO Whether the false option should appear before the true option.

Required Phrases

In addition to the standard metadata field phrases:

menu style

If you use input_style=>"menu" then you need two phrases of the type:

datasetid + "_fieldopt_" + fieldname + "_TRUE"
datasetid + "_fieldopt_" + fieldname + "_FALSE"

These control the display of the items in the menu.

Example:

   <epp:phrase id="eprint_fieldopt_myboolean_TRUE">Certainly!</epp:phrase>
   <epp:phrase id="eprint_fieldopt_myboolean_FALSE">No way!</epp:phrase>

optional phrase to replace 'UNSPECIFIED' text

To overwrite the default 'UNSPECIFIED' option displayed when a boolean field is not required, a phrase with an underscore at the end can be used:

datasetid + "_fieldopt_" + fieldname + "_"

Example:

   <epp:phrase id="eprint_fieldopt_myboolean_">Don't know.</epp:phrase>

radio style

This uses a single phrase with two pins in it to indicate the locations of the radio buttons. The phrase id is:

datasetid + "_radio_" + fieldname

We suggest placing a <label> element around the radio button and it's title - as well as being good practice, this also means that in some browsers clicking on the text will select the button.

For example:

   <epp:phrase id="eprint_radio_myboolean"><label><epc:pin name="true"/>Yes, I like cheese.</label>
<label><epc:pin name="false"/>No, cheese is bad.</label></epp:phrase>

Database

Boolean fields are stored in the database as

fieldname VARCHAR(5)

API

See API page.

In the code these fields are stored as strings containing TRUE, FALSE or undef if they are not set.

Examples

Most basic example. Display a checkbox as this is the default.

{ 
   name => "no_request_email_button",
   type => "boolean",
}

Display as radio group of options. Allows TRUE, FALSE and UNSPECIFIED but phrases uses will determine labelling of options displaye.

{
    name => 'refereed',
    type => 'boolean',
    input_style => 'radio',
},

Display as drop down list of options. Allows only TRUE or FALSE as required is set to true.

{ 
    name => 'is_artwork', 
    type => 'boolean', 
    required => 1, 
    input_style => 'menu',
},