This issue is being used to document the current functionality of the onboarding screens in the iOS and Android apps at this time. This is in its initial release on those platforms and may change, so it may be a good idea to hold off on the actual implementation of this in PWA until sufficient feedback has been returned from users and any additional changes they recommend have been added.
Functionality
The feature displays a set of one or more onboarding screens before any of the other views of the app appear. These screens only appear the first time the app is run after installation. They do not run again in subsequent starts of the application.
Below is a sample of an onboarding screen that is not the last screen (The screens used here are examples in format. The actual content would be more descriptive):
The screen has 5 defined fields. Any combination of these fields may be defined on a specific screen through Scripture App Builder. The fields are top-title, top-subtitle, onboarding-screen-image, bottom-title and bottom-subtitle. The titles are shown in a bold font while the sub-titles are not. There are no limits on the lengths of any of these fields and they can wrap multiple lines as needed to display all of the text.
The screen also has a page control at the bottom of the screen. This contains one button (the small circles) for each screen defined. Tapping one of the buttons should skip you forward to the specified screen.
Each screen except the last screen contains two buttons, a skip button and a next button. The next button causes the next screen in the set to display. The skip button ends the onboarding display sequence, sets a preference that indicates the onboarding screens have been displayed (so they won't display on the next start of the application) and launches the main application.
In addition to the page control and the next button, the user can simply swipe back and forth through the screens.
A sample for the last screen is shown below:
This screen has the same layout as the others except for the bottom buttons. The skip button is not present on this screen and the next button is replaced with a start button. When the start button is pressed, it does exactly what the skip button described above does.
By default, the background on these screens is white. The user can specify a specific background color for each screen or use the default. An example for a screen with a customized background is:
Screens are not required to have an image associated with them. An example where a fourth screen was added with text only, and text that extended over more than one line is:
AppDef Configuration
The screen definition is defined within the appDef file for the project inside the section. An example of an onboarding screen definition is:
<onboarding-screen>
<title type="top-title">
<translation>Onboarding Title</translation>
<translation lang="es">es: Onboarding Screen 1</translation>
<translation lang="fr">fr: Onboarding title</translation>
</title>
<title type="top-subtitle">
<translation>Onboarding Subtile</translation>
<translation lang="es">es: Onboarding Subtitle</translation>
<translation lang="fr">fr: Onboarding upper subtitle</translation>
</title>
<title type="bottom-title">
<translation>Onboarding Lower Title</translation>
<translation lang="es">es: Onboarding lower title</translation>
<translation lang="fr">fr: Onboarding Lower Title</translation>
</title>
<title type="bottom-subtitle">
<translation>Onboarding Lower Subtitle</translation>
<translation lang="es">es: Onboarding lower subtitle</translation>
<translation lang="fr">fr: Onboarding Lower Subtitle</translation>
</title>
<onboarding-screen-image lang="default">
<image>/Users/thisuser/Downloads/WiseAndFoolishBuilders.png</image>
</onboarding-screen-image>
<features type="onboarding-screen">
<feature name="background" value="default"/>
<feature name="image-max-height" value="45"/>
</features>
</onboarding-screen>If a field, such as bottom-title, is not defined for that screen, that field will simply not be present in the configuration.
For each of the string fields, the default translation of the string appears in the initial translation entry that has no language associated with it. If additional translations are available, the language code of the translation is specified (lang="es") and then the text for that translation. (The "translations" in the example are obviously not translations. They are just the original text with the language code stuck in front of them so it is easy to determine if the translation is appearing). At present, I think the language specific translations are more for the future since the application hasn't run and, for Android, the main configuration file hasn't been processed. The only thing this could be matched with is the locale for the current browser. The extra translations are not required and may not be present. The initial "translation" entry for each field is all that will always be present for a field that is to be displayed for this screen.
The images show the path to the original source of the image. The image is actually located in the images/onboarding folder of the SAB project with the same name. So for this screen, the image is located in App Builder/Scripture Apps/App Projects/project name/images/onboarding/WiseAndFoolishBuilders.png.
The features will always at least have the color information. If the user has selected a maximum height percentage for the image, that will also be specified here. In the example above, the color is "default" which means white. For another screen, where the color was specified, the entry appeared as follows:
<features type="onboarding-screen">
<feature name="background" value="custom"/>
<feature name="background-normal" value="#80FF65"/>
<feature name="background-sepia" value="#75EC68"/>
<feature name="background-dark" value="#75EC68"/>
</features>In this case the value of background is listed as custom and then color values for each of the three color themes. Again, I think this may be looking more to the future since the color theme can not have been selected at this point. So far, it always appears with the normal value.
HTML
The following is the html representation of the first screen in the example. For both iOS and Android, the page control and buttons were implemented outside the HTML, as native controls. So when developing for PWA, a suitable implementation will need to be selected.
<body class="onboarding">
<div id="onboarding-container">
<div class="onboarding-content">
<div class="onboarding-top-text">
<div class="onboarding-top-text-title">Onboarding Title</div>
<div class="onboarding-top-text-subtitle">Onboarding Subtile</div>
</div>
<div class="onboarding-image-block" style="background-image: url('file:///Users/thisuser/Library/Developer/CoreSimulator/Devices/30B19F2A-FB67-4F59-96BE-BA0F95CA9081/data/Containers/Bundle/Application/122D13F1-70CD-4294-B2D6-D01FE140480E/TemplateApp.app/assets/illustrations/WiseAndFoolishBuilders.png');"></div>
<div class="onboarding-bottom-text">
<div class="onboarding-bottom-text-title">Onboarding Lower Title</div>
<div class="onboarding-bottom-text-subtitle">Onboarding Lower Subtitle</div>
</div>
</div>
</div>
</body>
This issue is being used to document the current functionality of the onboarding screens in the iOS and Android apps at this time. This is in its initial release on those platforms and may change, so it may be a good idea to hold off on the actual implementation of this in PWA until sufficient feedback has been returned from users and any additional changes they recommend have been added.
Functionality
The feature displays a set of one or more onboarding screens before any of the other views of the app appear. These screens only appear the first time the app is run after installation. They do not run again in subsequent starts of the application.
Below is a sample of an onboarding screen that is not the last screen (The screens used here are examples in format. The actual content would be more descriptive):
The screen has 5 defined fields. Any combination of these fields may be defined on a specific screen through Scripture App Builder. The fields are top-title, top-subtitle, onboarding-screen-image, bottom-title and bottom-subtitle. The titles are shown in a bold font while the sub-titles are not. There are no limits on the lengths of any of these fields and they can wrap multiple lines as needed to display all of the text.
The screen also has a page control at the bottom of the screen. This contains one button (the small circles) for each screen defined. Tapping one of the buttons should skip you forward to the specified screen.
Each screen except the last screen contains two buttons, a skip button and a next button. The next button causes the next screen in the set to display. The skip button ends the onboarding display sequence, sets a preference that indicates the onboarding screens have been displayed (so they won't display on the next start of the application) and launches the main application.
In addition to the page control and the next button, the user can simply swipe back and forth through the screens.
A sample for the last screen is shown below:
This screen has the same layout as the others except for the bottom buttons. The skip button is not present on this screen and the next button is replaced with a start button. When the start button is pressed, it does exactly what the skip button described above does.
By default, the background on these screens is white. The user can specify a specific background color for each screen or use the default. An example for a screen with a customized background is:
Screens are not required to have an image associated with them. An example where a fourth screen was added with text only, and text that extended over more than one line is:
AppDef Configuration
The screen definition is defined within the appDef file for the project inside the section. An example of an onboarding screen definition is:
If a field, such as bottom-title, is not defined for that screen, that field will simply not be present in the configuration.
For each of the string fields, the default translation of the string appears in the initial translation entry that has no language associated with it. If additional translations are available, the language code of the translation is specified (lang="es") and then the text for that translation. (The "translations" in the example are obviously not translations. They are just the original text with the language code stuck in front of them so it is easy to determine if the translation is appearing). At present, I think the language specific translations are more for the future since the application hasn't run and, for Android, the main configuration file hasn't been processed. The only thing this could be matched with is the locale for the current browser. The extra translations are not required and may not be present. The initial "translation" entry for each field is all that will always be present for a field that is to be displayed for this screen.
The images show the path to the original source of the image. The image is actually located in the images/onboarding folder of the SAB project with the same name. So for this screen, the image is located in App Builder/Scripture Apps/App Projects/project name/images/onboarding/WiseAndFoolishBuilders.png.
The features will always at least have the color information. If the user has selected a maximum height percentage for the image, that will also be specified here. In the example above, the color is "default" which means white. For another screen, where the color was specified, the entry appeared as follows:
In this case the value of background is listed as custom and then color values for each of the three color themes. Again, I think this may be looking more to the future since the color theme can not have been selected at this point. So far, it always appears with the normal value.
HTML
The following is the html representation of the first screen in the example. For both iOS and Android, the page control and buttons were implemented outside the HTML, as native controls. So when developing for PWA, a suitable implementation will need to be selected.