trek 2.5.0 → 2.7.0

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 (232) hide show
  1. checksums.yaml +4 -4
  2. data/.node-version +1 -1
  3. data/AGENTS.md +18 -14
  4. data/CHANGELOG.md +88 -0
  5. data/Gemfile +5 -0
  6. data/Gemfile.lock +135 -124
  7. data/Makefile +9 -1
  8. data/README.md +17 -21
  9. data/app/components/trek/dashboard/tile_component/tile_component.css +9 -0
  10. data/app/components/trek/dashboard/tile_component/tile_component.html.slim +4 -2
  11. data/app/components/trek/dashboard/tile_component.rb +12 -2
  12. data/app/components/trek/form/content_editor_component/content_editor_component.css +9 -8
  13. data/app/components/trek/form/content_editor_component/content_editor_component.html.slim +19 -93
  14. data/app/components/trek/form/content_editor_component/content_editor_component.js +94 -251
  15. data/app/components/trek/form/content_editor_component/extensions/block_view.js +40 -0
  16. data/app/components/trek/form/content_editor_component/extensions/image_block.js +28 -26
  17. data/app/components/trek/form/content_editor_component/extensions/prompts_block.js +15 -26
  18. data/app/components/trek/form/content_editor_component/extensions/table_of_contents.js +1 -3
  19. data/app/components/trek/form/content_editor_component.rb +15 -0
  20. data/app/components/trek/form/image_field_component/image_field_component.css +40 -1
  21. data/app/components/trek/form/image_field_component/image_field_component.html.slim +0 -9
  22. data/app/components/trek/form/image_field_component/image_field_component.js +1 -2
  23. data/app/components/trek/form/image_field_component.rb +36 -9
  24. data/app/components/trek/form/password_strength_component/password_strength_component.css +2 -0
  25. data/app/components/trek/form/sound_field_component/sound_field_component.js +1 -2
  26. data/app/components/trek/security_check_component/security_check_component.css +69 -0
  27. data/app/components/trek/security_check_component/security_check_component.html.slim +19 -0
  28. data/app/components/trek/security_check_component/security_check_component.js +15 -0
  29. data/app/components/trek/security_check_component.rb +19 -0
  30. data/app/content/trek/content/cleaner.rb +53 -0
  31. data/app/content/trek/content/document.rb +2 -2
  32. data/app/content/trek/content/list_item.rb +1 -1
  33. data/app/content/trek/content/paragraph.rb +7 -2
  34. data/app/content/trek/content/prompts_block.rb +1 -2
  35. data/app/content/trek/content.rb +6 -0
  36. data/app/controllers/concerns/trek/auditable.rb +5 -2
  37. data/app/controllers/concerns/trek/localization.rb +6 -2
  38. data/app/controllers/concerns/trek/reorderable.rb +24 -6
  39. data/app/controllers/trek/csp_reports_controller.rb +14 -1
  40. data/app/controllers/trek/panels/prompts_controller.rb +1 -1
  41. data/app/controllers/trek/resource_controller.rb +5 -5
  42. data/app/jobs/trek/purge_expired_sessions_job.rb +4 -3
  43. data/app/jobs/trek/purge_expired_sign_in_codes_job.rb +15 -0
  44. data/app/models/concerns/trek/contentable.rb +15 -1
  45. data/app/models/concerns/trek/users/sign_in_code.rb +70 -0
  46. data/app/models/concerns/trek/users/sign_in_lockout.rb +4 -2
  47. data/app/policies/trek/security_check_policy.rb +8 -0
  48. data/app/uploaders/image_uploader.rb +77 -15
  49. data/app/views/trek/panels/links/_form.html.slim +2 -4
  50. data/app/views/trek/panels/prompts/create.turbo_stream.slim +0 -1
  51. data/config/locales/trek.en.yml +97 -11
  52. data/config/locales/trek.fr.yml +97 -11
  53. data/docs/.vitepress/config.mjs +5 -1
  54. data/docs/background-jobs.md +74 -0
  55. data/docs/content-editor.md +219 -0
  56. data/docs/customize.md +2 -0
  57. data/docs/deploy.md +69 -6
  58. data/docs/getting-started.md +16 -18
  59. data/docs/index.md +2 -2
  60. data/docs/personal-data.md +61 -0
  61. data/docs/proxies.md +2 -2
  62. data/docs/reference/components.md +4 -4
  63. data/docs/reference/concerns/contentable.md +10 -4
  64. data/docs/reference/concerns/formattable.md +1 -1
  65. data/docs/reference/concerns/fragmentable.md +12 -6
  66. data/docs/reference/concerns/orderable.md +2 -2
  67. data/docs/reference/concerns/search-engine-optimizable.md +1 -1
  68. data/docs/reference/concerns/searchable.md +14 -1
  69. data/docs/reference/concerns/sectionable.md +7 -3
  70. data/docs/reference/concerns/versionable.md +1 -1
  71. data/docs/reference/controllers.md +33 -1
  72. data/docs/reference/environment-variables.md +3 -2
  73. data/docs/reference/formatters.md +4 -31
  74. data/docs/reference/forms.md +7 -4
  75. data/docs/reference/generators/admin-user.md +1 -1
  76. data/docs/reference/generators/audit-log.md +12 -13
  77. data/docs/reference/generators/install.md +23 -11
  78. data/docs/reference/generators/public-accounts.md +159 -0
  79. data/docs/reference/generators/scaffold.md +28 -9
  80. data/docs/reference/generators/security-headers.md +5 -4
  81. data/docs/reference/generators/taxonomies.md +1 -1
  82. data/docs/reference/icons.md +5 -3
  83. data/docs/reference/index.md +10 -7
  84. data/docs/reference/models/current.md +5 -3
  85. data/docs/reference/models/page-version.md +1 -1
  86. data/docs/reference/models/user.md +7 -8
  87. data/docs/reference/uploaders.md +25 -0
  88. data/docs/reference/validators.md +1 -1
  89. data/docs/security.md +30 -9
  90. data/docs/what-is-trek.md +4 -4
  91. data/lib/generators/trek/USAGE +1 -1
  92. data/lib/generators/trek/audit_log_generator.rb +62 -0
  93. data/lib/generators/trek/helpers.rb +17 -0
  94. data/lib/generators/trek/install/admin/routes_generator.rb +2 -1
  95. data/lib/generators/trek/install/admin/security_check_generator.rb +36 -0
  96. data/lib/generators/trek/install/admin/users_generator.rb +6 -1
  97. data/lib/generators/trek/install/audit_log_generator.rb +9 -45
  98. data/lib/generators/trek/install/ci_generator.rb +19 -0
  99. data/lib/generators/trek/install/good_job_generator.rb +161 -0
  100. data/lib/generators/trek/install/model_specs_generator.rb +3 -3
  101. data/lib/generators/trek/install/postcss_generator.rb +1 -2
  102. data/lib/generators/trek/install/ruby_generator.rb +1 -1
  103. data/lib/generators/trek/install/scalingo_generator.rb +7 -45
  104. data/lib/generators/trek/install/translations_generator.rb +1 -2
  105. data/lib/generators/trek/install_generator.rb +18 -2
  106. data/lib/generators/trek/public_accounts_generator.rb +294 -0
  107. data/lib/generators/trek/scaffold_generator.rb +22 -21
  108. data/lib/generators/trek/scalingo_generator.rb +67 -0
  109. data/lib/generators/trek/templates/.gitlab-ci.yml +10 -1
  110. data/lib/generators/trek/templates/AGENTS.md +2 -2
  111. data/lib/generators/trek/templates/Makefile +1 -0
  112. data/lib/generators/trek/templates/config/i18n-tasks.yml.erb +0 -8
  113. data/lib/generators/trek/templates/controllers/admin/password_renewals_controller.rb +11 -0
  114. data/lib/generators/trek/templates/controllers/admin/security_checks_controller.rb +11 -0
  115. data/lib/generators/trek/templates/controllers/admin/user_sessions_controller.rb +1 -1
  116. data/lib/generators/trek/templates/controllers/admin/users_controller.rb +0 -8
  117. data/lib/generators/trek/templates/controllers/concerns/trek/authentication.rb +13 -4
  118. data/lib/generators/trek/templates/initializers/content_security_policy.rb +3 -2
  119. data/lib/generators/trek/templates/initializers/good_job.rb.tt +40 -0
  120. data/lib/generators/trek/templates/jobs/mail_delivery_job.rb +6 -0
  121. data/lib/generators/trek/templates/layouts/admin.html.slim +10 -0
  122. data/lib/generators/trek/templates/mailers/admin_mailer.rb +4 -2
  123. data/lib/generators/trek/templates/package.json.tt +1 -1
  124. data/lib/generators/trek/templates/policies/security_check.rb +4 -0
  125. data/lib/generators/trek/templates/public_accounts/api/authentication.rb.tt +76 -0
  126. data/lib/generators/trek/templates/public_accounts/api/controllers/accounts_controller.rb.tt +22 -0
  127. data/lib/generators/trek/templates/public_accounts/api/controllers/active_sessions_controller.rb.tt +21 -0
  128. data/lib/generators/trek/templates/public_accounts/api/controllers/base_controller.rb.tt +71 -0
  129. data/lib/generators/trek/templates/public_accounts/api/controllers/email_changes_controller.rb.tt +55 -0
  130. data/lib/generators/trek/templates/public_accounts/api/controllers/email_confirmations_controller.rb.tt +19 -0
  131. data/lib/generators/trek/templates/public_accounts/api/controllers/password_resets_controller.rb.tt +28 -0
  132. data/lib/generators/trek/templates/public_accounts/api/controllers/passwords_controller.rb.tt +17 -0
  133. data/lib/generators/trek/templates/public_accounts/api/controllers/registrations_controller.rb.tt +17 -0
  134. data/lib/generators/trek/templates/public_accounts/api/controllers/sessions_controller.rb.tt +57 -0
  135. data/lib/generators/trek/templates/public_accounts/api/controllers/sign_in_codes_controller.rb.tt +20 -0
  136. data/lib/generators/trek/templates/public_accounts/jobs/sign_in_code_job.rb.tt +23 -0
  137. data/lib/generators/trek/templates/public_accounts/locales/accounts.en.yml.tt +215 -0
  138. data/lib/generators/trek/templates/public_accounts/locales/accounts.fr.yml.tt +215 -0
  139. data/lib/generators/trek/templates/public_accounts/mailers/account_mailer.rb.tt +85 -0
  140. data/lib/generators/trek/templates/public_accounts/migrations/create_accounts.rb.tt +46 -0
  141. data/lib/generators/trek/templates/public_accounts/models/account/session.rb.tt +47 -0
  142. data/lib/generators/trek/templates/public_accounts/models/account/sign_in_code.rb.tt +8 -0
  143. data/lib/generators/trek/templates/public_accounts/models/account.rb.tt +87 -0
  144. data/lib/generators/trek/templates/public_accounts/spec/api/accounts_spec.rb.tt +90 -0
  145. data/lib/generators/trek/templates/public_accounts/spec/api/sign_ins_spec.rb.tt +188 -0
  146. data/lib/generators/trek/templates/public_accounts/spec/models/account/sign_in_code_spec.rb.tt +66 -0
  147. data/lib/generators/trek/templates/public_accounts/spec/models/account_spec.rb.tt +129 -0
  148. data/lib/generators/trek/templates/public_accounts/spec/web/accounts_spec.rb.tt +126 -0
  149. data/lib/generators/trek/templates/public_accounts/spec/web/authentication_spec.rb.tt +43 -0
  150. data/lib/generators/trek/templates/public_accounts/spec/web/sign_ins_spec.rb.tt +237 -0
  151. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.html.slim.tt +10 -0
  152. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.text.erb.tt +8 -0
  153. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.html.slim.tt +13 -0
  154. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.text.erb.tt +8 -0
  155. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.html.slim.tt +9 -0
  156. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.text.erb.tt +11 -0
  157. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.html.slim.tt +11 -0
  158. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.text.erb.tt +11 -0
  159. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.html.slim.tt +10 -0
  160. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.text.erb.tt +8 -0
  161. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.html.slim.tt +10 -0
  162. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.text.erb.tt +8 -0
  163. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.html.slim.tt +10 -0
  164. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.text.erb.tt +8 -0
  165. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.html.slim.tt +13 -0
  166. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.text.erb.tt +8 -0
  167. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.html.slim.tt +9 -0
  168. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.text.erb.tt +11 -0
  169. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.html.slim.tt +9 -0
  170. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.text.erb.tt +11 -0
  171. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.html.slim.tt +23 -0
  172. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.text.erb.tt +14 -0
  173. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.html.slim.tt +24 -0
  174. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.text.erb.tt +14 -0
  175. data/lib/generators/trek/templates/public_accounts/web/authentication.rb.tt +97 -0
  176. data/lib/generators/trek/templates/public_accounts/web/controllers/accounts_controller.rb.tt +33 -0
  177. data/lib/generators/trek/templates/public_accounts/web/controllers/active_sessions_controller.rb.tt +15 -0
  178. data/lib/generators/trek/templates/public_accounts/web/controllers/base_controller.rb.tt +52 -0
  179. data/lib/generators/trek/templates/public_accounts/web/controllers/email_changes_controller.rb.tt +85 -0
  180. data/lib/generators/trek/templates/public_accounts/web/controllers/email_confirmations_controller.rb.tt +19 -0
  181. data/lib/generators/trek/templates/public_accounts/web/controllers/password_resets_controller.rb.tt +41 -0
  182. data/lib/generators/trek/templates/public_accounts/web/controllers/passwords_controller.rb.tt +23 -0
  183. data/lib/generators/trek/templates/public_accounts/web/controllers/registrations_controller.rb.tt +24 -0
  184. data/lib/generators/trek/templates/public_accounts/web/controllers/sessions_controller.rb.tt +85 -0
  185. data/lib/generators/trek/templates/public_accounts/web/controllers/sign_in_codes_controller.rb.tt +32 -0
  186. data/lib/generators/trek/templates/public_accounts/web/views/_flash.html.slim.tt +5 -0
  187. data/lib/generators/trek/templates/public_accounts/web/views/accounts/show.html.slim.tt +52 -0
  188. data/lib/generators/trek/templates/public_accounts/web/views/email_changes/edit.html.slim.tt +17 -0
  189. data/lib/generators/trek/templates/public_accounts/web/views/email_changes/new.html.slim.tt +15 -0
  190. data/lib/generators/trek/templates/public_accounts/web/views/password_resets/edit.html.slim.tt +29 -0
  191. data/lib/generators/trek/templates/public_accounts/web/views/password_resets/new.html.slim.tt +15 -0
  192. data/lib/generators/trek/templates/public_accounts/web/views/passwords/edit.html.slim.tt +28 -0
  193. data/lib/generators/trek/templates/public_accounts/web/views/registrations/new.html.slim.tt +30 -0
  194. data/lib/generators/trek/templates/public_accounts/web/views/sessions/new.html.slim.tt +40 -0
  195. data/lib/generators/trek/templates/public_accounts/web/views/sign_in_codes/new.html.slim.tt +17 -0
  196. data/lib/generators/trek/templates/spec/jobs/mail_delivery_job_spec.rb +11 -0
  197. data/lib/generators/trek/templates/spec/mailers/admin_mailer_spec.rb +10 -0
  198. data/lib/generators/trek/templates/spec/requests/admin/fragments_spec.rb +1 -1
  199. data/lib/generators/trek/templates/spec/requests/admin/good_job_spec.rb +34 -0
  200. data/lib/generators/trek/templates/spec/requests/admin/pages_spec.rb +12 -1
  201. data/lib/generators/trek/templates/spec/requests/admin/panels_spec.rb +16 -0
  202. data/lib/generators/trek/templates/spec/requests/admin/password_renewal_spec.rb +2 -2
  203. data/lib/generators/trek/templates/spec/requests/admin/security_checks_spec.rb +24 -0
  204. data/lib/generators/trek/templates/spec/requests/admin/sign_in_lockout_spec.rb +1 -1
  205. data/lib/generators/trek/templates/spec/requests/admin/sign_in_notices_spec.rb +33 -0
  206. data/lib/generators/trek/templates/spec/requests/admin/user_sessions_spec.rb +2 -2
  207. data/lib/generators/trek/templates/views/admin/pages/_form.html.slim +1 -1
  208. data/lib/generators/trek/templates/views/admin/security_checks/show.html.slim +9 -0
  209. data/lib/generators/trek/templates/views/admin/user_password_resets/edit.html.slim +6 -1
  210. data/lib/generators/trek/templates/views/admin/user_sessions/new.html.slim +4 -1
  211. data/lib/generators/trek/templates/views/admin/users/index.html.slim +1 -1
  212. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.html.slim +1 -1
  213. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.text.erb +1 -1
  214. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.html.slim +1 -1
  215. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.text.erb +1 -1
  216. data/lib/tasks/trek/attachments.rake +12 -0
  217. data/lib/tasks/trek/security.rake +10 -0
  218. data/lib/trek/csp_reports.rb +22 -4
  219. data/lib/trek/disposable_email_domains.rb +9 -20
  220. data/lib/trek/engine.rb +5 -0
  221. data/lib/trek/json_compatibility.rb +20 -0
  222. data/lib/trek/security_check.rb +241 -0
  223. data/lib/trek/stored_image_metadata.rb +88 -0
  224. data/lib/trek/typography_formatter.rb +35 -4
  225. data/lib/trek/version.rb +1 -1
  226. data/lib/trek.rb +2 -1
  227. data/package.json +16 -13
  228. data/postcss.config.js +0 -3
  229. data/trek.gemspec +6 -7
  230. data/vitest.config.mjs +24 -0
  231. data/yarn.lock +1667 -1010
  232. metadata +122 -33
