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.