Storyboard projects generally keep all of the model structure within a single application model file. For large products that have very discrete and well separated areas of development, then Storyboard offers the possibility of segmenting this functionality into multiple application development model files. How to create multiple model files is created is introduced in Working with Multiple Application Design Files. Once multiple model files are created, then development can proceed in the same fashion as described in the chapters on general application development.
When it comes time to relate the disparate model files to one another and simulate and export the result, there are some differences from the standard Storyboard development process that are worth considering.
Screen transitions provide the means to tie together multiple applications to form a single, larger, unified application.
In order to indicate that one application (the source application) will be making a reference to screens in another application (external reference), the source application should list the external application in its Properties. Go to Application > Properties > External Model References
Once an application is added as an external reference, the screens from that application will show up in any of the Screen transition selection lists as well as any animation definitions..
Layers from any listed external applications can be added to an application by explicitly importing them using:
Add > Existing Layer > Import External Layer
Once a layer is added as an external layer, then a copy of the original layer from the external application is snapshot and incorporated directly into the source application. At this point, the external layer can be used with any source application screens just like any other layers.
Once applications have been developed, shared content leveraged, and transitions between application screens established the next step is to simulate or export the unified application.
The Storyboard simulation configuration dialog, accessed via Run > Storyboard Simulator Configurations allows multiple model files to be specified. All models in the 'Selected Models' block will be included in the application when launched.
The first source application in the list (tagged as Primary) will be used to determine the unified application's launch screen.
Similarly exporting a runtime application to be used with Storyboard Engine, Android, or iOS targets also allows multiple Storyboard application files to be selected. In these export scenarios, you will be prompted to select the source application that should be used for the unified application's launch screen.
If there are no conflicts among the selected applications they will be merged together and converted into a single unified application and used for the user-selected operation of simulation or export.
If there are conflicts among the resources then the differences will need to be resolved before continuing with an application merge.
When multiple applications are merged together to form a unified application, the following occurs:
-
All layers from all applications are assembled together into a unified list of available layers. If two or more layer names are the same then those layers have their content compared. If the content is identical then the merge continues. If the layer content differs, then an error is flagged and the user will be prompted to resolve the differences and the application merge stops.
-
All application/global level variables from all applications are assembled together into a unified list of global variables. If two or more variable names are the same then those variables have their values compared. If the values are identical then the merge continues. If the variable values differ, then an error is flagged and the user will be prompted to resolve the differences and the application merge stops.
-
All animation definitions from all applications are assembled together into a unified list of available animations. If two or more animation names are the same then those animations have their definitions compared. If the animation definitions are identical, the merge continues. If the animation definitions differ, then an error is flagged and the user will be prompted to resolve the differences and the application merge stops.
-
All screens from all applications are assembled together into a unified list of available screens. If two or more screens have the same name, then an error is immediately flagged and the user is prompted to resolve the differences.
The external referencing of model elements relies on names remaining consistent during the application development. In some instances, if names change it may be possible for content to become unsynchronized and it may need to be resynchronized on an application by application basis.
The application properties page provides a synchronization action that scans the project for externally referenced content and then compares that content to the source reference. If there is a difference, then the difference is flagged as a conflict for resolution and the user is prompted for different ways to solve the conflict based on the nature of the issue
To integrate Storyboard Comparator into your git workflow is pretty straightforward. This article will walk you through the setup steps for developers as well as for the integration infrastructures such as GitLab or Bitbucket.
Prerequisites: You have already installed Storyboard Comparator on the server or desktop.
Note
Storyboard Comparator automatically gets installed along with Storyboard Designer.
-
Setup your project to point to the Storyboard compare for .gde merges
In your project’s root directory include a .gitattributes file and add the following line
*.gde merge=mergegde
-
Next, you need to set up the .gitconfig in your home directory to configure the git merge driver
Infrastructure recommended settings:
[merge "mergegde"] driver=\"C:\\Program Files\\Storyboard_Comparator\StoryboardComparator.exe" -quiet -headless -output=%A %O %A %BDeveloper recommended settings:
[merge "mergegde"] driver=\""C:\\Program Files\\Storyboard_Comparator\\StoryboardComparator.exe\" -quiet -output=%A %O %A %B [mergetool "mergegde"] cmd = \""C:\\Program Files\\Storyboard_Comparato\\StoryboardComparator.exe\" -quiet $BASE $LOCAL $REMOTE -output=./Project/MyProject.gde trustExitCode = false -
With this setup the Storyboard Comparator will run when you do a git merge <branch> . Optionally, with the developer setup, you can also invoke the compare with git mergetool
--tool=mergegde {Name of GDE}
StoryboardComparator.exe [-quiet] [-headless|manual] [-output=/path/to/result.gde] {ancestor} {current} {other}
Table 3. Syntax
|
Option |
Description |
|---|---|
|
-quiet |
(optional) Suppresses output from tool and splash screen |
|
-headless |
(optional) will suppress the visual diff regardless of the result and just attempt an automatic merge, exiting if a failure occurs. Typically used in a continuous integration environment. |
|
-manual |
(optional) will skip an automatic merge attempt and jump straight into the visual diff of the files |
|
-output={filename} |
(optional) The merged content will be stored into the {current} file by default but can be redirected by specifying -output=newfilename |
|
ancestor |
Full path file name of common ancestor of the two .gde files being compared |
|
current |
Full path file name of locally changed .gde to be compared |
|
other |
Full path file name of remote changed .gde to be compared |
Alternately Storyboard Designer can be used for compares with a similar syntax:
${SB_DESIGNER_EXT} -nosplash -application com.crank.gdt.merge.gdemerge ${ancestor} ${current} ${other}
Here the ${SB_DESIGNER_EXT} represents the path to your Storyboard Designer executable and will vary based on your operating system and installation path. For a standard Windows distribution you would find the Storyboard Designer binary in
C:\Program Files\Crank Software\Storyboard_Designer\Crank Storyboard.exe
while on a MacOS system is may be
/Applications/Crank_Software/Storyboard_Designer/Storyboard.app/Contents/MacOS/Crank Storyboard