Guia per a la creació d'un tema visual de Dokuwiki (II)

Els fitxers cabdals d'un tema visual de Dokuwiki són style.ini i main.php. En aquesta pràctica trobareu informació de les seves característiques i funcionalitats per una millor comprensió per a la realització i personalització del tema visual.

style.ini

style.ini és un arxiu simple de configuració 1) que conté dos seccions relacionades amb els fulls d'estils del tema visual.

La primera secció determina quin seran els fulls d'estils actius del tema. Veieu la part de configuració:

; Define the stylesheets your template uses here. The second value
; defines for which output media the style should be loaded. Currently
; print, screen and rtl are supported. rtl styles are loaded additionally
; to screen styles if a right-to-left language is selected (eg. hebrew)
[stylesheets]
layout.css     = screen
design.css     = screen
style.css      = screen
 
media.css      = screen
 
rtl.css        = rtl
print.css      = print

Dins de la secció [stylesheets] queden determinats els fulls d'estils que s'enllaçaran al contingut i, associat a cada full d'estil, el valor de l'atribut media.

La segona secció de l'arxiu style.ini té un sentit semàntic i correspon a la declaració d'un conjunt de variables amb un valor de color. Aquestes variables les podeu utilitzar als fulls d'estils. Veieu primer un fragment d'aquesta secció de i, després, un selector del full d'estil que conté una de les variables declarades a l'arxiu style.ini.

Arxiu style.ini:

__text__           = "#000"
__background__     = "#fff"

Arxiu design.css:

body {
  font: 80% "Lucida Grande", Verdana, Lucida, Helvetica, Arial, sans-serif;
  background-color: __background__;
  color: __text__;
}

main.php

A banda de l'arxiu style.ini, l'altre component fonamental d'un tema visual de Dokuwiki és el fitxer main.php. Veieu a continuació quin són els elements necessaris perquè l'arxiu main.php sigui operatiu.

En primer lloc heu de declarar sempre la següent línia:

<?php if (!defined('DOKU_INC')) die(); ?>

Aquesta línia representa una condició: avalua si el fitxer es troba dins de l'infraestructura del Dokuwiki. En cas contrari, denegarà la lectura i execució de la resta de l'arxiu.

Seguidament declarareu la capçalera de l'estructura HTML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $conf['lang']?>"
 lang="<?php echo $conf['lang']?>">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title><?php tpl_pagetitle()?></title>
  <?php tpl_metaheaders()?>
  <link rel="shortcut icon" href="<?php echo DOKU_TPL?>images/favicon.ico" />
</head>

Segurament que heu diferenciat sense problemes algunes de les funcions pròpies de Dokuwiki que permeten la inclusió de contingut dinàmic dins de l'estructura HTML:

  • $conf['lang'] retorna el valor de l'idioma que heu configurat al panell d'administració de la wiki.
  • tpl_pagetitle() retorna el nom de la pàgina visible de la wiki.
  • tpl_metaheaders() Aquesta funció és imprescindible per a un funcionament correcte del tema visual: retornarà la llista -en llenguatge HTML- del fulls d'estils i codi javascript propi de Dokuwiki a més dels full d'estils declarats a l'arxiu style.ini.

Incorporeu seguidament l'estructura HTML que conté l'element body. A més d'aquest contingut, han d'estar present les següents funcions pròpies de Dokuwiki:

Contingut de la pàgina

La funció tpl_content() és la funció que presenta el contingut de la pàgina wiki. És evident, llavors, què és una funció necessària i que ha d'estar present sempre a l'arxiu main.php. Veieu a continuació el següent fragment on s'inclou la funció:

  <div class="contingut">
    <!-- inici del contingut de la wiki -->
    <?php tpl_content()?>
    <!-- final del contingut de la wiki -->
  </div>

Elements de navegació

Dokuwiki proporciona unes funcions específiques de la navegació interna de la wiki. Si bé no són imprescindibles, sí faciliten la interacció entre l'usuari/ària i la wiki. Les dues primeres funcions pertanyen al tipus de navegació molles de pa.

tpl_youarehere()

Aquesta funció mostra, de manera jeràrquica, el recorregut de l'índex de la wiki a la pàgina activa. Aquesta funció resulta necessària quan els nivells de directoris anidats és elevat. Veieu el següent exemple:

tpl_breadcrumbs()

Aquesta funció mostra el recorregut o camí de l'usuari/ària dins de la wiki:

Elements d'informació

Els següents elements proporcionen informació adicional de la wiki:

html_msgarea()

Aquesta funció té com a objectiu informar de qualsevol error a nivell d'administració de la wiki. Només és visible per a l'administrador/a. Es recomana que la funció sigui la primera en aparèixer dins del contingut de l'element body de l'HTML:

<body>
  <?php html_msgarea() ?>
  <!-- resta d'elements -->
 
</body>

tpl_pageinfo() i tpl_userinfo()

Aquestes dues funcions mostran quan es va realitzar l'última modificació i el nom de l'usuari/ària que la va realitzar.

Accions

Les accions a Dokuwiki vénen representades per butons i són elements clau, ja que permeten el mínim d'interacció entre l'usuari/ària i el contingut de les pàgines de la wiki. La funció que les gestiona és tpl_button i accepta com argument el tipus de butó/acció que realitzarà:

  • tpl_button('edit'): representa el butó de les diferents accions relaccionades amb el contingut de la pàgina wiki, és a dir, editar, crear, mostrar i esborrany. Aquesta acció és imprescindible per a un correcte funcionament de la wiki.
  • tpl_button('history'): Mostra les revisions antigues de la pàgina.
  • tpl_button('recent'): Mostra les modificacions recents de la pàgina.
  • tpl_searchform(): Mostra el formulari de cerca de la wiki.
  • tpl_button('subscription'): Mostra l'opció de suscripció als canvis de la pàgina.
  • tpl_button('admin'): Si l'usuari/ària és l'administrador/a de la wiki, mostrarà la pàgina del panel d'administració.
  • tpl_button('profile'): Mostra el perfil de l'usuari/ària.
  • tpl_button('login'): Acció d'autenticació de la wiki.
  • tpl_button('index'): Mostra l'índex jeràrquic de les pàgines de la wiki.
  • tpl_button('top'): Acció de tornar al principi de la pàgina (idònia quan el contingut de la pàgina és massa llarg).

Exemple de main.php

Finalment, aquí teniu un exemple mínim, però funcional, de l'arxiu main.php en base al que heu vist fins ara.

<?php
// must be run from within DokuWiki
if (!defined('DOKU_INC')) die();
 
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $conf['lang']?>"
 lang="<?php echo $conf['lang']?>">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title><?php tpl_pagetitle()?></title>
  <?php tpl_metaheaders()?>
  <link rel="shortcut icon" href="<?php echo DOKU_TPL?>images/favicon.ico" />
</head>
<body>
<div class="container">
<?php html_msgarea()?>
 
  <div id="capcalera">
 
  </div>
  <div id="central">
   <?php tpl_content()?>
  </div>
  <div id="lateral">
   <ul id="accions">
        <li><?php tpl_button('edit')?></li>
        <li><?php tpl_button('history')?></li>
        <li><?php tpl_button('subscribe')?></li>
        <li><?php tpl_button('subscribens')?></li>
   </ul>
  </div>
  <div id="peu">
 
  </div>
</div>