diff --git a/dsl/adrs.md b/dsl/adrs.md index be554ed..dc1ff83 100644 --- a/dsl/adrs.md +++ b/dsl/adrs.md @@ -2,7 +2,7 @@ layout: default title: Architecture Decision Records (ADRs) parent: Structurizr DSL -nav_order: 9 +nav_order: 10 permalink: /dsl/adrs --- diff --git a/dsl/basics.md b/dsl/basics.md index 3c73153..ab7d8cf 100644 --- a/dsl/basics.md +++ b/dsl/basics.md @@ -2,7 +2,7 @@ layout: default title: Basics parent: Structurizr DSL -nav_order: 2 +nav_order: 3 permalink: /dsl/basics --- diff --git a/dsl/cookbook/index.md b/dsl/cookbook/index.md index 95cd3f4..f48e2a4 100644 --- a/dsl/cookbook/index.md +++ b/dsl/cookbook/index.md @@ -1,7 +1,7 @@ --- layout: default title: Cookbook -nav_order: 13 +nav_order: 21 parent: Structurizr DSL has_children: true permalink: /dsl/cookbook/ diff --git a/dsl/defaults.md b/dsl/defaults.md index 03f97dc..089b775 100644 --- a/dsl/defaults.md +++ b/dsl/defaults.md @@ -2,7 +2,7 @@ layout: default title: Defaults parent: Structurizr DSL -nav_order: 3 +nav_order: 4 permalink: /dsl/defaults --- diff --git a/dsl/docs.md b/dsl/docs.md index 1e4e4b0..53ae042 100644 --- a/dsl/docs.md +++ b/dsl/docs.md @@ -2,7 +2,7 @@ layout: default title: Markdown/Asciidoc documentation parent: Structurizr DSL -nav_order: 8 +nav_order: 9 permalink: /dsl/docs --- diff --git a/dsl/example.md b/dsl/example.md index 01e1352..3c02983 100644 --- a/dsl/example.md +++ b/dsl/example.md @@ -15,14 +15,14 @@ an associated __view__ that describes a user using a software system. workspace { model { - user = person "User" - softwareSystem = softwareSystem "Software System" + u = person "User" + ss = softwareSystem "Software System" - user -> softwareSystem "Uses" + u -> ss "Uses" } views { - systemContext softwareSystem { + systemContext ss { include * autolayout lr } diff --git a/dsl/expressions.md b/dsl/expressions.md index 9a92a8b..5c73f93 100644 --- a/dsl/expressions.md +++ b/dsl/expressions.md @@ -2,7 +2,7 @@ layout: default title: Expressions parent: Structurizr DSL -nav_order: 6 +nav_order: 7 permalink: /dsl/expressions --- diff --git a/dsl/identifiers.md b/dsl/identifiers.md index bbed004..1dd175f 100644 --- a/dsl/identifiers.md +++ b/dsl/identifiers.md @@ -2,7 +2,7 @@ layout: default title: Identifiers parent: Structurizr DSL -nav_order: 5 +nav_order: 6 permalink: /dsl/identifiers --- diff --git a/dsl/includes.md b/dsl/includes.md index ada94d9..2116da1 100644 --- a/dsl/includes.md +++ b/dsl/includes.md @@ -2,7 +2,7 @@ layout: default title: Includes parent: Structurizr DSL -nav_order: 6 +nav_order: 7 permalink: /dsl/includes --- diff --git a/dsl/language.md b/dsl/language.md index 98d0b4f..2d9a1d0 100644 --- a/dsl/language.md +++ b/dsl/language.md @@ -2,7 +2,7 @@ layout: default title: Language reference parent: Structurizr DSL -nav_order: 12 +nav_order: 13 permalink: /dsl/language --- diff --git a/dsl/plugins.md b/dsl/plugins.md index 1781a59..e870972 100644 --- a/dsl/plugins.md +++ b/dsl/plugins.md @@ -2,7 +2,7 @@ layout: default title: Plugins parent: Structurizr DSL -nav_order: 11 +nav_order: 12 permalink: /dsl/plugins --- diff --git a/dsl/scripts.md b/dsl/scripts.md index 215c44b..707edf0 100644 --- a/dsl/scripts.md +++ b/dsl/scripts.md @@ -2,7 +2,7 @@ layout: default title: Scripts parent: Structurizr DSL -nav_order: 10 +nav_order: 11 permalink: /dsl/scripts --- diff --git a/dsl/tutorial.md b/dsl/tutorial.md new file mode 100644 index 0000000..092ad99 --- /dev/null +++ b/dsl/tutorial.md @@ -0,0 +1,307 @@ +--- +layout: default +title: Tutorial +parent: Structurizr DSL +nav_order: 2 +permalink: /dsl/tutorial +--- + +# Tutorial + +This tutorial provides a good starting point for learning how to use the Structurizr DSL. It will use the [Structurizr DSL demo page](https://structurizr.com/dsl) and doesn't require any special tooling to be installed. + +## 1. System context + +Let's start the tutorial with a basic example of how to use the DSL. The starting point is to define a Structurizr +`workspace`, which itself is a wrapper for a model (where we define elements and relationships) +and a set of views (where we define the views that will ultimately be rendered as diagrams). + +``` +workspace { +} +``` + +The `model` keyword can be used to define our software architecture model, which in this example comprises +a `person` named "User" (assigned to an identifier `u`) and a `softwareSystem` named "Software System" (assigned to an identifier `ss`). +A relationship is then defined between the user and the software system using the `->` symbol, with a description of "Uses". + +``` +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" + + u -> ss "Uses" + } + +} +``` + +We can then define a single [system context view](/dsl/language#systemcontext-view), with the software system `ss` +being the scope of this view. + +``` +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" + + u -> ss "Uses" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + } + +} +``` + +The `include *` statement says, +"include the software system that is the scope of this view, along with any people and software systems that have a +direct relationship to/from it". +Finally, the `autolayout lr` statement says that automatic layout should be used, with a left to right direction. +`Diagram1` is a unique diagram identifier/key that can be used to reference the diagram, for example, via the +[Structurizr on-premises diagram embed feature](/onpremises/embed). + +Running this example via the Structurizr DSL demo page (click the image below) results in the following diagram. + +[![](/dsl/tutorial/1.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/1.dsl) + +## 2. Containers + +Next we can define the containers (applications and data stores) that make up our software system, by adding a couple of +`container` definitions nested inside the software system (inside the curly braces). +We can also define a relationship from the user to the web application, and from the web application to the database. + +``` +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" + } + + u -> ss "Uses" + u -> wa "Uses" + wa -> db "Reads from" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + } + +} +``` + +The model is non-visual, so we need to define a [container view](/dsl/language#container-view), again with the software system `ss` +being the scope of this view. + +``` +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" + } + + u -> ss "Uses" + u -> wa "Uses" + wa -> db "Reads from" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + + container ss "Diagram2" { + include * + autolayout lr + } + } + +} +``` + +The `include *` statement now says, "include the containers inside the software system that is the scope of this view, along with any people and software systems that have a +direct relationship to/from them". The `autolayout lr` statement is the same as before. + +The example DSL creates two diagrams. First we have the system context diagram as before. + +[![](/dsl/tutorial/2-1.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/2.dsl&view=Diagram1) + +And if you double-click on the software system, you'll navigate to the container diagram. + +[![](/dsl/tutorial/2-2.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/2.dsl&view=Diagram2) + +## 3. Implied relationships + +"Don't repeat yourself" (DRY) is something that we always tell ourselves as software developers, yet that's essentially +what we've done with the relationship from the user to the software system, and from the user to the web application. + +``` + u -> ss "Uses" + u -> wa "Uses" + wa -> db "Reads from" +``` + +The Structurizr DSL has a feature named [implied relationships](/dsl/cookbook/implied-relationships/), which provides a +way to reduce the number of relationships that you need to explicitly define in your DSL files. In this example, we +can remove the first relationship definition, leaving only the latter two. + +``` + u -> wa "Uses" + wa -> db "Reads from" +``` + +The resulting diagrams are the same. There is an explicit relationship from the user to the web application, +and because the web application is a container inside the software system, +there is an implicit (or implied) relationship between the user and the software system itself. + +[![](/dsl/tutorial/3-1.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/3.dsl&view=Diagram1) + +## 4. View expressions + +Both of the view definitions use the `include *` statement, which provides a convenient way to include a default +set of elements that readers may want to see. But the DSL includes a number of other [expressions](/dsl/expressions) that can be used to +`include` or `exclude` elements and relationships. + +In this example, all the following are equivalent and will produce the same diagram: + +Include the default set of elements. + +``` + container ss "Diagram2" { + include * + autolayout lr + } +``` + +Include the user, web application, and database explicitly. + +``` + container ss "Diagram2" { + include u wa db + autolayout lr + } +``` + +Include the user, web application, and database explicitly (separate lines). + +``` + container ss "Diagram2" { + include u + include wa db + autolayout lr + } +``` + +Include the web application, plus the inbound and outbound dependencies. + +``` + container ss "Diagram2" { + include "->wa->" + autolayout lr + } +``` + +Include elements of type `container`, plus the inbound and outbound dependencies. + +``` + container ss "Diagram2" { + include "->element.type==container->" + autolayout lr + } +``` + +Include children of the software system, plus the inbound and outbound dependencies. + +``` + container ss "Diagram2" { + include "->element.parent==ss->" + autolayout lr + } +``` + +## 5. Styling elements + +Let's add some colours and shapes to our diagrams. Every element and relationship has a set of text-based tags +associated with it - much in the same way that HTML elements can have one or more CSS classes. +All elements have an `Element` tag, while people additionally have a `Person` tag, +software systems have a `Software System` tag, and containers have a `Container` tag. +Styling elements can be achieved by creating an [element style](/dsl/cookbook/element-styles/) for a given tag. + +``` + views { + ... + + styles { + element "Element" { + color white + } + element "Software System" { + background #2D882D + } + element "Person" { + background #116611 + shape person + } + } + } +``` + +This code: + +- sets the foreground colour of all elements to white +- sets the background colour of all software systems to green +- sets the background colour of all people to a darker green +- sets the shape of all people to a person shape + +[![](/dsl/tutorial/5-1.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/5.dsl&view=Diagram1) + +Changing the shape of the database schema element is a two-step process. +First we need to add a custom tag (in this case `Database` to the element). + +``` + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" { + tags "Database" + } + } +``` + +And then we can define an element style for that `Database` tag. + +``` + styles { + ... + element "Container" { + background #55aa55 + } + element "Database" { + shape cylinder + } + } +``` + +We have additionally added an element style for the `Container` tag, to set the colour of all containers to a lighter green. + +[![](/dsl/tutorial/5-2.png)](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/tutorial/5.dsl&view=Diagram2) + +Clicking the "i" button inside the diagram editor will reveal the automatically generated diagram key for that particular diagram. + +![](/dsl/tutorial/5-3.png) diff --git a/dsl/tutorial/1.dsl b/dsl/tutorial/1.dsl index 8535dbd..281409e 100644 --- a/dsl/tutorial/1.dsl +++ b/dsl/tutorial/1.dsl @@ -8,7 +8,7 @@ workspace { } views { - systemContext ss { + systemContext ss "Diagram1" { include * autolayout lr } diff --git a/dsl/tutorial/2-1.png b/dsl/tutorial/2-1.png new file mode 100644 index 0000000..2c23e0f Binary files /dev/null and b/dsl/tutorial/2-1.png differ diff --git a/dsl/tutorial/2-2.png b/dsl/tutorial/2-2.png new file mode 100644 index 0000000..7f893e6 Binary files /dev/null and b/dsl/tutorial/2-2.png differ diff --git a/dsl/tutorial/2.dsl b/dsl/tutorial/2.dsl new file mode 100644 index 0000000..079bc0c --- /dev/null +++ b/dsl/tutorial/2.dsl @@ -0,0 +1,27 @@ +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" + } + + u -> ss "Uses" + u -> wa "Uses" + wa -> db "Reads from" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + + container ss "Diagram2" { + include * + autolayout lr + } + } + +} \ No newline at end of file diff --git a/dsl/tutorial/3-1.png b/dsl/tutorial/3-1.png new file mode 100644 index 0000000..2c23e0f Binary files /dev/null and b/dsl/tutorial/3-1.png differ diff --git a/dsl/tutorial/3.dsl b/dsl/tutorial/3.dsl new file mode 100644 index 0000000..e5779d5 --- /dev/null +++ b/dsl/tutorial/3.dsl @@ -0,0 +1,26 @@ +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" + } + + u -> wa "Uses" + wa -> db "Reads from" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + + container ss "Diagram2" { + include * + autolayout lr + } + } + +} \ No newline at end of file diff --git a/dsl/tutorial/5-1.png b/dsl/tutorial/5-1.png new file mode 100644 index 0000000..3ff39ab Binary files /dev/null and b/dsl/tutorial/5-1.png differ diff --git a/dsl/tutorial/5-2.png b/dsl/tutorial/5-2.png new file mode 100644 index 0000000..6b0ac49 Binary files /dev/null and b/dsl/tutorial/5-2.png differ diff --git a/dsl/tutorial/5-3.png b/dsl/tutorial/5-3.png new file mode 100644 index 0000000..f4cb2dd Binary files /dev/null and b/dsl/tutorial/5-3.png differ diff --git a/dsl/tutorial/5.dsl b/dsl/tutorial/5.dsl new file mode 100644 index 0000000..e0f1ce1 --- /dev/null +++ b/dsl/tutorial/5.dsl @@ -0,0 +1,47 @@ +workspace { + + model { + u = person "User" + ss = softwareSystem "Software System" { + wa = container "Web Application" + db = container "Database Schema" { + tags "Database" + } + } + + u -> wa "Uses" + wa -> db "Reads from" + } + + views { + systemContext ss "Diagram1" { + include * + autolayout lr + } + + container ss "Diagram2" { + include * + autolayout lr + } + + styles { + element "Element" { + color white + } + element "Software System" { + background #2D882D + } + element "Person" { + background #116611 + shape person + } + element "Container" { + background #55aa55 + } + element "Database" { + shape cylinder + } + } + } + +} \ No newline at end of file diff --git a/dsl/workspace-extension.md b/dsl/workspace-extension.md index 7edf56c..a721e1d 100644 --- a/dsl/workspace-extension.md +++ b/dsl/workspace-extension.md @@ -2,7 +2,7 @@ layout: default title: Workspace extension parent: Structurizr DSL -nav_order: 7 +nav_order: 8 permalink: /dsl/workspace-extension ---