Zum Ende der Metadaten springen
Zum Anfang der Metadaten


Kompatibilität

Dieses Templatesystem ist erst ab LoxBerry V1.0 verfügbar.

Das alte Templatesystem (wo im eigenen Script das Template aus /templates/de usw. gelesen wird) wird weiterhin unterstützt

Verzeichnisstruktur (Plugin und System)

Die Verzeichnisstruktur wird betrachtet ausgehend vom template-Verzeichnis:

  • Bei Plugins wie bisher: /opt/loxberry/templates/plugins/<meinplugin>
  • Beim System wie bisher: /opt/loxberry/templates/system/

Auch im Plugin-Paket ändert sich somit nichts (Templates werden in /templates abgelegt).

Hauptverzeichnis

Die Templates liegen direkt im Hauptverzeichnis. Sprachverzeichnisse wie bisher fallen weg.
Die Templates sind multilingual. Mit Tags <TMPL_VAR Section.DasIstEineVariable> werden sprachspezifische Texte als Variablen im HTML codiert. 

Alle Sprachdateien werden in einem Ordner lang gesammelt. Die Sprachfunktionen von LoxBerry::Web suchen ohne Angabe eines Pfades immer in diesem Verzeichnis.

Die Hilfe wird in den Ordner help gelegt. Die Funktion LoxBerry::Web::lbheader, die für Ausgabe des HTML-Headers und der Hilfe zuständig ist, sucht die Hilfe immer, ohne Angabe eines Ordners, im help-Ordner. 

Verzeichnis help

Die Hilfe kann eine oder beliebig viele Hilfeseiten enthalten. Die meisten Plugins haben derzeit nur ein Hilfe-Template. Auch das Hilfe-Template wird mit oben genannten Tags sprachspezifisch aufgebaut.

Der Templatename wird bei LoxBerry::Web::lbheader übergeben: LoxBerry::Web::lbheader("Titel meines Plugins", "http://loxwiki.eu/meinplugin/", "pluginhelp.html"). Beachte: Es wird kein Ordner übergeben! Die Sprachdatei wird automatisch in /lang gesucht und muss so heißen wie das Template (siehe Verzeichnis lang). Das heißt, beispielsweise: Template heißt help/meinehilfe.html, das Sprachfile heißt lang/meinehilfe_en.ini, der Parameter ist (ohne Ordnerangabe!) "meinehilfe.html".


Dieses Beispiel geht von Hilfe-Templates mit <TMPL_VAR> Variablen aus. Beachte, dass LoxBerry auch noch ein klassisches Hilfesystem mit statischen HTML-Files pro Sprache unterstützt. Infos dazu hier: Funktionen zum Erstellen des Templates

Verzeichnis lang

Das Verzeichnis lang enthält alle Sprachdateien für alle unterstützten Sprachen. Jeweils das Sprachkürzel wird an den Namen angehängt. Die Dateiextension ist ini, weil das üblich ist bei Sprachdateien.

Der Name der Sprachdatei für das Plugin ist frei wählbar, der Name wird mit LoxBerry::System::readlanguage (auch wieder ohne Ordner) mitübergeben.

Das Hilfe-Sprachfile hingegen wird aus dem Namen des Hilfetemplates berechnet: /help/help_special.html sucht nach dem Sprachfile /lang/help_special_en.ini (Parameter ist "help_special.html").

Sprachfunktionen in LoxBerry::Web kümmern sich darum, dass man sich (bis auf die Erstellung des Templates und die Übersetzung) um sehr wenig kümmen muss.

 

Für eine genauere Erklärung der Parameter für die Hilfe siehe auch Funktionen zum Erstellen des Templates

Beispielcode

Dieser beispielhafte Code funktioniert nicht, soll aber verdeutlichen, wie einfach dieses System zu nutzen ist.

# Einbinden der LoxBerry-Module
use CGI;
use LoxBerry::System;
use LoxBerry::Web;
 
# Die Version des Plugins wird direkt aus der Plugin-Datenbank gelesen.
my $version = LoxBerry::System::pluginversion();

# Mit dieser Konstruktion lesen wir uns alle POST-Parameter in den Namespace R.
my $cgi = CGI->new;
$cgi->import_names('R');
# Ab jetzt kann beispielsweise ein POST-Parameter 'form' ausgelesen werden mit $R::form.


# Wir Übergeben die Titelzeile (mit Versionsnummer), einen Link ins Wiki und das Hilfe-Template.
# Um die Sprache der Hilfe brauchen wir uns im Code nicht weiter zu kümmern.
LoxBerry::Web::lbheader("Any-Plugin V$version", "http://www.loxwiki.eu/display/LOXBERRY/Any+Plugin", "help.html");
 
