Experiment actions

experiment.actions.base_action

`BaseAction`

Bases: object

base class for the experiment actions. Actions are used to configure components to be rendered on the frontend.

Source code in experiment/actions/base_action.py

class BaseAction(object):
    """base class for the experiment actions.
    Actions are used to configure components to be rendered on the frontend.    
    """

    ID = 'BASE'
    style = None

    def __init__(self, style: FrontendStyle = None):
        self.style = style
        pass

    def action(self) -> dict:
        """The action that can be sent to the frontend

        Returns:
            action_dict (dict): Frontend component configuration        
        """

        action_dict = self.__dict__
        action_dict['view'] = self.ID

        # we may have already converted the style object to a dictionary, e.g., after copying an Action object
        if self.style is not None and type(self.style) is not dict:
            action_dict['style'] = self.style.to_dict()

        return action_dict

`action()`

The action that can be sent to the frontend

Returns:

Name	Type	Description
`action_dict`	`dict`	Frontend component configuration

Source code in experiment/actions/base_action.py

def action(self) -> dict:
    """The action that can be sent to the frontend

    Returns:
        action_dict (dict): Frontend component configuration        
    """

    action_dict = self.__dict__
    action_dict['view'] = self.ID

    # we may have already converted the style object to a dictionary, e.g., after copying an Action object
    if self.style is not None and type(self.style) is not dict:
        action_dict['style'] = self.style.to_dict()

    return action_dict

experiment.actions.consent

`Consent`

Bases: BaseAction

Provide data for a view that ask consent for using the experiment data

Parameters:

Name	Type	Description	Default
`text`	`File`	Uploaded file via an experiment’s translated content’s consent (fileField)	required
`title`	`str`	The title to be displayed	`'Informed consent'`
`confirm`	`str`	The text on the confirm button	`'I agree'`
`deny`	`str`	The text on the deny button	`'Stop'`
`url`	`str`	If no text is provided the url will be used to load a template (HTML or MARKDOWN) HTML: (default) Allowed tags: html, django template language MARKDOWN: Allowed tags: Markdown language	`''`

Note

Relates to client component: Consent.js

Source code in experiment/actions/consent.py

class Consent(BaseAction):  # pylint: disable=too-few-public-methods
    """Provide data for a view that ask consent for using the experiment data

    Args:
        text: Uploaded file via an experiment's translated content's consent (fileField)
        title: The title to be displayed
        confirm: The text on the confirm button
        deny: The text on the deny button
        url:  If no text is provided the url will be used to load a template (HTML or MARKDOWN)
                    HTML: (default) Allowed tags: html, django template language
                    MARKDOWN: Allowed tags: Markdown language

    Note:
        Relates to client component: Consent.js
    """

    # default consent text, that can be used for multiple blocks
    ID = "CONSENT"

    default_text = "Lorem ipsum dolor sit amet, nec te atqui scribentur. Diam \
                molestie posidonium te sit, ea sea expetenda suscipiantur \
                contentiones, vix ex maiorum denique! Lorem ipsum dolor sit \
                amet, nec te atqui scribentur. Diam molestie posidonium te sit, \
                ea sea expetenda suscipiantur contentiones, vix ex maiorum \
                denique! Lorem ipsum dolor sit amet, nec te atqui scribentur. \
                Diam molestie posidonium te sit, ea sea expetenda suscipiantur \
                contentiones, vix ex maiorum denique! Lorem ipsum dolor sit \
                amet, nec te atqui scribentur. Diam molestie posidonium te sit, \
                ea sea expetenda suscipiantur contentiones."

    def __init__(self, text: File, title: str="Informed consent", confirm: str="I agree", deny: str="Stop", url: str="") -> dict:
        # Determine which text to use
        if text != "":
            # Uploaded consent via file field: block.consent (High priority)
            with text.open("r") as f:
                dry_text = f.read()
            render_format = get_render_format(text.url)
        elif url != "":
            # Template file via url (Low priority)
            dry_text = render_to_string(url)
            render_format = get_render_format(url)
        else:
            # use default text
            dry_text = self.default_text
            render_format = "HTML"
        # render text fot the consent component
        self.text = render_html_or_markdown(dry_text, render_format)
        self.title = title
        self.confirm = confirm
        self.deny = deny

`get_render_format(url)`

Detect markdown file based on file extension

Parameters:

Name	Type	Description	Default
`url`	`str`	Url of the consent file	required

Returns:

Type	Description
`str`	File format

Source code in experiment/actions/consent.py

def get_render_format(url: str) -> str:
    """
    Detect markdown file based on file extension

    Args:
        url: Url of the consent file

    Returns:
        File format

    """
    if splitext(url)[1] == ".md":
        return "MARKDOWN"
    return "HTML"

