powertom 0.2.2
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.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +447 -0
- data/lib/powertom/adapter/page_surgery.rb +229 -0
- data/lib/powertom/adapter/ruby_pptx_adapter.rb +403 -0
- data/lib/powertom/binder.rb +204 -0
- data/lib/powertom/data_loading.rb +45 -0
- data/lib/powertom/formatter.rb +114 -0
- data/lib/powertom/grid_value.rb +53 -0
- data/lib/powertom/path_resolver.rb +52 -0
- data/lib/powertom/render.rb +558 -0
- data/lib/powertom/run_merge.rb +26 -0
- data/lib/powertom/scanner.rb +146 -0
- data/lib/powertom/table_loop.rb +776 -0
- data/lib/powertom/validator.rb +697 -0
- data/lib/powertom/version.rb +6 -0
- data/lib/powertom.rb +63 -0
- metadata +84 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: feb18b4055ad1229aba28ef398e78d829e0ef427df7b1fb3462dd01a23225058
|
|
4
|
+
data.tar.gz: da8dfe60234ef32aa8f237d33d0539f14006d220e8f58c2c427d84a05e3e50af
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: aac6b281fe867b01794e63be088a67a07f34c26f1848313491258cdf41e12315f3740f78cbffb8a8ce2870ff9218b441fab08a51c1419725df7f4dd6940ff726
|
|
7
|
+
data.tar.gz: 130010e8e837f4aeb6168b3ccd26378c6cce4611ec128910cd49ad9bf4084b13daa8f8161f81f1316625990f3ed0401ea689c443012171c6235e502a4f122104
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PowerTom contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,447 @@
|
|
|
1
|
+
# PowerTom — PowerPoint template engine for Ruby
|
|
2
|
+
|
|
3
|
+
> Designers keep the template in PowerPoint. Engineers pass a Ruby Hash (or a TOML file) and get a finished deck.
|
|
4
|
+
> Layout, fonts, colours, masters and theme stay under the designer's control; the code only scans tags, binds data and clones slides.
|
|
5
|
+
|
|
6
|
+
<sub>Not affiliated with Microsoft or TomTom.</sub>
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## In 30 seconds
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
Designer Engineer
|
|
14
|
+
┌──────────────────────────┐ ┌──────────────────────────┐
|
|
15
|
+
│ A plain pptx in │ │ report.toml │
|
|
16
|
+
│ PowerPoint: │ │ title = "Final exams" │
|
|
17
|
+
│ body: {{title}} │ ─────────▶ │ [[classes]] │
|
|
18
|
+
│ notes: {{#each classes}}│ │ name = "Grade 8 (3)" │
|
|
19
|
+
│ picture named │ │ avg = 82.4 │
|
|
20
|
+
│ powertom:image:cover │ │ │
|
|
21
|
+
└──────────────────────────┘ └──────────────────────────┘
|
|
22
|
+
│ │
|
|
23
|
+
└──────────────┬───────────────────┘
|
|
24
|
+
▼
|
|
25
|
+
PowerTom.render("template.pptx", data: "report.toml")
|
|
26
|
+
▼
|
|
27
|
+
Finished deck: tags bound, pages cloned/removed,
|
|
28
|
+
pictures replaced — opens in PowerPoint without repair.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Why another one
|
|
32
|
+
|
|
33
|
+
Ruby has two ways to produce PPTX today, and neither fits "reuse the design asset":
|
|
34
|
+
|
|
35
|
+
| Approach | Examples | Problem |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| Code-driven generation | `powerpoint`, `ruby_slides` | Layout is hard-coded; changing one font size needs a developer |
|
|
38
|
+
| Low-level OOXML library | `ruby_pptx`, `rbpptx` | XML building blocks, no template layer; designers cannot use it directly |
|
|
39
|
+
|
|
40
|
+
PowerTom fills the middle layer: a **template engine on top of [`ruby_pptx`](https://rubygems.org/gems/ruby_pptx)**, without parsing OOXML itself. Think Carbone / Docxtemplater for Ruby — no Node dependency, no external service, one line in your Gemfile.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
```ruby
|
|
45
|
+
# Gemfile
|
|
46
|
+
gem "powertom"
|
|
47
|
+
|
|
48
|
+
# Chemin local tant que le gem n'est pas publié sur RubyGems
|
|
49
|
+
# gem "powertom", path: "/chemin/vers/PowerTom"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Requires Ruby >= 3.3; depends on `ruby_pptx ~> 0.2.0` (read/write) and `tomlrb ~> 3.0` (data files).
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
**1. The designer builds a template** — just a normal pptx, tags in the body, page directives in the notes:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
Body: Welcome to {{product_name}}
|
|
60
|
+
Adoption rate {{kpis[0].value}}
|
|
61
|
+
Notes: {{#each scenarios}}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**2. The engineer prepares the data** — TOML is the default data format:
|
|
65
|
+
|
|
66
|
+
```toml
|
|
67
|
+
# TOML — format de données par défaut
|
|
68
|
+
product_name = "Student workspace"
|
|
69
|
+
show_compare = true
|
|
70
|
+
|
|
71
|
+
[[kpis]]
|
|
72
|
+
name = "Adoption rate"
|
|
73
|
+
value = "29.7%"
|
|
74
|
+
|
|
75
|
+
[[scenarios]]
|
|
76
|
+
headline = "Morning reading pack"
|
|
77
|
+
detail = "Ready automatically every Sunday"
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**3. Render:**
|
|
81
|
+
|
|
82
|
+
```ruby
|
|
83
|
+
require "powertom"
|
|
84
|
+
|
|
85
|
+
# Lecture du modèle, liaison des balises, duplication/suppression de pages,
|
|
86
|
+
# remplacement des images
|
|
87
|
+
result = PowerTom.render("templates/report.pptx", data: "data/report.toml")
|
|
88
|
+
result.save("out/report.pptx")
|
|
89
|
+
result.warnings.each { |w| warn w } # champs inutilisés, valeurs de repli…
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Or pass a Hash directly when the data comes from a database or an API:
|
|
93
|
+
|
|
94
|
+
```ruby
|
|
95
|
+
# Même appel avec des données en mémoire
|
|
96
|
+
result = PowerTom.render("templates/report.pptx", data: {
|
|
97
|
+
product_name: "Student workspace",
|
|
98
|
+
kpis: [{ name: "Adoption rate", value: "29.7%" }],
|
|
99
|
+
scenarios: [{ headline: "Morning reading pack", detail: "Ready every Sunday" }]
|
|
100
|
+
})
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Template syntax
|
|
104
|
+
|
|
105
|
+
| Syntax | Where | Meaning |
|
|
106
|
+
| --- | --- | --- |
|
|
107
|
+
| `{{title}}` | body | Bind a field |
|
|
108
|
+
| `{{kpis[0].value}}` | body | Dot path + array index |
|
|
109
|
+
| `{{classes[].name}}` | table cell | Table row loop: clones the row per array item |
|
|
110
|
+
| `{{#rows groups}}` | table row | Nested loop marker: declares the parent array (marker row itself is not printed) |
|
|
111
|
+
| `{{#rows groups[].items}}` | table row | Nested loop marker: declares the child array |
|
|
112
|
+
| `{{#grid rows: .. cols: ..}}` | table header | Dynamic columns: clones the template column per `cols` item |
|
|
113
|
+
| `{{#rows groups}} ... {{/rows}}` | table rows | Paired row block: clones all rows between the markers per item (up to 3 levels) |
|
|
114
|
+
| `{{#cols subjects}} ... {{/cols}}` | table row | Column band: one or more template columns; may be declared in the header or inside a row block |
|
|
115
|
+
| `{{#if groups[].flag}} ... {{/if}}` | table rows | Conditional row block inside a `#rows` block |
|
|
116
|
+
| `{{price:currency}}` | body | Formatter: ¥1,234.56 |
|
|
117
|
+
| `{{ratio:percent.1}}` | body | Formatter: 29.7% |
|
|
118
|
+
| `{{day:date.year_month}}` | body | Formatter: 2026年11月 |
|
|
119
|
+
| `{{#each scenarios}}` | notes | Clone the page per array item (empty array removes the group) |
|
|
120
|
+
| `{{#if show_compare}}` | notes | Remove the page when falsy |
|
|
121
|
+
|
|
122
|
+
- **Split runs are handled**: if PowerPoint stores `{{title}}` as several runs, the engine merges the paragraph and replaces correctly; the result inherits the first run's style.
|
|
123
|
+
- **Nested table rows**: `{{#rows groups}}` occupies a whole row (first cell only), and the next row is the parent content row; `{{#rows groups[].items}}` followed by its own content row adds one nesting level. Two levels maximum; parent and child tags use full paths (`{{groups[].name}}`, `{{groups[].items[].name}}`).
|
|
124
|
+
- **Dynamic columns**: put `{{#grid rows: distribution cols: bands value: counts}}` in the header row's first cell. The header row's second cell is the column template (`{{col.label}}`), and the next row is the row template (`{{row.name}}` in the first cell, `{{cell}}` in the data columns). Exactly two columns; `value:` is optional (defaults to `row[col.key]`).
|
|
125
|
+
- **Row blocks (v0.2.x)**: `{{#rows groups}} ... {{/rows}}` each occupy a whole row; everything between them is one record template and is cloned per item. Up to 3 nested levels; `{{row.name}}` refers to the current record. A `{{#cols ...}}` band may be declared in the header or directly inside a row block, and may span several template columns; `value: scores,rates` maps one field to each template column (a single field is shared by all). A `{{#if ...}} ... {{/if}}` block inside a row block removes all its rows for items where the condition is falsy.
|
|
126
|
+
- **Pictures**: name the shape or its alt text `powertom:image:cover` and pass a file path in the data. Replacement always fills the shape and crops from the centre.
|
|
127
|
+
- One directive per notes page, maximum.
|
|
128
|
+
- TOML dates are written unquoted (`report_date = 2026-01-20`), normalised to Ruby `Date`, and can be formatted with `{{report_date:date.cn}}`.
|
|
129
|
+
- Full guide for designers (Chinese): [docs/模板制作规范.md](docs/模板制作规范.md).
|
|
130
|
+
|
|
131
|
+
Built-in formatters: `currency`, `percent`, `number`, `date` (with `.year_month` / `.cn` / `.short`).
|
|
132
|
+
Register your own:
|
|
133
|
+
|
|
134
|
+
```ruby
|
|
135
|
+
# Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
|
|
136
|
+
PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
|
|
137
|
+
# Utilisation dans le modèle : {{amount:rmb}}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Template checker
|
|
141
|
+
|
|
142
|
+
Most tools treat validation as a side effect of logging. PowerTom makes it a first-class step: bad templates fail in CI before anything is rendered.
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
bundle exec rake powertom:check TEMPLATE=templates/report.pptx DATA=data/sample.toml
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Example report (messages are currently emitted in Chinese):
|
|
149
|
+
|
|
150
|
+
```text
|
|
151
|
+
PowerTom 模板校验 — report.pptx
|
|
152
|
+
[warning] 第 9 页 形状'(备注)' {{scenarios}} 数组 'scenarios' 为空(0 项):渲染时该组页面将被整组删除
|
|
153
|
+
[error ] 第 2 页 形状'圆角矩形 4' {{workload}} 数据里没有字段 'workload'
|
|
154
|
+
[error ] 第 5 页 形状'powertom:image:banner' {{banner}} 图片文件不存在:/tmp/a.png
|
|
155
|
+
[warning] 数据字段 'unused_field' 未被模板使用
|
|
156
|
+
------------------------------------------------
|
|
157
|
+
2 个 error,2 个 warning(error 阻断渲染,修正后再调用 PowerTom.render)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Programmatic API:
|
|
161
|
+
|
|
162
|
+
```ruby
|
|
163
|
+
# Vérifie sans rendre ; les erreurs sont rapportées, pas levées
|
|
164
|
+
result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
|
|
165
|
+
result.ok? # => false
|
|
166
|
+
result.errors # chaque entrée porte slide_no / shape / label / message
|
|
167
|
+
result.report # le rapport lisible ci-dessus
|
|
168
|
+
result.exit_code # 0 ou 1 — utilisable en CI
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Checks: missing fields (including each item of an `#each` array), unregistered formatters, directive syntax, more than one directive per page, picture fields and missing files, placeholder overflow warnings, unused data fields, leftover tags in notes.
|
|
172
|
+
|
|
173
|
+
## Error model
|
|
174
|
+
|
|
175
|
+
| Situation | Behaviour |
|
|
176
|
+
| --- | --- |
|
|
177
|
+
| Missing field | `PowerTom::MissingDataError` by default, with slide number, shape name and tag; with `strict: false`, fills in blank and records a warning |
|
|
178
|
+
| Invalid tag syntax | `PowerTom::TemplateSyntaxError` before rendering |
|
|
179
|
+
| Not a valid pptx | `PowerTom::InvalidTemplateError` |
|
|
180
|
+
| Missing `#each` path | Always raises — pages are never silently dropped |
|
|
181
|
+
|
|
182
|
+
Output is **all or nothing**: every check runs before anything is written to disk.
|
|
183
|
+
|
|
184
|
+
## Limitations (v0.1)
|
|
185
|
+
|
|
186
|
+
| Limitation | Notes |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| Tables support row loops, paired row blocks, nesting and dynamic columns; charts are not bound | `{{classes[].name}}` clones one row; `{{#rows ...}} ... {{/rows}}` clones multi-row records (3 levels); `{{#grid ...}}` / `{{#cols ...}}` clone columns; merged cells inside loops are rejected |
|
|
189
|
+
| Notes are not rendered | Notes are only read for page directives |
|
|
190
|
+
| Tags on masters/layouts are ignored | Only shapes on slides are processed |
|
|
191
|
+
| No PPT → PDF | Use LibreOffice headless |
|
|
192
|
+
| `.pptx` only | No legacy 97-2003 binary format |
|
|
193
|
+
| TOML or Hash only | No YAML / JSON loader |
|
|
194
|
+
| Fixed picture cropping | Always fill the shape and crop from the centre |
|
|
195
|
+
| Messages are Chinese-only | Localisation is planned; the report format is language-neutral |
|
|
196
|
+
|
|
197
|
+
## Development
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
bundle install
|
|
201
|
+
bundle exec rspec
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
The golden-sample template used by the end-to-end tests (split runs, cloning, picture replacement, fidelity) is not committed, because of size and ownership; only its structural snapshot `spec/fixtures/hai_mate/manifest.toml` is. With the original template at hand:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
bundle exec rake fixtures:generate TEMPLATE=/path/to/template.pptx OUT=spec/fixtures/hai_mate
|
|
208
|
+
bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Without `template.pptx`, fixture-dependent examples are skipped and the unit suite still runs. Fidelity tests need LibreOffice (`soffice`).
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
MIT.
|
|
216
|
+
|
|
217
|
+
## Why PowerTom
|
|
218
|
+
|
|
219
|
+
The Tom in PowerTom is a dedication — left unexplained, on purpose.
|
|
220
|
+
|
|
221
|
+
Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
# PowerTom — moteur de modèles PowerPoint pour Ruby
|
|
227
|
+
|
|
228
|
+
> Les designers maintiennent le modèle dans PowerPoint. Les développeurs passent un Hash Ruby (ou un fichier TOML) et obtiennent une présentation finalisée.
|
|
229
|
+
> La mise en page, les polices, les couleurs, les masques et le thème restent sous le contrôle du designer ; le code se contente de scanner les balises, de lier les données et de dupliquer les diapositives.
|
|
230
|
+
|
|
231
|
+
<sub>Non affilié à Microsoft ni à TomTom.</sub>
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## En 30 secondes
|
|
236
|
+
|
|
237
|
+
```text
|
|
238
|
+
Designer Développeur
|
|
239
|
+
┌──────────────────────────┐ ┌──────────────────────────┐
|
|
240
|
+
│ Un pptx ordinaire dans │ │ report.toml │
|
|
241
|
+
│ PowerPoint : │ │ title = "Examens" │
|
|
242
|
+
│ corps : {{title}} │ ─────────▶ │ [[classes]] │
|
|
243
|
+
│ notes : {{#each classes}}│ │ name = "8e (3)" │
|
|
244
|
+
│ image nommée │ │ avg = 82.4 │
|
|
245
|
+
│ powertom:image:cover │ │ │
|
|
246
|
+
└──────────────────────────┘ └──────────────────────────┘
|
|
247
|
+
│ │
|
|
248
|
+
└──────────────┬───────────────────┘
|
|
249
|
+
▼
|
|
250
|
+
PowerTom.render("template.pptx", data: "report.toml")
|
|
251
|
+
▼
|
|
252
|
+
Présentation finale : balises liées, pages dupliquées
|
|
253
|
+
ou supprimées, images remplacées — s'ouvre dans
|
|
254
|
+
PowerPoint sans message de réparation.
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Pourquoi un nouveau moteur
|
|
258
|
+
|
|
259
|
+
Ruby propose aujourd'hui deux façons de produire des PPTX, et aucune ne convient à la réutilisation d'un actif de design :
|
|
260
|
+
|
|
261
|
+
| Approche | Exemples | Problème |
|
|
262
|
+
| --- | --- | --- |
|
|
263
|
+
| Génération pilotée par le code | `powerpoint`, `ruby_slides` | La mise en page est codée en dur ; changer une taille de police exige un développeur |
|
|
264
|
+
| Bibliothèque OOXML bas niveau | `ruby_pptx`, `rbpptx` | Des briques XML, pas de couche modèle ; inutilisable par un designer |
|
|
265
|
+
|
|
266
|
+
PowerTom occupe la couche intermédiaire : un **moteur de modèles au-dessus de [`ruby_pptx`](https://rubygems.org/gems/ruby_pptx)**, sans analyser OOXML lui-même. L'équivalent Ruby de Carbone / Docxtemplater — sans dépendance Node, sans service externe, une ligne dans le Gemfile.
|
|
267
|
+
|
|
268
|
+
## Installation
|
|
269
|
+
|
|
270
|
+
```ruby
|
|
271
|
+
# Gemfile
|
|
272
|
+
gem "powertom"
|
|
273
|
+
|
|
274
|
+
# Chemin local tant que le gem n'est pas publié sur RubyGems
|
|
275
|
+
# gem "powertom", path: "/chemin/vers/PowerTom"
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Nécessite Ruby >= 3.3 ; dépend de `ruby_pptx ~> 0.2.0` (lecture/écriture) et de `tomlrb ~> 3.0` (fichiers de données).
|
|
279
|
+
|
|
280
|
+
## Démarrage rapide
|
|
281
|
+
|
|
282
|
+
**1. Le designer construit le modèle** — un pptx normal, les balises dans le corps, les directives de page dans les notes :
|
|
283
|
+
|
|
284
|
+
```text
|
|
285
|
+
Corps : Bienvenue sur {{product_name}}
|
|
286
|
+
Taux d'adoption {{kpis[0].value}}
|
|
287
|
+
Notes : {{#each scenarios}}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
**2. Le développeur prépare les données** — TOML est le format de données par défaut :
|
|
291
|
+
|
|
292
|
+
```toml
|
|
293
|
+
# TOML — format de données par défaut
|
|
294
|
+
product_name = "Espace de travail enseignant"
|
|
295
|
+
show_compare = true
|
|
296
|
+
|
|
297
|
+
[[kpis]]
|
|
298
|
+
name = "Taux d'adoption"
|
|
299
|
+
value = "29.7%"
|
|
300
|
+
|
|
301
|
+
[[scenarios]]
|
|
302
|
+
headline = "Pack de lecture du matin"
|
|
303
|
+
detail = "Prêt automatiquement chaque dimanche"
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
**3. Rendu :**
|
|
307
|
+
|
|
308
|
+
```ruby
|
|
309
|
+
require "powertom"
|
|
310
|
+
|
|
311
|
+
# Lecture du modèle, liaison des balises, duplication/suppression de pages,
|
|
312
|
+
# remplacement des images
|
|
313
|
+
result = PowerTom.render("templates/report.pptx", data: "data/report.toml")
|
|
314
|
+
result.save("out/report.pptx")
|
|
315
|
+
result.warnings.each { |w| warn w } # champs inutilisés, valeurs de repli…
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Ou passez directement un Hash quand les données viennent d'une base ou d'une API :
|
|
319
|
+
|
|
320
|
+
```ruby
|
|
321
|
+
# Même appel avec des données en mémoire
|
|
322
|
+
result = PowerTom.render("templates/report.pptx", data: {
|
|
323
|
+
product_name: "Espace de travail enseignant",
|
|
324
|
+
kpis: [{ name: "Taux d'adoption", value: "29.7%" }],
|
|
325
|
+
scenarios: [{ headline: "Pack de lecture", detail: "Prêt chaque dimanche" }]
|
|
326
|
+
})
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
## Syntaxe des modèles
|
|
330
|
+
|
|
331
|
+
| Syntaxe | Emplacement | Signification |
|
|
332
|
+
| --- | --- | --- |
|
|
333
|
+
| `{{title}}` | corps | Lier un champ |
|
|
334
|
+
| `{{kpis[0].value}}` | corps | Chemin pointé + indice de tableau |
|
|
335
|
+
| `{{classes[].name}}` | cellule de tableau | Boucle de lignes : duplique la ligne pour chaque élément |
|
|
336
|
+
| `{{#rows groups}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau parent (la ligne de marqueur n'est pas imprimée) |
|
|
337
|
+
| `{{#rows groups[].items}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau enfant |
|
|
338
|
+
| `{{#grid rows: .. cols: ..}}` | en-tête de tableau | Colonnes dynamiques : duplique la colonne modèle pour chaque élément de `cols` |
|
|
339
|
+
| `{{#rows groups}} ... {{/rows}}` | lignes de tableau | Bloc de lignes apparié : duplique toutes les lignes entre les marqueurs par élément (3 niveaux max) |
|
|
340
|
+
| `{{#cols subjects}} ... {{/cols}}` | ligne de tableau | Bande de colonnes : une ou plusieurs colonnes modèles ; peut être déclarée dans l'en-tête ou dans un bloc de lignes |
|
|
341
|
+
| `{{#if groups[].flag}} ... {{/if}}` | lignes de tableau | Bloc de lignes conditionnel à l'intérieur d'un bloc `#rows` |
|
|
342
|
+
| `{{price:currency}}` | corps | Formateur : `¥1,234.56` |
|
|
343
|
+
| `{{ratio:percent.1}}` | corps | Formateur : `29.7%` |
|
|
344
|
+
| `{{day:date.year_month}}` | corps | Formateur : 2026年11月 |
|
|
345
|
+
| `{{#each scenarios}}` | notes | Duplique la page pour chaque élément (tableau vide = groupe supprimé) |
|
|
346
|
+
| `{{#if show_compare}}` | notes | Supprime la page si la valeur est fausse |
|
|
347
|
+
|
|
348
|
+
- **Les runs fractionnés sont gérés** : si PowerPoint découpe `{{title}}` en plusieurs runs, le moteur fusionne le paragraphe et remplace correctement ; le résultat hérite du style du premier run.
|
|
349
|
+
- **Lignes de tableau imbriquées** : `{{#rows groups}}` occupe une ligne entière (première cellule uniquement), et la ligne suivante est la ligne de contenu parent ; `{{#rows groups[].items}}` suivie de sa propre ligne de contenu ajoute un niveau. Deux niveaux maximum ; les balises parent et enfant utilisent le chemin complet (`{{groups[].name}}`, `{{groups[].items[].name}}`).
|
|
350
|
+
- **Colonnes dynamiques** : placez `{{#grid rows: distribution cols: bands value: counts}}` dans la première cellule de l'en-tête. La deuxième cellule de l'en-tête est le modèle de colonne (`{{col.label}}`), et la ligne suivante est le modèle de ligne (`{{row.name}}` dans la première cellule, `{{cell}}` dans les colonnes de données). Exactement deux colonnes ; `value:` est facultatif (par défaut `row[col.key]`).
|
|
351
|
+
- **Blocs de lignes (v0.2.x)** : `{{#rows groups}} ... {{/rows}}` occupent chacun une ligne entière ; tout ce qui se trouve entre eux est le modèle d'un enregistrement, dupliqué par élément. Jusqu'à 3 niveaux ; `{{row.name}}` désigne l'enregistrement courant. Une bande `{{#cols ...}}` peut être déclarée dans l'en-tête ou directement dans un bloc de lignes, et couvrir plusieurs colonnes modèles ; `value: scores,rates` associe un champ à chaque colonne modèle (un seul champ est partagé par toutes). Un bloc `{{#if ...}} ... {{/if}}` dans un bloc de lignes supprime toutes ses lignes pour les éléments dont la condition est fausse.
|
|
352
|
+
- **Images** : nommez la forme ou son texte de remplacement `powertom:image:cover` et fournissez un chemin de fichier dans les données. Le remplacement remplit toujours la forme et recadre depuis le centre.
|
|
353
|
+
- Une seule directive par page de notes, au maximum.
|
|
354
|
+
- Les dates TOML s'écrivent sans guillemets (`report_date = 2026-01-20`), sont normalisées en `Date` Ruby et peuvent être formatées avec `{{report_date:date.cn}}`.
|
|
355
|
+
- Guide complet pour les designers (en chinois) : [docs/模板制作规范.md](docs/模板制作规范.md).
|
|
356
|
+
|
|
357
|
+
Formateurs intégrés : `currency`, `percent`, `number`, `date` (avec `.year_month` / `.cn` / `.short`).
|
|
358
|
+
Ajoutez les vôtres :
|
|
359
|
+
|
|
360
|
+
```ruby
|
|
361
|
+
# Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
|
|
362
|
+
PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
|
|
363
|
+
# Utilisation dans le modèle : {{amount:rmb}}
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## Vérificateur de modèles
|
|
367
|
+
|
|
368
|
+
La plupart des outils traitent la validation comme un effet de bord des logs. PowerTom en fait une étape de premier ordre : un modèle défectueux échoue en CI avant tout rendu.
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
bundle exec rake powertom:check TEMPLATE=templates/report.pptx DATA=data/sample.toml
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Exemple de rapport (les messages sont actuellement en chinois) :
|
|
375
|
+
|
|
376
|
+
```text
|
|
377
|
+
PowerTom 模板校验 — report.pptx
|
|
378
|
+
[warning] 第 9 页 形状'(备注)' {{scenarios}} 数组 'scenarios' 为空(0 项):渲染时该组页面将被整组删除
|
|
379
|
+
[error ] 第 2 页 形状'圆角矩形 4' {{workload}} 数据里没有字段 'workload'
|
|
380
|
+
[error ] 第 5 页 形状'powertom:image:banner' {{banner}} 图片文件不存在:/tmp/a.png
|
|
381
|
+
[warning] 数据字段 'unused_field' 未被模板使用
|
|
382
|
+
------------------------------------------------
|
|
383
|
+
2 个 error,2 个 warning(error 阻断渲染,修正后再调用 PowerTom.render)
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
API programmatique :
|
|
387
|
+
|
|
388
|
+
```ruby
|
|
389
|
+
# Vérifie sans rendre ; les erreurs sont rapportées, pas levées
|
|
390
|
+
result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
|
|
391
|
+
result.ok? # => false
|
|
392
|
+
result.errors # chaque entrée porte slide_no / shape / label / message
|
|
393
|
+
result.report # le rapport lisible ci-dessus
|
|
394
|
+
result.exit_code # 0 ou 1 — utilisable en CI
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Contrôles : champs manquants (y compris chaque élément d'un tableau `#each`), formateurs non enregistrés, syntaxe des directives, plus d'une directive par page, champs d'image et fichiers absents, avertissements de débordement de texte, champs de données inutilisés, balises oubliées dans les notes.
|
|
398
|
+
|
|
399
|
+
## Modèle d'erreurs
|
|
400
|
+
|
|
401
|
+
| Situation | Comportement |
|
|
402
|
+
| --- | --- |
|
|
403
|
+
| Champ manquant | `PowerTom::MissingDataError` par défaut, avec numéro de diapositive, nom de forme et balise ; avec `strict: false`, remplit par du vide et enregistre un avertissement |
|
|
404
|
+
| Syntaxe de balise invalide | `PowerTom::TemplateSyntaxError` avant le rendu |
|
|
405
|
+
| Fichier pptx invalide | `PowerTom::InvalidTemplateError` |
|
|
406
|
+
| Chemin `#each` manquant | Lève toujours — aucune page n'est supprimée silencieusement |
|
|
407
|
+
|
|
408
|
+
La sortie est **tout ou rien** : tous les contrôles ont lieu avant la moindre écriture sur disque.
|
|
409
|
+
|
|
410
|
+
## Limites (v0.1)
|
|
411
|
+
|
|
412
|
+
| Limite | Précision |
|
|
413
|
+
| --- | --- |
|
|
414
|
+
| Tableaux : boucles de lignes, blocs appariés, imbrication et colonnes dynamiques ; graphiques non liés | `{{classes[].name}}` duplique une ligne ; `{{#rows ...}} ... {{/rows}}` duplique des enregistrements multi-lignes (3 niveaux) ; `{{#grid ...}}` / `{{#cols ...}}` dupliquent des colonnes ; les cellules fusionnées dans une boucle sont refusées |
|
|
415
|
+
| Les notes ne sont pas rendues | Elles servent uniquement aux directives de page |
|
|
416
|
+
| Les balises sur les masques/dispositions sont ignorées | Seules les formes des diapositives sont traitées |
|
|
417
|
+
| Pas de PPT → PDF | Utilisez LibreOffice en mode headless |
|
|
418
|
+
| `.pptx` uniquement | Pas de format binaire 97-2003 |
|
|
419
|
+
| TOML ou Hash uniquement | Pas de chargeur YAML / JSON |
|
|
420
|
+
| Recadrage d'image fixe | Toujours remplir la forme et recadrer depuis le centre |
|
|
421
|
+
| Messages en chinois uniquement | La localisation est prévue ; le format du rapport est neutre |
|
|
422
|
+
|
|
423
|
+
## Développement
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
bundle install
|
|
427
|
+
bundle exec rspec
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Le modèle de référence utilisé par les tests de bout en bout (runs fractionnés, duplication, remplacement d'images, fidélité) n'est pas versionné, pour des raisons de taille et de propriété ; seule son empreinte structurelle `spec/fixtures/hai_mate/manifest.toml` l'est. Avec le modèle d'origine :
|
|
431
|
+
|
|
432
|
+
```bash
|
|
433
|
+
bundle exec rake fixtures:generate TEMPLATE=/chemin/vers/modele.pptx OUT=spec/fixtures/hai_mate
|
|
434
|
+
bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
Sans `template.pptx`, les exemples qui en dépendent sont ignorés et la suite unitaire s'exécute normalement. Les tests de fidélité nécessitent LibreOffice (`soffice`).
|
|
438
|
+
|
|
439
|
+
## Licence
|
|
440
|
+
|
|
441
|
+
MIT.
|
|
442
|
+
|
|
443
|
+
## Pourquoi PowerTom
|
|
444
|
+
|
|
445
|
+
The Tom in PowerTom is a dedication — left unexplained, on purpose.
|
|
446
|
+
|
|
447
|
+
Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.
|