blockr.core (version 0.1.3)

register_block: Block registry

Description

Listing of blocks is available via a block registry, which associates a block constructor with metadata in order to provide a browsable block directory. Every constructor is identified by a unique ID (uid), which by default is generated from the class vector (first element). If the class vector is not provided during registration, an object is instantiated (by calling the constructor with arguments ctor and ctor_pkg only) to derive this information. Block constructors therefore should be callable without block- specific arguments.

Usage

register_block(
  ctor,
  name,
  description,
  classes = NULL,
  uid = NULL,
  category = NULL,
  icon = NULL,
  arguments = NULL,
  details = NULL,
  link = NULL,
  guidance = NULL,
  examples = list(),
  keywords = NULL,
  package = NULL,
  overwrite = FALSE
)
default_icon(category = default_category())
default_category()
suggested_categories()
list_blocks()
registry_id_from_block(block)
unregister_blocks(uid = list_blocks())
register_blocks(...)
available_blocks()
registry_metadata(blocks = list_blocks(), fields = "all")
create_block(id, ...)
register_package_blocks(which = "all", package = pkg_name(), overwrite = TRUE)

Value

register_block() and register_blocks() are invoked for their side effects and return block_registry_entry object(s) invisibly, while unregister_blocks() returns NULL (invisibly). register_package_blocks()

registers the blocks a package declares in its YAML registry (written by the block_registration_roclet()), likewise returning their entries invisibly. Listing via list_blocks()

returns a character vector and a list of block_registry_entry object(s) for available_blocks(). create_block() returns a newly instantiated block

object. A block's registered metadata is read with block_metadata() and the block_meta_*() accessors, and its argument specification is built and read with new_block_arg() and friends.

Arguments

ctor

Block constructor

name, description

Metadata describing the block

classes

Block classes

uid

Unique ID for a registry entry

category

Useful to sort blocks by topics. If not specified, blocks are uncategorized.

icon

Icon

arguments

Block argument specification, either a new_block_args() object or a (possibly empty) named character vector of argument descriptions

details

Optional longer human-facing description (e.g. for a help popover), complementing the short description

link

Optional URL to a block's help or documentation page

guidance

Optional model-facing construction guidance (do/don't rules, enums, pitfalls), distinct from the human-facing details. Retrieved with block_metadata()

examples

Optional list of complete worked configurations (each a named list keyed by argument name); supersedes the per-argument example assembly. Retrieved with block_metadata()

keywords

Optional character vector of free-text search terms for block discovery, retrieved with block_metadata()

package

Package where constructor is defined (or NULL)

overwrite

Overwrite existing entry

block

Block object

...

For register_blocks(), arguments forwarded to register_block(); for new_block_args(), named new_block_arg() objects (or strings), one per constructor formal

blocks

Character vector of registry IDs

fields

Metadata fields

id

Block ID as reported by list_blocks()

which

Character vector of block constructor names to register (or "all"), keying into the YAML registry generated by the block_registration_roclet()

Details

Due to current requirements for serialization/deserialization, we keep track the constructor that was used for block instantiation. This works most reliable whenever a block constructor is an exported function from a package as this function is guaranteed to be available in a new session (give the package is installed in an appropriate version). While it is possible to register a block passing a "local" function as ctor, this may introduce failure modes that are less obvious (for example when such a constructor calls another function that is only defined within the scope of the session). It is therefore encouraged to only rely on exported function constructors. These can also be passed as strings and together with the value of package, the corresponding function can easily be retrieved in any session.

Blocks can be registered (i.e. added to the registry) via register_block() with scalar-valued arguments and register_blocks(), where arguments may be vector-valued, while de-registration (or removal) is handled via unregister_blocks(). A listing of all available blocks can be created as list_blocks(), which will return registry IDs and available_blocks(), which provides a set of (named) block_registry_entry objects. Finally, block construction via a registry ID is available as create_block().

Examples

blks <- list_blocks()
register_block("new_dataset_block", "Test", "Registry test",
               uid = "test_block", package = "blockr.core")

new <- setdiff(list_blocks(), blks)
unregister_blocks(new)
setequal(list_blocks(), blks)