A Quick Sketch of the Ideal Drupal Site Planning

From 2011-01-16
With respect to: 
Here's a bunch of personal observations for a more effective team collaboration in working environments.

Block - based theming

  • Although .tpl files are slower, the coding flow should always go through .tpls.
  • Everything is a reusable block/partial.
  • CSS should be included from every reusable block - tpl. A custom include function for CSS should be added. It should check whether this CSS was already added to speed up the inclusion.
  • A CSS for an outer block should include the CSS of the inner block, so including from the PHP code will be written only once.
  • A MUST: Describe in some file what that specific CSS selector changes. For all pages, maintain page-xxx.css files. In any case, if the block is written well, it will look the same on each page. But since CSS inherits from [grand-x] parents, the description will provide enough info to understand to someone else how to deal with the bug. For example: everything floats left in block X on some page, but on other page it isn’t. The reason: the including div or one above on page X has float: left. The solution: adjust the block to look as previously. A possible practical solution: in .tpl file, add a wrapping div and give it a class with float:none/clear:both.
  • Document everything: functions, templates! Make charts for outer/inner blocks and everything else so anyone who develops could understand at once.
  • Maintain an active WIKI: Feature done files changed. So a quick search will provide all the necessary data where to intervene.
  • Use LESS CSS or similar CSS Framework.
  • Keep all CSS file either in modules, or in website’s main theme folder. Don’t mix!
  • Please ALWAYS validate HTML in the end of each related task.
  • Turn-off the cache. (A simple module should check this, and if cache is enabled, provide a huge link to turn it off!)
  • Panels / Context - check which one is appropriate.

Homely Modules Development

  • Intention is to simplify the modules / number of modules.
  • Don’t add to dependencies all modules to one site-wide module. Because it makes harder to maintain: disabling a module, requires commenting the entry in the .info file, and then enabling the site-wide module again.
  • Define a helper_functions module, which will have behaviour-categorized functions in separate include files. For example, all strings trimmings should go in string_operations.inc file, similarly node_operations.inc should contain node-logic etc.
  • The concept: Home-like environment. There is OUR, and THEIR. We always imply that we have enabled one of our modules, therefore we can call our function which is available.
  • In OUR way, choosing the Drupal-way instead of plain logic without defining clearly the Why’s, for example - coding with callbacks (hooks) unnecessarily extends other team member’s understanding and efficiency, finally making them pay by their extended hours. (Callbacks for example are needed, where it’s desired to encapsulate the Core code, and allowing other slave modules to extend or modify Core functionality)
  • On the other hand - if we’re planning to reuse some module such as Bank, we should clearly know that something like Bank type will be a reusable property (in case the hook returns anything) or method (in case where the hook modifies something, such as theming a table) in our future websites, therefore it should be declared in the interface (by a hook/callback).
  • In this sense, modules resemble classes in OOP, and hooking mechanism resembles polymorphism.
  • Plan the theming

Automated Testing

Tests are great when you have a clearly defined website specifications or plan or sketch or a skeleton. Whatever it's name, it provides the standards from the client, which shouldn't be changed. Therefore the standards, translated to the programming language are simply called automated tests. By defining these tests, which are by their nature can become a reusable code - we insure that the data presented to the user is always consistent with the spec. Of course it requires more work, but it pays off well when we start debugging by burning a significant amount of time after some minor change that we made.
Define 20+ presentable pages of the website. Write Selenium tests. For each commit, run tests to see if it fails and where. For example, header should be 800x50 pixels, so after changing a .js or a .css file, it should stay the same after page's loading.