Make a matrix editable

In the Syside VS Code Extension, an editable matrix adds and removes relationships from the matrix itself. This guide turns an existing read-only matrix into an editable one, which takes two things in the view: isEditable = true, and a cellView filter that admits exactly one of the six kinds of relationship a matrix can create.

Before you start:

  • You have a matrix view that shows its rows, columns and cells, as built in Build a matrix view.

  • The model loads without errors. A matrix over a model with errors is read-only.

Choose usage or definition traceability

Decide whether the matrix traces usages, such as engine and transmission inside one Powertrain, or definitions, such as Engine and Transmission wherever they are used. A relationship between usages never strongly marks a cell between definitions, or the other way round, so keep the rows, columns and relationships all on the side you choose. Usage and definition traceability explains the difference.

Allow exactly one kind of relationship

Add a cellView filter that admits exactly one of the six kinds of relationship. That kind is what every new cell creates. A filter that admits none or several leaves the matrix read-only. Take the filter from the table in Relationship kinds, from the usage or the definition row of the kind you want:

view :>> cellView {
    expose Drone;
    filter hastype SysML::AllocationUsage;
}

This filter is for usage traceability. For definition traceability, use the definition row instead, such as hastype SysML::AllocationDefinition, so that it matches the definitions on the rows and columns.

Write the filter exactly as in the table. Two close variants admit more than one kind:

  • istype instead of hastype. istype also matches more specific kinds, and allocations and derivations are both connections, so istype SysML::ConnectionUsage admits three kinds. hastype matches one kind exactly.

  • The derivation metadata on its own. Both a derivation usage and a derivation definition carry the metadata, so a derivation filter also names the usage or definition kind.

Point the cell view at where relationships go

New relationships are written where the cellView expose points, so the expose depends on the side you chose (What an editable matrix writes explains why).

Usage traceability writes into one context. Expose that one element by name, without ::* or ::**, and make sure every row and column element appears inside it exactly once:

view functionAllocation : MVD::MatrixView {
    view :>> rowView {
        expose Drone::*;
        filter hastype SysML::ActionUsage;
    }
    view :>> columnView {
        expose Drone::*;
        filter hastype SysML::PartUsage;
    }
    view :>> cellView {
        expose Drone;
        filter hastype SysML::AllocationUsage;
        attribute :>> direction = Dir::row2col;
    }
}

New allocations go into Drone. The cell view still reads every allocation inside it.

Definition traceability writes into a package, which can start out empty, such as package Interfaces;. The first expose of the cell view names it, and exposing its members with ::* makes the matrix read new definitions back:

view componentLinks : MVD::MatrixView {
    view :>> rowView {
        expose Components::*;
    }
    view :>> columnView {
        expose Components::*;
    }
    view :>> cellView {
        expose Interfaces::*;
        filter hastype SysML::ConnectionDefinition;
    }
}

New connection definitions go into Interfaces, which has to be writable, not a library.

For derivations, the direction decides which side becomes the #original end and which the #derive end. Set direction = Dir::row2col to make the row the original requirement in every cell, or leave the matrix undirected and choose per cell. Both rows and columns must be requirements.

Relationship kinds lists the exact SysML each kind writes.

Turn on editing

With the filter and the expose in place, set isEditable on the matrix view:

view functionAllocation : MVD::MatrixView {
    attribute :>> isEditable = true;

    // rowView and columnView as above

    view :>> cellView {
        expose Drone;
        filter hastype SysML::AllocationUsage;
        attribute :>> direction = Dir::row2col;
    }
}

Both are needed. isEditable = true without the filter leaves the matrix read-only, because the cellView then admits all six kinds of relationship and the matrix has no single kind to create. A banner lists the six. The filter without isEditable only narrows which relationships mark cells. The matrix offers no editing.

Check that it worked

Check that the matrix creates a relationship:

  1. Right-click an empty cell. Add Traceability should be enabled, and hovering it names the kind of relationship it creates.

  2. Choose Add Traceability. In an undirected matrix, first choose the direction from its submenu. The cell should be marked, and the relationship should appear in the model.

If the matrix opens read-only, its banner says why: the filter admits no kind or more than one, or the cell view does not expose what the side needs. If only some rows or columns are disabled, hover the warning on their header. Common reasons:

  • A usage row or column is not inside the cell view’s context, or appears there more than once.

  • A row or column is on the wrong side: a usage in a matrix that writes definitions, or the other way round.

  • The element has no name, so no path to it can be written.

  • In a derivation matrix, the element is not a requirement.

Continue with Matrix views UI for the rest of working in an open matrix, or see A matrix opened as read-only if it still opens read-only.