Temas 2.0

Moodle 2.0

Bem vindo ao novo mundo de temas do moodle 2.0 !!

O Moodle Temas permite que você mude o visual do seu site moodle. Você pode usar temas já existentes ou criar seus próprios temas para compartilha com a comunidade moodle. Os temas podem também ser baseados em temas já existentes com algumas personalizações. Você pode fazer isso através do CSS, mudando a estrutura base e também adicionando javascript para adicionar recursos mais avaçados.

A maioria dos temas Moodle são desenvolvidos adicionando algumas mudanças em um tema que já existe. A arquitetura dos Temas do Moodle é desenvolvida de tal forma que a mesma funcione como base quando nada for definido no tema editado. Isso torna mais fácil para quem deseja criar novos temas apenas fazendo algumas mudanças em temas já existentes.

Essa documentação explica como trabalhar com no Moodle e pretende ajudar você a criar ou modificar a maioria do temas do Moodle 2.0.

O que há de novo na versão 2.0

O sistema de temas foi completamente redesenhado no Moodle 2.0. Problemas conhecidos foram endereçados e novas características foram adicionadas para atender solicitações da comunidade Moodle. Infelizmente não foi possível manter a compatibilidade com verões anteriores, então todos os temas de Moodle 1.x devem ser recriados para o Moodle 2.0.

Maiores mudanças incluem:

As classes CSS ficaram mais claras e consistentes, alem de IDs em todas paginas do Moodle
Introdução a arquivos de layout (templates), descrevendo o layout HTML para diferentes tipos de paginas do Moodle
Introdução de processadores, que produzem as pequenas “partes” de uma página HTML. Temas avançados podem ter eles ativados manualmente se for decido
Introdução a métodos padronizados para adição de Javascript aos templetes
Controle mais fácil dos ícones e imagens do Moodle
O antigo tema "standard" (padrão) foi dividio em dois temas:
- base - contem o layout absolutamente básico, e
- standard - que adiciona CSS no tema base para torna-lo parecido com antigo tema padrão
Ajuste de desempenho: Em condições normais de produção, os arquivos CSS são combinados em um único arquivo otimizado, e ambos, arquivo CSS e javaScript são minimizados para assegurar que não haja desperdício de conexão e trafico.

A estrutura de um tema

Algumas coisas importantes para quem deseja construir bons temas:

config.php - Esse arquivo é requisitado em muitos temas. Ele define as configurações e define requisitos para funcionar o tema Moodle. Isso inclui o tema, arquivo, região, região padrão e opções
Layouts e arquivo de layout - Em config.php existe uma definição para cada tipo de pagina (veja Appendix A: Theme layouts para ver uma lista de 12 tipos). Cada tipo de definição de página diz qual arquivo de layout será utilizado, qual regiões de bloco esse modelo de página deve exibir e assim por diante. O arquivo de layout contém o HTML e o PHP minimo exigido para exibir a estrutura básica das paginas. (Se você conhece Moodle 1.9, Isso seria uma combinação de header.html e footer.html)
O tema base - Não se destina a ser usado para produção de sites. Estabelece o esquema genérico mais simples possível e inclui apenas CSS essencial para o layout ou para o Moodle como um todo. É a base perfeita para se começar a desenha um tema, pois há poucas cores, bordas, margens e alinhamentos para substituir. Você pode simplesmente começar a adicionar o que você precisar.

Arquivos e Pastas

Os arquivos dos temas são localizados em uma pasta com caminho Moodle/Theme e possui subpastas. Cada tema é definido da seguinte forma:

Diretório	Arquivo	Descrição
	/config.php	Contém todas as configurações e definições para cada tema.
	/lib.php	Contém classes especificas e funções que são usadas pelos temas.
	/renderers.php	Contém qualquer processador personalizado para o tema.
	/settings.php	Contém configurações personalizadas do tema. Essas configurações locais são definidos pelo tema, permitindo que o usuário do tema possa modificá-lo facilmente. (por exemplo, uma cor de fundo ou uma imagem de cabeçalho)
