R6 Class representing a LimeSurvey question

R6 Class representing a LimeSurvey question

R6 Class representing a LimeSurvey question

Details

A question has at least a code and a primary language.

The human-readable question types are (with some additional variants also being valid, in any case the literal labels used at https://www.limesurvey.org/manual/Question_object_types#Current_question_types):

  • "array dual scale"

  • "5 point choice"

  • "5 point array"

  • "10 point array"

  • "yes/no/uncertain array"

  • "date"

  • "increase/same/decrease array"

  • "array" (this is the "array (flexible labels)" type)

  • "gender"

  • "array by column"

  • "language switch"

  • "multiple numerical input",

  • "radio" (this is the "list" type)

  • "checkboxes" (this is the "multiple choice" type)

  • "numerical input",

  • "list with comment"

  • "multiple choice with comments"

  • "multiple short text"

  • "ranking"

  • "short text"

  • "long text"

  • "huge text"

  • "text display"

  • "yes/no"

  • "multiple texts array",

  • "multiple dropdown array"

  • "file"

  • "dropdown"

  • "equation".

Public fields

code

The code of the question.

id

The identifier of the question (a unique number in a survey).

gid

The identifier of the group to which this question belongs.

sid

The identifier of the survey to which this question belongs.

type

The question type.

lsType

The question type in LimeSurvey's format.

questionTexts

The question text(s) in all languages.

helpTexts

The question help text(s) in all languages.

relevance

The relevance.

validation

The question's validation.

language

The primary language of the question.

additional_languages

Any additional languages for the title and description elements.

answerOptions

The answer options in the question.

subquestions

The subquestions in the question.

parent_qid

The question identifier of the parent question (or 0).

mandatory

Whether the question is mandatory (Y or N).

other

Whether the question has an 'other' option (Y or N).

otherReplaceTexts

If the question has an 'other' option, its label if the default label should be overwritten (multilingual).

default

The default value.

same_default

Not entirely sure what this does.

array_filter

The question code of the array filter question to apply.

question_order

The question order (starts at 0)

cssclass

The CSS class(es) to apply to this question.

hide_tip

Whether to hide the tip (Y or N).

otherOptions

Any additional options, stored as a named list by assigning as.list(...).

Active bindings

has_subquestions

Whether the question has subquestions.

has_answerOptions

Whether the question has answer options

Methods

Public methods

Method new()

Create a new question object. Most of this text comes directly from the TSV manual page at https://www.limesurvey.org/manual/Tab_Separated_Value_survey_structure, so please see that page for more details.

Usage

Question$new(
  code,
  type = NULL,
  lsType = NULL,
  id = NULL,
  gid = NULL,
  sid = NULL,
  questionTexts = "",
  helpTexts = "",
  relevance = 1,
  validation = "",
  mandatory = "N",
  parent_qid = 0,
  other = "N",
  otherReplaceTexts = "",
  default = "",
  same_default = "0",
  array_filter = "",
  cssclass = "",
  hide_tip = "",
  language = "en",
  additional_languages = "",
  new_id_fun = NULL,
  question_order = 0,
  ...
)

Arguments

code

The question code.

type

The human-readable question type (see details).

lsType

The type as LimeSurvey type ("1"; "5"; "A" to "Y", except "J", "V" and "W"; "!"; ":"; ";"; "*"; or "|" –see https://www.limesurvey.org/manual/Question_object_types#Current_question_types).

id

The identifier of the question (in a survey).

gid

The identifier of the group to which this question belongs.

sid

The identifier of the survey to which this question belongs.

questionTexts

The question text(s).

helpTexts

The help text(s).

relevance

The question's relevance equation.

validation

The question's validation.

mandatory

Whether the question is mandatory (Y or N);.

parent_qid

The question identifier of the parent question (or 0).

other

Whether the question has an 'other' option (Y or N).

otherReplaceTexts

If the question has an 'other' option, its label if the default label should be overwritten (multilingual).

default

The default value.

same_default

Y for true, in which case any default value set for the primary language applies to other languages.

array_filter

The question code of the array filter question to apply.

cssclass

The CSS class(es) to apply to this question.

hide_tip

Whether to hide the tip (Y or N).

language

The question's primary language.

additional_languages

Any additional languages

new_id_fun

A function to set identifiers (for XML exports, which mirrors MySQL tables and so needs identifiers). By default, new question objects receive this function from the group containing them; and groups receive it from the survey containing them. This ensures that identifiers are always unique in a survey (despite question objects not being able to 'see' anything in the group containing them, and group objects not being able to 'see' anything in the survey containing them; because they 'received' this function from the parent object, and it 'bubbles down' through groups to the questions, those functions still get and set a private identifier property in the 'top-most' object).

question_order

The question order (starts at 0)

...

Any additional options, stored as a named list in the otherOptions property by assigning as.list(...).

Returns

A new Question object.

Method add_answer_option()

Add an answer option to a question. Most of this text comes directly from the TSV manual page at https://www.limesurvey.org/manual/Tab_Separated_Value_survey_structure, so please see that page for more details.

Usage

Question$add_answer_option(
  code,
  optionTexts,
  type.scale = 0,
  relevance = "",
  assessment.value = 0,
  sort.order = NULL
)

Arguments

code

The answer option code.

optionTexts

The answer option text(s).

type.scale

0 or 1 (e.g. for dual-scale; 'scale_id').

relevance

The answer option's relevance equation.

assessment.value

If using assessment, this is the assessment value for the answer ('assessment_value').

sort.order

The sort order (to manually specify); starts at 0. If left empty, new options are added at the bottom.

Returns

Invisibly, the question object.

Method add_subquestion()

Add a subquestion to a question. Most of this text comes directly from the TSV manual page at https://www.limesurvey.org/manual/Tab_Separated_Value_survey_structure, so please see that page for more details.

Usage

Question$add_subquestion(
  code,
  subquestionTexts,
  relevance = "",
  helpTexts = NULL,
  type.scale = 0,
  validation = "",
  mandatory = "",
  default = "",
  same_default = "",
  subquestion.order = NULL
)

Arguments

code

The subquestions code.

subquestionTexts

The subquestion text(s).

relevance

When to show this subquestion.

helpTexts

As far as I know not yet implemented in LimeSurvey; but the TSV help page says "(Future) to support subquestion-level help".

type.scale

0 or 1, depending upon question type (e.g. array text will have two scales)0 or 1, depending upon question type (e.g. array text will have two scales)."

validation

As far as I know not yet implemented in LimeSurvey; but the TSV help page says "(Future) to support subquestion-level regular expression validation (e.g. for address parts)"

mandatory

As far as I know not yet implemented in LimeSurvey; but the TSV help page says "(Future) to support subquestion-level mandatory (e.g. make only a few subquestions mandatory)"

default

If set, then this is the default value for the subquestion (inserted into defaultvalues table).

same_default

If set, then the default for the primary language is used for all other languages.

subquestion.order

The subquestion order (to manually specify); starts at 0. If left empty, new options are added at the bottom.

Returns

Invisibly, the question object.

Method xmlExport_row_question()

Export the question in XML format (for lss, lsg, or lsq files).

Usage

Question$xmlExport_row_question(silent = limonaid::opts$get("silent"))

Arguments

silent

Whether to be silent or chatty.

Returns

The produced XML

Method xmlExport_row_subquestions()

Export the question in XML format (for lss, lsg, or lsq files).

Usage

Question$xmlExport_row_subquestions(
  returnRows = FALSE,
  silent = limonaid::opts$get("silent")
)

Arguments

returnRows

Whether to return a list with each row as element, or a rows node (as xml2 object) containing each row as nodes

silent

Whether to be silent or chatty.

Returns

The produced XML

Method xmlExport_row_question_l10ns()

Export the question's question_l10ns info in a list of XML nodes.

Usage

Question$xmlExport_row_question_l10ns(
  id_fun = private$new_id(),
  silent = limonaid::opts$get("silent")
)

Arguments

id_fun

The function to use to produce unique identifiers

silent

Whether to be silent or chatty.

Returns

The produced list of XML nodes

Method xmlExport_row_answers()

Export the answer options in XML format (for lss, lsg, or lsq files).

Usage

Question$xmlExport_row_answers(
  returnRows = FALSE,
  silent = limonaid::opts$get("silent")
)

Arguments

returnRows

Whether to return a list with each row as element, or a rows node (as xml2 object) containing each row as nodes

silent

Whether to be silent or chatty.

Returns

The produced XML

Method xmlExport_row_answer_l10ns()

Export the question's answer optoin l10ns info in a list of XML nodes.

Usage

Question$xmlExport_row_answer_l10ns(
  id_fun = private$new_id,
  silent = limonaid::opts$get("silent")
)

Arguments

id_fun

The function to use to produce unique identifiers

silent

Whether to be silent or chatty.

Returns

The produced list of XML nodes

Method xmlExport_row_attributes()

Export the question's attributes in a list of XML nodes.

Usage

Question$xmlExport_row_attributes(silent = limonaid::opts$get("silent"))

Arguments

silent

Whether to be silent or chatty.

Returns

The produced list of XML nodes

Method clone()

The objects of this class are cloneable with this method.

Usage

Question$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.