galaxy/config/plugins/visualizations/visualization.dtd

<!-- each visualization must have a template (all other elements are optional) -->
<!ELEMENT visualization (
  description*,
  data_sources*,
  params*,
  template_root*,
  entry_point,
  render_target*
)>
<!-- visualization
        name: the title/display name of the visualization (e.g. 'Trackster', 'Fastq Stats', etc.) REQUIRED
        disabled: if included (value does not matter), this attribute will prevent the visualization being loaded
        embeddable: if included (value does not matter), indicates that this visualization can be rendered as a DOM
                fragment and won't render to a full page when passed the variable 'embedded' in the query string.
                DEFAULT false.
-->
<!ATTLIST visualization
    name        CDATA #REQUIRED
    disabled    CDATA #IMPLIED
    embeddable  CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>
<!-- a text description of what the visualization does -->

<!ELEMENT data_sources (data_source*)>
<!-- data sources are elements that describe what objects (HDAs, LDDAs, Job, User, etc.)
        are applicable to a visualization. Often these are used to fetch applicable links
        to the visualizations that use them.
-->
  <!ELEMENT data_source (model_class,(test|to_param)*)>
    <!ELEMENT model_class (#PCDATA)>
    <!-- model_class is currently the class name of the object you want to make a visualization
          applicable to (e.g. HistoryDatasetAssociation). Currently only classes in galaxy.model
          can be used.
          REQUIRED and currently limited to: 'HistoryDatasetAssociation', 'LibraryDatasetDatasetAssociation'
    -->
    <!ELEMENT test (#PCDATA)>
    <!-- tests help define what conditions the visualization can be applied to the model_class/target.
          Currently, all tests are OR'd and there is no logical grouping. Tests are run in order.
        (text): the text of this element is what the given target will be compared to (REQUIRED)
        type: what type of test to run (e.g. when the target is an HDA the test will often be of type 'isinstance'
                and test whether the HDA's datatype isinstace of a class).
                See lib/galaxy/visualizations/registry.py, DataSourceParser.parse_tests for test type options.
                DEFAULT: string comparison.
        test_attr: what attribute of the target object should be used in the test. For instance, 'datatype'
                will attempt to get the HDA.datatype from a target HDA. If the given object doesn't have
                that attribute the test will fail (with no error). test_attr can be dot separated attributes,
                looking up each in turn. For example, if the target was a history, one could access the
                history.user.email by setting test_attr to 'user.email' (why you would want that, I don't know)
                DEFAULT: to comparing the object itself (and not any of it's attributes)
        result_type: if the result (the text of the element mentioned above) needs to be parsed into
                something other than a string, result_type will tell the registry how to do this. E.g.
                if result_type is 'datatype' the registry will assume the text is a datatype class name
                and parse it into the proper class before the test (often 'isinstance') is run.
                DEFAULT: no parsing (result should be a string)
    -->
    <!ATTLIST test
        type        CDATA #IMPLIED
        test_attr   CDATA #IMPLIED
        result_type CDATA #IMPLIED
    >

    <!ELEMENT to_param (#PCDATA)>
    <!-- to_param tells the registry how to parse the data_source into a query string param.
          For example, HDA data_sources can set param_to text to 'dataset_id' and param_attr to 'id' and the
            the target HDA (if it passes the tests) will be passed as "dataset_id=HDA.id"
        (text): the query string param key this source will be parsed into (e.g. dataset_id)
                REQUIRED
        param_attr: the attribute of the data_source object to use as the value in the query string param.
                E.g. param_attr='id' for an HDA data_source would use the (encoded) id.
                NOTE: a to_param MUST have either a param_attr or assign
        assign: you can use this to directly assign a value to a query string's param. E.g. if the
                data_source is a LDDA we can set 'hda_or_ldda=ldda' using assign='ldda'.
                NOTE: a to_param MUST have either a param_attr or assign
    -->
    <!ATTLIST to_param
        param_attr  CDATA #IMPLIED
        assign      CDATA #IMPLIED
    >

<!ELEMENT params ((param|param_modifier)*)>
<!-- params describe what data will be sent to a visualization template and
      how to convert them from a query string in a URL into variables usable in a template.
      For example,
     param_modifiers are a special class of parameters that modify other params
      (e.g. hda_ldda can be 'hda' or 'ldda' and modifies/informs dataset_id to fetch an HDA or LDDA)
-->
  <!ELEMENT param (#PCDATA)>
  <!-- param tells the registry how to parse the query string param back into a resource/data_source.
        For example, if a query string has "dataset_id=NNN" and the type is 'dataset', the registry
        will attempt to fetch the hda with id of NNN from the database and pass it to the template.
      (text): the query string param key this source will be parsed from (e.g. dataset_id)
              REQUIRED
      type: the type of the resource.
              Can be: str (DEFAULT), bool, int, float, json, visualization, dbkey, dataset, or hda_ldda.
      default: if a param is not passed on the query string (and is not required) OR the given param
              fails to parse, this value is used instead.
              DEFAULT: None
      required: set this to true if the param is required for the template. Rendering will with an error
              if the param hasn't been sent.
              DEFAULT: false
      csv: set this to true if the param is a comma separated list. The registry will attempt to
              parse each value as the given type and send the result as a list to the template.
              DEFAULT: false
      constrain_to: (currently unused) constain a param to a set of values, error if not valid.
              DEFAULT: don't constrain
      var_name_in_template: a new name for the resource/variable to use in the template. E.g. an initial
              query string param key might be 'dataset_id' in the URL, the registry parses it into an HDA,
              and if var_name_in_template is set to 'hda', the template will be able to access the HDA
              with the variable name 'hda' (as in hda.title).
              DEFAULT: keep the original query string name
  -->
  <!ATTLIST param
      type        CDATA #IMPLIED
      default     CDATA #IMPLIED
      required    CDATA #IMPLIED
      csv         CDATA #IMPLIED
      constrain_to          CDATA #IMPLIED
      var_name_in_template  CDATA #IMPLIED
  >
  <!-- param_modifiers are the same as param but have a REQUIRED 'modifies' attribute.
        'modifies' must point to the param name (the text part of param element) that it will modify.
        E.g. <param_modifier modifies="dataset_id">hda_ldda</param_modifier>
  -->
  <!ELEMENT param_modifier (#PCDATA)>
  <!ATTLIST param_modifier
      modifies    CDATA #REQUIRED
      type        CDATA #IMPLIED
      default     CDATA #IMPLIED
      required    CDATA #IMPLIED
      csv         CDATA #IMPLIED
      constrain_to          CDATA #IMPLIED
      var_name_in_template  CDATA #IMPLIED
  >

<!-- template: the template used to render the visualization. DEPRECATED -->
<!-- <!ELEMENT template (#PCDATA)> -->
<!-- entry_point: the method the registry will use to begin rendering the visualization - a loading point. REQUIRED -->
<!ELEMENT entry_point (#PCDATA)>
<!ATTLIST entry_point
    entry_point_type  CDATA #REQUIRED
>
<!-- render_target: used as the target attribute of the link to the visualization.
      Can be 'galaxy_main', '_top', '_blank'. DEFAULT: 'galaxy_main'
-->
<!-- TODO: rename -> render_target -->
<!ELEMENT render_target (#PCDATA)>