@@ -7,7 +7,7 @@ This guide takes you from an empty directory to a working Rails application with
7
7
  Make sure the following are installed:
8
8
 
9
9
  - Ruby 3.3+
10
- - Rails 8.0+
10
+ - Rails 8.0 or 8.1: 8.1.4 or later, or add `gem "json", "< 3"` to the Gemfile, as json 3 needs Rails 8.1.4
11
11
  - PostgreSQL 12+
12
12
  - Node 22+
13
13
  - Yarn 4.x
@@ -27,13 +27,20 @@ Check your Yarn version:
27
27
  yarn -v
28
28
  ```
29
29
 
30
- If it's not a 4.x version, run:
30
+ If it's not a 4.x version, or `yarn` isn't found, install it with [corepack](https://github.com/nodejs/corepack). Node 25 and later no longer ship corepack, so install it first:
31
31
 
32
32
  ```sh
33
+ npm install --global corepack
33
34
  corepack enable
34
35
  corepack install --global yarn@4
35
36
  ```
36
37
 
38
+ Or, if you manage your tools with [mise](https://mise.jdx.dev):
39
+
40
+ ```sh
41
+ mise use --global yarn@4
42
+ ```
43
+
37
44
  ## Create your Rails project
38
45
 
39
46
  Replace `helloworld` with your own project name:
@@ -57,7 +64,7 @@ bundle add trek
57
64
  ## Run the installer
58
65
 
59
66
  ```sh
