Button

class alfred3.element.action.Button(text: str, func: callable, followup: str = 'refresh', submit_first: bool = True, button_style: str = 'btn-primary', button_round_corners: bool = False, button_block: bool = False, custom_js: str = '', **kwargs)

Bases: alfred3.element.core.Element

A button that triggers execution of a python function on click.

Parameters

• text (str) – Button text

• func (callable) – Python function to be called on button click. The function must take zero arguments, but it can be a method of a class or instance.

• followup (str) –

  What to do after the python function was called. Can take the following values:

  • refresh submits and reloads the current page (default),

  • none does nothing,

  • forward submits the current page and moves forward,

  • backward submits the current page and moves backward,

  • jump>page_name submits the current page and triggers a jump to a page with the name ‘page_name’

  • custom executes custom JavaScript. If you choose this option, you must supply your custom JavaScript through the argument custom_js.

• submit_first (bool) – If True, the current values of all input elements on the current page will be saved on button click, before func is called. This way, these values will be available in func through ExperimentSession.values, if func has access to the ExperimentSession object. See Example 3. Defaults to True.

• button_style (str) – Can be used for quick color-styling, using Bootstraps default color keywords: btn-primary, btn-secondary, btn-success, btn-info, btn-warning, btn-danger, btn-light, btn-dark. You can also use the “outline” variant to get outlined buttons (eg. “btn-outline-secondary”). Advanced users can supply their own CSS classes for button-styling. Defaults to “btn-primary”.

• button_round_corners (bool) – A boolean switch to toggle whether the button should be displayed with rounded corners. Defaults to False.

• button_block (bool) – A boolean switch to toggle whether the button should take up all horizontal space that is available. Can be quite useful when arranging buttons in Row. Defaults to False.

• custom_js (str) – Custom JavaScript to execute after the python function specified in func was called. Only takes effect, if followup is set to ‘custom’.

• **kwargs –

  Inherited keyword arguments

  align	Horizontal alignment of text in the element. Does not usually apply to labels. Think of it as an alignment that applies to the innermost layer of an element (while labels are generally located at outer layers). See LabelledElement for more on labelled elements. Can be left (default), center, right, or justify.
  font_size	Font size for text in the element. You can use a keyword or an exact specification. The available keywords are tiny, small, normal, big, and huge. The exact specification shoul ideally include a unit, such as 1rem, or 12pt. If you supply an integer without a unit, a unit of pt will be assumed. Defaults to normal.
  height	Vertical height of the elements display area. Supply a string with a unit, e.g. 80px. Usually, the default is fine. For adding vertical space to a page, you should prefer the VerticalSpace element, as it is sematically more clear.
  instance_log	If True, the element will use an instance-specific logger, thereby allowing detailed fine- tuning of its logging behavior.
  name	Name of the element. This should be a unique identifier. It will be used to identify the corresponding data in the final data set.
  position	Horizontal position of the full element on the page. Values can be left, center (default), end, or any valid value for the justify-content flexbox utility. Takes effect only, when the element is not full-width.
  showif	A dictionary, defining conditions that must be met for the element to be shown. The conditions take the form of key-value pairs, where each key is an element name and the value is the required input. See showif for details.
  width	Defines the horizontal width of the element from small screens upwards. It is always full-width on extra small screens. Possible values are narrow, medium, wide, and full. For more detailed control, you can define the element_width attribute.

Notes

Note that by default, the Button will not save data itself. If you wish to save information about button clicks, you can utilize the ExperimentSession.adata dictionary in the button’s callable. See Example 4.

Warning

This element is very powerful. Remember that with great power comes great responsibility. Be aware that the callable func will be executed every time the button is clicked.

Examples

Example 1: A minimal example that will print some text to your terminal window on button click:

import alfred3 as al
exp = al.Experiment()

@exp.member
class Demo(al.Page):

    def on_exp_access(self):
        self += al.Button("Demo Button", func=self.demo_function)

    def demo_function(self):
        print("\nThis is a demonstration")
        print(self.exp.exp_id)
        print("\n")

Example 2: An example with a jump after the function call:

import alfred3 as al
exp = al.Experiment()

@exp.member
class Demo(al.Page):

    def on_exp_access(self):
        self += al.Button("Demo Button", func=self.demo_function, followup="jump>page3")

    def demo_function(self):
        print("\nThis is a demonstration")
        print(self.exp.exp_id)
        print("\n")

exp += al.Page(title="Page 2", name="page2")
exp += al.Page(title="Page 3", name="page3")

Example 3: An example that uses values entered on the current page:

import alfred3 as al
exp = al.Experiment()


@exp.member
class Demo(al.Page):

    def on_exp_access(self):
        self += al.TextEntry(leftlab="Enter", name="entry1")
        self += al.Button("Demo Button", func=self.demo_function)

    def demo_function(self):
        print("\nThis is a demonstration")
        print(self.exp.exp_id)
        print(self.exp.values["entry1"])
        print("\n")

Example 4: An example that saves a count of how often the button was clicked:

import alfred3 as al
exp = al.Experiment()

@exp.member
class Demo(al.Page):

    def on_exp_access(self):
        self += al.Button("Demo Button", func=self.demo_function)

    def demo_function(self):
        print("\nThis is a demonstration")

        if "demo_button" in self.exp.adata:
            self.exp.adata["demo_button"] += 1
        else:
            self.exp.adata["demo_button"] = 1

        print("\n")

Methods

add_css	Adds CSS to the element.
add_js	Adds Javascript to the element.
added_to_experiment	Tells the element that it was added to an experiment.
added_to_page	Tells the element that it was added to a page.
prepare_web_widget	Hook for computations for preparing an element's web widget.
render_inner_html	Renders the element template element_template.

Attributes

base_template	Base template for the element, which will be used to hold the rendered element template.
converted_width	List of bootstrap column widths at different screen sizes.
css_class_container	Returns the name the element container's CSS class.
css_class_element	Returns the name of the element's CSS class.
css_code	A list of tuples, which contain a priority and CSS code.
css_urls	A list of tuples, which contain a priority and an url pointing to CSS code.
display_standalone	If True (default), the element will be displayed as usual on its own.
element_template	The element's specific, inner template.
element_width	Returns a string of column width definitions.
exp	The experiment session to which this element belongs.
experiment	Alias for exp
font_size	Font size
js_code	A list of tuples, which contain a priority and Javascript.
js_template
js_urls	A list of tuples, which contain a priority and an url pointing to JavaScript.
name	Unique identifier for the element.
page	The page to which this element belongs.
position	Position of the whole element on the page.
section	The direct parent section of this element's page.
short_tree	String, giving the exact position in the experiment.
should_be_shown	Boolean, indicating whether the element is meant to be shown.
showif	Conditions that have to be met for the element to be shown.
template_data	Dictionary of data to be passed on to jinja templates.
tree	String, giving the exact position in the experiment.
web_widget	The element's rendered html code for display on a page.
width	Element width