`render_html_or_markdown(dry_text, render_format)`

render html or markdown

Parameters:

Name	Type	Description	Default
`dry_text`	`str`	contents of a markdown or html file	required
`render_format`	`str`	type of contents, either ‘HTML’ or ‘MARKDOWN’	required

Returns:

Type	Description
`str`	Content rendered to html

Source code in experiment/actions/consent.py

def render_html_or_markdown(dry_text: str, render_format: str) -> str:
    """render html or markdown

    Args:
        dry_text: contents of a markdown or html file
        render_format: type of contents, either 'HTML' or 'MARKDOWN'

    Returns:
        Content rendered to html
    """

    if render_format == "HTML":
        template = Template(dry_text)
        context = Context()
        return template.render(context)
    if render_format == "MARKDOWN":
        return formatter(dry_text, filter_name="markdown")

experiment.actions.explainer

`Explainer`

Bases: BaseAction

Provide data for a explainer that explains the experiment steps

Relates to client component: Explainer.js

Explainer view automatically proceeds to the following view after timer (in ms) expires. If timer=None, explainer view will proceed to the next view only after a click of a button. Intro explainers should always have timer=None (i.e. interaction with a browser is required), otherwise the browser will not autoplay the first segment.

Source code in experiment/actions/explainer.py

class Explainer(BaseAction):
    """
    Provide data for a explainer that explains the experiment steps

    Relates to client component: Explainer.js

    Explainer view automatically proceeds to the following view after timer (in ms) expires. If timer=None, explainer view will proceed to the next view only after a click of a button. Intro explainers should always have timer=None (i.e. interaction with a browser is required), otherwise the browser will not autoplay the first segment.
    """

    ID = "EXPLAINER"

    def __init__(self, instruction, steps, button_label="Let's go!", timer=None, step_numbers=False):
        self.instruction = instruction
        self.steps = steps
        self.button_label = button_label
        self.timer = timer
        self.step_numbers = step_numbers

    def action(self):
        """Get data for explainer action"""
        if self.step_numbers:
            serialized_steps = [step.action(index+1) for index, step in enumerate(self.steps)]
        else:
            serialized_steps = [step.action() for step in self.steps]
        return {
            'view': self.ID,
            'instruction': self.instruction,
            'button_label': self.button_label,
            'steps': serialized_steps,
            'timer': self.timer,
        }

`action()`

Get data for explainer action

Source code in experiment/actions/explainer.py

def action(self):
    """Get data for explainer action"""
    if self.step_numbers:
        serialized_steps = [step.action(index+1) for index, step in enumerate(self.steps)]
    else:
        serialized_steps = [step.action() for step in self.steps]
    return {
        'view': self.ID,
        'instruction': self.instruction,
        'button_label': self.button_label,
        'steps': serialized_steps,
        'timer': self.timer,
    }

`Step`

Bases: object

Source code in experiment/actions/explainer.py

class Step(object):

    def __init__(self, description, number=None):
        self.description = description
        self.number = number

    def action(self, number=None):
        """Create an explainer step, with description and optional number"""
        return {
            'number': self.number if self.number else number,
            'description': self.description
        }

`action(number=None)`

Create an explainer step, with description and optional number

Source code in experiment/actions/explainer.py

def action(self, number=None):
    """Create an explainer step, with description and optional number"""
    return {
        'number': self.number if self.number else number,
        'description': self.description
    }

experiment.actions.final

`Final`

Bases: BaseAction

Provide data for a final view

Relates to client component: Final.js

Source code in experiment/actions/final.py

