Wrappers for question types

Modified

2024-10-21

`survey()`

Create a survey object.

Signature

survey(
    *pages: PageModel | list[PageModel],
    createStructure: bool = True,
    buildForPublication: bool = False,
    folderName: str = 'survey',
    path: str | pathlib.Path = '/home/jakub/Pulpit/git-repos/VelesResearch',
    addScoreToResults: bool = True,
    allowCompleteSurveyAutomatic: bool = True,
    allowResizeComment: bool = True,
    autoGrowComment: bool = False,
    backgroundImage: str | None = None,
    backgroundOpacity: int = 1,
    calculatedValues: list[dict] | None = None,
    checkErrorsMode: str = 'onNextPage',
    commentAreaRows: int = 2,
    completedBeforeHtml: str | None = None,
    completedHtml: str | None = None,
    completedHtmlOnCondition: list[dict] | None = None,
    completeText: str | None = None,
    cookieName: str | None = None,
    editText: str | None = None,
    firstPageIsStarted: bool | None = None,
    focusFirstQuestionAutomatic: bool = False,
    focusOnFirstError: bool = True,
    goNextPageAutomatic: bool = False,
    locale: str = 'en',
    logo: str | None = None,
    logoFit: str = 'contain',
    logoHeight: str = '200px',
    logoPosition: str = 'left',
    logoWidth: str = '300px',
    matrixDragHandleArea: str = 'entireItem',
    maxOthersLength: int = 0,
    maxTextLength: int = 0,
    maxTimeToFinish: int | None = None,
    maxTimeToFinishPage: int | None = None,
    mode: str = 'edit',
    navigateToUrl: str | None = None,
    navigateToUrlOnCondition: list[dict] | None = None,
    numberOfGroups: int = 1,
    pageNextText: str | None = None,
    pagePrevText: str | None = None,
    previewText: str | None = None,
    progressBarInheritWidthFrom: str = 'container',
    progressBarShowPageNumbers: bool = False,
    progressBarShowPageTitles: bool = False,
    progressBarType: str = 'pages',
    questionDescriptionLocation: str = 'underTitle',
    questionErrorLocation: str = 'top',
    questionsOnPageMode: str = 'standard',
    questionsOrder: str = 'initial',
    questionStartIndex: int | str | None = None,
    questionTitleLocation: str = 'top',
    questionTitlePattern: str = 'numTitleRequire',
    requiredText: str = '*',
    scoresSuffix: str = '_score',
    showCompletedPage: bool = True,
    showNavigationButtons: str = 'bottom',
    showPageNumbers: bool | None = None,
    showPageTitles: bool = True,
    showPrevButton: bool = True,
    showPreviewBeforeComplete: str = 'noPreview',
    showProgressBar: str = 'off',
    showQuestionNumbers: bool | str = True,
    showTimerPanel: str = 'none',
    showTimerPanelMode: str = 'all',
    showTitle: bool = True,
    showTOC: bool = False,
    startSurveyText: str | None = None,
    storeOthersAsComment: bool = True,
    textUpdateMode: str = 'onBlur',
    title: str | None = None,
    tocLocation: str = 'left',
    triggers: list[dict] | None = None,
    validateVisitedEmptyFields: bool = False,
    width: str | None = None,
    widthMode: str = 'auto',
    addCode: dict | None = None,
    **kwargs
) -> SurveyModel

Arguments

addScoreToResults : bool
Whether to add the scores of the questions with correctAnswer to the results data. See scoresSuffix.

allowCompleteSurveyAutomatic : bool
Whether the survey should complete automatically after all questions on the last page had been answered. Works only if goNextPageAutomatic=True. Default is True.

allowResizeComment : bool
Whether to allow resizing the long questions input area. Default is True. Can be overridden for individual questions.

autoGrowComment : bool
Whether to automatically grow the long questions input area. Default is False. Can be overridden for individual questions.

backgroundImage : str | None
URL or base64 of the background image.

backgroundOpacity : int
The opacity of the background image. 0 is transparent, 1 is opaque.

calculatedValues : list[dict] | None
The calculated values for the survey. List of dictionaries with keys name, expression and optionally includeIntoResult (bool) to save the value in the db.

checkErrorsMode : str
The mode of checking errors. Can be ‘onNextPage’, ‘onValueChanged’, ‘onComplete’.

commentAreaRows : int
The number of rows for the comment area of the questions with showCommentArea or showOtherItem set to True. Default is 2. Can be overridden for individual questions.

completedBeforeHtml : str | None
HTML content to show if the survey had been completed before. Use with cookieName.

completedHtml : str | None
HTML content to show after the survey is completed.

completedHtmlOnCondition : list[dict] | None
HTML content to show after the survey is completed if the condition is met. List of dictionaries with keys expression and html keys.

completeText : str | None
Text for the ‘Complete’ button.

cookieName : str | None
The name of the cookie to store the information about the survey having been completed. See completedBeforeHtml.

editText : str | None
Text for the ‘Edit’ button if showPreviewBeforeComplete=True.

firstPageIsStarted : bool | None
Whether the first page is a start page. Default is False.

focusFirstQuestionAutomatic : bool
Whether to focus the first question automatically. Default is False.

focusOnFirstError : bool
Whether to focus on the first error if it was raised. Default is True.

goNextPageAutomatic : bool
Whether to go to the next page automatically after all questions had been answered. Default is False.

locale : str
The locale of the survey. Default is ‘en’.

logo : str | None
URL or base64 of the logo image.

logoFit : str
The object-fit CSS property logo image. Can be ‘contain’, ‘cover’, ‘fill’, ‘none’.

logoHeight : str
The height of the logo image in CSS units. Default is ‘200px’.

logoPosition : str
The position of the logo image. Can be ‘left’, ‘right’, ‘none’.

logoWidth : str
The width of the logo image in CSS units. Default is ‘300px’.

matrixDragHandleArea : str
The part of an item with which the users can drag and drop in dynamic matrix questions. Can be ‘entireItem’ (default), ‘icon’ (drag icon only).

maxOthersLength : int
The maximum length of the comment area in the questions with showOtherItem or showCommentArea set to True. Default is 0 (no limit).

maxTextLength : int
The maximum length of the text in the textual questions. Default is 0 (no limit).

maxTimeToFinish : int | None
Maximum time in seconds to finish the survey.

maxTimeToFinishPage : int | None
Maximum time in seconds to finish the page. 0 means no limit.

mode : str
The mode of the survey. Can be ‘edit’ (can be filled), ‘display’ (read-only).

navigateToUrl : str | None
URL to navigate to after the survey is completed.

navigateToUrlOnCondition : list[dict] | None
URL to navigate to after the survey is completed if the condition is met. List of dictionaries with keys expression and url keys.

pageNextText : str | None
Text for the ‘Next’ button.

pagePrevText : str | None
Text for the ‘Previous’ button.

previewText : str | None
Text for the ‘Preview’ button if showPreviewBeforeComplete=True.

progressBarInheritWidthFrom : str
The element from which the progress bar should inherit the width. Can be ‘container’, ‘survey’.

progressBarShowPageNumbers : bool
Whether to show the page numbers on the progress bar. Only if progressBarType="pages". Default is False. See showProgressBar.

progressBarShowPageTitles : bool
Whether to show the page titles on the progress bar. Only if progressBarType="pages". Default is False. See showProgressBar.

progressBarType : str
The type of the progress bar. Can be ‘pages’ (default), ‘questions’, ‘requiredQuestions’, ‘correctQuestions’.

questionDescriptionLocation : str
The location of the description for the questions. Can be ‘underTitle’ (default), ‘underInput’. Can be overridden for individual questions.

questionErrorLocation : str
The location of the error text for the questions. Can be ‘top’ (default), ‘bottom’. Can be overridden for individual questions.

questionsOnPageMode : str
The mode of the questions on the page. Can be ‘standard’ (default; use structure in JSON), ‘singlePage’ (combine all questions into a single page), ‘questionPerPage’ (move all questions to separate pages).

questionsOrder : str
The order of the questions. Can be ‘initial’ (default), ‘random’. Can be overridden for individual pages.

questionStartIndex : int | str | None
The number or letter with which the questions numbering should start.

questionTitleLocation : str
The location of the title for the questions. Can be ‘top’ (default), ‘bottom’, ‘left’. Can be overridden for individual questions or pages.

questionTitlePattern : str
The pattern of the question title. See https://surveyjs.io/form-library/documentation/design-survey/configure-question-titles#title-pattern.

requiredText : str
The text denoting the required questions. Default is ’*’.

scoresSuffix : str
The suffix of the score column if addScoreToResults=True. Default is ’_score’.

showCompletedPage : bool
Whether to show the completed page. Default is True.

showNavigationButtons : str
The location of the navigation buttons. Can be ‘bottom’ (default), ‘top’, ‘both’, ‘none’.

showPageNumbers : bool | None
Whether to show the page numbers in the pages’ titles.

showPageTitles : bool
Whether to show the page titles. Default is True.

showPrevButton : bool
Whether to show the ‘Previous’ button. Default is True.

showPreviewBeforeComplete : str
Whether to preview all answers before completion. Can be ‘noPreview’ (default), ‘showAllQuestions’, ‘showAnsweredQuestions’.

showProgressBar : str
Whether to show the progress bar. Can be ‘off’ (default), ‘aboveHeader’, ‘belowHeader’, ‘bottom’, ‘topBottom’, ‘auto’.

showQuestionNumbers : bool | str
Whether to show the question numbers. Default is True. Can be True, ‘on’, False, ‘off’, ‘onpage’ (number each page anew).

showTimerPanel : str
Whether to show the timer panel. Can be ‘none’ (default), ‘top’, ‘bottom’. See maxTimeToFinish, maxTimeToFinishPage, and showTimerPanelMode.

showTimerPanelMode : str
What times to show on the timer panel. Can be ‘all’ (default), ‘page’, ‘survey’. See showTimerPanel.

showTitle : bool
Whether to show the survey title. Default is True.

showTOC : bool
Whether to show the table of contents. Default is False. See tocLocation.

startSurveyText : str | None
Text for the ‘Start’ button if firstPageIsStarted=True.

storeOthersAsComment : bool
Whether to store the ‘Other’ answers in a separate column (True; see commentSuffix) or in the question column (False). Default is True.

textUpdateMode : str
The mode of updating the text. Can be ‘onBlur’ (default; update after the field had been unclicked), ‘onTyping’ (update every key press). Can be overridden for individual questions.

title : str | None
The title of the survey.

tocLocation : str
The location of the table of contents. Can be ‘left’ (default), ‘right’. See showTOC.

triggers : str | None
Triggers for the survey. Usually not necessary. See https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers.

validateVisitedEmptyFields : bool
Whether to validate empty fields that had been clicked, and unclicked empty. Default is False.

width : str | None
Width of the survey in CSS units. Default is None (inherit from the container).

widthMode : str
The mode of the width. Can be ‘auto’ (default; the width is set by the content), ‘static’, ‘responsive’.

addCode : dict | None
Additional code for the survey. Usually not necessary.

customCode : str | None
Custom JS commands to be added to the survey.

customFunctions : str | None
Custom JS functions definitions to be added to the survey. To be used with customCode.

`page()`

Create a page object.

Signature

page(
    name: str,
    *questions: QuestionModel | list[QuestionModel],
    description: str | None = None,
    enableIf: str | None = None,
    id: str | None = None,
    isRequired: bool = False,
    maxTimeToFinish: int | None = None,
    maxWidth: str = '100%',
    minWidth: str = '300px',
    navigationButtonsVisibility: str = 'inherit',
    navigationDescription: str | None = None,
    navigationTitle: str | None = None,
    questionErrorLocation: str = 'default',
    questionTitleLocation: str = 'default',
    questionsOrder: str = 'default',
    readOnly: bool = False,
    requiredErrorText: str | None = None,
    requiredIf: str | None = None,
    state: str = 'default',
    title: str | None = None,
    visible: bool = True,
    visibleIf: str | None = None,
    visibleIndex: int | None = None,
    addCode: dict | None = None,
    **kwargs
) -> PageModel

Arguments

questions : QuestionModel | list[QuestionModel]
The questions on the page.

description : str | None
Optional subtitle or description of the page.

enableIf : str | None
Expression to enable the page.

id : str | None
HTML id attribute for the page. Usually not necessary.

isRequired : bool
Whether the page is required (at least one question must be answered).

maxTimeToFinish : int | None
Maximum time in seconds to finish the page.

maxWidth : str
Maximum width of the page in CSS units.

minWidth : str
Minimum width of the page in CSS units.

navigationButtonsVisibility : str
The visibility of the navigation buttons. Can be ‘inherit’, ‘show’, ‘hide’.

navigationDescription : str | None
Description for the page navigation.

navigationTitle : str | None
Title for the page navigation.

questionErrorLocation : str
The location of the error text for the questions. Can be ‘default’, ‘top’, ‘bottom’.

questionTitleLocation : str
The location of the title for the questions. Can be ‘default’, ‘top’, ‘bottom’.

questionsOrder : str
The order of the questions. Can be ‘default’, ‘random’.

readOnly : bool
Whether the page is read-only.

requiredErrorText : str | None
Error text if the required condition is not met.

requiredIf : str | None
Expression to make the page required (at least one question must be answered).

state : str
If the page should be collapsed or expanded. Can be ‘default’, ‘collapsed’, ‘expanded’.

title : str
The visible title of the page.

visible : bool
Whether the page is visible.

visibleIf : str | None
Expression to make the page visible.

visibleIndex : int | None
The index at which the page should be visible.

width : str
Width of the page

addCode : dict | None
Additional code for the survey. Usually not necessary.

customCode : str | None
Custom JS commands to be added to the survey.

customFunctions : str | None
Custom JS functions definitions to be added to the survey. To be used with customCode.

`panel()`

Create a panel.

Signature

panel(
    name: str,
    *questions: QuestionModel | list[QuestionModel],
    description: str | None = None,
    enableIf: str | None = None,
    id: str | None = None,
    innerIndent: int | None = None,
    isRequired: bool = False,
    maxWidth: str = '100%',
    minWidth: str = '300px',
    questionErrorLocation: str = 'default',
    questionsOrder: str = 'default',
    questionStartIndex: str | None = None,
    questionTitleLocation: str = 'default',
    questionTitleWidth: str | None = None,
    readOnly: bool = False,
    requiredErrorText: str | None = None,
    requiredIf: str | None = None,
    rightIndent: int | None = None,
    showNumber: bool = False,
    showQuestionNumbers: str = 'default',
    startWithNewLine: bool = True,
    visible: bool = True,
    visibleIf: str | None = None,
    width: str = '',
    **kwargs
) -> PanelModel

Arguments

questions : QuestionModel | list[QuestionModel]
The questions on the panel.

description : str | None
Optional subtitle or description of the panel.

enableIf : str | None
Expression to enable the panel.

id : str | None
HTML id attribute for the panel. Usually not necessary.

innerIndent : int | None
The inner indent of the panel.

isRequired : bool
Whether the panel is required (at least one question must be answered).

maxWidth : str
Maximum width of the panel in CSS units.

minWidth : str
Minimum width of the panel in CSS units.

questionErrorLocation : str
The location of the error text for the questions. Can be ‘default’, ‘top’, ‘bottom’.

questionsOrder : str
The order of the questions. Can be ‘default’, ‘random’.

questionStartIndex : str | None
The number or letter with which the questions numbering should start.

questionTitleLocation : str
The location of the title for the questions. Can be ‘default’, ‘top’, ‘bottom’.

questionTitleWidth : str | None
The width of the question title.

readOnly : bool
Whether the panel is read-only.

requiredErrorText : str | None
Error text if the required condition is not met.

requiredIf : str | None
Expression to make the panel required (at least one question must be answered).

rightIndent : int | None
The right indent of the panel.

showNumber : bool
Whether to show the panel number.

showQuestionNumbers : str
Whether to show the question numbers. Can be ‘default’, ‘on’, ‘off’, ‘onpage’ (number each page anew).

startWithNewLine : bool
Whether to start the panel on a new line.

visible : bool
Whether the panel is visible.

visibleIf : str | None
Expression to make the panel visible.

width : str
Width of the panel.

`dropdown()`

Create a single-select dropdown question object.

Signature

dropdown(
    name: str,
    title: str | list[str] | None,
    *choices: str | dict | list,
    titleLocation: str = 'default',
    description: str | None = None,
    descriptionLocation: str = 'default',
    isRequired: bool = False,
    readOnly: bool = False,
    visible: bool = True,
    requiredIf: str | None = None,
    enableIf: str | None = None,
    visibleIf: str | None = None,
    validators: velesresearch.helperModels.ValidatorModel | list[velesresearch.helperModels.ValidatorModel] | None = None,
    showOtherItem: bool = False,
    showCommentArea: bool = False,
    commentPlaceholder: str | None = None,
    commentText: str | None = None,
    correctAnswer: str | None = None,
    defaultValue: str | None = None,
    defaultValueExpression: str | None = None,
    requiredErrorText: str | None = None,
    errorLocation: str = 'default',
    hideNumber: bool = False,
    id: str | None = None,
    maxWidth: str = '100%',
    minWidth: str = '300px',
    resetValueIf: str | None = None,
    setValueIf: str | None = None,
    setValueExpression: str | None = None,
    startWithNewLine: bool = True,
    state: str = 'default',
    useDisplayValuesInDynamicTexts: bool = True,
    width: str = '',
    addCode: dict | None = None,
    choicesFromQuestion: str | None = None,
    choicesFromQuestionMode: str = 'all',
    choicesOrder: str = 'none',
    showDontKnowItem: bool = False,
    dontKnowText: str | None = None,
    hideIfChoicesEmpty: bool | None = None,
    showNoneItem: bool = False,
    noneText: str | None = None,
    otherText: str | None = None,
    otherErrorText: str | None = None,
    showRefuseItem: bool = False,
    refuseText: str | None = None,
    choicesMax: int | None = None,
    choicesMin: int | None = None,
    choicesStep: int | None = None,
    placeholder: str | None = None,
    **kwargs
) -> QuestionDropdownModel | list[QuestionDropdownModel]

Arguments

title : str | None
The visible title of the question. If None, name is used.

choices : str | dict | list
The choices for the question. Can be string(s) or dictionary(-ies) with structure {"value": ..., "text": ...}. You can also add visibleIf, enableIf, and requiredIf to the dictionary.

choicesFromQuestion : str | None
The name of the question to get the choices from if the are to be copied. Use with choicesFromQuestionMode.

choicesFromQuestionMode : str
The mode of copying choices. Can be ‘all’, ‘selected’, ‘unselected’.

choicesMax : int | None
Maximum for automatically generated choices. Use with choicesMin and choicesStep.

choicesMin : int | None
Minimum for automatically generated choices. Use with choicesMax and choicesStep.

choicesOrder : str
The order of the choices. Can be ‘none’, ‘asc’, ‘desc’, ‘random’.

choicesStep : int | None
Step for automatically generated choices. Use with choicesMax and choicesMin.

commentPlaceholder : str | None
Placeholder text for the comment area.

commentText : str | None
Text for the comment area.

correctAnswer : str | None
Correct answer for the question. Use for quizzes.

defaultValue : str | None
Default value for the question.

defaultValueExpression : str | None
Expression deciding the default value for the question.

description : str | None
Optional subtitle or description of the question.

descriptionLocation : str
The location of the description. Can be ‘default’, ‘underTitle’, ‘underInput’.

dontKnowText: str | None = None

enableIf : str | None
Expression to enable the question.

