Accessing Elements
In this chapter, we're going to learn how to access elements. Before you read this chapter, you
need to have clear understanding of the difference between software model and diagram as well
as model elements and view elements. If you don't know about this, please read Basic Concepts
first.
In the following sections, we will use an example software model as shown in the below figure.
Actual model file can be obtained from here: https://github.com/staruml/staruml-dev-docs/blob/
master/samples/Book.mdj. There are two classes Book and Author and a association wrote
connecting between the two classes. In addition, there is a diagram named Main which
containing three view elements, each corresponds to Book, Author, wrote respectively. All these
elements and a diagram are contained by a model named Model which is also contained by the
top-level project element named Book Sample.
Getting a top-level project
First we will access to the top-level project element. The top-level project element can be
obtained by using app.project .
var project = app.project.getProject()
console.log(project.name) // "Book Sample"
Note
all Javascript code examples can be executed in console (select Debug > Show DevTools
and then click Console tab).
The obtained element is just a Javascript object, so you can access to any fields such as
project.name or project.ownedElements[0] . Printing the element itself in console like
console.log(project) is helpful to get all information about the element.
Inspecting elements
Then, how can we know which classes of elements are available and which attributes or
operations are available for each class of elements? You can find documentations of the
metamodel at Metamodel documentation or additionally at API Reference.
You can access to any elements via the top-level project. Containment structure is shown in
Explorer of the above capture image.
var model = project.ownedElements[0]
console.log(model.name) // "Model"
var mainDiagram = model.ownedElements[0]
console.log(mainDiagram.name) // "Main"
var book = model.ownedElements[1]
var author = model.ownedElements[2]
console.log(book.name) // "Book"
console.log(author.name) // "Author"
var association = book.ownedElements[0]
console.log(association.name) // "wrote"
console.log(association.end1.name) // "publications"
console.log(association.end1.multiplicity) // "1..*"
console.log(association.end2.name) // "authors"
console.log(association.end2.multiplicity) // "1..*"
var bookISBN = book.attributes[0]
console.log(bookISBN.name) // "ISBN"
console.log(bookISBN.type) // "String"
console.log(bookISBN.visibility) // "public"
console.log(bookISBN.isID) // true
So far we inspected model elements only, now you will see the view elements contained by the
diagram Main.
var bookView = mainDiagram.ownedViews[0]
console.log(bookView.left) // 32
console.log(bookView.top) // 20
console.log(bookView.width) // 114
console.log(bookView.height) // 103
console.log(bookView.fillColor) // "#ffffff"
console.log(bookView.model.name) // "Book"
console.log(bookView.model === book) // true
var authorView = mainDiagram.ownedViews[1]
...
Each element has a corresponding Javascript class definition. The class definitions are in a global
variable type .
console.log(project instanceof type.Project) // true
console.log(model instanceof type.UMLModel) // true
console.log(mainDiagram instanceof type.UMLClassDiagram) // true
console.log(book instanceof type.UMLClass) // true
console.log(bookISBN instanceof type.UMLAttribute) // true
console.log(association instanceof type.UMLAssociation) // true
console.log(bookView instanceof type.UMLClassView) // true
Retrieving elements by query
Accessing elements from the top-level project is very inconvenient and tedious. How can we get
all elements of UMLClass type? To retrieve elements easily, StarUML provides a very simple query
expression.
Following are several examples for query expression. To see the full specification of query
expression, refer to https://github.com/staruml/metadata-json/wiki/SelectorExpression.
app.repository.select("@Project")
// returns elements of type.Project: [Project]
app.repository.select("@UMLClass")
// returns elements of type.UMLClass: [Book, Author]
app.repository.select("Model::Book")
// returns elements named "Book" contained by an element named "Model": [Book]
app.repository.select("Book.attributes")
// returns elements in 'attributes' field of an element named "Book": [ISBN,
title, summary, publisher]
app.repository.select("@UMLAttribute[type=String]")
// returns elements of type.UMLAttribute only if whose 'type' field has "String"
value: [ISBN, title, summary, publisher, name, biography]
Creating and Modifying Elements
In this chapter, we're goint to learn how to create and modify elements.
The most important is that you should not create or modify elements directly like var class1 =
new UMLClass() or class1.name = "New Name" because all changes should be done via
operations which supports by undo and redo.
Creating elements
Creating a model element
You can call createModel function of app.factory to create a model element with an option
object.
The option object may have following fields:
id : ID of factory function to create an element. To see the full ID list, execute
app.factory.getModelIds() .
parent : A parent element where the created element to be contained.
field (optional) : Field name of the parent element (default is ownedElements ).
modelInitializer (optional) : A function to initialize the created model element.
// Get a reference to top-level project
var project = app.repository.select("@Project")[0]
// Create a UMLModel element as a child of project
var model1 = app.factory.createModel({ id: "UMLModel", parent: project })
// Create a UMLClass element as a child of the model
var class1 = app.factory.createModel({ id: "UMLClass", parent: model1 })
// Create a UMLAttribute element and add to the field 'attributes' of the class
var attr1 = app.factory.createModel({ id: "UMLAttribute", parent: class1, field:
"attributes" })
// Create a UMLClass with options
var options = {
id: "UMLClass",
parent: model1,
modelInitializer: function (elem) {
elem.name = "MyClass";
elem.isAbstract = true;
}
}
var class2 = app.factory.createModel(options);
You can see the created elements in Model Explorer and undo and redo are available for each
creation.
Creating a diagram
Call createDiagram function of app.factory to create a diagram with an option object:
The option object may have following fields:
id : ID of Factory function to create a diagram. To see the full ID list, execute
app.factory.getDiagramIds() .
parent : A parent element where the created diagram to be contained.
options (optional) : An object containing the below options.
diagramInitializer (optional) : A function to initialize the created diagram.
// Get a reference to top-level project
var project = app.repository.select("@Project")[0]
// Create a UMLModel element as a child of project
var model1 = app.factory.createModel({ id: "UMLModel", parent: project })
// Create a UMLClassDiagram as a child of the model
var diagram1 = app.factory.createDiagram({ id: "UMLClassDiagram", parent: model1
})
// Create a UMLClassDiagram with options
var options = {
id: "UMLClassDiagram",
parent: model1,
diagramInitializer: function (dgm) {
dgm.name = "MyDiagram";
dgm.defaultDiagram = true;
}
}
var diagram2 = app.factory.createDiagram(options)
Creating a model element and a view element at once
Call createModelAndView function of app.factory to create a model element and a view
element at once with an option object.
The option object may have following fields:
id : ID of Factory function. To see the full ID list, execute Factory.getModelAndViewIds() .
parent : A parent element where the created model element to be contained.
diagram : A diagram element where the created view element to be contained.
modelInitializer (optional) : A function to initialize the created model element.
viewInitializer (optional) : A function to initialize the created view element.
x1 , y1 , x2 , y2 (optional) : Rectangle coordinate to initialize position and size of the
created view element.
tailView , headView (optional) : If you try to create a relationship (e.g. UMLAssociation ),
the created view element connects these two view elements tailView and headView .
tailModel , and headModel (optional) : If you try to create a relationship, the created model
element connects these two model elements tailModel and headModel .
containerView (optional) : A view element where the created view element to be
contained.
The function createModelAndView returns the created view element, so you need to get the
create model element by accessing model field. (e.g. classView1.model ). Following code will
create two classes and a association connecting the two classes.
