BookStack Code Mirror - website/blob - content/blog/beta-release-v0-28-0.md

2 categories = ["Releases"]

3 tags = ["Releases"]

4 title = "Beta Release v0.28.0"

5 date = 2020-02-03T21:00:00Z

6 author = "Dan Brown"

7 image = "/images/blog-cover-images/books-radu-marcusu.jpg"

8 description = "Our first 2020 release arrives with some great new features such as an initial API implementation and SAML2 authentication alongside further new customisation options"

9 slug = "beta-release-v0-28-0"

10 draft = false

11 +++

12

13 Our first 2020 release arrives with some great new features such as an initial API implementation and SAML2 authentication alongside further new customisation options.

14

15 * [Update instructions](https://www.bookstackapp.com/docs/admin/updates)

16 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v0.28.0)

17

18 **This release increases the minimum supported PHP version from 7.0.5 to 7.2. Please view the "Update instructions" page above for more details.**

19

20 ### Initial REST API Implementation

21

22 The foundations for the API have been constructed as part of this release. This is intended to be a limited trial to ensure the core work and API formats function as required, so only a limited set of endpoints that cover basic "book" CRUD operations are available at this time.

23

24 A new "Access system API" role permission has been added to BookStack which, when assigned to a user, enables access to the API docs and endpoints while also showing the following API tokens section on the user profile screen:

25

26 ![API User Tokens](/images/2020/02/api-user-tokens.png)

27

28 New API tokens can be generated with a custom name, to help label the use of the token, in addition to an expiry date.

29 Once created, the token ID and the token secret will be provided. The token secret is hashed in the database so is only shown to the user once.

30

31 ![API Token Generation](/images/2020/02/api-token-generation.png)

32

33 These tokens details can then be used as a HTTP header in API requests to authenticate.

34 API requests will have the same permissions as those that belong to the user which generated the token used for the request.

35

36 Documentation for the API, including authentication details, can be found built-in to your BookStack instance at the `/api/docs` endpoint.

37 The "Access system API" permission is required to view the documentation so ensure you've assigned that before trying to access.

38

39 ![API Docs](/images/2020/02/api-docs.png)

40

41 We'll be extending the available endpoints in future releases.

42 I've created an issue on GitHub to collect feedback, regarding the API implementation, so that we can capture any issues or important required changes early on.