class Final(BaseAction):  # pylint: disable=too-few-public-methods
    """
    Provide data for a final view

    Relates to client component: Final.js
    """

    ID = 'FINAL'

    RANKS = {
        'PLASTIC': {'text': _('plastic'), 'class': 'plastic'},
        'BRONZE':  {'text': _('bronze'), 'class': 'bronze'},
        'SILVER': {'text': _('silver'), 'class': 'silver'},
        'GOLD': {'text': _('gold'), 'class': 'gold'},
        'PLATINUM': {'text': _('platinum'), 'class': 'platinum'},
        'DIAMOND': {'text': _('diamond'), 'class': 'diamond'}
    }

    def __init__(
        self,
        session: Session,
        title: str = _("Final score"),
        final_text: str = None,
        button: dict = None,
        points: str = None,
        rank: str = None,
        show_profile_link: bool = False,
        show_participant_link: bool = False,
        show_participant_id_only: bool = False,
        feedback_info: dict = None,
        total_score: float = None,
        logo: dict = None,
    ):

        self.session = session
        self.title = title
        self.final_text = final_text
        self.button = button
        self.rank = rank
        self.show_profile_link = show_profile_link
        self.show_participant_link = show_participant_link
        self.show_participant_id_only = show_participant_id_only
        self.feedback_info = feedback_info
        self.logo = logo
        if total_score is None:
            self.total_score = self.session.total_score()
        else:
            self.total_score = total_score
        if points is None:
            self.points = _("points")
        else:
            self.points = points

    def action(self):
        """Get data for final action"""
        return {
            "view": self.ID,
            "score": self.total_score,
            "rank": self.rank,
            "final_text": self.final_text,
            "button": self.button,
            "points": self.points,
            "action_texts": {
                "play_again": _("Play again"),
                "profile": _("My profile"),
                "all_experiments": _("All experiments"),
            },
            "title": self.title,
            "social": self.get_social_media_config(self.session),
            "show_profile_link": self.show_profile_link,
            "show_participant_link": self.show_participant_link,
            "feedback_info": self.feedback_info,
            "participant_id_only": self.show_participant_id_only,
            "logo": self.logo,
        }

    def get_social_media_config(self, session: Session) -> dict:
        experiment = session.block.phase.experiment
        if (
            hasattr(experiment, "social_media_config")
            and experiment.social_media_config
        ):
            return serialize_social_media_config(
                experiment.social_media_config, session.total_score()
            )

`action()`

Get data for final action

Source code in experiment/actions/final.py

def action(self):
    """Get data for final action"""
    return {
        "view": self.ID,
        "score": self.total_score,
        "rank": self.rank,
        "final_text": self.final_text,
        "button": self.button,
        "points": self.points,
        "action_texts": {
            "play_again": _("Play again"),
            "profile": _("My profile"),
            "all_experiments": _("All experiments"),
        },
        "title": self.title,
        "social": self.get_social_media_config(self.session),
        "show_profile_link": self.show_profile_link,
        "show_participant_link": self.show_participant_link,
        "feedback_info": self.feedback_info,
        "participant_id_only": self.show_participant_id_only,
        "logo": self.logo,
    }

experiment.actions.form

`Form`

Bases: BaseAction

Form is a view which brings together an array of questions with submit and optional skip button - form: array of questions - button_label: label of submit button - skip_label: label of skip button - is_skippable: can this question form be skipped

Source code in experiment/actions/form.py

class Form(BaseAction):
    ''' Form is a view which brings together an array of questions with submit and optional skip button
    - form: array of questions
    - button_label: label of submit button
    - skip_label: label of skip button
    - is_skippable: can this question form be skipped
    '''

    def __init__(self, form, submit_label=_('Continue'), skip_label=_('Skip'), is_skippable=False):
        self.form = form
        self.submit_label = submit_label
        self.skip_label = skip_label
        self.is_skippable = is_skippable

    def action(self):
        serialized_form = [question.action() for question in self.form]
        return {
            'form': serialized_form,
            'submit_label': self.submit_label,
            'skip_label': self.skip_label,
            'is_skippable': self.is_skippable,
        }

`Question`

Bases: BaseAction

Question is part of a form. - key: description of question in results table - view: which widget the question should use in the frontend - explainer: optional instructions for this specific question - question: the question text - scoring_rule: optionally, specify a scoring rule which should be applied - is_skippable: whether the question can be skipped - submits: whether entering a value for the question submits the form - style: one (string) or multiple (dict) class names to apply for styling the frontend component

Source code in experiment/actions/form.py

class Question(BaseAction):
    ''' Question is part of a form.
    - key: description of question in results table
    - view: which widget the question should use in the frontend
    - explainer: optional instructions for this specific question
    - question: the question text
    - scoring_rule: optionally, specify a scoring rule which should be applied
    - is_skippable: whether the question can be skipped
    - submits: whether entering a value for the question submits the form
    - style: one (string) or multiple (dict) class names to apply for styling the frontend component
    '''

    def __init__(
        self,
        key,
        result_id=None,
        view='STRING',
        explainer='',
        question='',
        is_skippable=False,
        submits=False,
        style=STYLE_NEUTRAL
        ):

        self.key = key
        self.view = view
        self.explainer = explainer
        self.question = question
        self.result_id = result_id
        self.is_skippable = is_skippable
        self.submits = submits
        self.style = style

    def action(self):
        if settings.TESTING and self.result_id:
            from result.models import Result
            result = Result.objects.get(pk=self.result_id)
            if result and result.expected_response:
                self.expected_response = result.expected_response
        return self.__dict__

experiment.actions.frontend_style

`FrontendStyle`

