class_docstr: Dashboard class for creating interactive dashboard objects.
  
  Dashboards are dicts that contain boxes which hold plot information.
  These boxes can be arranged in various ways. The most basic form of
  a box is:
  
  ```
  {
      'type': 'box',
      'boxType': 'plot'
  }
  ```
  
  where 'fileId' can be set to the 'username:#' of your plot. The other
  parameters a box takes are `shareKey` (default is None) and `title`
  (default is '').
  
  `.get_preview()` should be called quite regularly to get an HTML
  representation of the dashboard in which the boxes in the HTML
  are labelled with on-the-fly-generated numbers or box ids which
  change after each modification to the dashboard.
  
  `.get_box()` returns the box located in the dashboard by calling
  its box id as displayed via `.get_preview()`.
  
  Example 1: Create a simple Dashboard object
  ```
  import plotly.dashboard_objs as dashboard
  
  box_a = {
      'type': 'box',
      'boxType': 'plot',
      'fileId': 'username:some#',
      'title': 'box a'
  }
  
  box_b = {
      'type': 'box',
      'boxType': 'plot',
      'fileId': 'username:some#',
      'title': 'box b'
  }
  
  box_c = {
      'type': 'box',
      'boxType': 'plot',
      'fileId': 'username:some#',
      'title': 'box c'
  }
  
  my_dboard = dashboard.Dashboard()
  my_dboard.insert(box_a)
  # my_dboard.get_preview()
  my_dboard.insert(box_b, 'above', 1)
  # my_dboard.get_preview()
  my_dboard.insert(box_c, 'left', 2)
  # my_dboard.get_preview()
  my_dboard.swap(1, 2)
  # my_dboard.get_preview()
  my_dboard.remove(1)
  # my_dboard.get_preview()
  ```
  
  Example 2: 4 vertical boxes of equal height
  ```
  import plotly.dashboard_objs as dashboard
  
  box_a = {
      'type': 'box',
      'boxType': 'plot',
      'fileId': 'username:some#',
      'title': 'box a'
  }
  
  my_dboard = dashboard.Dashboard()
  my_dboard.insert(box_a)
  my_dboard.insert(box_a, 'below', 1)
  my_dboard.insert(box_a, 'below', 1)
  my_dboard.insert(box_a, 'below', 3)
  # my_dboard.get_preview()
  ```
docstr: Insert a box into your dashboard layout.
  
  :param (dict) box: the box you are inserting into the dashboard.
  :param (str) side: specifies where your new box is going to be placed
      relative to the given 'box_id'. Valid values are 'above', 'below',
      'left', and 'right'.
  :param (int) box_id: the box id which is used as a reference for the
      insertion of the new box. Box ids are memoryless numbers that are
      generated on-the-fly and assigned to boxes in the layout each time
      .get_preview() is run.
  :param (float) fill_percent: specifies the percentage of the container
      box from the given 'side' that the new box occupies. For example
      if you apply the method
  
      .insert(box=new_box, box_id=2, side='left', fill_percent=20)
  
      to a dashboard object, a new box is inserted 20% from the left
      side of the box with id #2. Run .get_preview() to see the box ids
      assigned to each box in the dashboard layout.
      Default = 50
  Example:
  ```
  import plotly.dashboard_objs as dashboard
  
  box_a = {
      'type': 'box',
      'boxType': 'plot',
      'fileId': 'username:some#',
      'title': 'box a'
  }
  
  my_dboard = dashboard.Dashboard()
  my_dboard.insert(box_a)
  my_dboard.insert(box_a, 'left', 1)
  my_dboard.insert(box_a, 'below', 2)
  my_dboard.insert(box_a, 'right', 3)
  my_dboard.insert(box_a, 'above', 4, fill_percent=20)
  
  my_dboard.get_preview()
  ```
