Themes ====== Themes (sinngem.: Thema, Leitmotiv) stellen eine Methode dar, das Aussehen einer Webseite systematisch anzupassen. Durch das Anwenden eines Themes kann man das komplette Erscheinungsbild einer Webanwendung praktisch auf Knopfdruck grundlegend verändern. Jedes Theme wird in Yii von einem Verzeichnis dargestellt, das View-, Layout- und andere relevante Ressourcedateien, wie Bilder, CSS- und Javascript-Dateien enthält. Der Name eines Themes entspricht dem Verzeichnisnamen. Alle Themes befinden sich unterhalb von `WebVerzeichnis/themes`. Es kann jeweils immer nur ein Theme aktiv sein. > Tip|Tipp: Das Standardverzeichnis für Themes kann auch an einem anderen Ort als `WebVerzeichnis/themes` liegen. Dazu konfiguriert man einfach die beiden Eigenschaften [basePath|CThemeManager::basePath] (Basispfad) und [baseUrl|CThemeManager::baseUrl] (Basis-URL) der [themeManager|CWebApplication::themeManager]-Anwendungskomponente. Verwenden von Themes -------------------- Um ein Theme anzuwenden, setzt man die Eigenschaft [theme|CWebApplication::theme] der Webanwendung auf den Namen des gewünschten Themes. Dies kann entweder in der [Anwendungskonfiguration](/doc/guide/basics.application#application-configuration) oder während der Laufzeit in einer Controller-Action geschehen. > Note|Hinweis: Beim Namen eines Themes spielt die Groß-/Kleinschreibung eine > Rolle. Wenn man ein Theme konfiguriert, das es gar nicht gibt, > liefert `Yii::app()->theme` den Wert `null` zurück. Erstellen eines Themes ---------------------- Die Inhalte eines Themeverzeichnisses sollten genau wie im [Anwendungsverzeichnis](/doc/guide/basics.application#application-base-directory) abgelegt werden. Alle View-Dateien müssen sich zum Beispiel in `views`, Layout-Dateien in `views/layout` und System-View-Dateien unter `views/system` befinden. Möchte man z.B. den View `create` für `PostController` durch einen View des Themes `classic` ersetzen, sollte die neue Datei unter `WebVerzeichnis/themes/classic/views/post/create.php` abgelegt werden. Für die View-Dateien eines Controllers, der in einem [Modul](/doc/guide/basics.module) enthalten ist, sollte die entsprechende View-Datei des Themes ebenfalls unterhalb des `views`-Verzeichnisses abgelegt werden. Wenn der genannte `PostController` zum Beispiel in einem Modul namens `forum` enthalten ist, sollte die View-Datei für `create` unter `WebVerzeichnis/themes/classic/views/forum/post/create.php` abgespeichert werden. Falls das `forum`-Modul selbst wiederum als verschachteltes Modul in einem Modul namens `support` enthalten ist, sollte die View-Datei unter `WebVerzeichnis/themes/classic/views/support/forum/post/create.php` liegen. > Note|Hinweis: Da das `views`-Verzeichnis sicherheitskritische Daten enthalten könnte, sollten Sie dafür sorgen, dass es nicht vom Web aus zugänglich ist. Beim Aufruf von [render|CController::render] oder [renderPartial|CController::renderPartial] zum Anzeigen eines Views, werden die entsprechenden View- und Layout-Dateien im Verzeichnis des gerade aktiven Themes gesucht und, falls dort vorgefunden, zum Rendern verwendet. Falls nicht, wird in den üblichen Verzeichnissen gesucht, wie mit [viewPath|CController::viewPath] und [layoutPath|CWebApplication::layoutPath] vorgegeben. > Tip|Tipp: Innerhalb eines Theme-Views muss evtl. öfter auf andere > Ressource-Dateien des Theme verlinkt werden. Zum Beispiel um eine > Bilddatei im Ordner `images` des Themes anzuzeigen. Mit Hilfe der > Eigenschaft [baseUrl|CTheme::baseUrl] des aktuellen Themes kann man die > Bild-URL wie folgt zusammenbauen: > > ~~~ > [php] > Yii::app()->theme->baseUrl . '/images/BildName.gif' > ~~~ Nachfolgend ein Beispiel für die Verzeichnisstruktur einer Anwendung mit den beiden Themes `basic` und `fancy`. ~~~ WebVerzeichnis/ assets protected/ .htaccess components/ controllers/ models/ views/ layouts/ main.php site/ index.php themes/ basic/ views/ .htaccess layouts/ main.php site/ index.php fancy/ views/ .htaccess layouts/ main.php site/ index.php ~~~ Konfiguriert man die Anwendung so: ~~~ [php] return array( 'theme'=>'basic', ...... ); ~~~ wird das Theme `basic` verwendet. Das bedeutet, dass das Layout in `themes/basic/views/layouts` der Index-View in `themes/basics/views/site` verwendet wird. Falls Yii dort keine Viewdatei findet, verwendet es die Datei in `protected/views`. Themes für Widgets ------------------ Ab Version 1.1.5 können Themes auch für Widget-Views verwendet werden. Rendert man einen Widgetview mit [CWidget::render()], sucht Yii auch im Themeverzeichnis nach einer entsprechenden Datei. Möchte man den View `xyz` eines Widgets `Foo` in ein Theme einbeziehen, so legt man zunächst einen Ordner `Foo` (dem Namen des Widgets) im aktiven Themeverzeichnis an. Falls die Widgetklasse Namespaces (seit PHP 5.3.0) verwendet, wie z.B. `\app\widgets\Foo`, sollte dieser Ordner `app_widgets_Foo` heißen. Man ersetzt in diesem Fall also die Namespace-Separatoren mit einem Unterstrich. Jetzt legt man die Viewdatei `xyz.php` in diesem Verzeichnis ab. Falls das aktuelle Theme `basic`ist, sollte man also nun eine Datei `themes/basic/views/Foo/xyz.php` haben, die dann vom Widget verwendet wird, um den ursprünglichen View zu ersetzen. Widgets global anpassen ----------------------- > Note|Hinweis: Dieses Feature steht seit Version 1.1.3 zur Verfügung. Beim Arbeiten mit Widgets aus Yii oder von anderen Anbietern muss man diese häufig an spezifische Bedürfnisse anpassen. Etwa wenn der Wert von [CLinkPager::maxButtonCount] nicht 10 (Standard), sondern 5 sein soll. Man kann diesen Startwert zwar beim Aufruf von [CBaseController::widget] setzen, allerdings muss das dann wiederholt an jeder Stelle geschehen, an der [CLinkPager] verwendet wird. ~~~ [php] $this->widget('CLinkPager', array( 'pages'=>$pagination, 'maxButtonCount'=>5, 'cssFile'=>false, )); ~~~ Nutzt man das Feature für die globale Anpassung von Widgets, kann man diese Startwerte auch zentral in der Konfiguration setzen. Spezifische Widget-Anpassungen lassen sich so wesentlich einfacher verwalten. Dazu muss eine [widgetFactory|CWebApplication::widgetFactory] wie folgt konfiguriert werden: ~~~ [php] return array( 'components'=>array( 'widgetFactory'=>array( 'widgets'=>array( 'CLinkPager'=>array( 'maxButtonCount'=>5, 'cssFile'=>false, ), 'CJuiDatePicker'=>array( 'language'=>'ru', ), ), ), ), ); ~~~ Damit werden die Starteigenschaften von [CLinkPager] und [CJuiDatePicker] über die [CWidgetFactory::widgets]-Eigenschaft bestimmt. Wie Sie sehen, wird dazu ein Array mit dem Namen der Widgetklasse als Schlüssel und ein Array mit Startwerten als Wert verwendet. Jedesmal wenn nun ein [CLinkPager] in einem View erstellt wird, werden die obigen Eigenschaftswerte zugewiesen. Der Code dafür reduziert sich somit auf: ~~~ [php] $this->widget('CLinkPager', array( 'pages'=>$pagination, )); ~~~ Die Eigenschaften können bei Bedarf immer noch überschrieben werden. Soll zum Beispiel in einem speziellen View `maxButtonCount` stattdessen auf 2 gesetzt werden, kann das wie folgt erreicht werden: ~~~ [php] $this->widget('CLinkPager', array( 'pages'=>$pagination, 'maxButtonCount'=>2, )); ~~~ Skin ---- Während man mit Themes das Aussehen von Views schnell verändern können, erlauben Skins (sinngem.: Haut, Verkleidung), das Aussehen von [Widgets](/doc/guide/basics.view#widget) systematisch anzupassen. Eine Skin ist ein Array von Name-Wert-Paaren, die zum Initalisieren der Eigenschaften eines Widgets verwendet werden können. Eine Skin gehört dabei zu einer Widgetklasse. Und eine Widgetklasse kann mehrere Skins haben, die über ihren Namen identifiziert werden können. So kann es zum Beispiel eine Skin für das [CLinkPager]-Widget namens `classic` geben. Um Skins verwenden zu können, richtet man in der Anwendungskonfiguration die Komponente [widgetFactory|CWebApplication::widgetFactory] (sinngem.: Widget-Fabrik) ein: ~~~ [php] return array( 'components'=>array( 'widgetFactory'=>array( 'enableSkin'=>true, ), ), ); ~~~ Bitte beachten Sie, dass man Skins für Widgets vor Version 1.1.3 so konfigurieren musste: ~~~ [php] return array( 'components'=>array( 'widgetFactory'=>array( 'class'=>'CWidgetFactory', ), ), ); ~~~ Danach müssen die benötigten Skins erstellt werden. Alle Skins, die zu einem bestimmten Widget gehören, werden gemeinsam in einem PHP-Script mit dem Namen der Widgetklasse gespeichert. Skindateien werden standardmäßig unter `protected/views/skins` abgelegt. Wenn Sie dieses Verzeichnis ändern möchten, können Sie die Eigenschaft `skinPath` der Komponente `widgetFactory` anpassen. Man kann in diesem Verzeichnis zum Beispiel die Datei `CLinkPager.php` mit folgendem Inhalt anlegen: ~~~ [php] array( 'nextPageLabel'=>'>>', 'prevPageLabel'=>'<<', ), 'classic'=>array( 'header'=>'', 'maxButtonCount'=>5, ), ); ~~~ Damit werden zwei Skins für das [CLinkPager]-Widget definiert: `default` und `classic`. Erstere wird für alle [CLinkPager]-Widgets verwendet, bei denen keine explizite `skin`-Eigenschaft gesetzt wurde. Die zweite wird für jene [CLinkPager] verwendet, bei denen `skin` auf `classic` gesetzt wurde. Der erste Pager im folgenden Beispiel verwendet also die `default`-Skin, der Zweite die Skin `classic`: ~~~ [php] widget('CLinkPager'); ?> widget('CLinkPager', array('skin'=>'classic')); ?> ~~~ Eigenschaften, die direkt beim Anzeigen eines Widgets übergeben werden haben Vorrang vor den in der Skin definierten Eigenschaften. Der folgende Viewcode erzeugt zum Beispiel einen Pager mit den Starteigenschaften `array('header'=>'', 'maxButtonCount'=>6, 'cssFile'=>false)`, also den überlagerten Eigenschaften aus dem View und der `classic`-Skin. ~~~ [php] widget('CLinkPager', array( 'skin'=>'classic', 'maxButtonCount'=>6, 'cssFile'=>false, )); ?> ~~~ Beachten Sie, dass der Einsatz von Skins keine Themes voraussetzt. Ist allerdings ein Theme aktiv, sucht Yii auch im Verzeichnis `skins` im View-Verzeichnis des Themes nach Skins (z.B. `WebVerzeichnis/themes/classic/views/skins`). Falls sowohl im Theme als auch im Hauptverzeichnis eine Skindatei mit dem gleichen Namen existiert, hat die Theme-Skin Vorrang. Falls ein Widget eine Skin verwendet, die es nicht gibt, erzeugt Yii das Widget wie gewohnt ohne Fehler. > Info|Info: Die Verwendung von Skins kann die Performance negativ beeinflussen, > da Yii beim ersten Einsatz eines Widgets nach Skindateien suchen muss. Skins ähneln dem Feature zur globalen Anpassung von Widgets. Die wesentlichen Unterschiede sind: - Eine Skin ist eher zur Anpassung der Darstellungseigenschaften gedacht - Ein Widget kan mehrere Skins haben - Eine Skin kann mit einem Theme versehen werden - Skins beeinflußen die Leistung mehr, als Widgets global anzupassen
$Id: topics.theming.txt 2890 2011-01-18 15:58:34Z qiang.xue $