1 of 13

2 of 13

Building App

  • Scripture App Builder is a tool for taking formatted text like USFM files from Paratext and making them into an Android app that will display the text on an Android phone or tablet. If audio files exist, they can be built into the app, so that as the audio plays, the corresponding words in the text are highlighted.
  • 1. Preparing content for your app
  • Before you build an app with Scripture App Builder (SAB), you need to get your content (text, images and audio) into formats that SAB can handle.
  • 1.1. Preparing text
  • The text format you need depends on the type of app content you have.
  • • Books of the Bible:
  • The Scripture text needs to be in one of the following formats:
  • o Paratext files (.usfm, .sfm, .ptx, etc.)
  • o USX files (.usx)
  • o Digital Bible Library Text Release Bundles (.zip)

​

3 of 13

Other types of app content such as commentaries, picture story books, song books and Bible studies:

​

  • The text needs to be in one of the following formats:
  • o Word documents (.docx)
  • o SFM text files (.sfm)
  • o HTML files (.html)
  • o Bloom books (.bloomd)

​

4 of 13

�1. Paratext files for Bible books

  • SAB can import text from Paratext USFM (Unified Standard Format Marker) files. These are the files used in Paratext projects – one per book of the Bible.
  • \p \v 20 Yeesuh uni markambah isah ilaaleh wah iniini yedʼeeni,
  • \q1 <<Nageh kʼabdani isani kah deegah,
  • \q2 malyenani isani anamah hayuma Waakʼa ati.
  • \q1 \v 21 Nageh kʼabdani isani kah teemtana beela kʼau,
  • \q2 isani kʼuufsah ah jirani.
  • \q1 \v 22 *Nageh kʼabdani mala anamah ani isani jibu,
  • \q2 mala isaani kʼofah isani kaayanu,
  • \q2 amaleh isani didanu aka wunih hamtuh ah,
  • \q2 malyenani Gurbah Anamah atiifi.
  • \m \v 23 *<<Kikitaa mala wunsuh gidi baatu amaleh gamadani sirbah malyenani yooyah guduyuh uni teesani gara samah. Abootih isaanih akumsuni rhaagoleh tochite.
  • In USFM files, the chapters, section headings and paragraphs are marked by standard format markers such as \c, \s and \p. For more details, please see http://paratext.org/about/usfm.

5 of 13

  • It is recommended that you run the Paratext Basic Checks to ensure the text is as clean as possible for publishing. Select Checking Run Basic Checks… from the Paratext main menu.
  • Critical checks:
  • • Chapter/Verse Numbers: Checks for duplicate or invalid chapter or verse numbers. Checks that all chapters and verses defined in the versification for the project are present.
  • • Markers: Checks you are using valid USFM markers and they are not in unexpected places.
  • • References: Checks that Scripture references, e.g. “Mat 6:1-5”, follow exact abbreviations and syntax. If not, they will not work as links in the app.

​

  • Important checks:
  • • All of the remaining basic checks: Characters, Punctuation, Capitalization, Repeated Words, Unmatched Pairs of Punctuation, Quotations, Numbers.
  • • Spelling: In Paratext, select Checking Spell Check Current Book…

​

​

6 of 13

2. Other SFM text files

  • SAB can import text from SFM files which contain content other than Bible books, such as commentaries, Bible studies, stories or songs. Like Paratext USFM files, the chapters, section headings and paragraphs need to be marked by standard format markers such as \c, \s and \p.
  • The first marker in the file must be \id XYZ, where XYZ is a code you choose. Do not choose a code already reserved for a Scripture book, e.g. GEN.
  • SFM book files must be plain text files. If you have Unicode characters, the text files should use UTF-8 encoding.
  • To create a text file in Windows, use a text editor such as Notepad.
  • To create a text file on a Mac, use TextEdit, remembering to choose Plain text files in the preferences because otherwise the default file type is RTF (which contains a lot of additional formatting codes).
  • For more details about how to define picture story books and song books using SFM text files, please see sections 15 and 16.

​

​

​

7 of 13

���������3. Word documents (.docx)�� SAB can import text and images from Microsoft Word (.docx) documents. �When Word documents are displayed in the app, basic formatting will be preserved such as character styles (bold, italic, underline), numbered lists, bullet points, hyperlinks, footnotes and simple tables. �

​

​

  • To define separate chapters or pages, insert page breaks using CTRL+Enter.
  • For more details about how to define picture story books and song books using Word documents, please see sections 15 and 16.

​

8 of 13

4.Digital Bible Library Text Release Bundles

