2.4. The import component element

An import component element information item (referred to in this specification as an import component element) is an element in the CellML namespace with a local name equal to component, which appears as a child of an import element.

  1. Every import component element MUST contain a name attribute.

    1. The value of the name attribute MUST be a CellML identifier.

    2. The value of the name attribute MUST NOT be identical to the value of the name attribute of any other component or import component element in the CellML infoset.

  1. Every import component element MUST contain a component_ref attribute.

    1. The value of the component_ref attribute MUST be a CellML identifier.

    2. The value of the component_ref attribute MUST be identical to the value of the name attribute on a component or import component element in the imported CellML infoset.

See more

The ablility to import and reuse component items is one of the most powerful features in CellML, as it allows modellers to easily plug-n-play different variations and model parts. There are three ingredients required in importing any item:

  • A destination in the importing model (this is the component item called pi_calculator in the example below),

  • A file to import from, specified using the xlink:href attribute of the parent import block. This is discussed in more detail in 2.2 The import element. In the example below this is the pi_approximators.cellml file.

  • The specific item name to retrieve from the imported file. In the example below this is the circumference_over_diameter value passed to the component_ref attribute.

Thus we can read the import statement below as: “retrieve the component named circumference_over_diameter from the file pi_approximators.cellml, and store it here in this model under the name pi_calculator”.

<import xlink:href="pi_approximators.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
   <component component_ref="circumference_over_diameter" name="pi_calculator"/>
</import>

Things to watch out for:

  1. The namespace. Note that if you’ve already defined the xmlns:xlink namespace inside the <model> tags then you would not need to repeat it here.

  2. The name attribute. Imported items have the same restrictions as locally defined items regarding the uniqueness of their names and their format. In the example below, the name pi_calculator is used for the locally defined component in line 2, but the same name is used as the name for the imported component in line 6. This is not permitted as it violates the uniqueness requirement for names specified above. The second imported component uses an invalid name attribute (see 1.3 Data representation formats in CellML) so is not permitted either.

<model name="circle">
  <component name="pi_calculator">
    ...
  </component>

  <!-- This destination name conflicts with the locally defined name above: -->
  <import xlink:href="series_approx_of_pi.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
    <component component_ref="GregoryLeibnizApproximator" name="pi_calculator"/>
  </import>

  <!-- This destination name is not valid CellML as it contains whitespace and special characters: -->
  <import xlink:href="series_approx_of_pi.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
    <component component_ref="GregoryLeibnizApproximator" name="pi calculator!"/>
  </import>

</model>

  1. The component_ref attribute. This must be a valid CellML identifier (see 1.3 Data representation formats in CellML). It also has to actually exist as a component in the given href location! Neither of the imports below are permitted:

<model name="circle">

  <!-- This component_ref name does not exist at in the file specified: -->
  <import xlink:href="series_approx_of_pi.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
    <component component_ref="I_dont_exist" name="pi_calculator"/>
  </import>

  <!-- This component_ref name is not a valid CellML identifier: -->
  <import xlink:href="series_approx_of_pi.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
    <component component_ref="I have spaces so am not a valid ID" name="pi_calculator"/>
  </import>
</model>