docstr_tok: ["Insert","a","box","into","your","dashboard","layout",".",":","param","(","dict",")","box",":","the","box","you","are","inserting","into","the","dashboard",".",":","param","(","str",")","side",":","specifies","where","your","new","box","is","going","to","be","placed","relative","to","the","given","'box_id","'",".","Valid","values","are","'above","'",",","'below","'",",","'left","'",",","and","'right","'",".",":","param","(","int",")","box_id",":","the","box","id","which","is","used","as","a","reference","for","the","insertion","of","the","new","box",".","Box","ids","are","memoryless","numbers","that","are","generated","on-the-fly","and","assigned","to","boxes","in","the","layout","each","time",".get_preview","(",")","is","run",".",":","param","(","float",")","fill_percent",":","specifies","the","percentage","of","the","container","box","from","the","given","'side","'","that","the","new","box","occupies",".","For","example","if","you","apply","the","method",".insert","(","box=new_box",",","box_id=2",",","side='left","'",",","fill_percent=20",")","to","a","dashboard","object",",","a","new","box","is","inserted","20","%","from","the","left","side","of","the","box","with","id","#","2",".","Run",".get_preview","(",")","to","see","the","box","ids","assigned","to","each","box","in","the","dashboard","layout",".","Default","=","50","Example",":","``","`","import","plotly.dashboard_objs","as","dashboard","box_a","=","{","'type","'",":","'box","'",",","'boxType","'",":","'plot","'",",","'fileId","'",":","'username",":","some","#","'",",","'title","'",":","'box","a'","}","my_dboard","=","dashboard.Dashboard","(",")","my_dboard.insert","(","box_a",")","my_dboard.insert","(","box_a",",","'left","'",",","1",")","my_dboard.insert","(","box_a",",","'below","'",",","2",")","my_dboard.insert","(","box_a",",","'right","'",",","3",")","my_dboard.insert","(","box_a",",","'above","'",",","4",",","fill_percent=20",")","my_dboard.get_preview","(",")","``","`"]
code: def insert(self, box, side="above", box_id=None, fill_percent=50):
      """
      Insert a box into your dashboard layout.
  
      :param (dict) box: the box you are inserting into the dashboard.
      :param (str) side: specifies where your new box is going to be placed
          relative to the given 'box_id'. Valid values are 'above', 'below',
          'left', and 'right'.
      :param (int) box_id: the box id which is used as a reference for the
          insertion of the new box. Box ids are memoryless numbers that are
          generated on-the-fly and assigned to boxes in the layout each time
          .get_preview() is run.
      :param (float) fill_percent: specifies the percentage of the container
          box from the given 'side' that the new box occupies. For example
          if you apply the method\n
          .insert(box=new_box, box_id=2, side='left', fill_percent=20)\n
          to a dashboard object, a new box is inserted 20% from the left
          side of the box with id #2. Run .get_preview() to see the box ids
          assigned to each box in the dashboard layout.
          Default = 50
      Example:
      ```
      import plotly.dashboard_objs as dashboard
  
      box_a = {
          'type': 'box',
          'boxType': 'plot',
          'fileId': 'username:some#',
          'title': 'box a'
      }
  
      my_dboard = dashboard.Dashboard()
      my_dboard.insert(box_a)
      my_dboard.insert(box_a, 'left', 1)
      my_dboard.insert(box_a, 'below', 2)
      my_dboard.insert(box_a, 'right', 3)
      my_dboard.insert(box_a, 'above', 4, fill_percent=20)
  
      my_dboard.get_preview()
      ```
      """
      box_ids_to_path = self._compute_box_ids()
  
      # doesn't need box_id or side specified for first box
      if self["layout"] is None:
          self["layout"] = _container(
              box, _empty_box(), size=MASTER_HEIGHT, sizeUnit="px"
          )
      else:
          if box_id is None:
              raise _plotly_utils.exceptions.PlotlyError(
                  "Make sure the box_id is specfied if there is at least "
                  "one box in your dashboard."
              )
          if box_id not in box_ids_to_path:
              raise _plotly_utils.exceptions.PlotlyError(
                  ID_NOT_VALID_MESSAGE
              )
  
          if fill_percent < 0 or fill_percent > 100:
              raise _plotly_utils.exceptions.PlotlyError(
                  "fill_percent must be a number between 0 and 100 "
                  "inclusive"
              )
          if side == "above":
              old_box = self.get_box(box_id)
              self._insert(
                  _container(
                      box,
                      old_box,
                      direction="vertical",
                      size=fill_percent,
                  ),
                  box_ids_to_path[box_id],
              )
          elif side == "below":
              old_box = self.get_box(box_id)
              self._insert(
                  _container(
                      old_box,
                      box,
                      direction="vertical",
                      size=100 - fill_percent,
                  ),
                  box_ids_to_path[box_id],
              )
          elif side == "left":
              old_box = self.get_box(box_id)
              self._insert(
                  _container(
                      box,
                      old_box,
                      direction="horizontal",
                      size=fill_percent,
                  ),
                  box_ids_to_path[box_id],
              )
          elif side == "right":
              old_box = self.get_box(box_id)
              self._insert(
                  _container(
                      old_box,
                      box,
                      direction="horizontal",
                      size=100 - fill_percent,
                  ),
                  box_ids_to_path[box_id],
              )
          else:
              raise _plotly_utils.exceptions.PlotlyError(
                  "If there is at least one box in your dashboard, you "
                  "must specify a valid side value. You must choose from "
                  "'above', 'below', 'left', and 'right'."
              )
  
      self._set_dashboard_size()
  
imports: import pprint
  import _plotly_utils.exceptions
  from _plotly_utils import optional_imports
  from chart_studio import exceptions
label_desc: Use image node_id 9 for calling the Dashboard obj's underlying member method code with example usage: obj.insert(box, side, box_id, fill_percent) without return types