API documentation

Base

The base module provides the virtual Block class used as a base class for “block” objects, and the Store class, which is a convenient adaptation of the Store used for client-side data storage. This module also includes the Data and Component classes but these were not implemented with the intention of being relevant outside of this module.

Block

class dash_building_blocks.base.Block(app=None, data=None, id=None, **kwargs)

The Block virtual class.

Parameters:

• app (dash.Dash) – The Dash app object.
• data (dict) – The data dict that will be wrapped as the data Data attribute.
• id (str) – The id unique to the block object. If None, it will be` generated internally using generate_random_string().
• **kwargs – Extra keyword arguments are processed by parameters().

id

The id representing the “namespace” of the block object. It is determined as follows: '{}-{}'.format(block.class_id, block._uid) , where _uid is the unique block id assigned to the block object during initialization.

layout()

Define the block layout. Remember, Block is a virtual class, with this being the one method that must be overriden when subclassing to create a valid block class. At initialization, the returned layout will become the layout attribute of the instantiated block.

Returns:The block layout, composed of Dash components.

register(local_id, global_id=None, ext='')

Register a local_id to be mapped to global_id. If global_id is not provided, it is determined internally as the following: '{}-{}-{}'.format(block.class_id, block._uid, local_id). If ext is is not empty, it will be appended to the global_id such that: '{}-{}'.format(global_id, ext).

Parameters:

• local_id (str) – The localized id that is unique in the scope of the block.
• global_id (str) – The globally unique id.
• ext (str) – An extension to be appended to the end of the globally unique id.

Returns:

The globally unique id.

parameters(**kwargs)

Sometimes, it may be desired to pass in arguments that are separate from data. For this, additional keyword arguments (**kwargs) passed to __init__() will be processed through this method. By default, it will simply update __dict__ with kwargs.

Parameters:**kwargs – The keyword arguments.

callback(*args, **kwargs)

Convenience method that acts as an alias for app.callback

class_id()

Define the id unique to the block class. By default, this will be the result of decamelify()ing __class__.__name__, so it is only optionally overriden if a custom class id is desired. Similar to layout(), it becomes an attribute with the same name, class_id.

Returns:The string representing the block class id

input(component_id, component_property='children')

Create the dash.dependencies.Input dependency with component_id equal to the globally unique component id mapped from the component_id argument, and matching component property.

Parameters:

• component_id (str) – The registered component id, local to the block.
• component_property (str) – The component property.

Returns:

The dash.dependencies.Input dependency object.

output(component_id, component_property='children')

Create the dash.dependencies.Output dependency with component_id equal to the globally unique component id mapped from the component_id argument, and matching component property.

Parameters:

• component_id (str) – The registered component id, local to the block.
• component_property (str) – The component property.

Returns:

The dash.dependencies.Output dependency object.

state(component_id, component_property='children')

Create the dash.dependencies.State dependency with component_id equal to the globally unique component id mapped from the component_id argument, and matching component property.

Parameters:

• component_id (str) – The registered component id, local to the block.
• component_property (str) – The component property.

Returns:

The dash.dependencies.State dependency object.

Store

class dash_building_blocks.base.Store(app, id='', hide=True)

The Store class streamlines the creation and use of hidden storage divs. The interface is similar to that of Blocks but slightly different due to its more specific function.

Parameters:

• app (dash.Dash) – The Dash app object.
• id (str) – The id unique to the store object.
• hide (bool) – Whether or not to hide the layout of the store object.

layout

The layout containing divs for all registered data items.

register(local_id, inputs=None, state=None, initially='')

Register a local_id to be internally mapped to a globally unique id. If inputs is provided, it will return a decorator function that mediates the inputs and state to an app.callback() call. For example this:

store.register(
    'hello',
    inputs=[Input('foo', 'value')],
    state=[State('bar', 'children')]
)
def update_something(value, children):
    return 'some data'

… is a shortcut for this:

store.register('hello')
store.app.callback(
    store.output('hello'),
    inputs=[Input('foo', 'value')],
    state=[State('bar', 'children')]
)
def update_something(value, children):
    return 'some data'

Parameters:

• local_id (str) – The localized id that is unique in the scope of the block. A div with this id will be created in the store object’s layout.
• inputs (list(dash.dependency.Input)) – The Dash input dependencies to the callback that updates the div with local_id.
• state (list(dash.dependency.State)) – The Dash state dependencies to the callback that updates the div with local_id.
• initially – The initial value in the created div with local_id

input(component_id)

Create the dash.dependencies.Input dependency with component_id equal to the globally unique component id mapped from the component_id argument, and component_property equal to 'children' since all store inner components are dash.html_components.Divs.

Parameters:component_id (str) – The stored div component id, local to the store. Returns:The dash.dependencies.Input dependency object.

output(component_id)

Create the dash.dependencies.Output dependency with component_id equal to the globally unique component id mapped from the component_id argument, and component_property equal to 'children' since all store inner components are dash.html_components.Divs.

Parameters:component_id (str) – The stored div component id, local to the store. Returns:The dash.dependencies.Output dependency object.

state(component_id)

Create the dash.dependencies.State dependency with component_id equal to the globally unique component id mapped from the component_id argument, and component_property equal to 'children' since all store inner components are dash.html_components.Divs.

Parameters:component_id (str) – The stored div component id, local to the store. Returns:The dash.dependencies.State dependency object.

Data

class dash_building_blocks.base.Data(**kwargs)

Convenience class that wraps a dict object so keys may be accessed as attributes.

Parameters:**kwargs – Keyword arguments are set as class attributes.

classmethod from_dict(d)

Create a Data object from a dict object d.

Parameters:d (dict) – The data dictionary. Returns:The Data object wrapping the data dictionary. Return type:Data

to_dict()

Convert this to a dict object.

Returns:The converted dictionary. Return type:dict

Util

util.generate_random_string()

Generate a pseudo-random alphanumerical string.

Parameters:int (size) – The number of characters in the string. Returns:The pseudo-random alphanumerical string.

util.camelify(name, delims=['-', '_'])

Convert name to camelCase.

>> camelify('hello-world')
'helloWorld'

Parameters:

• str (name) – The string to be converted.
• list(str) (delims) – The list of delims that identify where the camel “humps” occur.

Returns:

The converted string.

util.decamelify(delim='-')

Convert name from camelCase to a non-camel version delimited by delim.

>> decamelify('HelloWorld')
'hello-world'

Parameters:

• str (delim) – The string to be converted.
• str – The delimiting string.

Returns:

The converted string.