Get Started with Storyboard Updates

In this tutorial, you will learn the basics about creating and dynamically updating a storyboard-based application with Bounces.

Create and run the application

Bounces Project Templates enable the creation of a complete dynamic application project with a single command. In this tutorial you will use a tab-based iOS app template as a starting point.

  1. Select New Project from Template… in the File menu.

  2. Select the Tabbed App template in the iOS Applications section in the left column, set the Product Name field in the right pane to "LiveTabs", and leave other fields with their default values.

    Tabbed iOS App creation in Bounces
  3. Click on the Next button and select a parent directory for the created project. A * LiveTabs* Bounces project window appears on the screen.

    LiveTabs project window in Bounces

    You can ignore the code in the LiveTabs project, as this project will be used in this tutorial only for triggering dynamic storyboard update in the target application.

    However, notice the MainStoryboard file reference in the project files list: this file reference is a link to the Main storyboard in the associated Xcode project, and this link is needed for enabling dynamic storyboard updates by Bounces.

    If you click on the Xcode Project button in the toolbar, you can see that all three ViewControllers defined in the Main storyboard are already configured for dynamic update:

    LiveTabs associated Xcode project configuration
  4. Open the associated HelloWorld Xcode project from Bounces by selecting Open Xcode Project in the Program menu, or by pressing cmd shift O.

  5. In Xcode, select a target device or simulator, and run the application.

    LiveTabs running initial state

    You can see that the LiveTabs project window in Bounces has changed:

    LiveTabs running initial state in Bounces

    The Execution Contexts section in the toolbar shows a connected target application: an iPhone 11 simulator running on a machine named "maquereau". The LOADED ITEMS section in the files list contains the Lua code files and resources loaded in this execution context, and an execution control area is now displayed at the project window bottom, including a variable inspector and a Lua console for the connected target execution context.

Edit the storyboard

You can now start to edit Main.storyboard in Xcode and watch the running target application change on the fly in the simulator.

  1. Select the Second tab in the running target application (in the simulator). Then in Xcode, change the background color of the Second ViewController's view to orange and the text color of the Second View label to white.

    Save the storyboard (cmd-S) in Xcode, and a few seconds later, the target application gets updated with the new storyboard content.

    In the following steps of this tutorial, saving the storyboard in Xcode will be implicit, but saving is nevertheless highly recommended to speed up storyboard changes propagation in the running target application!

    First dynamic storyboard update

    Notice that the target application still shows the Second tab: this means that the selected-tab state of the UITabBarController has be preserved during storyboard update.

  2. In Xcode, reorder the tabs in the Tab Bar Controller scene, by dragging the Second tab to the leftmost position and save the storyboard. In the simulator, the target application shows the changed tabs order.

    Updated target application with changed tabs order
  3. Now you will add an image view near the Second View label.

    Embed the Second View label in a Stack View, then add layout constraints to make this StackView centered in its parent view and correctly aligned with the small black Loaded by… label. If some inconsistency occurs with the layout constraints, you may experience unexpected positioning of both labels in the target application in the simulator. In such case, fixing the constraints with bring everything back at the right position.

    Insert an Image View in the Stack View and specify a fixed height constraint of 64pts. The result should look like this:

    Image View added to the Second View Controller in a Stack View

    Notice how the SecondView labels have been shifted down by the currently-empty Image View.

Use dynamic image assets

In this step, we will add an image to the assets catalog in the Xcode project, reference this image in the storyboard, and then modify the image. As expected the target application in the simulator will reflect these changes as they occur.

  1. Add an image to the LiveTabs app's asset catalog in Xcode (here a kangaroo photo) and set the Image View's image in the Second View Controller to this asset. The image appears in the running target application.

    Image View configured with an asset image in the Second View Controller
  2. In the Stack View, the image and label appear a little too close. Adjust the Stack View Spacing to improve this.

    Updated Stack View Spacing in the Second View Controller
  3. In the asset catalog editor in Xcode, edit the kangaroo image with an external editor, using the contextual menu. This will open the Preview application by default. In Preview, make the kangaroo image black and white by reducing the saturation to zero, and save the image. The running target application get automatically updated.

    Editing an asset image in an external editor

Update on multiple devices