43 [This can be found here](https://github.com/BookStackApp/BookStack/issues/1852).

44

45

46 ### SAML2 Authentication

47

48 A SAML2 authentication option is now available to provide a seamless single-sign-on experience.

49 Massive thanks to [@Xiphoseer](https://github.com/Xiphoseer) for getting this started.

50 This can be used instead of the default Email & Password authentication and it works much like the existing LDAP authentication system.

51

52 ![BookStack SAML2 Authentication](/images/2020/02/bookstack-saml.png)

53

54 A range of options are available to configure the SAML2 authentication, including the option to sync BookStack roles with groups from your Identity Provider.

55 You can choose the attributes to use for details, such as email & id, and SAML single-logout is supported.

56

57 [Details of configuring your instance to use SAML2 can be found here](/docs/admin/saml2-auth/).

58

59 ### Theme Colour Customisation

60

61 As part of release v0.27 we made the application theme colours more accessible by making them CSS variables.

62 Thanks to [@james-geiger](https://github.com/james-geiger)'s efforts, these have now been made into easy-to-change options within the settings area of BookStack:

63

64 ![BookStack theme color customisation](/images/2020/02/theme-colors.png)

65

66 ### Test Email Sending

67

68 Email sending could be a tricky aspect to debug in BookStack, made harder by the fact it was difficult to find a way

69 to trigger an email send. A new section in the maintenance area of BookStack, thanks to [@timoschwarzer](https://github.com/timoschwarzer), helps alleviate

70 this difficulty by allowing you to send test emails at the press of a button:

71

72 ![BookStack Test Email Sending](/images/2020/02/test-emails.png)

73

74 This option will force a test email to be sent out as shown below:

75

76 ![BookStack Test Email Example](/images/2020/02/bookstack-test-email.png)

77

78 ### Override Translation Text

79

80 It's now possible to override BookStack translation text, used for the BookStack interface, without having to alter

81 the original BookStack files:

82

83 ![BookStack Translation Text Overrides](/images/2020/02/text-overrides.png)

84

85 Overrides can be done on a per-translation basis and are performed via the theme system.

86 Details of the theme system and the use of text content overrides can be [found in the docs here](/docs/admin/hacking-bookstack/#text-content).

87

88 ### Under-the-Hood Changes

89

90 ##### Laravel & PHP

91

92 Many changes have taken place to the core code for this release cycle.

93 We've updated the version of Laravel, the framework BookStack is built upon, from 5.5 to 6.12.

94 This enforced a change in the minimum supported version of PHP from 7.0.5 to 7.2.

95

96 ##### Core Refactor

97

98 To support the introduction of the API many of the core logic files have been refactored to be simpler and easier to share across front-end and API routes.

99 The inclusion of SAML2 authentication prompted a revision of how authentication is handled leading to a cleaner, more consistent approach with better testing coverage.

100

101 ##### Editor Events

102

103 Some editor events are now emitted for both the WYSIWYG and markdown editors.

104 This allows those with some JavaScript knowledge to listen to such events to gain a reference to the underlying configuration and libraries used enabling greater modification opportunities without needing to edit core BookStack code.

105

106 [Details of these events can be found here](/docs/admin/hacking-bookstack/#bookstack-editor-events).

107

108 ### Translations

109

110 ##### New Translation Management

111

112 During this release cycle we have started to use [crowdin](https://crowdin.com/project/bookstack) to help manage translations.

113 Massive thanks to crowdin for letting us use the platform for free.

114

115 ![BookStack Translation Text Overrides](/images/2020/02/crowdin-overview.png)

116

117 Crowdin provides a friendly user interface in addition to other great features such as auto-suggestions and change control which makes

118 translation management much easier and ensures better quality of translations overall.

119

120 This effectively negates the need for a translator to be familiar with git and/or GitHub which is a great benefit since it lowers the technical barrier for language contributions.

121

122 ##### Translation Updates

123

124 A big thanks to the following crowdin members for providing the following translation updates:

125

126 * Rodrigo Saczuk Niz (rodrigoniz) - _Portuguese, Brazilian_

127 * 叫钦叔就好 (254351722) - _Chinese Traditional; Chinese Simplified_

128 * aekramer - _Dutch_

129 * cipi1965 - _Italian_

130 * Mykola Ronik (Mantikor) - _Ukrainian_

131 * JachuPL - _Polish_

132 * m0uch0 - _Spanish_

133 * milesteg - _Hungarian_

134 * Beenbag - _German_

135 * furkanoyk - _Turkish_

136 * nutsflag - _French_

137 * Lett3rs - _Danish_

138 * Julian (julian.henneberg) - _German; German Informal_

139 * Maxim Zalata (zlatin) - _Russian; Ukrainian_

140 * 3GNWn - _Danish_

141 * dbguichu - _Chinese Simplified_

142 * Randy Kim (hyunjun) - _Korean_

143 * Francesco M. Taurino (ftaurino) - _Italian_

144 * DanielFrederiksen - _Danish_

145 * Finn Wessel (19finnwessel6) - _German_

146 * Leonardo Mario Martinez (leonardo.m.martinez) - _Spanish, Argentina_

147

148 Also a big thanks to the following GitHub members for providing the following translation updates:

149

150 * [@johnroyer](https://github.com/BookStackApp/BookStack/pull/1819) - Traditional Chinese

151 * [@artskoczylas](https://github.com/BookStackApp/BookStack/pull/1804) - Polish

152 * [@dellamina](https://github.com/BookStackApp/BookStack/pull/1762) - Italian

153 * [@qianmengnet](https://github.com/BookStackApp/BookStack/pull/1797) - Simplified Chinese

154 * [@jzoy](https://github.com/BookStackApp/BookStack/pull/1791) - Simplified Chinese

155 * [@ististudio](https://github.com/BookStackApp/BookStack/pull/1734) - Korean

156 * [@qligier](https://github.com/BookStackApp/BookStack/pull/1695) - French

157 * [@leomartinez](https://github.com/BookStackApp/BookStack/pull/1681) - Spanish Argentina

158 * [@oykenfurkan](https://github.com/BookStackApp/BookStack/pull/1660) - Turkish

159 * [@kostefun](https://github.com/BookStackApp/BookStack/pull/1646) - Russian

160 * [@ezzra](https://github.com/BookStackApp/BookStack/pull/1503) - German

161

162 ### Copy Shelf Permissions Command

163

164 A new command is available as of v0.28 which copies the permission settings of a shelf to all child books:

165

166 ```bash

167 # Copy the permission settings of a specified, or all, shelf to their child books

168 php artisan bookstack:copy-shelf-permissions --all

169 php artisan bookstack:copy-shelf-permissions --slug=my_shelf_slug

170 ```

171

172 Many users requested the ability for books to auto-inherit shelf permissions, which is unfortunately unavailable

173 at this time to the complications where books can be in multiple shelves.

174 This new command provides a way to semi-emulate that scenario. If desired, you could run the command as a daily cron-job on your system.

175

176 ### Full List of Changes

177

178 ##### Additions

179

180 * Added a baseline API implementation. ([#1414](https://github.com/BookStackApp/BookStack/issues/1414), [#1826](https://github.com/BookStackApp/BookStack/pull/1826))

181 * Added SAML2 authentication option. Thanks to [@Xiphoseer](https://github.com/BookStackApp/BookStack/pull/1576). ([#1787](https://github.com/BookStackApp/BookStack/pull/1787), [#1576](https://github.com/BookStackApp/BookStack/pull/1576), [#276](https://github.com/BookStackApp/BookStack/issues/276))

182 * Added ability to override translations with custom text using the theme system. ([#1749](https://github.com/BookStackApp/BookStack/pull/1749))

183 * Added the ability to customise application theme colours in settings. Thanks to [@james-geiger](https://github.com/BookStackApp/BookStack/pull/1723). ([#1723](https://github.com/BookStackApp/BookStack/pull/1723), [#1380](https://github.com/BookStackApp/BookStack/issues/1380))

184 * Added ability to send test e-mails. Thanks to [@timoschwarzer](https://github.com/BookStackApp/BookStack/pull/1719). ([#1719](https://github.com/BookStackApp/BookStack/pull/1719), [#1696](https://github.com/BookStackApp/BookStack/issues/1696))

185 * Added Pascal support for content code blocks. Thanks to [@albergoniSivaf](https://github.com/BookStackApp/BookStack/pull/1730). ([#1730](https://github.com/BookStackApp/BookStack/pull/1730))

186 * Added support INI syntax in code editor. Thanks to [@c0shea](https://github.com/BookStackApp/BookStack/pull/1667). ([#1667](https://github.com/BookStackApp/BookStack/pull/1667), [#1648](https://github.com/BookStackApp/BookStack/issues/1648))

187 * Added event hooks for core editor setup actions. ([#1721](https://github.com/BookStackApp/BookStack/issues/1721))

188 * Added a "Cascade Shelf Permissions" command to copy shelf permission to books. ([#1091](https://github.com/BookStackApp/BookStack/issues/1091))

189 * Added ability to fullscreen markdown editor and improved mobile layout. ([#1675](https://github.com/BookStackApp/BookStack/issues/1675))

190

191 ##### Updates

192

193 * Updated focus outline to be a sensible width and consistent across browsers. ([#1738](https://github.com/BookStackApp/BookStack/issues/1738))

194 * Updated page deletion flow so the user lands on the parent chapter if existing. ([#1715](https://github.com/BookStackApp/BookStack/issues/1715))

195 * Updated book-create-cancel flow to return to shelf if that's the origin. Thanks to [@cw1998](https://github.com/BookStackApp/BookStack/pull/1687). ([#1687](https://github.com/BookStackApp/BookStack/pull/1687), [#1662](https://github.com/BookStackApp/BookStack/issues/1662))

196 * Updated collapsible form sections to auto-open if containing validation errors. ([#1693](https://github.com/BookStackApp/BookStack/issues/1693))

197 * Updated LDAP functionality to fetch gravatar upon registration. Thanks to [@philjak](https://github.com/BookStackApp/BookStack/pull/1746). ([#1746](https://github.com/BookStackApp/BookStack/pull/1746))

198 * Updated the login fields to autofocus on visit. Thanks to [@almandin](https://github.com/BookStackApp/BookStack/pull/1584). ([#1584](https://github.com/BookStackApp/BookStack/pull/1584))

199 * Updated PHP code block syntax highlighting to detect, and highlight, PHP code without opening <?php tags. ([#1557](https://github.com/BookStackApp/BookStack/issues/1557))

200 * Updated registration settings to indicate non-used settings when LDAP/SAML is active and removed confusing overriding behaviour. ([#1541](https://github.com/BookStackApp/BookStack/issues/1541))

201 * Updated image upload handling to prevent generated thumbnails being used if larger than original image. ([#1751](https://github.com/BookStackApp/BookStack/issues/1751))

202 * Updated LDAP authentication to allow the attribute, that's stored and used as a unique identifier, to be configurable. ([#592](https://github.com/BookStackApp/BookStack/issues/592))

203 * Updated notifications to show a close icon. Thanks to [@SoarinFerret](https://github.com/BookStackApp/BookStack/pull/1845). ([#1845](https://github.com/BookStackApp/BookStack/pull/1845), [#1525](https://github.com/BookStackApp/BookStack/issues/1525))

204 * Updated maintenance page to link to GitHub release page. Thanks to [@DeftNerd](https://github.com/BookStackApp/BookStack/pull/1462). ([#1462](https://github.com/BookStackApp/BookStack/pull/1462))

205 * Updated codeblocks so white-space is not trimmed. ([#1771](https://github.com/BookStackApp/BookStack/issues/1771))

206

207 ##### Translations

208

209 * Updated Traditional Chinese translations. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/1819). ([#1819](https://github.com/BookStackApp/BookStack/pull/1819))

210 * Updated Polish translations. Thanks to [@artskoczylas](https://github.com/BookStackApp/BookStack/pull/1804). ([#1804](https://github.com/BookStackApp/BookStack/pull/1804))

211 * Updated Italian translations. Thanks to [@dellamina](https://github.com/BookStackApp/BookStack/pull/1762). ([#1762](https://github.com/BookStackApp/BookStack/pull/1762))

212 * Updated Simplified Chinese translations. Thanks to [@qianmengnet](https://github.com/BookStackApp/BookStack/pull/1797) and [@jzoy](https://github.com/BookStackApp/BookStack/pull/1791). ([#1797](https://github.com/BookStackApp/BookStack/pull/1797), [#1791](https://github.com/BookStackApp/BookStack/pull/1791))

213 * Updated Korean translations. Thanks to [@ististudio](https://github.com/BookStackApp/BookStack/pull/1734). ([#1734](https://github.com/BookStackApp/BookStack/pull/1734))

214 * Updated French translations. Thanks to [@qligier](https://github.com/BookStackApp/BookStack/pull/1695). ([#1695](https://github.com/BookStackApp/BookStack/pull/1695))

215 * Updated 'Spanish Argentina' translations. Thanks to [@leomartinez](https://github.com/BookStackApp/BookStack/pull/1681). ([#1681](https://github.com/BookStackApp/BookStack/pull/1681))

216 * Updated Turkish translations. Thanks to [@oykenfurkan](https://github.com/BookStackApp/BookStack/pull/1660). ([#1660](https://github.com/BookStackApp/BookStack/pull/1660))

217 * Updated Russian translations. Thanks to [@kostefun](https://github.com/BookStackApp/BookStack/pull/1646). ([#1646](https://github.com/BookStackApp/BookStack/pull/1646))

218 * Updated German translations. Thanks to [@ezzra](https://github.com/BookStackApp/BookStack/pull/1503). ([#1503](https://github.com/BookStackApp/BookStack/pull/1503))

219 * Updated translations for: Portuguese, Brazilian; Chinese Traditional; Chinese Simplified; Dutch; Italian; Ukrainian; Polish; Spanish; Hungarian; German; Turkish; French; Danish; German Informal; Russian; Korean; Spanish, Argentina. Thanks to [Crowdin Users](https://github.com/BookStackApp/BookStack/blob/development/.github/translators.txt).

220

221 ##### Maintenance

222

223 * Upgraded framework to Laravel 6. Thanks to [@timoschwarzer](https://github.com/timoschwarzer) and [@JtheBAB](https://github.com/JtheBAB) for assisting with this. ([#1641](https://github.com/BookStackApp/BookStack/pull/1641), [#1600](https://github.com/BookStackApp/BookStack/issues/1600))

224 * Setup Crowdin to manage translations. ([#1261](https://github.com/BookStackApp/BookStack/issues/1261))

225 * Refactored entity repository code & refactored core controllers. ([#1690](https://github.com/BookStackApp/BookStack/pull/1690))

226 * Aligned authentication service functionality, config & behaviour. ([#1866](https://github.com/BookStackApp/BookStack/pull/1866))

227

228 ##### Fixes

229

230 * Fixed issue where base64 images would paste as text. ([#1697](https://github.com/BookStackApp/BookStack/issues/1697))

231 * Fixed issue where pasted images would not auto upload in some circumstances. ([#1651](https://github.com/BookStackApp/BookStack/issues/1651))

232 * Fixed issue where code block content would be hidden until clicked. ([#1672](https://github.com/BookStackApp/BookStack/issues/1672))

233 * Fixed a possible middleware exception. Thanks to [@abublihi](https://github.com/BookStackApp/BookStack/pull/1793). ([#1793](https://github.com/BookStackApp/BookStack/pull/1793))

234 * Fixed issue where a shelf image may not be assigned properly. Thanks to [@philjak](https://github.com/BookStackApp/BookStack/pull/1735). ([#1735](https://github.com/BookStackApp/BookStack/pull/1735))

235 * Fixed missing git dependency in developer docker setup. Thanks to [@ammardev](https://github.com/BookStackApp/BookStack/pull/1698). ([#1698](https://github.com/BookStackApp/BookStack/pull/1698))

236 * Fixed issue where inline code blocks could overrun the page and cut-off. Thanks to [@james-geiger](https://github.com/BookStackApp/BookStack/pull/1587). ([#1587](https://github.com/BookStackApp/BookStack/pull/1587), [#1575](https://github.com/BookStackApp/BookStack/issues/1575))

237 * Fixed missing translations for "actions". Thanks to [@ezzra](https://github.com/BookStackApp/BookStack/pull/1502). ([#1502](https://github.com/BookStackApp/BookStack/pull/1502))

238

239

240 ### Next Steps

241

242 Over the next couple of releases I'll be taking any API feedback into account and deploying a wider set of endpoints.

243 That will be my core focus although I'll likely also look to align & review how we track activity in BookStack

244 so this can be used for other opportunities such as webhooks, feeds, notifications & audit logs.

245

246 As said above, if you have any feedback on the API implementation [I'd love to hear it here](https://github.com/BookStackApp/BookStack/issues/1852).

247

248 ----

249

250 <span style="font-size: 0.8em;opacity:0.8;">Header Image Credits:   <a style="background-color:black;color:white;text-decoration:none;padding:4px 6px;font-family:-apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif;font-size:12px;font-weight:bold;line-height:1.2;display:inline-block;border-radius:3px" href="https://unsplash.com/@radu_marcusu?utm_medium=referral&utm_campaign=photographer-credit&utm_content=creditBadge" target="_blank" rel="noopener noreferrer" title="Download free do whatever you want high-resolution photos from Radu Marcusu"><span style="display:inline-block;padding:2px 3px"><svg xmlns="http://www.w3.org/2000/svg" style="height:12px;width:auto;position:relative;vertical-align:middle;top:-2px;fill:white" viewBox="0 0 32 32"><title>unsplash-logo</title><path d="M10 9V0h12v9H10zm12 5h10v18H0V14h10v9h12v-9z"></path></svg></span><span style="display:inline-block;padding:2px 3px">Radu Marcusu</span></a></span>