Globale Variablen für Druckvorlagen nach %::lx_office_conf verschoben
[kivitendo-erp.git] / doc / 2010_template_changes.txt
1 Table of Contents
2 -----------------
3
4 Inhalt der Anleitung
5 1 Zusammenfassung
6 2 Bisheriger Mechanismus und Motivation zur Änderung
7 3 Änderungen
8 4 Migration
9
10 Zusammenfassung
11 ---------------
12
13 Dieses Dokument beschreibt die Änderungen, die 2010 am Templatesystem von
14 Lx-Office vorgenommen wurden, sowie Möglichkeiten zur Migration aus alten
15 Systemen.
16
17 Die betroffenen Templates sind alle lokalisierten Templates im Verzeichnis
18 templates/. Die Druckvoragen sind nicht betroffen.
19
20
21 Bisheriger Mechanismus und Motivation zur Änderung
22 --------------------------------------------------
23
24 SQL Ledger benutzt für Darstellung garkein Templatesytem. HTML wird im Perlcode
25 zusammengebaut, und dabei über das Locale Modul lokalisiert. Gleichzeitig
26 werden Druckvorlagen in einer lokalisierten Version mitgeliefert und
27 vorgehalten, und werden beim anlegen eines Benutzers in sein lokales
28 Templateverzeichnis kopiert. Mit einem mitgelieferten Editor konnten diese HTML
29 Dateien dann editiert werden.
30
31 Das Lx-Office Templatesystem ist zuerst in Anlehnung daran entstanden.
32 Templates wurden in einer _master Version vorgehalten und mit den lokalisierten
33 Strings aus dem Programm statisch übersetzt, und dann zur Laufzeit mit
34 Variablen gefüllt. Das Template System war zuerst HTML::Template, wurde später
35 aber durch Template Toolkit ersetzt, was flexiblere Syntax bietet und eine
36 Größenordnung schneller ist.
37
38 Das System hat diverse Probleme. Templates sind im Programm in einem Coding
39 hinterlegt, das maßgeblich durch die einkompilierte Sprache bestimmt wird. Wenn
40 die Sprachtexte Latin-1 sind, sind die übersetzten Templates auch Latin-1.
41 Wenn die angeforderte Sprache aber UTF-8 ist, müssen die Templates zur Laufzeit
42 umcodiert werden. Das kostet Zeit, und erschwert caching.
43
44 Das nächste Problem sind Untertemplates. In ein kompiliertes Template ein
45 anderes Template einzubinden ist möglich, hat aber diverse Probleme mit Coding
46 und Lokalisierung, weil gewisse Kontextinformationen nicht weitergegeben
47 werden. Die Modularisierung von Templates ist ein langfristiges Ziel, deshalb
48 ist es gewünscht, dass das funktioniert.
49
50
51 Änderungen
52 ----------
53
54 Bisher wurden alle html Templates in allen Sprachversionen separat
55 vorgehalten. Diese sind jetzt entfernt, es wird nur noch die _master.html
56 weitergepflegt, die jetzt ohne diese Endung behandelt wird. So wird aus
57
58   template/webpages/oe/search_master.html und
59   template/webpages/oe/search_de.html
60   template/webpages/oe/search_en.html
61
62 jetzt nur noch
63
64   templates/webpages/oe/search.html
65
66 die alle Rollen übernimmt.
67
68 Gleichzeitig wurde der an HTML angelehnte <translate></translate> Operator
69 überall ersetzt durch das Template Modul T8, dass zur Templateverarbeitungszeit
70 auf die Lokalisierung von Lx-Office zugreift. Der <translate> Operator war für
71 statische Kompilierung gedacht, und ist dynamisch nicht ohne massive
72 Geschwindigkeitseinbusse umzusetzen.
73
74 Folgende Konstrukte sollten ab jetzt verwendet werden:
75
76   <translate>Originaltext</translate>
77   LxERP.format_text('<translate>Text with var #1</translate>', value)
78
79 werden zu:
80
81   [%- USE T8 %]
82   [%- USE LxERP %]
83
84   [% 'Originaltext' | $T8 %]
85   [% LxERP.t8('Text with var #1', value) | html %]
86
87 Beide Module sind in Perl geschrieben und sind Instanzen der Module
88
89   SL::Template::Plugin::T8 und
90   SL::Template::Plugin::LxERP
91
92 Migration
93 --------
94
95 Installationen, die Änderungen an den Templates vorgenommen haben, müssen
96 diese Änderungen manuell in die neuen Templates einpflegen.
97
98 Um die <translate> Operatoren umzuwandeln steht ein Hilfsscript bereit:
99
100   scripts/migrate_template_to_t8.pl <file>
101
102 Bitte vorher die Dokumentation von dem Script lesen.
103
104 Es gibt einige Fälle die nicht abgedeckt sind davon, aber die sollte mit einem
105 Diff danach zu finden sein. Vor allem kann es keine LxERP.format_text Aufrufe
106 umwandeln, und es hat keinen Schutz gegen nicht escapte Anführungszeichen in
107 den zu übersetzenden Strings.