Functions and Controls
Writing backend functions¶
When you add an app-specific block, such as a Form, you pass it a backend function to run when it is triggered.
The function passed into an app block can be any Python function, including a
lambda or nested inline function. The main requirements are that the function returns Datapane blocks. If the function is being called by a form, it must also take a params dict.
We recommend using Jupyter whilst building your app, as it makes it easy to debug interactively. You can build your function in one cell and call it from another with sample parameters. As they are normal Python functions, no magic is needed.
Datapane will automatically display the result from the function below where you call it so you can interactively develop your functions and app piece-by-piece.
dp.Form function takes a
params parameter which is a dictionary containing all the controls specified in the
controls parameter to the compute block. For instance, if you have a Form with the following controls:
first_name parameter would be accessible as follows:
For convenience, you can specify several, or all, of the names of the
params in the function definition and Datapane will automatically unpack them, e.g.
def f(params, foo: str): # params will contain only `bar` return dp.Text(foo) dp.Form(on_submit=f, controls=dict(foo=dp.TextBox(), bar=dp.NumberBox()) )
Datapane functions can return any Datapane block or raw Python objects that are supported by Datapane. You can return these directly, as a list, or return a layout or container block like
dp.Group for a more advanced layout.
You can even return compute blocks like
dp.Dynamic from a function, allowing you to chain functions together that build more complex operations and interactive apps, such as wizards.
Controls are used to define the specific parameters to present to the user for input, such as a
TextField, a number
Range, or even a
These parameters are collected from the user and passed by Datapane into the respective Python function when calling it. This way you can collect input from your user and your user can use your app interactively.
When the user submits the form, Datapane automatically handles uploading the user's input, validates it, converts it to the correct type, and provides initial values if none are given. From there, Datapane calls the Compute function with the params in the
params dict as mentioned above.
When adding a Compute Block to your code, you pass in the collection of parameters that make up your controls via a
dp.Form(on_submit=f, controls=dp.Controls(name=dp.TextBox(), age=dp.Range(initial=30, min=0, max=100)))
Datapane comes with many parameters built-in to handle a wide variety of user inputs. All these parameters accept some common options, including,
name- the name given to the parameter when used in your compute function
initial- the initial value used when displaying the parameter in your app
label- a descriptive label used when displaying the parameter in your app
The built-in parameters include,
||A boolean toggle|
||A field to enter text|
||A field to enter numbers|
||A slider to select a number from a range|
||Select an single choice from a set of options|
||Select multiple choices from a set of options|
||Create multiple string tags|
||Select a date|
||Select a time|
||Select a date and a time|
||Upload a file|
The Controls API docs also include detailed information and live samples of each parameter type.