Marketplace API References - Form Element

Reference of all API calls available. Consult also the concepts documentation and the Swagger documentation available for the interactive version of the API.

Presenting the customer’s data to the clickworker requires a visual representation. Customers can control the output and apply rules to the input using a “Form.” A Form is a container element living inside a Task Template or a Job (see section Form Element - Options and Job). It defines Form Elements, which are used for rendering data or input fields in various formats, like HTML.

Every Form Element has a type. Currently, the following types are available:

Single Line Text (type marker “text_field”)
Multi-Line Text (type marker “text_area”)
Numeric (type marker “number”)
Date (type marker “date”)
Multi media (type marker “media”)
Keyword (type marker “keyword”)
URL (type marker “url”)
E-Mail Address (type marker “email”)
Selection from a definable list of options in several visual representations
- Dropdownbox(typemarker“drop_box”)
- Listboxwithmultipleselection(typemarker“multi_select”)
- Groupofcheckboxes(typemarker“check_box”)
- Groupofradiobuttons(typemarker“radio_button”)

Please note: Forms are presented in the clickworker’s own language, if available. At the very least, customers must provide an English version of attributes like title and help.

Attributes

Name	Type	Access	Description
type	String	r/c	An indicator for the elements type. Supported values are: text_field text_area number keyword url email select
code	String	r/-	The element’s symbolic name. Used to identify the element in certain situations.
titles	Localized String	r/w	The Form Element’s title, as presented to the clickworker.
descriptions	Localized Text	r/-
is_output	Boolean	r/w	If set to <true>, the element will be used to output task data, if set to <false> it will store the received data to the Task.
is_madatory	Boolean	r/w	The Form Element’s “mandatory” indicator. This attribute must be set to <true> if the clickworker is required to enter a value for this element.
item_code	String	r/w	Allows the Task’s data to be referenced by this element. If the element has set the “is_output” attribute to <true>, the data to display is fetched from the given column. If it’s set to <false>, the column is populated by the element’s value
options	object	r/w	Options to configure the Form Element, depending on its type. Every option has two attributes: The option’s code (opt_code) The option’s value (opt_value)

As stated above, every Form Element supports a set of options based on its type. The following sections list the available options for each type.

Representation

XML Representation (Single Instance)

<elements>
  <type>$<text_field|text_area|number|keyword|email|url|select></type>
  <titles> 
    <$<en|fr|de>>${title}</$<en|fr|de>>
  </titles> 
  <descriptions>
    <$<en|fr|de>>${description}</$<en|fr|de>> 
  </descriptions> 
  <item_code>${item_code}</item_code> 
  <is_output>${is_output}</is_output> 
  <is_mandatory>${is_mandatory}</is_mandatory> 
  <options>
    <code>${opt_code}”></code>
    <value><![CDATA[${opt_value}]]></value> 
  </options>
</elements>

JSON Representation (Single Instance)

{ 
  type:
  “$<text_field|text_area|number|keyword|email|url|select>”, 
  titles: {
    “$<en|fr|de>”: “${title}” 
  },
  descriptions: {
  “$<en|fr|de>”: “${description}”
  },
  item_code: “${item_code}”, 
  is_output: ${is_output}, 
  is_mandatory: ${is_mandatory}, 
  options: [{
    code: “${opt_code}”,
    value: ${opt_value} 
  }]
}

Options

Single Line Text (“text_field”) Options

Code	Value	Description	Required
is_madatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
min_length	Integer	Minimum input length in characters	No
max_length	Integer	Maximum input length in characters	No

Multi Line Text (“text_area”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
min_length	Integer	Minimum input length in characters	No
max_length	Integer	Maximum input length in characters	No
is_richtext	Boolean	Defines, whether this field supports HTML rich text. The default is “false”	No

Numeric (“number”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
min_value	Integer	The minimum value allowed	No
max_value	Integer	The maximum value allowed	No

Date (“date”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
min_date	Date	Defines the earliest date that can be entered by the clickworker	No
max_date	Date	Defines the latest date that can be entered by the clickworker	No

Multi media (“media”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
media_player	String	Defines which media player should be used (at this time only “flowplayer” is supported)	No

Keyword (“keyword”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
min_occurence_ref	String	The minimum keyword occurrence count is not set directly, but is instead read from the Task’s data. This option defines the Task’s data item code to read from.	No
max_occurence_ref	String	The maximum keyword occurrence count is not set directly, but is instead read from the Task’s data. This option defines the Task’s data item code to read from.	No
reference_code	String	Defines the Task’s data item where keywords are expected and will be counted. Enter the code of a data item here to check for keywords only in this item. Otherwise, leave blank or use the special value “:all” to scan for keywords in all suitable fields	No
density_unit	"percent" or "absolute"	Defines how the min/max occurrence values will be interpreted: Using “percent” will interpret the value as a percent value. To use “5” as an example, the given keywords must make up 5% of the entire input Using “absolute” will interpret the value as a fixed quantity. With an example of “5,” the given keywords must occur 5 times in all scanned input fields.	No

E-Mail(“email”) options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes

URL(“url) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
with_protocol	Boolean	Defines whether the user has to enter the No protocol prefix (e.g. http://)	No

Select (“drop_box”, “multi_select”, “check_box” and “radio_button”) Options

Code	Value	Description	Required
is_mandatory	Boolean	Defines whether this field must be filled out by the clickworker. The default is “false”	Yes
alternatives	List	List of alternatives to pick from. Every alternative has two attributes: The localized title The alternatives value that will be used when setting the Form Element’s value	Yes, at least two alternatives must be given

XML Example

<elements> 
  <type>drop_box</type> 
  <titles>
    <en>Please choose</en> 
    <de>Bitte wählen Sie</de>
  </titles> 
  <item_code>selected_language</item_code> 
  <options>
    <code>alternatives</code> 
    <value>
      <titles> 
        <en>German</en> 
        <de>Deutsch</de>
      </titles>
      <value>de</value> 
    </value>
    <value> 
      <titles>
        en>French</en>
        <de>Französisch</de> 
        </titles> 
      <value>fr</value>
    </value> 
  </options> 
</elements>

JSON Example

{
  type: “drop_box”,
  title: “Please select a language”, 
  item_code: “selected_language”, 
  options: [{
    code: “alternatives”, 
    value: [{
      titles: {
        en: “German”,
        de: “Deutsch” 
      },
      value: “de” 
    },{
      titles: {
        en: “French”,
        de: “Französisch”
      },
      value: “fr” 
    }]
  }] 
}

Tags: