.. include:: ../../global.rst


Survey
####################################################################################################

This custom control shows a survey given a properly formatted data source.
A survey consists of one or more sections.
Each section consists of one or more questions.
A question has a certain input type.
Questions can be invisible until a specified condition is fulfilled, e.g. a value in a previous question must be larger than a certain amount.

Properties
****************************************************************************************************

Details
====================================================================================================
*	**Name**, the name of the control.

General
====================================================================================================
*   :strike:`Width`, the width of the control.
*	**Visible**, whether the control is shown.
*	**Enabled**, whether the control is enabled.

|br|

.. _Events:

Events
====================================================================================================

.. _DataSource Value:

*   **DataSource Value**, the survey item's value since the last `OnAnswerChanged`_, `OnAnswerRemarkChanged`_ or `OnCustomButtonClicked`_ event triggered.

.. _Answer:

*   **Answer**, the entered answer for the survey item since the last `OnAnswerChanged`_ event triggered.

.. _Answer Remark:

*   **Answer Remark**, the entered answer remark for the survey item since the last `OnAnswerRemarkChanged`_ event triggered.

.. _Button Name:

*   **Button Name**, the name of the button that the user clicked on for the survey item since the last `OnCustomButtonClicked`_ event triggered.

.. _Question:

*   **Question**, the question text from the survey item since the last event triggered.

.. _Question ID:

*   **Question ID**, the question ID from the survey item since the last event triggered.

.. _Question Mandatory:

*   **Question Mandatory**, whether the question from the survey item since the last event triggered is mandatory or not.

.. _DataType:

*   **DataType**, the datatype from the survey item since the last event triggered.

.. _Attachment ID:

*   **Attachment ID**, the ID from the attachment on a survey item since the last attachment event. This property will be cleared if a non-attachment event is triggered. 

.. _Attachment Index:

*   **Attachment Index**,  the index from the attachment on a survey item since the last attachment event. This property will be cleared if a non-attachment event is triggered. 

.. _Attachment Remark:

*   **Attachment Remark**,  the remark on the attachment on a survey item since the last attachment event. This property will be cleared if a non-attachment event is triggered. 

.. _Attachment Count:

*   **Attachment Count**, the amount of attachments on a survey item since the last event triggered.

.. _Highest Attachment Index:

*   **Highest Attachment Index**, the highest index from all attachments on a survey item since the last event triggered. This will be set to -1 if no attachments are present.

|br|

Data Source
====================================================================================================

.. _SmartObject:

*   **SmartObject**, the smartobject that will be used when the populate method is executed for this control. 

.. _Method:

*   **Method**,  the smartobject method that will be used when the populate method is executed for this control.

.. _Value:

*   **Value**, the value reported in events when the user interacts with a survey item. 

.. _Item Answer:

*   **Item Answer**, the survey item's answer entered by the user.

.. _Item Answer Watermark:

*   **Item Answer Watermark**, the text displayed when no answer is set (see `Item Answer`_).

.. _Item Answer Remark:

*   **Item Answer Remark**, the survey item's answer remark entered by the user.

.. _Item Answer Remark Watermark:

*   **Item Answer Remark Watermark**, the text displayed when no answer remark is set (see `Item Answer Remark`_).

.. _Item Condition Value:

*   **Item Condition Value**, the value that will be the right side of the cisibility condition (to be used in conjunction with `Item Parent Question ID`_ & `Item Parent Visibility Condition`_). The data type must match the type of the configured parent's answer.

.. _Item Control Type:

*   **Item Control Type**, the type of answer a user must enter. The following values are supported: 

    * ``Calendar``
    * ``Checkbox``
    * ``CheckboxList``
    * ``Dropdown``
    * ``Grid``, see :doc:`grid control<grid>` for more details.
    * ``PickerMulti``
    * ``PickerSingle``
    * ``RadioButtonList``
    * ``TextArea``
    * ``TextBox``

.. _Item DataType:

*   **Item DataType**, the data type of that the provided answer must be. Certain control types can only be used with certain control types. (see: `Item Control Type`_).  The following values are supported: 

    * ``Boolean``   (ControlType: Checkbox)
    * ``Date``      (ControlType: Calendar)
    * ``DateTime``  (ControlType: Calendar)
    * ``Decimal``   (ControlType: TextBox)
    * ``Guid``      (ControlType: TextBox)
    * ``Json``      (ControlType: TextBox, TextArea)
    * ``Number``    (ControlType: TextBox)
    * ``Smo``, to be used in conjunction with `Item Smo ID`_, `Item Smo Method Name`_, `Item Smo ID Property Name`_ & `Item Smo Display Property Name`_. |br| *(Only valid for Control Types:* ``CheckboxList``, ``Dropdown``, ``Picker``, ``RadioButtonList`` *)*
    * ``Text``      (ControlType: TextBox, TextArea)
    * ``Time``      (ControlType: Calendar)
    * ``Xml``       (ControlType: TextBox, TextArea, Grid)

.. _Item Parent Question ID:

*   **Item Parent Question ID**, the question's answer that will be the left side of the visibility condition (to be used in conjunction with `Item Condition Value`_ & `Item Parent Visibility Condition`_).

.. _Item Parent Visibility Condition:

*   **Item Parent Visibility Condition**, the operator that will be used in the visibility condition (to be used in conjunction with `Item Condition Value`_ & `Item Parent Question ID`_). The following values are supported:
    
    * ``Answered``, the parent's answer must have any value (watermark excluded). *The property* `Item Condition Value`_ *is not used in this case.*
    * ``EQ``, the parent's answer must be equal to the condition value.
    * ``GT``, the parent's answer must be greater than to the condition value.
    * ``GTE``, the parent's answer must be greater than or equal to the condition value.
    * ``IN``, all condition values must be in the the parent's answer set. *The parent's* `Item DataType`_ *must be* ``Smo`` *.*
    * ``LT``, the parent's answer must be less than to the condition value.
    * ``LTE``, the parent's answer must be less than or equal to the condition value.  
    * ``NEQ``, the parent's answer must not be equal to the condition value.

.. _Item Question ID:

*   **Item Question ID**, the ID that will be used for a survey item's question. This can be the same property as `Value`_.

.. _Item Question IsMandatory:

*   **Item Question IsMandatory**, the boolean that will be used to determine if a survey item's question is mandatory. This property is used for the methods `IsSurveyComplete`_ & `ValidateQuestions`_.

.. _Item Question Text:

*   **Item Question Text**, the text that will be used for a survey item's question.

.. _Item Question Remark:

*   **Item Question Remark**. the optional remark that will be shown below the question for a survey item's question. |br| If this value is null it will not be shown on the survey item. 

.. _Item Section Name:

*   **Item Section Name**, the section's name that will be display for all survey item's with teh same section ID (see : `Item Section ID`_). This value can be empty in the data source.

.. _Item Section ID:

*   **Item Section ID**, the ID that will be used to group question together. If this is empty than the question will be grouped with all other questions that have an empty section id. 

.. _Item Smo ID:

*   **Item Smo ID**, the SmartObject ID that will be used to retrieve data for this question. This value will be ignored if the survey item's datatype (see: `Item Section ID`_) is **not** ``Smo``.

.. _Item Smo Method Name:

*   **Item Smo Method Name**, the SmartObject method name that will be executed when retrieving data for this question. This value will be ignored if the survey item's datatype is **not** ``Smo`` (see: `Item DataType`_).

.. _Item Smo Inputs:

*   **Item Smo Inputs**, the SmartObject's properties and values that will be used as inputs when retrieving data for this question. This value will be ignored if the survey item's datatype is **not** ``Smo`` (see: `Item DataType`_). The format that should be used is: ``property1=value1;property2=value2``.

.. _Item Smo ID Property Name:

*   **Item Smo ID Property Name**, the return property of `Item Smo ID`_ that is stored in the answer for a question. This value will be ignored if the survey item's datatype is **not** ``Smo`` (see: `Item DataType`_).

.. _Item Smo Display Property Name:

*   **Item Smo Display Property Name**, the return property that is used to display values from `Item Smo ID`_. This value will be ignored if the survey item's datatype is **not** ``Smo`` (see: `Item DataType`_).

.. _Item Smo Sort Property Name:

*   **Item Smo Sort Property Name**, the SmartObject's properties that will be used to sort the results on. Multiple values can be provided by seperating them with a semicolon. This value will be ignored if the survey item's datatype is **not** ``Smo`` (see: `Item DataType`_).

.. _Item Smo Sort Direction:

*   **Item Smo Sort Direction**, the SmartObject's property that will determine the sorting direction. This value will be ignored if there are no sorting properties found. (see: `Item Smo Sort Property Name`_). Valid values are: 
    
    * ``asc``, the results will be sorted ascending. (default)
    * ``desc``, the results will be sorted descending.

|br|

.. _Item Button:

Item Button X
====================================================================================================
A button that will be displayed on each question. An event will be triggered when the user selects a button.
When multiple buttons are configured, they will be displayed left to right starting at the lowest button number.  