​

  • SAB can import text from Digital Bible Library (DBL) text release bundles. These are zip files containing USX files for each book as well as other configuration information.
  • For more information about the DBL, see: https://www.thedigitalbiblelibrary.org/.
  • You can find some DBL text release bundles available for free use on Biblica’s Open.Bible website: https://open.bible/resources/
  • 5. HTML files (.html)
  • SAB can display HTML files and make use of associated stylesheets (CSS) and images. Audio-text synchronization is not supported yet with this format

​

  • 6. Bloom books (.bloomd)
  • SAB can display Bloom books. There are two ways in which it can do this:
  • • By using an embedded Bloom Player, as used in the Bloom Reader app, or
  • • By converting the book into a Picture Story Book.

​

  • For more information about Bloom, please see: https://bloomlibrary.org

9 of 13

How to build your first app

  • To build your first app with Scripture App Builder:
  • 1. Launch Scripture App Builder from its icon on the desktop.
  • 2. Click New App on the toolbar. The New App wizard will appear.
  • 3. On the first page of the wizard, specify: • the App Name, such as “Dogon Bible”, “Giriama bible”, “Waata NT”, etc. This is the main title of your app and will be seen by the user. Do not include underscores or hard to understand abbreviations.
  • Click Next to move to the next page.
  • 4. On the second page of the wizard, specify:

• the Package Name, a dot-separated string which uniquely identifies your app. For testing, try something like: com.example.myapp1

  • com.example.myapp2, etc.
  • (More details about choosing a good package name can be found in section 3.1 How should I choose the package name?)
  • Click Next to move to the next page.

10 of 13

  • 5. On the page of the wizard titled Books, click Add Books… and select the books you want to see in the app. These can be USFM (Paratext) files, USX files, Digital Bible Library text release bundles, Word documents (docx) or a zipped file of USFM or USX files.
  • Click Next to move to the next page.
  • 6. If you have selected Scripture books, the next page will be titled Book Order. Choose the book ordering according to the church tradition of the target users.
  • Click Next to move to the next page.
  • 7. On the page of the wizard titled Copyright and Licensing, specify the copyright and licensing information that you would like to appear on the About box in the app. This includes the copyright owner for the text. Use the Copyright Helper wizard to help you.
  • If you do not know what to put here, please ask the publishing department of your organisation for advice. They will want to make sure you get this right and do not simply make a guess as to what to include.
  • Click Next to move to the next page.
  • 8. On the page of the wizard titled Fonts, choose the font. You can either select from the given list of fonts or specify a different TrueType font file.
  • Click Next to move to the next page.

11 of 13

​

  • 9. On the page of the wizard titled Color Scheme, choose the color scheme for the app. The color you choose is the one that will be used for the main app bar. Individual colors for text, titles, links, backgrounds, etc. can be customised later.
  • Click Next to move to the next page.
  • 10. On the page of the wizard titled Default Interface Language, choose the language you want users to see when they first enter the app. This can be the current system language.
  • Click Next to move to the next page.
  • 11. On the page of the wizard titled Interface Languages, choose the app interface languages that the user can choose between.
  • Click Next to move to the next page.
  • 12. On the page of the wizard titled Features, choose the features you want to enable in the app.
  • Click Next to move to the next page.
  • 13. On the page of the wizard titled Icon, choose the application launcher icon. You can select one of the images in the table or if you have your own PNG image files for the icon, click Browse and select them.
  • Click Next to move to the next page.

12 of 13

  • 14. On the page of the wizard titled Signing, you need to specify the keystore and alias to use to sign the app. An app must be signed in this way so that it can installed on an Android device.
  • If you do not already have a keystore file (which you are unlikely to have if this is your first time using the program):
  • i. Click Create New KeyStore Wizard.
  • ii. Enter a new filename for the keystore, such as “test” or something like that. Specify a password.
  • iii. Click Next to continue.
  • iv. Enter an alias name for a key to create within your new keystore, such as “testkey”. Specify a password and enter at least one piece of information in the fields below.
  • v. Click Next to continue.
  • vi. A new keystore will be created for you. Click Close.
  • 15. Back on the Signing page of the New App wizard, you need to specify the keystore password, select the alias and enter the alias password (just as you entered them in the step above).
  • Click Next to continue.
  • 16. On the page of the wizard titled Project, you can enter modify the project name and add an optional description of the app project. Neither of these will be visible to the user of your app. They are just for your own use and might help you distinguish between multiple app projects.
  • Click Finish to continue. The New App wizard will close, and the app definition will be added to the tree view on the left of the screen.

13 of 13

​

  • 17. Take a look at each of the app configuration pages by selecting them in the tree view on the left. Look in each of the tabs on each page to verify that you have the settings you want. You can always go back to them later to change them if you find you need to make modifications to fonts, colors, styles, etc.

​

  • 18. When you have finished configuring the app, click on Build App.
  • If something is not configured correctly for the build to work, you will be notified.
  • 19. A black command box will appear. Wait about a minute while the app is compiled.

​