wiki:WebTemplateProposal

Proposal for a new general website template

This proposal is rejected by BOINC for now. There is an alternative Twitter Bootstrap integration underway. Check with the boinc_dev mailinglist.

The current design of the BOINC web pages is a mixture of PHP with HTML that is grown over the years. The tight integration of PHP functions in HTML output makes it very difficult to maintain or change the layout of the individual project site. This proposal aims to separate PHP (application code) from HTML (presentation code) and provide an easy way (for a web designer) to give each project a unique look and feel. The tools described below are still under investigation if and how they could be implemented into BOINC source code.

Smarty template engine (LGPLv3)
To separate application from presentation code, has own simplified syntax to be used in templates (easy to use for webdesigners that don't know PHP), built in caching system, well maintained, good documentation.
Fluid 960 Grid System (GPLv3/MIT) with jQuery JavaScript library (GPLv2/MIT)
This can be used to create standard templates by providing CSS classes for cross-browser support and nice looking, userfriendly JavaScript effects.

All tools can be updated separately after implementing into BOINC source code.

Problems to avoid:

  • smarty has to know what language is currently used so files are compiled and cached for each language (using caching multiple caches feature)
  • allow project specific template enhancements or replacement without tampering the standard templates (is done by specifying two template directories)
  • HTML is used widely in .php and .inc files and is echo'ed by a lot of functions directly, this must be changed so that functions in /inc return a string to the calling script or function
  • As this is a lengthy task and development and bug fixing goes on with the normal source code it will get difficult to merge changes with already transformed code

What using Smarty means:

  • No HTML-Tags in any .php or .inc files needed (read: allowed)
  • Output of .php must be assigned to Smarty-variables that are then replaced in the template files
  • Output of lists must be assigned to arrays that can then be iterated by Smarty within the template (Sample follows)

DONE list:

  • write a tra block plugin to translate template text directly using the pre-compiled php files in /languages/compiled/ (no need to use native gettext as we do not use it anywhere else at the moment)
  • transform sample_index.php into a smarty_index.php and index.tpl (possibly also header.tpl and footer.tpl) as a proof-of-concept
  • create sample files (e.g.: project_description.php/.tpl) to store project specific content (e.g.: project description, text about the group behind the project)
  • enable usage of a MEMCACHE server via the custom cache implementation
  • extend the current script that creates the language.pot files to also check the template files

TODO list:

  • print date/time strings according to user defined language (default: MM/DD/YYYY, German: DD.MM.YYYY, ...) also try to use time zone settings (user defined)
  • document available Smarty functions/modifiers to be used in templates, best practice for using Smarty within PHP files
  • find a suitable way to transform all other files
  • transform ;)

Ideas to how the actual transformation can be done:

  • In general one should start with /user/index.php and transform all files that are directly linked from there and so on
  • create a separate directory structure (/smarty_inc, /smarty_project, /smarty_user) with same filenames as original but copy and change only those functions that are neccessary for current transformation state OR
  • work in same directory structure but rename files that contain already transformed functions (prepend a unique string that can be easily replaced after transformation is complete) OR
  • use some kind of hybrid method by changing filenames and function names by prepending a unique string
  • other suggestions?

Concept for integrating Smarty Template Engine into BOINC

Current directory structure of /html/ (installed project):

/inc/
contains .inc php files that are included by .php files in /ops and /user, normally it's outside of docroot but should be secured to prevent direct access via browser
/languages/
contains .po and .po.inc files to be used by php scipts in /inc and /user, normally it's outside of docroot but should be secured to prevent direct access via browser
/project/
contains .inc php files that are included by php scripts in /user and /ops,normally it's outside of docroot but should be secured to prevent direct access via browser
/ops/
contains .php files that are used for administrative operations (called via browser AND command-line), is available via http://PROJECTURL/PROJECT_SHORT_NAME_ops by default
/user/
contains .php files that are used to interact with the users via browser (http://PROJECTURL/PROJECT_SHORT_NAME by default)

directories that need to be added for Smarty:

/libs/
contains smarty library (file smarty.class.php needs to be required by each .php file), should be secured to prevent direct access
/cache/
contains smarty cache, should be secured to prevent direct access
/project/configs/
contains config files to alter smarty behaviour (should probably go into /project/project.inc if applicable)
/templates/
contains .tpl files that specify the look of the individual pages, should be secured to prevent direct access
/project/templates/
contains .tpl files that override the general templates, should be secured to prevent direct access
/templates_c/
contains cached files of templates, should be secured to prevent direct access

How the smarty system works:

  • .php files in /user gather all the data that should be shown to the user and assign this data to smarty-variables (using $smarty->assign()), at the end they call a template to be used to show this page ($smarty->display()). NO html code should be used here!
  • .tpl files specify what smarty-variables are shown where in HTML source code. NO php code should be used here. There are special modifiers and functions provided by smarty to automate lists, forms and other stuff.
  • to make text translateable in .tpl files the {tra} block can be used which is replaced by smarty compiler with the information from the language directory.
Last modified 4 years ago Last modified on 04/04/14 04:15:14