<p class="note">Note: This is a technical document. It discusses technical aspects of theme module and developing a custom theme which requires a good knowledge of advanced PHP, HTML, CSS and Javascript and is not meant for non-technical users. Know more about themes: [[Help:Themes|What are themes?]] | [[Help:Using Themes|Using Themes]] | [[Help :Templating Engines]].</p>

+

<p class="note">Note: This is a technical document. It discusses technical aspects of theme module and developing a custom theme which requires a good knowledge of advanced PHP, HTML, CSS and Javascript and is not meant for non-technical users. Know more about themes: [[Help:Themes|What are themes?]] | [[Help:Themes#How to change Themes|How to change Themes]].</p>

__TOC__

__TOC__

Line 7:

Line 7:

==Nature of themes==

==Nature of themes==

-

Themes are neither solid, liquid or gas. They are collection of PHP scripts, HTML/CSS files and images, living under themes folder at root with folder name same as theme name. For Example: Theme '''Demo''' will be at ROOT/themes/demo. Theme files are interlinked and hooked together to form the actual website.

+

Themes are collection of PHP scripts, HTML/CSS files and images, living under themes folder at root with folder name same as theme name. For Example: Theme '''Demo''' will be at ROOT/themes/demo. Theme files are interlinked and hooked together to form the actual website.

-

+

-

==Why develop themes?==

+

-

+

-

These are the reasons why should you learn theme development of Social Network Software.

+

+

==Why learn developing themes?==

*Complete control over layout, presentation and various design elements.

*Complete control over layout, presentation and various design elements.

-

*Tweaking already existing themes according to your and your community taste.

+

*Tweaking already existing themes according to you and your community taste.

*When your requirements are too unique and specific to be found in our theme gallery.

*When your requirements are too unique and specific to be found in our theme gallery.

*Migrating from a non-Social-Network-Software powered website to a Social-Network-Software powered one.

*Migrating from a non-Social-Network-Software powered website to a Social-Network-Software powered one.

Line 41:

Line 38:

It is actually done with the help of '''assign_vars''' method of '''$template''' object of Template class. For example to assign some HTML code to {PLACEHOLDER}, first generate HTML and store it in some variable or as a constant (say $placeholder_data) and then assign that value to {PLACEHOLDER} by

It is actually done with the help of '''assign_vars''' method of '''$template''' object of Template class. For example to assign some HTML code to {PLACEHOLDER}, first generate HTML and store it in some variable or as a constant (say $placeholder_data) and then assign that value to {PLACEHOLDER} by

$template->assign_vars(array(

$template->assign_vars(array(

-

'PLACEHOLDER'=> $placeholder_data

+

'PLACEHOLDER'=> $placeholder_html

));

));

[[Image:Theme-structure-main-home-php.gif|Placeholder Data is defined by main_home.php]]

[[Image:Theme-structure-main-home-php.gif|Placeholder Data is defined by main_home.php]]

-

<div class="note">Header and footer data can also be populated using this technique but it is not recommended.</div>

+

<div class="note">Header and footer data can also be populated using this technique but it is not recommended.

+

+

So following is a deprecated technique to replace {HEADER_HTML} and {FOOTER_HTML} inside text.htm:

+

+

$template->assign_vars(array(

+

'HEADER_HTML'=>$header_html,

+

'FOOTER_HTML'=>$footer_html

+

));

+

+

</div>

==Recommended theme files==

==Recommended theme files==

Line 66:

Line 72:

?>

?>

-

Above code shows that the task of rendering the common elements is done automatically, provided that they are defined at their respective places. So everything is reduced to taking care of four additional theme files as following:

+

Above code shows that the task of rendering the common elements is automatic, provided that these common elements are defined in their respective theme files. So we have to take care of four additional theme files.

+

*header.php

+

*footer.php

+

*left.php

+

*left_community.php

===header.php===

===header.php===

-

Header is a global element. Header covers banner and menu. Banner in turn includes site logo too and so requisite HTML must be taken care of.

+

Header is a global element. Header covers

+

*Everything till opening BODY html tag.

+

**includes the DOCTYPE declaration, opening HTML tag and HEAD section.

+

*HTML of banner.

+

**Banner in turn includes site logo too.

+

*HTML of menu bar.

Minimal header.php has data for {HEADER_HTML} defined.

Minimal header.php has data for {HEADER_HTML} defined.

+

<pre>

<?php

<?php

$header_html_data = '<html>

$header_html_data = '<html>

Line 86:

Line 102:

<ul id="menu">

<ul id="menu">

-

+

<li><!-- MENU ITEM 1 --></li>

-

<li><!-- MENU ITEMS --></li>

+

<li><!-- MENU ITEM 2 --></li>

-

+

<li><!-- MENU ITEM 3 --></li>

</ul>

</ul>

';

';

define('HEADER_HTML',$header_html_data);

define('HEADER_HTML',$header_html_data);

?>

?>

+

</pre>

===footer.php===

===footer.php===

-

Footer is also a global element which includes links to copyright, social media sharing, RSS feeds, Disclaimer, Privacy Policy and sometimes sitemap resides in footer.

Absence of any of these files do not lead to any problem and they provide additional features which do not alter theme functionality or theme development.

===index.php===

===index.php===

+

+

This file do not contribute to theme development but is a security feature. It contains a simple line:

+

<?php header('../'); ?>

+

It simply redirects anyone trying to reach the theme folder one directory back. e.g. user trying to go to folder of default theme i.e. {ROOT}/themes/defaulttheme will bounce back to {ROOT}/themes.

+

+

As {ROOT}/themes again have identical index.php redirection script, so user is redirected again one directory back to homepage i.e. at {ROOT}/index.php.

+

+

<div class="note">Though directory listing in Apache is prevented by setting directory permissions which shows an Apache's untidy access denied error, so this is just a nice and friendly way to tell user that he is not allowed to do so.</div>

===screenshot.gif===

===screenshot.gif===

+

+

This contains the screenshot of the theme's homepage which is shown as a thumbnail in admin panel theme choosing screen so that a particular theme can be visually recognized.

+

+

If absent, no thumbnail is shown.

===info.txt===

===info.txt===

+

+

This text contains information about theme which is displayed again in admin panel theme selection screen. Information contains, theme's name, description and version in following format.

+

+

Theme Name: Default theme

+

Description: This is default theme for social network software.

+

Version: 1.0

+

+

If absent, theme folder name is displayed as theme name and rest information is not displayed.

<div class="note">Only theme dependent images (e.g. bullets, backgrounds, buttons and icons etc.) must be stored inside images folder and images which are part of website instead (e.g. logo and products images) must be put at {ROOT}/images so that they can be shared among all themes.</div>

Latest revision as of 12:26, 28 July 2011

Theme Development

Note: This is a technical document. It discusses technical aspects of theme module and developing a custom theme which requires a good knowledge of advanced PHP, HTML, CSS and Javascript and is not meant for non-technical users. Know more about themes: What are themes? | How to change Themes.

Nature of themes

Themes are collection of PHP scripts, HTML/CSS files and images, living under themes folder at root with folder name same as theme name. For Example: Theme Demo will be at ROOT/themes/demo. Theme files are interlinked and hooked together to form the actual website.

Why learn developing themes?

Complete control over layout, presentation and various design elements.

Tweaking already existing themes according to you and your community taste.

When your requirements are too unique and specific to be found in our theme gallery.

Migrating from a non-Social-Network-Software powered website to a Social-Network-Software powered one.

You wish to frame out of box ideas inside Social Network Software.

Theme Structure

For a minimal theme you will require two files:

text.htm - Which is responsible for basic layout of the homepage. It determines where elements like banner, menu, footer and other elements of homepage will be placed and arranged which in turns makes clear structural layout of homepage.

main_home.php - This file paints what will reside inside other elements of homepage like login form, signup form, welcome text and featured content.

So the homepage is rendered at two levels.

text.htm

Controls homepage structure. It looks like an HTML file with placeholders enclosed in curly braces.

Our basic website structure is clear here.

main_home.php

It is actually done with the help of assign_vars method of $template object of Template class. For example to assign some HTML code to {PLACEHOLDER}, first generate HTML and store it in some variable or as a constant (say $placeholder_data) and then assign that value to {PLACEHOLDER} by

$template->assign_vars(array(
'PLACEHOLDER'=> $placeholder_html
));

Header and footer data can also be populated using this technique but it is not recommended.

So following is a deprecated technique to replace {HEADER_HTML} and {FOOTER_HTML} inside text.htm:

Recommended theme files

The above files are bare bones of a theme but for a full featured theme which is not just a static homepage we have to go beyond and create some more files for a robust and extensible theme structure.

Website has some elements which are global or are common to a large number of pages. eg. Banner is a global element as it is included in every webpage whereas user-page-navigation makes sense only when a user is logged in.

Such elements need to be included in every page. A file called body.php (which is not a part of theme files) is responsible for assigning values to these common template placeholders (just like main_home.php) and is included in every page automatically. A minimal code is shown below.

Above code shows that the task of rendering the common elements is automatic, provided that these common elements are defined in their respective theme files. So we have to take care of four additional theme files.

left_community.php

stylesheet.css

Miscellaneous theme files

Absence of any of these files do not lead to any problem and they provide additional features which do not alter theme functionality or theme development.

index.php

This file do not contribute to theme development but is a security feature. It contains a simple line:

<?php header('../'); ?>

It simply redirects anyone trying to reach the theme folder one directory back. e.g. user trying to go to folder of default theme i.e. {ROOT}/themes/defaulttheme will bounce back to {ROOT}/themes.

As {ROOT}/themes again have identical index.php redirection script, so user is redirected again one directory back to homepage i.e. at {ROOT}/index.php.

Though directory listing in Apache is prevented by setting directory permissions which shows an Apache's untidy access denied error, so this is just a nice and friendly way to tell user that he is not allowed to do so.

screenshot.gif

This contains the screenshot of the theme's homepage which is shown as a thumbnail in admin panel theme choosing screen so that a particular theme can be visually recognized.

If absent, no thumbnail is shown.

info.txt

This text contains information about theme which is displayed again in admin panel theme selection screen. Information contains, theme's name, description and version in following format.

theme specific images

Only theme dependent images (e.g. bullets, backgrounds, buttons and icons etc.) must be stored inside images folder and images which are part of website instead (e.g. logo and products images) must be put at {ROOT}/images so that they can be shared among all themes.