A common pitfall of designing with layout constraints comes from the increasing variety of device screen or window sizes. A set of constraints may look fine in a given test situation but present unexpected views position or spacing in others.

In this section, we will see how running multiple occurrences of the target application simultaneously may be a significant help to quickly detect and fix such constraint-based-related issues.

  1. From Xcode, run the target application on a second device, for example on an iPhone SE simulator. If this makes Xcode stop the currently running application instance (in the iPhone 11 simulator), simply tap on the LiveTabs app icon in the corresponding simulated device to restart it.

    So now, two instances of the target application are running. Rotate the iPhone SE simulator to put it in landscape mode, so that you can test how the app design behave in a compact vertical size class.

    Target application with two running instances

    In Bounces, the LiveTabs project window now shows two connected target execution contexts: an iPhone 11 simulator and an iPhone SE simulator.

    Bounces project window with two connected execution contexts
  2. Try changing the Second view background color in the storyboard. Both running target application instances get updated.

    Simultaneous dynamic update of two target application instances

    Now cancel the change in the storyboard (cmd-Z) to revert to the orange background color in the Second view.

  3. The target app design stipulates that in landscape mode on iPhones, the image shall be horizontally aligned left to the Second View label. To achieve this, in the Stack View properties, add a Variation of the Axis property for (Width: any, Height: compact) and set its value to Horizontal.

    Stack View axis variation for compact height

    After this change, you notice that the Second View label is not visible anymore on the iPhone SE simulator. This reveals a problem in the Stack View layout and we have to fix it.

    After debugging the app view layout with Xcode, we realize that the problem is related to the width of the kangaroo image view, which is much larger than the visible scaled image, and that we'd better add a layout constraint to specify this image view width.

  4. Add an aspect ratio constraint to the kangaroo image view and set the aspect ratio to 3:2. Both simulator get updated and the target app now looks like:

    Aspect ratio constraint added to the kangaroo image view

    The horizontal Stack View on the iPhone SE simulator now looks as expected, but the Second View label size on the iPhone 11 simulator has been unexpectedly reduced.

  5. This unwanted side-effect is caused by the Stack View Alignment parameter, set to Fill by default. Set this parameter to Center to allow Stack View elements to keep their natural width in case of vertical axis(or height in case of horizontal axis).

    Aspect ratio constraint added to the kangaroo image view

    This is better. The target app now looks as expected for both portrait orientation (regular height) and landscape orientation (compact height).

  6. If it comes to your mind that the second view would look nicer with a bigger image in portrait orientation, add a variation of the image height constraint for compact height size classes, set the constraint's constant to 128 for non-compact height, and check how it looks.

    Bigger kangaroo image view in portrait orientation

Work with localizations

App and storyboard localization can be a time-consuming activity, for example when you realize that some of the provided translations for a given language do not fit in the space specified by the target app design.

Interactive visualization of localized strings and assets in the target application can help speeding up this process. To illustrate this point, let's add a new language to our LiveTabs project.

  1. Select the Xcode project file and add a French localization to the project. In the dialog asking which files to localize, be sure to specify the Main storyboard.

    French localization added in LiveTabs Xcode project
  2. Edit the LiveTabs Scheme in Xcode and set the Application Language to French in the Options tab.

    Application language configuration in Xcode scheme editor

    Run the app again on the iPhone 11 simulator.

  3. In the Main storyboard strings file for the French localization, change the translation for the Second View label and save the strings file. The change appears in the running target application.

    First localized string in LiveTabs Main storyboard
  4. In the Main storyboard strings file, set other translations visible in the second View Controller, and save.

    More localized strings in LiveTabs Main storyboard
  5. Now suppose that the kangaroo image has to be localized. In the project's assets catalog, add a French localization to the kangaroo image asset.

    Adding an image localization in the app assets catalog
  6. Drag the localized kangaroo image in the placeholder for the French localization and save the assets catalog. The localized image variant gets displayed in the running target application.

    After setting a localized image variant in the LiveTabs assets catalog

    Note: as localizing assets catalog is only supported on iOS 13+, if your application targets iOS 12 or below, you can use separate resource images and localize them individually in Xcode. Dynamic update and localization of resource images referenced by storyboards is also supported by Bounces.

Next steps

To be completed…

Post a Comment