errorLocation : str | None
Location of the error text. Can be ‘default’ ‘top’, ‘bottom’.

hideIfChoicesEmpty: bool | None = None

hideNumber : bool
Whether to hide the question number.

id : str | None
HTML id attribute for the question. Usually not necessary.

maxWidth : str
Maximum width of the question in CSS units.

minWidth : str
Minimum width of the question in CSS units.

noneText: str | None = None

otherErrorText: str | None = None

otherText: str | None = None

placeholder : str | None
Placeholder text.

readOnly : bool
Whether the question is read-only.

refuseText: str | None = None

isRequired : bool
Whether the question is required.

requiredErrorText : str | None
Error text if the required condition is not met.

requiredIf : str | None
Expression to make the question required.

resetValueIf : str | None
Expression to reset the value of the question.

setValueExpression : str | None
Expression to decide on the value of the question to be set. Requires setValueIf.

setValueIf : str | None
Expression with a condition to set the value of the question. Requires setValueExpression.

showCommentArea : bool
Whether to show the comment area. Doesn’t work with showOtherItem.

showDontKnowItem: bool = False

showNoneItem: bool = False

showOtherItem : bool
Whether to show the ‘Other’ item. Doesn’t work with showCommentArea.

showOtherItem: bool = False

showRefuseItem: bool = False

startWithNewLine : bool
Whether to start the question on a new line.

state : str | None
If the question should be collapsed or expanded. Can be ‘default’, ‘collapsed’, ‘expanded’.

titleLocation : str
The location of the title. Can be ‘default’, ‘top’, ‘bottom’, ‘left’, ‘hidden’.

useDisplayValuesInDynamicTexts : bool
Whether to use display names for question values in placeholders.

validators : ValidatorModel | list[ValidatorModel] | None
Validator(s) for the question.

visible : bool
Whether the question is visible.

visibleIf : str | None
Expression to make the question visible.

width : str
Width of the question in CSS units.

addCode : dict | None
Additional code for the question. Usually not necessary.

customCode : str | None
Custom JS commands to be added to the survey.

customFunctions : str | None
Custom JS functions definitions to be added to the survey. To be used with customCode.

`text()`

Create a text question object.

Signature

text(
    name: str,
    *title: str | list[str] | None,
    titleLocation: str = 'default',
    description: str | None = None,
    descriptionLocation: str = 'default',
    isRequired: bool = False,
    readOnly: bool = False,
    visible: bool = True,
    requiredIf: str | None = None,
    enableIf: str | None = None,
    visibleIf: str | None = None,
    validators: velesresearch.helperModels.ValidatorModel | list[velesresearch.helperModels.ValidatorModel] | None = None,
    showOtherItem: bool = False,
    showCommentArea: bool = False,
    commentPlaceholder: str | None = None,
    commentText: str | None = None,
    correctAnswer: str | None = None,
    defaultValue: str | None = None,
    defaultValueExpression: str | None = None,
    requiredErrorText: str | None = None,
    errorLocation: str = 'default',
    hideNumber: bool = False,
    id: str | None = None,
    maxWidth: str = '100%',
    minWidth: str = '300px',
    resetValueIf: str | None = None,
    setValueIf: str | None = None,
    setValueExpression: str | None = None,
    startWithNewLine: bool = True,
    state: str = 'default',
    useDisplayValuesInDynamicTexts: bool = True,
    width: str = '',
    addCode: dict | None = None,
    autocomplete: str | None = None,
    inputType: str = 'text',
    max: str | int | None = None,
    maxErrorText: str | None = None,
    maxLength: int | None = None,
    maxValueExpression: str | None = None,
    min: str | int | None = None,
    minErrorText: str | None = None,
    minValueExpression: str | None = None,
    placeholder: str | None = None,
    size: int | None = None,
    step: str | None = None,
    textUpdateMode: str = 'default',
    **kwargs
) -> QuestionTextModel

Arguments

title : str | None
The visible title of the question. If None, name is used.

autocomplete : str | None
A value of autocomplete attribute for <input>. See MDN for a list: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#token_list_tokens.