SVG file declarations

Before any other CIF/SVG declarations can be specified, you need to indicate to which SVG image (file) they apply, using an SVG file declaration. A typical SVG file declaration looks like this:

svgfile "some_file.svg";

The SVG files are declared based on their file names. If possible, it is recommended to use the same file name for the CIF specification and for the SVG image, only with different file extensions. This way, it is easy to see which images goes with which CIF specification.

Paths

It is possible to use relative (or absolute) paths for the SVG files. For instance:

svgfile "svg_files/some_file.svg";
svgfile "../images/some_file.svg";

For the first SVG file declaration, the tools will look for an svg_files directory in the same directory as the CIF file, and for a some_file.svg file in that svg_files directory. For the second SVG file declaration, the tools will look for an images directory in the parent directory of the directory that contains the CIF file, and for a some_file.svg file in that images directory.

Files and directories are separated using slashes (/), regardless of the used operating system. It is also allowed to use backslashes (\), which are more common on Microsoft Windows operating systems, but they need to be escaped as \\ for this to work, making it easier to use slashes (/) instead.

Scoping

CIF/SVG file declarations (and all 'other' CIF/SVG declarations) can be specified in all components. That is, they can be specified in the top level scope of the specification, in groups and group definitions, as well as in automata and automaton definitions. An SVG file declaration that is specified in a certain scope applies to that scope, as well as all child scopes that don’t have an SVG file declaration of their own. Additionally, all 'other' CIF/SVG declarations (such as SVG output mappings) may include a local SVG file declaration, that only applies to that specific CIF/SVG declaration.

For instance, consider the following CIF specification:

svgfile "file1.svg";

svgout id "a" attr "b" value 5;

svgout id "c" attr "d" value 6 file "file2.svg";

group g:
  svgfile "file3.svg";

  svgout id "e" attr "f" value 7;

  svgout id "g" attr "h" value 8;

  svgout id "i" attr "j" value 9 file "file4.svg";

  group h:
    svgfile "file5.svg";
  end

  group i:
    svgout id "k" attr "l" value 10;
  end
end

The mapping for the SVG element with id a is declared in the top level scope of the specification, and does not have a local SVG file declaration. As such, the SVG file declaration from the top level scope (file1.svg) applies to it. The mapping for the SVG element with id b is declared in the same scope, but has a local SVG file declaration (file2.svg). The local SVG file declaration (file2.svg) overrides the SVG file declaration from the top level scope (file1.svg).

Group g also has an SVG file declaration (file3.svg). This overrides the SVG file declaration from the top level scope (file1.svg). The SVG file declaration from group g (file3.svg) thus applies to the mappings for ids e and g, as they are declared in the same scope, and don’t have local SVG file declarations. The mapping for SVG element id i has a local SVG file declaration (file4.svg), and as such the SVG file declaration from group g (file3.svg) does not apply to it.

The SVG file declaration (file5.svg) from group g.h does not apply to any mappings. The image is connected to the model, but its is not updated based on the state of the model.

Group g.i does not have an SVG file declaration, so the SVG file declaration (file3.svg) from group g (the parent scope of group g.i) applies to the mapping for SVG element id k.

See also the Push SVG file declarations into other CIF/SVG declarations CIF to CIF transformation.

Completeness and uniqueness

Every CIF/SVG declaration that is not itself an SVG file declaration, requires an SVG file declaration, in its scope, in one of its ancestor scopes, or locally in that CIF/SVG declaration itself.

In each scope, there may be at most one SVG file declaration.

In every scope (or component), in principle at most one SVG file declaration may be specified. The exception is that for a single scope, specified in multiple CIF files (when imports are used), if the SVG file declarations refer to the same image file, they are merged. If however the two CIF files refer to different image files, this is still considered an error. It is also considered an error if two SVG file declarations are present in a single scope, in a single file, regardless of whether they refer to the same image file or not. In the end, after processing imports, for every scope there must be a unique SVG file declaration, if one is declared at all.

If the same SVG image file is specified multiple times, in different SVG file declarations, the corresponding image is connected to the model only once. For instance, consider the following CIF specification:

svgout id "..." attr "..." value 5 file "some_file.svg";

svgout id "..." attr "..." value 6 file "some_file.svg";

Even though both output mappings specify an SVG file locally, they use the same file. The SVG image will thus be connected to the model only once, and both mappings apply to the same image.