60
- rails g trek:install
67
+ bin/rails g trek:install
61
68
  ```
62
69
 
63
70
  The installer will:
@@ -84,22 +91,12 @@ You can also do it manually afterwards:
84
91
  EDITOR="code --wait" bin/rails credentials:edit
85
92
  ```
86
93
 
87
- ### Configure DeepL (optional)
88
-
89
- DeepL is used to translate locale files automatically when running the scaffold generator. To enable it, define this ENV variable before running the installer:
90
-
91
- ```sh
92
- export DEEPL_AUTH_KEY=YOUR_TOKEN
93
- ```
94
-
95
- Without it, translations won't happen automatically and you will have to edit each non-English locale file by hand.
96
-
97
94
  ## Create an admin user
98
95
 
99
96
  Set `ADMIN_EMAIL` and `ADMIN_PASSWORD` in your `.env`, then run:
100
97
 
101
98
  ```sh
102
- rails g trek:admin:user
99
+ bin/rails g trek:admin:user
103
100
  ```
104
101
 
105
102
  ## Start the server
@@ -115,21 +112,22 @@ Open `http://localhost:3000/admin` and sign in with your admin credentials. Welc
115
112
  Trek's scaffold generator creates everything an admin panel needs for a model:
116
113
 
117
114
  ```sh
118
- rails g trek:scaffold Book title:string intro:text
115
+ bin/rails g trek:scaffold Book title:string intro:text
116
+ bin/rails db:migrate
119
117
  ```