/javascript/		Todos os arquivos JavaScript específicos para o tema devem ser localizados aqui.
/lang/		Quaisquer arquivos de linguagem especial que o tema exige devem ser localizados aqui.
/layout/		Contém os arquivos de layout do tema.
/pix/		Contém todas as imagens que o tema usa tanto do CSS quanto dos arquivo de layout.
/pix	/favicon.ico	O favicon para exibir o tema.
/pix	/screenshot.jpg	Um screenshot do tema pode ser visualizado na tela de seleção dos temas.
/style		Localização padrão para os arquivos CSS.
	/*.css	CSS arquivos que o tema precisa

Há também diversos lugares que folhas de estilo podem ser incluídas (veja o a seção CSS de como e porquê abaixo).

Opções de temas

Todas as opções de temas são definidos dentro do arquivo config.php. As configurações que são mais usadas são: parents,sheets, layouts e javascripts. Dê uma olhada em theme options table para completar essa lista de opções de temas que incluem algumas configurações menos usadas e mais avançadas.

Exemplo de uma configuração basica

Vamos dar uma olhada em um arquivo com configuração básica de tema e as diferentes partes que a estruturam: $THEME->name = 'newtheme';

$THEME->parents = array(

   'base'

);
$THEME->sheets = array(

   'admin',
   'blocks',
   'calendar',
   'course',
   'grade',
   'message',
   'question',
   'user'

);
$THEME->layouts = array(

   'base' => array(
       'theme' => 'newtheme',
       'file' => 'general.php',
       'regions' => array(),
   ),
   'standard' => array(
       'theme' => 'newtheme',
       'file' => 'general.php',
       'regions' => array('side-pre', 'side-post'),
       'defaultregion' => 'side-post',
   )
   //.......

);
$THEME->javascripts_footer = array(

   'navigation'

);

Expandindo as configurações de um exemplo básico

Primeiramente, antes de tudo, você vai notar que tudo é adicionado para $THEME. Esse é o objeto para configuração de tema. Ele é criado usando a configuração padrão do Moodle e em seguida atualizado para qualquer configuração que você adicionar.

$THEME->name: A primeira configuração, é o nome do tema. Ele deve ser simplesmente o nome do tema que você quiser nomear. O mais recomendado é que você use o mesmo nome do diretório do tema.

$THEME->parents: Esse define os temas que o tema estendera. Nesse caso, você esta apenas ampliando o tema base. Então seu tema será uma extensão de outro tema base.

$THEME->sheets: Um vetor contendo os nomes das folhas de estilo CSS para incluir em esse tema. Note que é apenas o nome da folha de estilo e não contém o caminho do diretório ou a extensão do arquivo. No moodle assume que as folhas de estilo do tema serão localizadas no diretório de estilos do tema e tem .css como extensão.

$THEME->layouts: Nesse exemplo, dois layouts foram definidos para substituir o layouts do tema base. Para mais informações você deve ver sessão abaixo layouts.

$THEME->javascripts_footer: A configuração final é incluir um arquivo JavaScript. Assim como as folhas de estilo, você só precisa fornecer o nome dos arquivos. Moodle assumirá que eles estarão no diretório JavaScript do seu tema e serão um arquivo .js .

Note: Quando você começar a escrever seus temas, Certifique-se de dar uma olhada nos arquivos de configuração de outros temas que já vem no Moodle. Você vai ter uma boa idéia de como tudo funciona e vai perceber o que esta acontecendo dentro do tema moodle, conhecendo o que é inclusão ou exclusão dentro do tema.

CSS

Localização dos arquivos CSS

Primeiramente vamos da uma olhada onde o CSS pode ser incluído dentro do Moodle:

\theme\themename\style\*.css: Essa é a localização padrão das folhas de estilo que são usadas por um tema e o local que deve ser usado para o desenvolvimento do seu tema.

Novos desenvolvedores de temas devem notar que a ordem em que os arquivos CSS são encontrados e incluídos cria uma hierarquia. Essa ordem assegura que as regras, dentro das folhas de estilo dos temas, tenham prioridade sobre regras idênticas em outros arquivos que podem ter sido introduzidas antes. Isso pode também se extender a outras definições de arquivo (veja vetor principal no arquivo de configuração) e também garante que as regras/definições do tema CSS tenha a última palavra.

Há outras localizações que podem ser usadas (embora muito raramente) para incluir CSS em uma página. Um desenvolvedor de um arquivo PHP pode especificar manualmente onde se encontra a folha de estilo no Moodle, como um banco de dados. Normalmente, se código esta fazendo isso, é porque existe uma configuração de um não tema ou de um plugin que precisa de uma informação especial de CSS. Como desenvolvedor de temas, você deve estar ciente da localização de arquivos CSS, mas não tem que se preocupar com isso. Aqui estão alguns exemplos:

{pluginpath}\styles.css e.g. \block\blockname\styles.css or \mod\modname\styles.css: Cada plugin pode ter seu próprio arquivo styles.css . Este arquivo deve conter apenas as normas CSS necessárias para o módulo e não deve acrescentar qualquer alteração para a aparência do plugin como cores, tamanho das fontes, ou margens. Nada além daqueles que são verdadeiramente requisitados.

Estilos de tema específicos para um plugin devem ser localizados dentro do diretório de estilo do tema.

{pluginpath}\styles_themename.css: Este só deve ser usado por desenvolvedores de plugins. Permite escrever CSS, que é projetado para um tema específico sem ter que fazer alterações a esse tema. Você irá notar que esse nunca é usado dentro do Moodle e é destinado para ser usado apenas como código de contribuição.

Organização do Núcleo CSS do Moodle

O próximo passo é olhar para a organização e regras do CSS dentro de um tema. Embora, como um desenvolvedor de temas, é responsabilidade sua criar e organizar seu CSS. Por favor, note que os temas padrões que já vem no Moodle tem uma organização muito clara do CSS.

Primeiro tem-se arquivo pagelayout.css. Ele contém o CSS necessário para criar o visual do seu layout. Ele não contém regras que afetam o conteúdo gerado pelo Moodle.

Próximo arquivo é o core.css. Se você abrir o núcleo vai notar que ele contém regras de uso geral (geralmente simples) que não se aplicam a uma seção especifica do Moodle e sim ao Moodle como um todo.

Também pode haver regras que se relacionam com seções específicas. No entanto, isso é feito apenas quando há apenas algumas regras para essa seção. Esses pequenos grupos de regras são agrupados e separados por comentários de identificação para cada seção.

Finalmente, existem todos os outros arquivos CSS, você vai notar que há um arquivo para cada seção do Moodle, que tem uma coleção significativa de regras.

Para aqueles que estão familiarizados com tema Moodle 1.9, esta organização terá uma grande mudança. Em 1.9, o CSS foi organizado pela sua natureza (por exemplo: cores, layout, outros.)

Como escrever regras do CSS eficazes dentro do Moodle

Em Moodle 2.0, escrever boas regras de CSS é muito importante.

Devido a requisitos de desempenho e limitações do navegador, todos os arquivos CSS são combinados em um único arquivo CSS que é incluído sempre. Isto significa que as regras precisam ser escritas de tal forma que minimize as chances de uma colisão, levando a aplicação de estilos indesejados. Por outro lado, escrever um bom CSS é algo que muitos desenvolvedores aspiram para que nós implementemos em diversas classes da estrutura e acaba estimulando desenvolvedores a usar o nome apropriado das classes.

<body> CSS id e classes

A partir do Moodle 2.0 a tag ID (etiqueta de identificação) que é aplicado à estrutura será sempre uma representação de seu endereço. Por exemplo, se você está olhando para uma mensagem do fórum e o endereço é "mod / forum / / view.php ', então a tag ID da estrutura será " # page-mod-forum-view ".

Como a identificação da estrutura atribuida ao URI também é explodida para formar diversar classes CSS que são adicionadas para a estrutura, então o exemplo '/mod/forum/view' deveria acabar com a seguinte classe adicionada para a estrutura '.path-mod', '.path-mod-forum'. Observe que '.path-mod-forum-view' não é adicionado como uma classe, sendo intencionalmente deixado de for a para evitar confusão e duplicação, visto que as regras podem ligar diretamente para a página usando o ID e não precisa da classe final.

O ID e as classes do corpo descrito acima irão forma o básico para muitas das regras CSS que você terá que escrever para o seu tema, no entanto, existe muitas outras classes muito úteis que podem ser adicionadas as tags do corpo. Algumas das classes mais interessantes estão listadas abaixo.

Se o JavaScript é habilitado, então 'jsenabled1' será adicionado como uma classe para a tag do corpo, permitindo-lhe estilo baseado em JavaScript ser ativado ou não
Ou 'dir-rtl "ou" dir-ltr' será adicionado ao corpo como uma classe, dependendo da direção do pacote de idioma: rtl = direita para a esquerda, ltr = esquerda para a direita. Isto permite determinar o seu alinhamento de texto com base na língua, se necessário.
A classe será adicionada para representar o pacote de idioma em uso atualmente, por padrão en_utf8 é usada pelo Moodle e resultará na adição da na classe 'lang-en_utf8 " à tag do corpo
O wwwroot para Moodle também será convertido em uma classe e adicionado à tag do corpo, o que lhe permite criar um estilo para seu tema baseado na URL através do qual ele foi atingido. Por exemplo,http://sam.moodle.local/moodle/ se tornará ". sam-moodle-local-moodle '
Se o usuario corrente não esta logado então '.notloggedin' 'será adicionado à tag do corpo.

O que tudo isso parece na prática? Bem, usando o exemplo acima / mod / forum / view.php, você teria pelo menos a seguinte etiqueta de corpo: <body id=”page-mod-forum-view” class=”path-mod path-mod-forum” />

Escrevendo suas regras

Seguindo as melhores praticas de CSS e compreendendo a ordem em cascata de CSS , o desenvolvedor do tema poderá reduzir colisões e linhas do CSS que é escrito. Classes CSS foram colocadas em locais onde se acredita que qualquer um possa querer aplicar seus próprios estilos CSS.

Ao começar a escrever regras certifique-se que você tem um bom entendimento de onde você quer que essas regras sejam aplicadas, é uma boa idéia para tirar o máximo partido das classes do body acima mencionadas. Se você quiser escrever uma regra para uma página específica deve-se usar o ID para a tag do corpo:

#page-mod-forum-view .forumpost {border:1px solid orange;)

Se você quiser escrever uma regra que seja aplicada para todo o forum:

.path-mod-forum .forumpost {border:1px solid orange;}

Outra coisa muito importante para levar em consideração é a estrutura que antecederam a tag que você quer editar. O navegador adota entre os estilos conflitantes aquele que possui seletores mais específicos. Pode ser muito benéfico manter isso em mente e escrever seletores completos que dependem da estrutura das etiquetas direcionando para o caminho que você espera alterar.

Ao fazer o uso de classes, identificação de etiquetas e escrevendo seletores para funcionar na estrutura principal se consegue minimizar as chances de uma colisão do Moodle agora e no futuro.

Layouts

Layouts são definidos em config.php.

Todos os temas são requeridos para definir os layouts que eles querem se responsabilizar ou criar; contudo, muitos arquivos de layout são requeridos por aqueles layouts. Se um tema está substituindo outro tema, então este é um caso de decidir qual dos layouts, o mais novo será substituído. Se o tema é completamente novo, então você precisará definir um layout para casa uma das diferentes possibilidades.

É também importante notar que um novo tema que se baseará em se mesmo em outro tema (substituindo ele) não precisa definir qualquer layout ou usar qualquer arquivo de layout se não há mudanças que se quer fazer no layout do tema existente. O tema padrão no Moodle é um bom exemplo disso, pois ele estende o tema base adicionando CSS para conseguir o visual.

Então layouts... como mencionado antes, são definidos em config.php em $THEME->layouts. O seguinte é um exemplo de tal definição: $THEME->layouts = array(

   // Standard layout with blocks, this is recommended for most pages with general information
   'standard' => array(
       'theme' => 'base',
       'file' => 'general.php',
       'regions' => array('side-pre', 'side-post'),
       'defaultregion' => 'side-post'
   )

) A primeira coisa que o Moodle olha é o nome do layout, neste caso é o ‘padrão’ (o vetor chave em PHP), depois procura pelas configurações de layout, que é o tema, arquivo, regiões, e região padrão. Há também algumas outras opções que podem ser configuradas por um layout.

Tema - theme: é o tema em que o arquivo de layout existe. Isso mesmo, você pode fazer uso dos layouts a partir de outros temas instalados. Opcional
Arquivo - file: é o nome do arquivo do layout que o layout quer usar. Requerido
Regiões - regions: são os diferentes bloco de regiões (lugares onde você pode colocar blocos) no tema. Requerido
Regiõespadrões – defaultregion: é a localização padrão quando adicionados novos blocos. Requerido se região não é vazia, se não, opcional
Opções – options: um vetor das opções específicas do layout mencionado em detalhes abaixo. Opcional

O tema é opcional. Normalmente o arquivo de layout é preso ao tema atual, ou, se não está lá, no tema principal. Contudo, você pode usar um arquivo de layout de qualquer outro tema adicionando o nome.

Você pode definir quais regiões você prefere. Você só precisa escolher o nome de cada qual. A maioria dos temas só usam um ou ambos de side_pre e side_post, que seria como ‘lado esquerdo’ e ‘lado direito’, exceto na linguagem direita para esquerda, quando são trocados. Se você disser em config.php que seus layouts regiões chamadas ‘fred’ e ‘barney’, então você deve chamar $OUTPUT->blocks_for_region('fred') and $OUTPUT->blocks_for_region('barney') em algum lugar no arquivo de layout.

A configuração final de opções é um caso especial que só precisa ser ligada se você quiser usar disto. Essas configurações permitem que o desenvolvedor do tema especifique opções especiais que eles gostaria de criar e podem ser acessadas dentro do arquivo do layout. Isso permite que o tema tome decisões de design durante a definição e seja capaz de reagir de acordo com essas decisões em qualquer arquivo de layout que esteja sendo usado.

Um desses lugares que isso vem sido usado é no tema base. Se você observar em theme/base/config.php, perceberá que há diversas opções específicas nonavbar e nofooter que podem ambas ser marcadas como verdadeiro ou falso. Então se você olhar em theme/base/layout/general.php você identificará linhas como as seguintes: <?php $hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()); $hasfooter = (empty($PAGE->layout_options['nofooter'])); ?> ............ <?php if ($hasnavbar) { ?>


<?php echo $OUTPUT->navbar(); ?>
 <?php echo $PAGE->button; ?>

<?php } ?> O que você está vendo aqui é o uso de algumas dessas configurações do layout existentes dentro do arquivo de layout. Neste caso, está sendo usado para barra de rolagem e rodapé da página.

Arquivo Layout

O arquivo layout é o arquivo que contem a estrutura do codigo HTML para o layout incluindo o header , conteúdo e regiões de bloco. Para aqueles de vocês que estão familiarizados com os temas em Moodle 1.9 isto é simplesmente a combinação dos arquivos header.html e footer.html. Claro que não é tudo HTML, há pedaços de codigo e conteúdos que o Moodle precisa colocar na paginas, dentro de cada arquivo de layout isso sera feito por uma simples chamada PHP para obter pedaços e incluir conteúdo.

Antes de aprender mais, é bom conhecer os dois objetos primários que serão usados em seus arquivos de layout: $OUTPUT e $PAGE.

$OUTPUT é uma instância da classe core_renderer que é definido em lib / outputrenderers.php. Cada método é claramente documentados lá, junto com o que é apropriado para uso dentro dos arquivos de layout.

$PAGE é uma instância da classe moodle_page definido no lib / pagelib.php. A maioria das coisas que você vai querer usar são as propriedades que estão documentadas no topo do arquivo. Se você não estiver familiarizado com propriedades do PHP, você deve acessá-los como $ PAGE-> activityname, assim como campos de um objeto PHP comum. (No entanto, em segundo plano, o valor que você recebe é produzido pela chamada de uma função. Além disso, você não pode alterar esses valores, eles são somente de leitura. No entanto, você não precisa entender tudo isso se você está apenas usando essas propriedades no seu tema).

O seguinte arquivo de layout é uma simples ilustração dos pedaços que o compõem: <?php echo $OUTPUT->doctype() ?> <html <?php echo $OUTPUT->htmlattributes() ?>> <head>

   <title><?php echo $PAGE->title ?></title>
   <?php echo $OUTPUT->standard_head_html() ?>

</head>
<body id="<?php p($PAGE->bodyid) ?>" class="<?php p($PAGE->bodyclasses) ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>




<?php echo $PAGE->heading ?>
<?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?>




           <?php echo $OUTPUT->blocks_for_region('side-pre') ?>



           <?php echo core_renderer::MAIN_CONTENT_TOKEN ?>



           <?php echo $OUTPUT->blocks_for_region('side-post') ?>





<?php echo page_doc_link(get_string('moodledocslink')) ?>
           <?php
           echo $OUTPUT->login_info();
           echo $OUTPUT->home_link();
           echo $OUTPUT->standard_footer_html();
           ?>

<?php echo $OUTPUT->standard_end_of_body_html() ?> </body> </html>

Nós assumimos que você sabe o suficiente de HTML para compreender a estrutura básica acima, mas vamos explicar o código PHP uma vez que é menos óbvio.

<?php echo $OUTPUT->doctype() ?> This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<html <?php echo $OUTPUT->htmlattributes() ?>> Aqui nós começamos a escrever a tag de abertura html e pedimos ao Moodle para nos dar os atributos HTML que deve ser aplicada a ele. Isso novamente é determinada por várias configurações dentro do HTML gerado da instalação do Moodle.

<?php echo $PAGE->title ?> Isso dá o titulo para a pagina.

<?php echo $OUTPUT->standard_head_html() ?> Essa chamada é muito importante pois nos leva ao cabeçalho html padrão que precisamos para esta dentro da tag HEAD da pagina. É onde o CSS e o JavaScript são requisitados no topo do arquivo, bem como qualquer script especial ou tags de estilo.

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>"> Muito parecido com o tag html acima nós começamos a escrever a tag body and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<?php echo $PAGE->heading; ?><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?>

Aqui estamos criando o cabeçalho da página,Neste caso, queremos o título da página, queremos mostrar as informações de login, que será o nome de usuário username corrente ou um link para efetuar login, se não estiver logado, e queremos o título do menu se existir um.

<?php echo $OUTPUT->blocks_for_region('side-pre') ?> Aqui temos o HTML para mostrar os blocos que foram adicionados à página. Neste caso, pedimos para todos os blocos que foram adicionados à área denominada side-pre.

<?php echo core_renderer::MAIN_CONTENT_TOKEN ?> Esse é um dos mais importantes chamadas dentro do arquivo, ele determina onde o conteúdo real da pagina sera inserido.

<?php echo $OUTPUT->blocks_for_region('side-post') ?> Aqui temos o HTML para mostrar os blocos que foram adicionados à página. Neste caso, pedimos para todos os blocos que foram adicionados à área denominada side-post.

<?php echo $OUTPUT->login_info(); echo $OUTPUT->home_link(); echo $OUTPUT->standard_footer_html(); ?> Esse pedaço final de codigo obtém o conteúdo para o rodapé da página. This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

Note: Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

When writing layout files think about the different layouts and how the HTML that each makes use of will differ. You will most likely find you do not need a different layout file for each layout, most likely you will be able to reuse the layout files you create across several layouts. You can of course make use of layout options as well to further reduce the number of layout files you need to produce.

Of course as mentioned above if you are customising an existing theme then you may not need to create any layouts or layout files at all.

Language File

You need to create a language file for your theme with a few standard strings in it. At a minimum create a file called lang/en.theme_themename.php in your theme folder. For example, the 'standard' theme has a language file called lang/en/theme_standard.php.

You must define the following lines in your file (example is from standard theme, adapt as required):

$string['pluginname'] = 'Standard'; $string['region-side-post'] = 'Right'; $string['region-side-pre'] = 'Left'; $string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of

CSS added to the base theme to make it actually usable.';

Without the above you will get notices for the missing strings.

Making use of images

Right at the start when listing the features of the new themes system one of the features mentioned was the ability to override any of the standard images within Moodle from within your theme. At this point we will look at both how to make use of your own images within your theme, and secondly how to override the images being used by Moodle. So first up a bit about images within Moodle,

Images you want to use within your theme need to be located within your theme's pix directory.
You can use sub directories within the pix directory of your theme.
Images used by Moodle's core are located within the pix directory of Moodle.
Modules, blocks and other plugins should also store there images within a pix directory.

So making use of your own images first up. Lets assume you have added two image files to the pix directory of your theme.

/theme/yourthemename/pix/imageone.jpg
/theme/yourthemename/pix/subdir/imagetwo.png

Notice that one image is a JPEG image, and the second is a PNG. Also the second image is in a subdirectory.

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file. <img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" /> <img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />

DO NOT include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images. .divone {background-image:url(imageone);} .divtwo {background-image:url(subdir/imagetwo);} If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all something tags and replaces them with what is required.

The final thing to notice with both of the cases above is that at no point do we include the images file extension. The reason for this leads us into the next topic, how to override images.

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle. So for instance we wanted to override the following two images:

/pix/moodlelogo.gif
/pix/i/user.gif

We would simply need to add our replacement images to the theme in the following locations

/theme/themename/pix_core/moodlelogo.gif
/theme/themename/pix_core/i/user.gif

Note that we have created a pix_core directory in our theme. For module images we need a pix_mod directory. See using images within your theme for the full story.

Now the other very cool thing to mention is that Moodle looks for not just replacements of the same image type (jpg, gif, etc...) but also replacements in any image format. This is why above when working with our images we never specified the images file extension. This means that the following would also work:

/theme/themename/pix_core/moodlelogo.png
/theme/themename/pix_core/i/user.bmp

For a more detailed description of how this all works see the page on using images within your theme

Unobvious Things

Getting Your Theme to Appear Correctly in Theme Selector

If you follow the examples on this page to the letter, when you go to the Theme Selector page you may be discouraged to find that your theme does not appear like the other themes do. In fact, instead of your theme's name, you will see something along the lines of [[pluginname]].

To correct this, you must add the /lang/en/theme_THEMENAME.php file, where THEMENAME is the name of the theme folder. Inside that file, add the string "$string['pluginname'] = 'THEMENAME'; ". Make THEMENAME the name of your theme, however you want it displayed in the Theme selector.

The screenshot for the theme should be about 500x400 px.

Required theme divs

Some parts of Moodle may rely on particular divs, for example the div with id 'page-header'.

Consequently all themes must include at least the divs (with the same ids) that are present in the 'base' theme.

Missing out these elements may result in unexpected behaviour within specific modules or other plugins.

Appendix A

Theme options as of April 28th, 2010

Setting	Effect
$THEME->csspostprocess	Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
$THEME->editor_sheets	An array of stylesheets to include within the body of the editor.
$THEME->enable_dock	If set to true the side dock is enabled for blocks
$THEME->hidefromselector	Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
$THEME->filter_mediaplugin_colors	Used to control the colours used in the small media player for the filters
$THEME->javascripts	An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
$THEME->javascripts_footer	As above but will be included in the page footer.
$THEME->larrow	Overrides the left arrow image used throughout Moodle
$THEME->layouts	An array setting the layouts for the theme
$THEME->name	Name of the theme. Most likely the name of the directory in which this file resides.
$THEME->parents	An array of themes to inherit from
$THEME->parents_exclude_javascripts	An array of JavaScript files NOT to inherit from the themes parents
$THEME->parents_exclude_sheets	An array of stylesheets not to inherit from the themes parents
$THEME->plugins_exclude_sheets	An array of plugin sheets to ignore and not include.
$THEME->rarrow	Overrides the right arrow image used throughout Moodle
$THEME->renderfactory	Sets a custom render factory to use with the theme, used when working with custom renderers.
$THEME->resource_mp3player_colors	Controls the colours for the MP3 player
$THEME->sheets	An array of stylesheets to include for this theme. Should be located in the theme's style directory.

The different layouts as of August 17th, 2010

Layout	Purpose
base	Most backwards compatible layout without the blocks - this is the layout used by default.
standard	Standard layout with blocks, this is recommended for most pages with general information.
course	Main course page.
coursecategory	Use for browsing through course categories.
incourse	Default layout while browsing a course, typical for modules.
frontpage	The site home page.
admin	Administration pages and scripts.
mydashboard	My dashboard page.
mypublic	My public page.
login	The login page.
popup	Pages that appear in pop-up windows - no navigation, no blocks, no header.
frametop	Used for legacy frame layouts only. No blocks and minimal footer.
embedded	Embeded pages, like iframe/object embedded in moodleform - it needs as much space as possible
maintenance	Used during upgrade and install. This must not have any blocks, and it is good idea if it does not have links to other places - for example there should not be a home link in the footer.
print	Used when the page is being displayed specifically for printing.

Documentation