IReport Plugins

Interactive Reports (IReports) are plugins that generate output for Understand to display. Report output and options are accessed through the IReport object provided as a parameter to the init and generate functions.

The generated output can link to entities, locations and comparison database difference views. There are style options such as bold, italic, and color. The output can also be structured as a tree.

An IReport plugin must have a name function and a generate function. The name function identifies the report and the generate function creates the output. At least one test_ function should be defined to indicate when the report is available. A sample plugin is below.

def name():
  """
  Required, the name of the ireport.
  """
  return "Test Report"

#
# The following three functions determine when the report is available.
# If ommitted, they're assumed false.
#
def test_global(db):
  """
  Optional method, return true for project level reports
  """
  return True

def test_entity(ent):
  """
  Optional method, return true if report is valid for the entity
  """
  return True

def test_architecture(arch):
  """
  Optional method, return true if report is valid for the architecture
  """
  return True

#
# Optional methods to support abort
#
def support_abort():
  """
  Optional method, return True if this report can be aborted.

  Use report.is_aborted() to check if an abort has been requested
  """
  return False;

def pages(report,target):
  """
  Optional method for multi-page reports.

  A report can have multiple pages which each become their own html
  page, or are concantenated together in a pdf export. Implement this
  function to return all the pageIds that belong to this report. The
  pageId is used to construct links, and is not shown to the user.
  """
  return []

# Report Options
def init(report,target):
  """
  Optional method, define options that can be changed by the user
  """
  # Define options for the user to configure like this:
  report.options().checkbox("test", "This is a test", True)

# Report generation
def generate(report, target, pageId):
  """
  Required, generate the report

  The pageId parameter is optional. It will be an empty string the first
  time a report is generated. On subsequent generations, it can be any
  value returned from pages() or provided as a pageId to report.pagelink()
  or report.breadcrumbs() functions.
  """
  # If the report can be valid for multiple types of objects, use
  # isinstance to determine the target type.
  if isinstance(target, understand.Arch):
    report.print("arch: ")
  if isinstance(target, understand.Ent):
    report.print("ent: ")
  if isinstance(target, understand.Db):
    report.print("db: ")
  report.bold()
  # This take advantage of the fact that there is a name method
  # for entities, architectures, and datases.
  report.print(target.name())
  report.nobold()
  report.print("\n")

  # retrieve options defined in init like this:
  option = report.options().lookup("test")
  report.print("option: {}\n".format(option))