120
118
 
121
119
  This generates, in a single command:
122
120
 
123
- - the `Book` model and migration (calling the Rails `model` generator behind the scenes)
121
+ - the `Book` model and migration (calling the Rails `model` generator behind the scenes), whose `to_s`, the title the admin shows a book by, returns its `title`
124
122
  - the `Admin::BooksController` based on `Trek::ResourceController`
125
123
  - the index, show, new, edit views and form partial
126
124
  - the `Admin::BookPolicy` with role-based permissions
127
125
  - the admin routes
128
- - the locale files (auto-translated via DeepL if configured)
126
+ - the locale files
129
127
  - a menu entry in the admin dashboard
130
128
 
131
129
  Next steps:
132
130
 
133
131
  - [Customize Trek](/customize) — branding, favicon, components
134
132
  - [Reference manual](/reference/) — generators, models, components and more
135
- - [Deploying to Scalingo](/deploy) — `trek:install:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest
133
+ - [Deploying to Scalingo](/deploy) — `trek:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest
data/docs/index.md CHANGED
@@ -23,13 +23,13 @@ features:
23
23
  details: One installer sets up authentication, authorization, file uploads, emails, i18n and a polished admin UI — with sensible conventions you can override later.
24
24
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 6H30V30A12 12 0 0 1 18 42H6ZM12 14H24V18H12ZM12 22H20V26H12Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M34 6H42V32A4 4 0 0 1 34 32Z"/></svg>'
25
25
  title: Modern content editing
26
- details: A Tiptap-based rich text editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
26
+ details: A Tiptap-based content editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
27
27
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 18H30V30H42V42H6Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M6 18V6A12 12 0 0 1 18 18Z"/></svg>'
28
28
  title: Scaffold-driven development
29
29
  details: One command generates the model, admin panel, views, policy, routes and locales for any resource — just like Rails scaffolding, but for your back-office.
30
30
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M22 22H5A17 17 0 0 1 22 5ZM22 26V43A17 17 0 0 1 5 26ZM26 26H43A17 17 0 0 1 26 43Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M26 22V5A17 17 0 0 1 43 22Z"/></svg>'
31
31
  title: Multilingual by default
32
- details: Content and admin UI translations powered by Mobility and i18n-tasks, with optional automatic translation via DeepL.
32
+ details: Content and admin UI translations powered by Mobility and i18n-tasks.
33
33
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M14 22V16A10 10 0 0 1 34 16V22H28V16A4 4 0 0 0 20 16V22ZM8 22H24V42H16A8 8 0 0 1 8 34Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M24 22H40V34A8 8 0 0 1 32 42H24Z"/></svg>'
34
34
  title: Roles & policies built in
35
35
  details: Authentication on Rails' own has_secure_password and ActionPolicy authorization with admin, editor, user, reader and guest roles, enforced across every panel.