Source code in experiment/actions/frontend_style.py

class FrontendStyle:

    VALID_STYLES = EFrontendStyle.__members__.values()

    """
    Initialize the FrontendStyle with a root style.
    :param root_style: The style name for the root element.
    """
    def __init__(self, root_style: EFrontendStyle = EFrontendStyle.EMPTY):

        if not EFrontendStyle.is_valid(root_style):
            raise ValueError(f"Invalid root style: {root_style}")

        self.styles = {'root': root_style}

    def get_style(self, element: str) -> str:
        """
        Get the style for a specific element.
        :param element: The element identifier for which to get the style.
        :return: The style name for the given element.
        """
        return self.styles.get(element, None)

    def apply_style(self, element: str, style: str) -> None:
        """
        Apply a specific style to an element after validating the style.
        :param element: The element identifier to apply the style to.
        :param style: The style name to apply.
        """
        if EFrontendStyle.is_valid(style):
            self.styles[element] = style
        else:
            valid_styles = ', '.join([str(s) for s in self.VALID_STYLES])
            raise ValueError(f"Invalid style: {style}. Valid styles are {valid_styles}.")

    def to_dict(self) -> dict:
        serialized_styles = { 'root': self.styles['root'].value }

        return serialized_styles

    def __str__(self):
        return str(self.to_dict())

    def __json__(self):
        return self.to_dict()

`VALID_STYLES = EFrontendStyle.members.values()` `class-attribute` `instance-attribute`

Initialize the FrontendStyle with a root style. :param root_style: The style name for the root element.

`apply_style(element, style)`

Apply a specific style to an element after validating the style. :param element: The element identifier to apply the style to. :param style: The style name to apply.

Source code in experiment/actions/frontend_style.py

def apply_style(self, element: str, style: str) -> None:
    """
    Apply a specific style to an element after validating the style.
    :param element: The element identifier to apply the style to.
    :param style: The style name to apply.
    """
    if EFrontendStyle.is_valid(style):
        self.styles[element] = style
    else:
        valid_styles = ', '.join([str(s) for s in self.VALID_STYLES])
        raise ValueError(f"Invalid style: {style}. Valid styles are {valid_styles}.")

`get_style(element)`

Get the style for a specific element. :param element: The element identifier for which to get the style. :return: The style name for the given element.

Source code in experiment/actions/frontend_style.py

def get_style(self, element: str) -> str:
    """
    Get the style for a specific element.
    :param element: The element identifier for which to get the style.
    :return: The style name for the given element.
    """
    return self.styles.get(element, None)

experiment.actions.html

`HTML`

Bases: BaseAction

A custom view that handles a custom HTML question Relates to client component: HTML.js

Source code in experiment/actions/html.py

class HTML(BaseAction):  # pylint: disable=too-few-public-methods
    """
    A custom view that handles a custom HTML question
    Relates to client component: HTML.js    
    """

    ID = 'HTML'

    def __init__(self, body):
        """
        - body: HTML body
        """
        self.body = body

`init(body)`

body: HTML body

Source code in experiment/actions/html.py

def __init__(self, body):
    """
    - body: HTML body
    """
    self.body = body

experiment.actions.info

`Info`

Bases: BaseAction

Provide data for a view that shows information (HTML)

Relates to client component: Info.js

Source code in experiment/actions/info.py

class Info(BaseAction):  # pylint: disable=too-few-public-methods
    """
    Provide data for a view that shows information (HTML)

    Relates to client component: Info.js    
    """

    ID = "INFO"

    def __init__(self, body, heading="", button_label=None, button_link=None):
        """
        Info shows an formatted information page with an HTML body
        body: html body
        heading: title/heading on top
        button_label: label of button on bottom
        button_link: (optional) button link. If no link is set, 'onNext' is called
        """

        self.body = body
        self.heading = heading
        self.button_label = button_label
        self.button_link = button_link

`init(body, heading='', button_label=None, button_link=None)`

Info shows an formatted information page with an HTML body body: html body heading: title/heading on top button_label: label of button on bottom button_link: (optional) button link. If no link is set, ‘onNext’ is called

Source code in experiment/actions/info.py

def __init__(self, body, heading="", button_label=None, button_link=None):
    """
    Info shows an formatted information page with an HTML body
    body: html body
    heading: title/heading on top
    button_label: label of button on bottom
    button_link: (optional) button link. If no link is set, 'onNext' is called
    """

    self.body = body
    self.heading = heading
    self.button_label = button_label
    self.button_link = button_link

experiment.actions.playback

`Autoplay`

Bases: Playback

This player starts playing automatically - show_animation: if True, show a countdown and moving histogram