themes.rst 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  1. Themes
  2. ######
  3. Customize the look and feel of Elgg.
  4. A theme is a type of :doc:`plugin </admin/plugins>` that overrides display aspects of Elgg.
  5. This guide assumes you are familiar with:
  6. * :doc:`/admin/plugins`
  7. * :doc:`views`
  8. .. contents:: Contents
  9. :local:
  10. :depth: 2
  11. Create your plugin
  12. ==================
  13. Create your plugin as described in the :doc:`developer guide </guides/index>`.
  14. - Create a new directory under mod/
  15. - Create a new start.php
  16. - Create a manifest.xml file describing your theme.
  17. Customize the CSS
  18. =================
  19. As of Elgg 1.8, the css is split into several files based on what
  20. aspects of the site you're theming. This allows you to tackle them one
  21. at a time, giving you a chance to make real progress without getting
  22. overwhelmed.
  23. Here is a list of the existing CSS views:
  24. * css/elements/buttons: Provides a way to style all the different kinds of buttons your site will use. There are 5 kinds of buttons that plugins will expect to be available: action, cancel, delete, submit, and special.
  25. * css/elements/chrome: This file has some miscellaneous look-and-feel classes.
  26. * css/elements/components: This file contains many “css objects” that are used all over the site: media block, list, gallery, table, owner block, system messages, river, tags, photo, and comments.
  27. * css/elements/forms: This file determines what your forms and input elements will look like.
  28. * css/elements/icons: Contains styles for the sprite icons and avatars used on your site.
  29. * css/elements/layout: Determines what your page layout will look like: sidebars, page wrapper, main body, header, footer, etc.
  30. * css/elements/modules: Lots of content in Elgg is displayed in boxes with a title and a content body. We called these modules. There are a few kinds: info, aside, featured, dropdown, popup, widget. Widget styles are included in this file too, since they are a subset of modules.
  31. * css/elements/navigation: This file determines what all your menus will look like.
  32. * css/elements/typography: This file determines what the content and headings of your site will look like.
  33. * css/rtl: Custom rules for users viewing your site in a right-to-left language.
  34. * css/admin: A completely separate theme for the admin area (usually not overridden).
  35. * css/elgg: Compiles all the core css/elements/\* files into one file (DO NOT OVERRIDE).
  36. * css/elements/core: Contains base styles for the more complicated “css objects”. If you find yourself wanting to override this, you probably need to report a bug to Elgg core instead (DO NOT OVERRIDE).
  37. * css/elements/reset: Contains a reset stylesheet that forces elements to have the same default
  38. View extension
  39. --------------
  40. There are two ways you can modify views:
  41. The first way is to add extra stuff to an existing view via the extend
  42. view function from within your start.php’s initialization function.
  43. For example, the following start.php will add mytheme/css to Elgg's core
  44. css file:
  45. .. code:: php
  46. <?php
  47. function mytheme_init() {
  48. elgg_extend_view('css/elgg', 'mytheme/css');
  49. }
  50. elgg_register_event_handler('init', 'system', 'mytheme_init');
  51. ?>
  52. View overloading
  53. ----------------
  54. Plugins can have a view hierarchy, any file that exists here will
  55. replace any files in the existing core view hierarchy... so for example,
  56. if my plugin has a file:
  57. ``/mod/myplugin/views/default/css/elements/typography.php``
  58. it will replace:
  59. ``/views/default/css/elements/typography.php``
  60. But only when the plugin is active.
  61. This gives you total control over the way Elgg looks and behaves. It
  62. gives you the option to either slightly modify or totally replace
  63. existing views.
  64. Tools
  65. =====
  66. Starting in Elgg 1.8, we've provided you with some development tools to help you
  67. with theming: Turn on the “Developers” plugin and go to the “Theme
  68. Preview” page to start tracking your theme's progress.
  69. Customizing the front page
  70. ==========================
  71. The main Elgg index page runs a plugin hook called 'index,system'. If this
  72. returns true, it assumes that another front page has been drawn and
  73. doesn't display the default page.
  74. Therefore, you can override it by registering a function to the
  75. 'index,system' plugin hook and then returning true from that function.
  76. Here's a quick overview:
  77. - Create your new plugin
  78. - In the start.php you will need something like the following:
  79. .. code:: php
  80. <?php
  81. function pluginname_init() {
  82. // Replace the default index page
  83. elgg_register_plugin_hook_handler('index', 'system', 'new_index');
  84. }
  85. function new_index() {
  86. if (!include_once(dirname(dirname(__FILE__)) . "/pluginname/pages/index.php"))
  87. return false;
  88. return true;
  89. }
  90. // register for the init, system event when our plugin start.php is loaded
  91. elgg_register_event_handler('init', 'system', 'pluginname_init');
  92. ?>
  93. - Then, create an index page (/pluginname/pages/index.php) and use that
  94. to put the content you would like on the front page of your Elgg
  95. site.