@@ -0,0 +1,61 @@
1
+ # Personal data
2
+
3
+ The personal data an app gets from Trek's generators: where it's kept, why, for how long, what deletes it, and which third parties receive some of it. It's what a GDPR record of processing activities (Art. 30) and security questionnaires ask for. The app adds its own models to it, and the organization running it decides the legal bases and informs the people concerned.
4
+
5
+ ## In the database
6
+
7
+ | Table | Personal data | Why | Kept | Deleted by |
8
+ | --- | --- | --- | --- | --- |
9
+ | `users` | Name, email, role, language and theme; password hash; last activity; the current and previous sign-ins (date, IP address, user agent); failed sign-ins and lockout; password changes | Signing in to the admin, and showing users their sign-ins to spot one that wasn't theirs | While the account exists | Deleting the user |
10
+ | `user_sessions` | IP address and its host name, user agent, last activity | One row per signed-in browser, listed to its user, who can end it | Until signing out, or 48 hours idle, 30 days in all | Signing out; [`Trek::PurgeExpiredSessionsJob`](/background-jobs#scheduled-jobs-cron), every night; deleting the user |
11
+ | `user_passkeys` | The browser it was added from, its provider, last use | Signing in with a passkey | While the passkey exists | Its user removing it; deleting the user |
12
+ | `user_previous_passwords` | Hashes of the 4 previous passwords | Refusing a password used recently | Until replaced by newer ones | Changing the password (only the last ones stay); deleting the user |
13
+ | `audit_logs` | The author (type and id), IP address, user agent, path, the parameters' names | Investigating an incident or a misuse (see [Audit log › Personal data](/reference/generators/audit-log#personal-data)) | 6 months | [`Trek::AuditLog::PurgeJob`](/reference/generators/audit-log#purging-old-rows), every night |
14
+
15
+ With [public accounts](/reference/generators/public-accounts) (`trek:public_accounts Member`):
16
+
17
+ | Table | Personal data | Why | Kept | Deleted by |
18
+ | --- | --- | --- | --- | --- |
19
+ | `members` | Email, name, last activity; with passwords, the password hash, an email waiting for confirmation, failed sign-ins and lockout | The account | While the account exists | Its holder deleting it; the app (see [below](#retention-to-decide)) |
20
+ | `member_sessions` | IP address and its host name, user agent, last activity | One row per signed-in browser or device | Until signing out, or 30 days idle, 1 year in all | Signing out; `Trek::PurgeExpiredSessionsJob`, every night; deleting the account |
21
+ | `member_sign_in_codes` | The email a code was sent to | Signing in with a code | 10 minutes of validity | The next code requested for that email, which also deletes every expired one; `Trek::PurgeExpiredSignInCodesJob`, every night; deleting the account |
22
+
23
+ ## In the browser
24
+
25
+ - `session_id` (and `member_session_id` with public accounts): a signed cookie naming the session, until signing out or the session's expiry.
26
+ - `trek_known_users`: an encrypted cookie holding the ids of the last 20 users who signed in from this browser, for 13 months after the last of those sign-ins, to email a user when they sign in from a new browser. It serves to secure signing in.
27
+
28
+ ## Uploads
29
+
30
+ Files are stored in the S3-compatible bucket, with metadata in the record's column: the original file name, size, MIME type, and for an image its dimensions and [blurhash](https://blurha.sh). An image's own metadata (EXIF, with the GPS location and the camera's serial number, XMP, IPTC) is stripped on upload, as the file is public: see [Uploaders](/reference/uploaders#image-metadata). Images uploaded before Trek stripped it still carry it, until `bin/rails trek:attachments:strip_image_metadata` strips them in place; their [sizes](/reference/uploaders#sizes) don't.
31
+
32
+ A file is deleted with its record, and with it its sizes (thumbnails…), stored under `derivatives/`; the sizes of images deleted before Trek did that stay in the bucket, at URLs nobody links to any more. A file uploaded to the cache but never attached, e.g. from a form left without saving, stays in the bucket's `cache/` prefix: a lifecycle rule on the bucket deleting `cache/` objects after a day or two takes care of it.
33
+
34
+ ## Deleting a user or an account
35
+
36
+ Deleting a user deletes their sessions, passkeys and previous passwords. Their audit log rows stay, with the id the user had but not their name, until the purge deletes them: they record what was done, which an investigation still needs. Pages, fragments and their versions record no author.
37
+
38
+ Deleting a public account deletes its sessions and sign-in codes; its audit log rows stay until the purge, as for a user.
39
+
40
+ ## Third parties
41
+
42
+ What a default app sends, and to whom:
43
+
44
+ | Service | Receives | When |
45
+ | --- | --- | --- |
46
+ | The hosting | Everything: the database, the logs (which hold the requests' IP addresses) | Always |
47
+ | S3-compatible storage | The uploaded files | Always |
48
+ | [Postmark](https://postmarkapp.com) | The emails sent: their address and content, e.g. password reset links, sign-in codes, and the new sign-in alert, which gives the date, the browser and the IP address | When an email is sent |
49
+ | [AppSignal](https://www.appsignal.com) | Errors and performance: the request's path and parameters as filtered by `filter_parameters` (passwords, emails, tokens…), and the signed-in user's id; CSP violation reports (a page's path, a blocked origin, the file and line that caused it, the start of a blocked inline script, the browser's user agent) | On every request it samples, and on every error |
50
+ | The DNS resolver | A session's IP address, for its host name (reverse lookup) | After each sign-in |
51
+ | [Have I Been Pwned](https://haveibeenpwned.com/API/v3#PwnedPasswords) | The first 5 characters of the new password's SHA-1 hash, never the password | When a password is set, if `password_check_pwned` is on (off by default) |
52
+
53
+ The admin's fonts are served by the app itself: its pages make no request to a font provider.
54
+
55
+ ## Retention to decide
56
+
57
+ What Trek leaves to each app:
58
+
59
+ - **Inactive accounts.** Users and public accounts are kept until deleted. `Member.inactive_since(time)` lists the accounts unused since `time`, to delete them on the schedule the organization sets.
60
+ - **The uploads' cache**, as [above](#uploads).
61
+ - **The logs**, kept by the hosting: set their retention there.
data/docs/proxies.md CHANGED
@@ -4,7 +4,7 @@ Trek relies on `request.remote_ip`, the visitor's IP address as Rails works it o
4
4
 
5
5
  - the **active sessions** list, on each user's profile;
6
6
  - the **audit log** (`ip_address`), when installed;
7
- - the **rate limits** on signing in and on password reset requests (5 attempts in 3 minutes per address);
7
+ - the **rate limits** on signing in and on password reset requests (5 attempts in 3 minutes per address), and on the admin's failed sign-ins (20 an hour per address);
8
8
  - the **admin's allowed addresses**, when set (see [below](#restricting-the-admin-to-ip-addresses)).
9
9
 
10
10
  ## How Rails finds the address
@@ -16,7 +16,7 @@ Requests rarely reach the app directly: a hosting platform's load balancer or ro
16
16
  A CDN or a firewall in front of the app (Cloudflare, Imperva, Bunny…) adds another hop, from public addresses Rails doesn't trust. `remote_ip` is then the CDN's address for every request:
17
17
 
18
18
  - every session and every audit log row shows the same IP;
19
- - everyone shares one rate limit: a few failed sign-ins anywhere lock everyone out for 3 minutes.
19
+ - everyone shares the rate limits: a few failed sign-ins anywhere lock everyone out for 3 minutes, and 20 for up to an hour.
20
20
 
21
21
  List the CDN's address ranges, which it publishes, in `config/application.rb`:
22
22
 
@@ -18,10 +18,10 @@ The main building blocks, all in the `Trek::` namespace:
18
18
  | `ListComponent` | record lists |
19
19
  | `PropertiesComponent` | key-value property display |
20
20
  | `PaginationComponent` | Kaminari-backed pagination |
21
- | `ToasterComponent` / `ToastComponent` | flash notifications |
21
+ | `ToasterComponent` / `Toaster::ToastComponent` | flash notifications |
22
22
  | `HeadingComponent` | headings |
23
23
  | `SectionComponent` | a titled section of a page, with an optional hint under its heading |
24
- | `GateComponent` | authorization-based visibility gate |
24
+ | `GateComponent` | the frame of the sign-in and password reset screens: a centred card under the brand |
25
25
  | `IconComponent` | SVG [icon](/reference/icons) renderer |
26
26
  | `Dashboard::SectionComponent` / `Dashboard::TileComponent` | dashboard sections of shortcut tiles |
27
27
 
@@ -47,10 +47,10 @@ Rendered by the [form builder](/reference/forms) helpers, under `Trek::Form::`:
47
47
 
48
48
  ## Content editor
49
49
 
50
- `Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts three options — `nodes`, `blocks` and `floating` (all enabled by default) — to toggle the node toolbar, block formatting and floating menu:
50
+ `Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts `nodes`, `blocks` and `floating` (all enabled by default) to toggle the text buttons, the block buttons and the floating menu, and `autofocus`:
51
51
 
52
52
  ```ruby
53
53
  f.content_editor :intro, nodes: false, floating: false
54
54
  ```
55
55
 
56
- Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers).
56
+ Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers). See the [Content editor](/content-editor) guide for its toolbar, how content is stored and rendered, and how to customize it.
@@ -1,6 +1,6 @@
1
1
  # Trek::Contentable
2
2
 
3
- Utilities for rich text stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/reference/components#content-editor).
3
+ Utilities for content stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/content-editor).
4
4
 
5
5
  ## Methods
6
6
 
@@ -8,8 +8,8 @@ Utilities for rich text stored as ProseMirror JSON in a `content` column — the
8
8
  | --- | --- |
9
9
  | `parsed_content` | the content as a hash (parsing JSON strings if needed) |
10
10
  | `content_document` | the content as a `Prosemirror::Document`, to query or render it |
11
- | `formatted_content` | safe HTML, rendered as described in [Rich text rendering](/reference/formatters#rich-text-rendering) |
12
- | `content_text` | plain text extracted from all text nodes |
11
+ | `formatted_content` | safe HTML, rendered as described in [Rendering on the site](/content-editor#rendering-on-the-site) |
12
+ | `content_text` | the plain text of the content: blocks separated by a blank line, hard breaks by a newline |
13
13
  | `prosemirror_content?` | whether `content` is a valid ProseMirror document |
14
14
 
15
15
  ## Usage
@@ -23,7 +23,13 @@ page.formatted_content # => "<p>Hello <strong>world</strong></p>"
23
23
  page.content_text # => "Hello world"
24
24
  ```
25
25
 
26
+ Content in another column renders through the same schema: `Trek::Content::Document.parse(record, record.intro).to_html`. See the [Content editor](/content-editor) guide for the whole path, from the editor to the HTML.
27
+
28
+ ## Cleaning before saving
29
+
30
+ Before validation, empty paragraphs, empty list items and lists left empty are removed from the content, as rendering skips them (`Trek::Content::Cleaner`). The document stays one the editor opens: an empty document keeps one paragraph, a list item keeps the first paragraph it needs, and node types or attributes the schema doesn't know are kept. Content submitted as a JSON string, as the content editor sends it, is stored as a document. Translated content is cleaned in the current locale.
31
+
26
32
  ## Requirements
27
33
 
28
34
  - A `content` jsonb column
29
- - Used by [Page](/reference/models/page), [PageVersion](/reference/models/page-version) and [Fragment](/reference/models/fragment)
35
+ - Used by [Page](/reference/models/page) and [Fragment](/reference/models/fragment)
@@ -21,4 +21,4 @@ page.valid?
21
21
  page.title # => "Un titre : voici…"
22
22
  ```
23
23
 
24
- Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved).
24
+ Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved), including a document submitted by the content editor as a JSON string, which comes back as a Hash.
@@ -1,17 +1,23 @@
1
1
  # Trek::Fragmentable
2
2
 
3
- Composes a record from reusable [fragments](/reference/models/fragment), based on a configuration matrix mapping record keys to fragment ids.
3
+ Composes a record from reusable [fragments](/reference/models/fragment), based on a configuration matrix mapping record keys to the attributes finding each fragment.
4
4
 
5
5
  ## Configuration
6
6
 
7
+ In `config/page_fragments.yml`, read with `config_for`, so under `shared:` or an environment's key:
8
+
7
9
  ```yaml
8
- # page_fragments configuration
9
- page_fragments:
10
+ shared:
10
11
  matrix:
11
- home: [1, 2, 3]
12
- about: [4, 5]
12
+ home:
13
+ - { namespace: home, key: intro }
14
+ - { namespace: home, key: newsletter }
15
+ about:
16
+ - { namespace: about, key: team }
13
17
  ```
14
18
 
19
+ Each entry is passed to `Fragment.find_by`. Without the file, a record has no fragments.
20
+
15
21
  ## Methods
16
22
 
17
23
  | Method | Purpose |
@@ -27,7 +33,7 @@ class Page < ApplicationRecord
27
33
  end
28
34
 
29
35
  page = Page.find_by(key: "home")
30
- page.fragments # => [Fragment(1), Fragment(2), Fragment(3)]
36
+ page.fragments # => the home/intro and home/newsletter fragments
31
37
  ```
32
38
 
33
39
  This is what powers the fragment editing UI on page forms in the admin.
@@ -5,7 +5,7 @@ Position tracking with [acts_as_list](https://github.com/brendon/acts_as_list),
5
5
  ## What it adds
6
6
 
7
7
  - `acts_as_list scope: :parent, top_of_list: 0`
8
- - An `ordered` scope (position order)
8
+ - An `ordered` scope (position order), which adds nothing on a [closure_tree](https://github.com/ClosureTree/closure_tree) model such as `Page` or `MenuNode`: closure_tree already orders its records by `position`
9
9
  - All the `acts_as_list` instance methods: `insert_at`, `move_to_top`, `move_to_bottom`, `move_higher`, `move_lower`…
10
10
 
11
11
  ## Requirements
@@ -19,7 +19,7 @@ class MenuNode < ApplicationRecord
19
19
  include Trek::Orderable
20
20
  end
21
21
 
22
- MenuNode.where(parent: menu).ordered
22
+ menu.children # ordered by position, through closure_tree
23
23
  node.move_to_top
24
24
  ```
25
25
 
@@ -1,6 +1,6 @@
1
1
  # Trek::Pages::SearchEngineOptimizable
2
2
 
3
- SEO metadata with sensible fallbacks: explicit title/description/image when set, model defaults otherwise (including the parent page's image).
3
+ SEO metadata from the page's title, description and image: a blank title or description gives `""`, a missing image `nil`. Override the `default_*` methods to fall back on other values.
4
4
 
5
5
  ## Methods
6
6
 
@@ -19,4 +19,17 @@ Article.search("élève") # matches "eleve", "Élève"…
19
19
 
20
20
  ## Controller side
21
21
 
22
- The `Trek::Search` controller concern wires this into index actions: it filters `@objects` by `params[:search]` whenever the model responds to `search` — that's what powers the search field in admin lists.
22
+ The `Trek::Search` concern wires this into an admin controller's index, as the generated fragments controller does. It's opt-in: include it and call `search_in_objects!` after loading `@objects`:
23
+
24
+ ```ruby
25
+ class Admin::ArticlesController < Trek::ResourceController
26
+ include Trek::Search
27
+
28
+ def index
29
+ super
30
+ search_in_objects!
31
+ end
32
+ end
33
+ ```
34
+
35
+ `search_in_objects!` filters `@objects` by `params[:search]` when it's present, and raises `Trek::Search::ModelNotSearchable` when the model has no `search` scope.
@@ -4,16 +4,20 @@ Organizes a record's content into ordered, typed sections (hero, features, testi
4
4
 
5
5
  ## What it adds
6
6
 
7
+ When the app has a `Section` model:
8
+
7
9
  - `has_many :sections, -> { ordered }, as: :sectionable, dependent: :destroy`
8
10
  - `sections_instances` — the unwrapped section objects, in order
9
11
 
12
+ ## Requirements
13
+
14
+ Trek doesn't generate the `Section` model: the app provides it, with a polymorphic `belongs_to :sectionable`, an `ordered` scope, and a `section` method returning the section's own object. Without a `Section` model, the concern adds nothing.
15
+
10
16
  ## Usage
11
17
 
12
18
  ```ruby
13
19
  class Page < ApplicationRecord
14
20
  include Trek::Sectionable
15
-
16
- SECTIONS = [HeroSection, FeaturesSection].freeze
17
21
  end
18
22
 
19
23
  page.sections_instances.each do |section|
@@ -21,4 +25,4 @@ page.sections_instances.each do |section|
21
25
  end
22
26
  ```
23
27
 
24
- Sections are opt-in per page via the `sectioned` boolean column. The including class defines the allowed section types through the `SECTIONS` constant.
28
+ Sections are opt-in per page via the `sectioned` boolean column.
@@ -4,7 +4,7 @@ Content versioning for [pages](/reference/models/page): snapshot the current con
4
4
 
5
5
  ## What it adds
6
6
 
7
- - `has_many :versions` (most recent first) with a `current` sub-scope, plus `accepts_nested_attributes_for :versions`
7
+ - `has_many :versions` (most recent first), plus `accepts_nested_attributes_for :versions`; `page.versions.current` returns the current version, a record (or `nil`)
8
8
 
9
9
  ## Methods
10
10
 
@@ -20,9 +20,41 @@ end
20
20
  ## Mixins
21
21
 
22
22
  - `include Trek::Pagination` — paginates the index with Kaminari
23
- - `include Trek::Search` — filters the index by `params[:search]` when the model is [Searchable](/reference/concerns/searchable)
23
+ - `include Trek::Search` — adds `search_in_objects!`, to call in `index`: it filters the index by `params[:search]`, for a [Searchable](/reference/concerns/searchable) model
24
24
  - `include Trek::Filters` — filters the index by attribute equality (`where(column => value)`) from `params[:filters]`
25
25
  - `include Trek::Scopes` — filters the index by **named scopes** from `params[:scopes]`
26
+ - `include Trek::Localization` — answers each request in the [locale](#localization) of the request, the user or the browser
27
+
28
+ ### Localization
29
+
30
+ `Trek::Localization` sets `I18n.locale` around each action, and restores the previous locale afterwards, even when
31
+ the action raises. `Trek::BaseController` includes it, as do the generated `Admin::BaseController` and
32
+ `Admin::UploadsController`. Include it in an app's own controllers, e.g. public pages, for the same behaviour.
33
+
34
+ The locale is the first one found among:
35
+
36
+ 1. `params[:locale]`, e.g. `?locale=fr`
37
+ 2. the signed-in user's `locale` (`Current.user`, set by `Trek::Authentication`)
38
+ 3. the browser's `Accept-Language` header: its first language among `I18n.available_locales`, a regional
39
+ variant matching its language (`fr-CA` gives `fr`), through [http_accept_language](https://github.com/iain/http_accept_language)
40
+
41
+ Without any, the request is answered in `I18n.default_locale`.
42
+
43
+ To add a source, or a fallback other than the default locale, override `locale_for_request` and call `super` for
44
+ Trek's chain:
45
+
46
+ ```ruby
47
+ class EventsController < ApplicationController
48
+ include Trek::Localization
49
+
50
+ private
51
+
52
+ # The event's own language first, then Trek's chain
53
+ def locale_for_request
54
+ Current.event&.locale.presence || super
55
+ end
56
+ end
57
+ ```
26
58
 
27
59
  ### Filters
28
60
 
@@ -7,7 +7,8 @@
7
7
  | `POSTMARK_API_TOKEN` | Postmark email delivery (auto-injected into credentials by the [installer](/reference/generators/install)) |
8
8
  | `APPSIGNAL_PUSH_API_KEY` | AppSignal error tracking and performance monitoring (auto-injected into credentials by the [installer](/reference/generators/install)) |
9
9
  | `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
10
- | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
11
10
  | `FEATURE_AUDIT_LOG` | `false` stops the [audit log](/reference/generators/audit-log) recording requests (on by default) |
12
- | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
11
+ | `GOOD_JOB_MAX_THREADS` | number of job threads GoodJob runs, and the share of the database pool reserved for them (optional, defaults to `RAILS_MAX_THREADS`) — see [Background jobs](/background-jobs) |
12
+ | `FEATURE_STORAGE` | `s3` stores the uploads on S3 outside production too, e.g. in development; otherwise development stores them in `public/uploads` and the tests in memory. Production always uses S3 |
13
+ | `TREK_LOCALES` | the locales the [installer](/reference/generators/install) sets up, comma-separated, e.g. `en,fr,de` (the `--locales` option of `trek:install:locales` too; defaults to `en, fr`) |
13
14
  | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |
@@ -4,7 +4,8 @@
4
4
 
5
5
  `Trek::TypographyFormatter` applies French typography rules to strings **and** ProseMirror documents (only `text` nodes are modified):
6
6
 
7
- - non-breaking spaces before `: ; ! ? % € $ »` and after `«`, dashes, `n°`
7
+ - non-breaking spaces before `»`, after `«`, `n°`, and on both sides of dashes (`–`, `—`)
8
+ - before `: % € $`, a non-breaking space, and before `; ! ?` a narrow one (U+202F): only when the sign ends a word (followed by a space, punctuation or the end of the text), so a time (`10:30`) or a URL is left alone
8
9
  - non-breaking spaces before units (km, kg, h, min, °C…) and between digit groups
9
10
  - `...` → `…`, ASCII apostrophes → typographic `'`
10
11
  - removes double spaces and spaces before periods/commas
@@ -18,36 +19,8 @@ format_attributes Trek::TypographyFormatter, :title
18
19
 
19
20
  ## Rich text rendering
20
21
 
21
- `formatted_content` (from [Contentable](/reference/concerns/contentable)) renders the content editor's ProseMirror JSON to HTML with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem. HTML is escaped as it is built, attributes are typed, and links and images only allow `http`, `https`, `mailto`, `tel` and relative URLs. Invalid content is fixed and reported to `Rails.error`.
22
-
23
- `Trek::Content.schema` is Tiptap's schema, with:
24
-
25
- | Node type | Role |
26
- | --- | --- |
27
- | `Trek::Content::Paragraph` | skips empty paragraphs |
28
- | `Trek::Content::ListItem` | skips empty list items, with no content or only empty paragraphs |
29
- | `Trek::Content::BulletList`, `OrderedList` | skip lists with only empty items |
30
- | `Trek::Content::ImageBlock` | renders image blocks as a `<figure>`: the image, its caption and credit |
31
- | `Trek::Content::PromptsBlock` | renders prompt blocks as a link |
32
-
33
- Links to records are stored as GlobalIDs (`gid://app/Page/1`). `Trek::Content::LinkResolver` turns them into the record's URL with `url_for`, loading the records of a document's links at once, with one query per model; a link to a deleted record is removed and its text kept, and reported to `Rails.error` as a `Prosemirror::UnresolvedURL`. Problems in content are reported with the record holding it in their context (`trek_content: "Page#12"`), which AppSignal shows as a tag.
22
+ `formatted_content` (from [Contentable](/reference/concerns/contentable)) renders the content editor's ProseMirror JSON to HTML with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem, through `Trek::Content.schema`: HTML is escaped as it is built, attributes are typed, links and images only allow safe URLs, and links to pages are resolved. See [Rendering on the site](/content-editor#rendering-on-the-site) for what the HTML contains, and how invalid content is reported.
34
23
 
35
24
  ### Custom blocks
36
25
 
37
- Node types are [Phlex](https://www.phlex.fun) components with [Literal](https://literal.fun) properties (see the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#custom-nodes-and-marks)). To render the image block with the app's own component, subclass it and register it in an initializer:
38
-
39
- ```ruby
40
- # app/content/image_block.rb
41
- class ImageBlock < Trek::Content::ImageBlock
42
- def view_template
43
- render Components::Figure.new(src: image&.url, alt: @alt, caption: @text, credit: @credit)
44
- end
45
- end
46
-
47
- # config/initializers/trek.rb
48
- Rails.application.config.to_prepare do
49
- Trek::Content.schema = Trek::Content.default_schema.with(ImageBlock)
50
- end
51
- ```
52
-
53
- The same works for a node type of your own, added to the editor with a Tiptap extension.
26
+ Trek's node types (`Trek::Content::ImageBlock`, `PromptsBlock`…) can be subclassed to render the app's own components, and registered with `Trek::Content.schema = Trek::Content.default_schema.with(…)`: see [Customizing the rendering](/content-editor#customizing-the-rendering).
@@ -4,8 +4,8 @@ Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://
4
4
 
5
5
  | Helper | Renders |
6
6
  | --- | --- |
7
- | `f.group` | a label + input wrapper with errors |
8
- | `f.content_editor` | the Tiptap rich text editor |
7
+ | `f.group` | a wrapper giving the input nested in it a label, and a hint (errors are listed by `Trek::Form::ErrorsComponent`) |
8
+ | `f.content_editor` | the [content editor](/content-editor), based on Tiptap |
9
9
  | `f.image_field` | an image uploader with thumbnail preview (Uppy + Shrine) |
10
10
  | `f.sound_field` | an audio file uploader |
11
11
  | `f.switch_box` | a toggle switch |
@@ -18,6 +18,9 @@ Standard helpers are styled too: a plain `f.file_field` inside an `f.group` gets
18
18
  ```slim
19
19
  = form_with model: [:admin, @book] do |f|
20
20
  = f.group :title
21
- = f.content_editor :intro, floating: false
22
- = f.switch_box :published
21
+ = f.text_field :title
22
+ = f.group :intro
23
+ = f.content_editor :intro, floating: false
24
+ = f.group :published
25
+ = f.switch_box :published
23
26
  ```
@@ -1,7 +1,7 @@
1
1
  # Admin user
2
2
 
3
3
  ```sh
4
- rails g trek:admin:user
4
+ bin/rails g trek:admin:user
5
5
  # or (soon)
6
6
  trek admin:user
7
7
  ```
@@ -1,7 +1,7 @@
1
1
  # Audit log
2
2
 
3
3
  ```sh
4
- rails g trek:install:audit_log
4
+ bin/rails g trek:audit_log
5
5
  bin/rails db:migrate
6
6
  ```
7
7
 
@@ -43,6 +43,10 @@ class Api::BaseController < ActionController::API
43
43
  # Record reads as well as mutations
44
44
  self.audit_reads = true
45
45
 
46
+ # Actions that only read although they're not a GET, skipped as reads are (default: none),
47
+ # e.g. the chips hotwire_combobox requests with a POST
48
+ self.audit_read_actions = %i[chips]
49
+
46
50
  # The parameters whose values are recorded, the others by name only (default: id and role)
47
51
  self.audit_param_values = %w[id role status]
48
52
 
@@ -77,19 +81,14 @@ end
77
81
 
78
82
  ## Purging old rows
79
83
 
80
- `Trek::AuditLog::PurgeJob` deletes the rows older than 6 months, the low end of the [CNIL's recommendation](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000044272396) for logs (6 months to 1 year, up to 3 years for a particularly sensitive processing). Schedule it daily with your Active Job backend, e.g. with GoodJob's cron in `config/initializers/good_job.rb`:
84
+ `Trek::AuditLog::PurgeJob` deletes the rows older than 6 months, the low end of the [CNIL's recommendation](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000044272396) for logs (6 months to 1 year, up to 3 years for a particularly sensitive processing). The generator schedules it every night in GoodJob's cron, in the `config/initializers/good_job.rb` the installer writes. With another Active Job backend, it says so, and the job is to schedule daily with that backend. An app that installed the audit log before the generator did this adds the entry to its `config.good_job.cron` by hand:
81
85
 
82
86
  ```ruby
83
- Rails.application.configure do
84
- config.good_job.enable_cron = true
85
- config.good_job.cron = {
86
- purge_audit_logs: {
87
- cron: "0 4 * * *",
88
- class: "Trek::AuditLog::PurgeJob",
89
- description: "Delete the audit log rows past the retention window"
90
- }
91
- }
92
- end
87
+ purge_audit_logs: {
88
+ cron: "0 4 * * *",
89
+ class: "Trek::AuditLog::PurgeJob",
90
+ description: "Delete the audit log rows past the retention window"
91
+ },
93
92
  ```
94
93
 
95
94
  To keep the rows longer or shorter, set the retention in an initializer: `Trek::AuditLog::PurgeJob.retention = 1.year`.
@@ -108,6 +107,6 @@ The rows hold personal data: the author, the IP address, the user agent, and wha
108
107
 
109
108
  The `audit_logs` table uses the column names of the audit logs some apps wrote themselves (`actor`, `auditable`, `action`, `http_method`, `path`, `http_status`, `params`, `ip_address`, `user_agent`, `request_id`, `error_class`, `created_at`), so existing rows carry over. In such an app, skip the migration and replace the app's own files:
110
109
 
111
- 1. Run `rails g trek:install:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
110
+ 1. Run `bin/rails g trek:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
112
111
  2. Delete the app's `Auditable` concern, its initializer and its purge job, and update the job's cron entry to `Trek::AuditLog::PurgeJob`.
113
112
  3. Move app-specific columns (e.g. a request duration, or a denormalized foreign key) to `audit_attributes`, and their scopes and associations to the `AuditLog` model.