Appearance
Web app (UI)
The fetch(bible) web app is a generic bible reading app that can be embedded within your own project, and it can also be customised, and interacted with via Javascript postMessage
calls.
Also see the web enhancer
Example
Features
- Works offline
- Swipe to change chapter
- Scroll through entire books
- Show multiple translations (both landscape and portrait)
- Private (no tracking of individuals)
Usage
Novice use
Create a blank page on your website and add the following code to make the app fill the page:
html
<iframe src="https://app.fetch.bible" style="position:fixed;width:100vw;height:100vh;top:0;left:0;border:none;"></iframe>
Professional use
- Embed it as an iframe
<iframe src='https://app.fetch.bible'>
- Load it in a webview in a native app
- Navigate to the app and provide a back URL
- e.g.
https://app.fetch.bible/#back=https://example.com
- Doesn’t support interaction via
postMessage
- e.g.
- Self-host on your own subdomain
npm install @gracious.tech/fetch-app
- Extend the app with your own components/routes
Customisation
You can pass config to the app when it first loads via search params embedded within the #
of the URL. They should be in the same format as regular search params (i.e. you can use URLSearchParams
to create them).
Example: https://app.fetch.bible/#back=true&dark=true&search=exo10:1
Interaction
If you embed the app as an iframe or webview then you can use Javascript postMessage
calls to change the app’s config at runtime and also get status updates about what passage the user is reading and some actions they take.
Params
These are the params available for use in the URL #
and/or postMessage
calls:
Param | Type | Default | Description |
---|---|---|---|
dark | true|false | [auto] | Whether to force dark/light theme. Only use this if your app already has a theme setting that you want to sync with, and also update it by listening for changes via this app’s own theme setting). |
status | string | [disabled] | A status message to display in the toolbar (must be short and may get cut off). |
hue | 0 - 360 | 290 | Color hue for app’s theme. |
saturation | 20 - 80 | 70 | Color saturation for app’s theme (limited to 20-80% for readability). |
back | true|URL | false | Whether to show a back button in the toolbar (iframes should listen to click via postMessage, don’t use URL if using an iframe/webview). |
button1_icon | coordinates | [disabled] | The icon to display for a custom button in the toolbar. It must be a string for an SVG <path d=""> that must conform to a 48x48 viewport (any value from a Material icon/symbol will work). |
button1_color | CSS color | currentColor | A color for the button’s fill. |
trans | lll_ttt | [auto] | A translation to force use of (comma-separate for multiple). Must be a fetch(bible) id (preview any translation to find the id in the url). |
search | string | [auto] | A passage reference in the language of the given translations (English names and book codes always work, e.g. Genesis 1:1 ). |
Messages
From the app
Every message sent from the app via postMessage
contains the following data. The event type is the most important but every event also reports what the user is currently reading.
Property | Type | Description |
---|---|---|
type | ready|translation|verse|back|button1|dark | The event type |
languages | [string, ...] | The three char language codes (ISO 639‑3) of the translations being viewed |
translations | [string, ...] | The translations currently being used (always at least one) |
book | bbb | USX bible book code (in lowercase) |
chapter | number | Chapter number currently being viewed |
verse | number | Verse number currently being viewed |
dark | true|false | Whether the app’s theme is dark (or light) |
When the app is ready to receive messages it will emit the ready
event. Whenever the user scrolls or changes book the verse
event will emit (may be very frequent). Other events trigger for button clicks or other state changes.
To the app
You can use postMessage
to send the app a message with {"type": "update", ...}
and add any of the config params you’d like to change.
js
window.addEventListener('message', event => {
// Only handle events from fetch(bible) app
const app_origin = 'https://app.fetch.bible'
if (event.origin !== app_origin){
return
}
// Once app is ready, update the status text
if (event.data.type === 'ready'){
// Send an update command to the app
event.source.postMessage({type: 'update', status: "Custom text"}, app_origin)
}
// If user clicks back button in app, hide the app
if (event.data.type === 'back'){
my_method_to_hide_iframe()
}
})
Offline support
The app will work offline by default on most devices, however there are some situations that it won’t. If a user has disabled third-party cookies in their browser it can prevent iframes from caching responses (even though the app doesn’t use any actual cookies).
If this is a problem you should use a method other than iframes to include the app in your own project.