bloom-player 2.7.5 → 2.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +62 -21
  2. package/dist/{bloomPlayer.jbXOwOZh.js → bloomPlayer.DJ0YQIJM.js} +44 -44
  3. package/dist/bloomplayer.htm +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -2,14 +2,13 @@
2
2
 
3
3
  This project, _bloom-player_, lets users view and interact with [Bloom](https://bloomlibrary.org) books in any browser.
4
4
 
5
- Specifically, the books must be in _BloomPub_ format (.bloompub or .bloomd, which are zipped Bloom Digital books).
5
+ The Bloom project uses _bloom-player_ in the following places:
6
6
 
7
- The Bloom project uses _bloom-player_ is used in the following places:
8
-
9
- - In [Bloom Editor](https://github.com/bloombooks/bloomdesktop) / Publish / Bloom Reader tab, for previewing what the book will look like on a device.
10
- - In [Bloom Reader](https://github.com/bloombooks/bloomreader) itself (starting with BR version 2.0)
11
- - On [BloomLibrary.org](https://bloomlibrary.org)
12
- - In [BloomPUB Viewer](https://github.com/bloombooks/bloompub-viewer)
7
+ - In [Bloom Editor](https://github.com/bloombooks/bloomdesktop) / Publish / Bloom Reader tab, for previewing what the book will look like on a device.
8
+ - In the [Bloom Reader](https://github.com/bloombooks/bloomreader) Android app
9
+ - On [BloomLibrary.org](https://bloomlibrary.org)
10
+ - In [BloomPUB Viewer](https://github.com/bloombooks/bloompub-viewer)
11
+ - In Android and IOS apps created with Reading App Builder
13
12
 
14
13
  # Using bloom-player in a website
15
14
 
@@ -21,7 +20,7 @@ So to embed a book in your website, you just need an iframe element that points
21
20
 
22
21
  ```html
23
22
  <iframe
24
- src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=path-to-your-book"
23
+ src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=path-to-your-book"
25
24
  ></iframe>
26
25
  ```
27
26
 
@@ -33,7 +32,7 @@ You can customize some aspects of the bloom-player to fit your context. For exam
33
32
 
34
33
  ```html
35
34
  <iframe
36
- src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=path-to-your-book&initiallyShowAppBar=false&allowToggleAppBar=false"
35
+ src="https://bloomlibrary.org/bloom-player/bloomplayer.htm?url=path-to-your-book&initiallyShowAppBar=false&allowToggleAppBar=false"
37
36
  ></iframe>
38
37
  ```
39
38
 
@@ -55,12 +54,17 @@ Default: `false`
55
54
 
56
55
  #### showBackButton
57
56
 
58
- If true, displays an arrow in the upper left corner of the app bar. When clicked, bloom-player will post a message "backButtonClicked" that the surrounding context can catch and respond to.
57
+ If true, displays a button in the upper left corner of the app bar. When clicked, bloom-player will post a message "backButtonClicked" that the your host can catch and respond to.
59
58
 
60
59
  Example: `showBackButton=true`
61
60
 
62
61
  Default: `false`
63
62
 
63
+ > [!NOTE]
64
+ > Normally this button will be a left arrow. However if bloom-player is the top level window (i.e. it is not embedded in another page), it will show as an ellipsis.
65
+ >
66
+ > This is used in BloomLibrary.org when the user has used a link from somewhere else to jump directly into to reading a book. In that case, this button isn't really taking them "back", it's instead taking them to the "Detail" page for that same book on BloomLibrary.org.
67
+
64
68
  #### lang
65
69
 
66
70
  If set, determines the initial language to be displayed. The user can still change the display language using the language picker.
@@ -71,7 +75,7 @@ Default: none (The initial language will be the vernacular language when the boo
71
75
 
72
76
  #### hideFullScreenButton
73
77
 
74
- If true, the Full Screen icon button will not appear in the upper right hand corner of the window. Otherwise, a Full Screen icon button is displayed and allows the user to toggle between full screen and window mode.
78
+ If true, the Full Screen icon button will not appear in the upper right hand corner of the window. Otherwise, a Full Screen icon button is displayed and allows the user to toggle between full screen and window mode.
75
79
 
76
80
  Example: `hideFullScreenButton=true`
77
81
 
@@ -79,7 +83,7 @@ Default: `false`
79
83
 
80
84
  #### independent
81
85
 
82
- If true, bloom-player reports its own analytics directly to segment. If false, bloom-player sends messages to its host, and the host is responsible for reporting analytics.
86
+ If true, bloom-player reports its own analytics directly to segment. If false, bloom-player sends messages to its host, and the host is responsible for reporting analytics.
83
87
 
84
88
  Example: `independent=false`
85
89
 
@@ -87,7 +91,7 @@ Default: `true`
87
91
 
88
92
  #### host
89
93
 
90
- If set, provides a host value for analytics. If not set, bloom-player attempts to derive a value from the available information if independent is `true` (information can be limited in an iframe) and does nothing otherwise.
94
+ If set, provides a host value for analytics. If not set, bloom-player attempts to derive a value from the available information if independent is `true` (information can be limited in an iframe) and does nothing otherwise.
91
95
 
92
96
  Examples: `host=bloomlibrary` or `host=bloomreader` or `host=bloompubviewer` or `host=readerapp`
93
97
 
@@ -95,16 +99,49 @@ Examples: `host=bloomlibrary` or `host=bloomreader` or `host=bloompubviewer` or
95
99
 
96
100
  Default: `nothing/undefined`
97
101
 
102
+ # How to support books that link to other books
103
+
104
+ Some books are designed to be published together as a collection. These books may link to each other using underlined phrases or buttons. Users can click on these links and also backtrack. You can see examples of this in the StoryBook stories under "MultiBook".
105
+
106
+ Instead of asking your host to handle the navigation, history, etc., this navigation happens within the one instance of Bloom Player. However, Bloom Player needs your help, because it does not have a way to know what the URL to each book is in the context of your host, which could be a website, an app, a desktop program, etc. So if you want to support these collections of linked books, your host has to do some extra work.
107
+
108
+ Bloom books link to each other using each book's "Instance ID". This is a guid that is given as a property in the `meta.json` file:
109
+
110
+ ```json
111
+ {
112
+ "bookInstanceId":"0b82aab3-61fb-429e-864f-ce7671a3d372",
113
+ "title":"หมู่บ้านแห่งความดี\r\nVillage of good",
114
+ "credits":"มิได้จัดจำหน่าย  แต่จัดทำเพื่อส่งเสริมการเรียนรู้",
115
+ "tags":["topic:Fiction"],
116
+ "pageCount":16,
117
+ ```
118
+
119
+ To support this, your host needs to:
120
+
121
+ 1. intercept that request
122
+ 2. extract the Instance ID
123
+ 3. figure out the path to that book in your system
124
+ 4. if the target is still zipped in a BloomPUB, you may need to unzip it or read the resource directly out of the archive
125
+ 5. handle the incoming urls for all subsequent.
126
+
127
+ Note that when Bloom Player wants to switch to a different book, it will start requesting resources, e.g. `/book/THE-INSTANCE-ID/.distribution`, `/book/THE-INSTANCE-ID/meta.json` and `/book/THE-INSTANCE-ID/index.htm`. Be prepared to receive several of these before you've handled the first one.
128
+
129
+ Depending on your situation, you may find handling this as simple as doing a 302 redirect (as Bloom Editor does), or you may want to take each incoming URL and return the contents of that file (as BloomPUB Viewer does).
130
+
131
+ If step (3) is slow, you might need to cache or even pre-prepare an index for use at runtime.
132
+
133
+ As an example, in this repository, the file `.storybook/main.ts` sets up Storybook's vite dev server to proxy a couple instance ids to correct folders in this repository's `/public/testBooks` directory.
134
+
98
135
  # Development
99
136
 
137
+ If you haven't already, install `volta` globally. Volta takes care of getting all the correct versions of things like node and yarn to match what this repository expects.
138
+
100
139
  Run `yarn` to get the dependencies.
101
140
 
102
- Either, run `yarn storybook` (which has multiple books),
141
+ Either run `yarn storybook` (which has multiple books),
103
142
 
104
143
  or run `yarn dev` (which will use `index-for-developing.html`).
105
144
 
106
- Note: you need to have `chrome` on your path.
107
-
108
145
  See package.json for other scripts.
109
146
 
110
147
  ### Testing with a book hosted on the web
@@ -115,15 +152,19 @@ Both `yarn storybook` and `yarn dev` do this for you.
115
152
 
116
153
  ### Testing with a book hosted by Bloom
117
154
 
118
- Note that while testing, one option is to run Bloom, select your book, go to the publish tab, and choose Bloom Reader. Bloom will make the book available through its local fileserver. Modify index.html to use a path like this
155
+ To test Bloom Player on a book in the Bloom Editor, follow these steps:
119
156
 
120
- <iframe src="bloomplayer.htm?url=http://localhost:8089/bloom/C%3A/Users/YourName/AppData/Local/Temp/PlaceForStagingBook/myBookTitle"/>
121
-
122
- For more information, see README-advanced.md
157
+ 1. Go to the Publish tab in Bloom, choose "BloomPUB", and click "Preview".
158
+ 2. Back in this repository, run storybook (`yarn storybook`).
159
+ 3. Choose the "Live From Bloom Editor" story.
123
160
 
124
161
  ### Running unit tests
125
162
 
126
- To run unit tests use `yarn test`. This will run all "*.test.ts", which should be collocated with the thing being tested.
163
+ To run unit tests use `yarn test`. This will run all `*.test.ts`, which should be collocated with the thing being tested.
164
+
165
+ ### More info
166
+
167
+ For more information, see README-advanced.md
127
168
 
128
169
  ## License
129
170