# Wir holen uns die Plugin-Config in den Hash %pcfg. Damit kannst du die Parameter mit $pcfg{'Section.Label'} direkt auslesen.
my %pcfg;
tie %pcfg, "Config::Simple", "$lbpconfigdir/anyplugin.cfg";


# Wir initialisieren unser Template. Der Pfad zum Templateverzeichnis steht in der globalen Variable $lbptemplatedir.
# Mit associate verknüpfen wir die Plugin-Config %pcfg. Variablen aus der Config können direkt im Template verwendet werden, 
# ohne diese extra zu initialisieren: <TMPL_VAR SECTION.NAME>
my $template = HTML::Template->new(
	filename => "$lbptemplatedir/index.html",
	global_vars => 1,
	loop_context_vars => 1,
	die_on_bad_params => 0,
	associate => %pcfg,
);
 
# Jetzt lassen wir uns die Sprachphrasen lesen. Ohne Pfadangabe wird im Ordner lang nach language_de.ini, language_en.ini usw. gesucht.
# Wir kümmern uns im Code nicht weiter darum, welche Sprache nun zu lesen wäre.
# Mit der Routine wird die Sprache direkt ins Template übernommen. Sollten wir trotzdem im Code eine brauchen, bekommen
# wir auch noch einen Hash zurück.
my %L = LoxBerry::Web::readlanguage($template, "language.ini");
 
# Checkboxen, Select-Lists sind mit HTML::Template kompliziert. Einfacher ist es, mit CGI das HTML-Element bauen zu lassen und dann
# das fertige Element ins Template einzufügen. Für die Labels und Auswahlen lesen wir aus der Config $pcfg und dem Sprachhash $L.
# Nicht mehr sicher, ob in der Config True, Yes, On, Enabled oder 1 steht? Die LoxBerry-Funktion is_enabled findet's heraus. 
# Weitere Beispiele finden sich hier: http://perlmeme.org/tutorials/cgi_form.html
my $activated = $cgi->checkbox(-name => 'activated',
								  -checked => is_enabled($pcfg{'Main.activated'}),
									-value => 'True',
									-label => $L{'Plugin_activated'},
								);
# Den so erzeugten HTML-Code schreiben wir ins Template.
$template->param( ACTIVATED => $activated);
 
# Nun wird das Template ausgegeben.
print $template->output();
 
# Schlussendlich lassen wir noch den Footer ausgeben.
LoxBerry::Web::lbfooter();
 

 Damit dieses Beispiel funktioniert, müssen die Dateien in der Ordnerstruktur folgendermaßen aussehen:

Funktionsaufruf
LoxBerry::Web::lbheader(
"Any-Plugin V$version", 
"http://www.loxwiki.eu/display/LOXBERRY/Any+Plugin", 
"help.html"
);

Hilfetemplate liegt unter

/help/help.html

Sprachdatei liegt unter

/lang/help_en.ini

my %L = LoxBerry::Web::readlanguage(
$template, 
"language.ini"
);

Sprachdatei liegt unter

/lang/language_en.ini


Tipps und Tricks

Wie kann ich einen Flipswitch über CGI und HTML::Template erzeugen?

Für einen Flipswitch (https://api.jquerymobile.com/flipswitch/) muss dem Select-Element das Attribut data-role="flipswitch" mit übergeben werden. Das sieht allerdings Perl-CGI nicht vor. Daher muss man dieses Attribut im HTML-Source-Code noch mit Javascript hinzufügen.

Perl Code
# Einbinden der LoxBerry-Module
use CGI;
use LoxBerry::System;
use LoxBerry::Web;
 
# Wir erzeugen eine Select-Liste mit 2 Einträgen für ON und OFF
@values = ('1', '0' );
%labels = (
      '1' => 'On',
      '0' => 'Off',
  );
my $selectlist = $cgi->popup_menu(
      -name    => 'selectlist',
      -values  => \@values,
      -labels  => \%labels,
      -default => '1',
  );
$template->param( SELECTLIST => $selectlist ); 


Im HTML-Template binden wir nun das zuvor fertig generierte Select-Element SELECTLIST ein und weisen im per Javascript noch das fehlende Attribut data-role="flipswitch" zu, damit die Liste nicht als Dropdown-Liste sondern als Flipswitch-Button gerendert wird.

HTML Template
<!-- Select-Element einbinden -->
<fieldset>
  <TMPL_VAR SELECTLIST>
</fieldset>

<!-- per Javascript dem Element das "data-role"-Attribut hinzufügen -->
<script>
// Add some attributes PERL::CGI doesn't provide
$('select[name=selectlist]').attr('data-role','flipswitch');
</script>



  • Keine Stichwörter