Skip to content

Developer docs

Antony Milne edited this page Mar 13, 2024 · 5 revisions

These are things which are useful to refer back to. At some point in the future they might make their way into a proper docs page on RTD. These notes can be rough and might not always be up to date. If it's a quick answer then put it inline here; if it's a longer read then just link to it.

Link to a page, use an asset

Source: https://github.com/mckinsey/vizro/pull/151

Here's the rules for how we should write code so that paths are always correctly formed:

  • always use dash.get_relative_path to link to pages with href (see _make_page_404_layout example link)
  • always use dash.get_relative_path(f"/{STATIC_URL_PREFIX}/..") to refer to built-in assets in the static folder (see _make_page_404_layout example html.Img)
  • always use dash.get_asset_url to refer to things in the user assets folder (we don't have any examples of this at the moment outside docs)

html.Div(hidden=True) vs. None

Source: https://github.com/mckinsey/vizro/pull/188

  • prefer to use None over html.Div(hidden=True) in the case that we don't need to refer to the element in any way (basically whenever you don't set an id). e.g. html.P(self.title) if self.title else None
  • prefer to use html.Div(hidden=True) over None in the case that we do need to refer to the element (basically when you do set an id). e.g. html.Div(hidden=True, id="nav_panel_outer"). Generally these can be identified by the fact that build return values have a type like _NavBuildType
  • prefer to use "" as default value for optional fields which are str. These fields do not need to accept None values at all

CapturedCallable attributes

Source: https://github.com/mckinsey/vizro/pull/367#issuecomment-1994052080

when it comes to using CapturedCallable we should always prefer to use the highest-level interface possible to avoid delving into private/protected things. There's basically three categories of attributes here:

  • dunder attributes like __call__ and __getitem__: these are the main point of entry to any callers and should be used wherever possible
  • protected attributes like _function and _arguments: ok to use if needed but will be removed or made into proper public things in due course, so put some thought into exactly what you're trying to do and whether you really need to use them or if you can already achieve it just with dunder attributes
  • private attributes like __arguments: you should never need to use these

assert_component_equal

See https://github.com/mckinsey/vizro/pull/195.