* **Name**, the name of the button, all five buttons should have a unique name. This is used in the `OnCustomButtonClicked`_ event.  
* **Icon Unicode**, the Font Awesome unicode char that will be used to display the button.  
* **Color**, the background color for this button. *This property is optional*.  
* **Text Color**, the icon's color for this button. *This property is optional*.  
* **Only Show If Answered**, only show this button on a survey item once an answer is provided.  
* **Only Show when datatype in**, only show this button on a survey item's datatype is one of the provided datatypes. The value must be a ';' seperated list, e.g.: ``Text;Smo``.  
* **Allowed In App**, this property determines if the button can be diplayed and used in the k2 business app.  

|br|

.. _Image Attachments - Data Source:

Image Attachments - Data Source
====================================================================================================

* **Add Icon Unicode**, the unicode value of the font awesome icon that will be used on the new attachment button. 
* **Question Attachment Limit**, the amount of attachments that can be attached to a survey item by the new button. This will **not** limit the amount of items returned by the list method when populating the attachments. 
* **Thumbnail Size**, the size in pixels for all thumbnails of the attachments.
* **SmartObject**, the smartobject that will be used when the attachments are populated for a single survey item. 
* **List Method**, the smartobject method that will be used when the attachments are populated for a single survey item. A survey item's data source value will always used on the configured AnswerID property. (see: `Value`_).
* **Update Remark Method**, the smartobject method that will be used when the attachment to update an attachment item's remark. This will fire when the attachment's remark textarea loses focus. The method will be called with just the runtime values of the configured ``Attachment ID`` and ``Attachment Remark`` properties. The method will only be called if a Attachment Remark property has been configured. 
* **Attachment ID**, the id of an attachment item. 
* **Attachment Image**, the image of an attachment item.
* **Attachment Remark**, the remark on an attachment item. *This property is optional*.  
* **Attachment Index**, the index of an attachment item. If configured, attachments will be sorted ascending. *This property is optional*.  
* **Attachment AnswerID**, the name of the property that represents the link to a survey item's Value (see: `Value`_).

|br|

Events
****************************************************************************************************

.. _OnAnswerChanged:
.. _OnAnswerRemarkChanged:
.. _OnCustomButtonClicked:

*	**Initialized**
*   **OnAnswerChanged**, all `Events`_ properties will be updated with data from the affected survey item, apart from button name and the attachment properties. 
*   **OnAnswerRemarkChanged**, all `Events`_ properties will be updated with data from the affected survey item, apart from button name and the attachment properties. 
*   **OnAttachmentClicked**, all `Events`_ properties will be updated with data from the affected survey item and the affected attachment.
*   **OnAttachmentDeleteClicked**, all `Events`_ properties will be updated with data from the affected survey item and the affected attachment.
*   **OnCustomButtonClicked**, all `Events`_ properties will be updated with data from the affected survey item, apart from the attachment properties.
*   **OnNewAttachmentClicked**, all `Events`_ properties will be updated with data from the affected survey item, apart from button name and the attachment properties.

|br|

Methods
****************************************************************************************************

.. _IsSurveyComplete:
.. _ValidateQuestions:

*   **CloseAttachmentLightBox**    

*   **GetHighestAttachmentIndex**
    
    * ``Answer ID``, the survey item's value that matches the provided value, it's highest attachment index will be returned.

*   **IsSurveyComplete**
    
    * ``MandatoryQuestionsOnly``, whether all questions should be checked or only questions that are marked as mandatory (see: `Item Question IsMandatory`_). *Optional parameter, default:* ``false``

*   **HideCustomButton**
    
    * ``Name``, the name of the button to hide (see: `Item Button`_).

*   **RefreshAttachments**
    
    * ``Answer ID``, the survey item's value that matches the provided value, it's attachments will be populated again (see: `Value`_).

*   **ShowCustomButton**

    * ``Name``, the name of the button to show (see: `Item Button`_).

*   **SetQuestionsReadOnly**

    * ``ReadOnly``, disables/enables the answer and answer remark fields for each survey item. All other items of the survey will still function normally. 

*   **ValidateQuestions**
    
    * ``MandatoryQuestionsOnly``, whether all questions should be validated or only questions that are marked as mandatory (see: `Item Question IsMandatory`_). *Optional parameter, default:* ``false``

|br|

Screenshots
****************************************************************************************************

| Browser: 
|   Example Section - 3 Item buttons, 1 question answered

.. image::	../../images/reference/controls/survey/survey-browser-1section.png
	:class:		browswer-screenshot with-shadow

|   Example Section Validated - 3 Item buttons, 1 question answered, 1 mandatory question unanswered

.. image::	../../images/reference/controls/survey/survey-browser-1section-validated.png
	:class:		browswer-screenshot with-shadow

| Android: 
|   *not yet available* 

| iOS:te
|   *not yet available*