search

sammarks / ablecore

A library for Drupal developers.
MIT License
5 stars 4 forks source link

readme

Able Core

Able Core is a set of modifications for Drupal to enhance the development process. Able Core implements a "no-boilerplate" philosophy. That is, all the defaults are abstracted away and only modifications of the defaults are required to be represented in the code. Able Core provides several OO-based implementations of standard Drupal configuration arrays (for example, things like hook_menu and hook_theme) so that developers don't have to constantly refer to the Drupal API documentation when creating a website.

Able Core introduces syntactic sugar wherever it can and has the following ultimate goals:

Basically, you shouldn't have to write thousands of lines of code to get a decent site setup with Drupal.

Able Core is sponsored by Able Engine, a web services company located in Lexington, Kentucky.

Getting Started

To take advantage of all the benefits of Able Core, you'll have to declare your module as an Able Core module. To do this, simply add the following to your module's .module file:

// Declare this module as an Able Core module.
function MODULE_ablecore() { }

Simply having the hook present will help Able Core to determine which modules it should expose its advanced features to (like auto-inclusion of files inside helpers/ and hooks).

File Structure

Able Core employs specific naming conventions. Therefore, in order to use Able Core to its fullest, you'll probably want to follow these conventions:

All PHP logic goes in the module and all HTML, CSS and Javascript goes in the theme. The CSS, Javascript and HTML all live in their own parts of the theme.

Modules

module_name/
    preprocessors/
        theme-hook-name.php
        other-theme-hook.php
    callbacks/
        page-callback-a.php
        page-callback-b.php
    helpers/
        misc-file-1.inc
        misc-file-2.inc
    hooks/
        block.inc
        token.inc
    module_name.info
    module_name.module

Footnotes

Themes

While the standards set below are highly recommended, they are completely optional.

theme_name/
    themes/ (not templates)
        node/ (the module name)
            node.tpl.php
            node--type.tpl.php
            node--type--display.tpl.php (node--type--teaser.tpl.php)
        core/
            html.tpl.php
            page.tpl.php
        module_name/
            theme-name.tpl.php
            other-theme-name.tpl.php
    styles/
        default.[scss|less|sass]
        core/
            layout.[scss|less|sass] (layout under SMACSS)
            base.[scss|less|sass] (base under SMACSS)
        themes/ (modules under SMACSS)
            theme-name.[scss|less|sass]
            other-theme-name.[scss|less|sass]
            subfolder/ (... these can be organized into subfolders.)
        vendor/
            third-party.[scss|css|less|sass]
            other-third-party.[scss|css|less|sass]
    scripts/
        default.js
        themes/
            theme-name.js
            other-theme-name.js
        vendor/
            equalize.js
    theme_name.info

Footnotes

Usage in Modules

One of the major ideas introduced by Able Core is to create modules that drive the custom aspects of any Drupal site. This idea was initally discovered in the White House Petitions Repository.

Looking through the source code for the repositories, I noticed something really nasty about Drupal's configuration syntax for things like hook_menu and hook_theme. It consisted of nasty PHP arrays. The code was not readable (especially if many declarations were made in the same file), and the module file went on for miles.

Because of that, several helpers classes were introduced to collapse the basic configuration for these files into one-liners. Creating a custom menu entry for hook_menu is as simple as the following:

<?php

    function mymodule_menu()
    {
        return AbleCore\Modules\PathManager::init()
            ->define('this/is/a/custom/path', 'controllerFile@index', 'Page Title')
            ->fin();
    }

?>

That way, multiple configuration options can be passed into a single block of code. This idea is very similar to the way routing works in the top MVC frameworks (yes, Drupal is not an MVC). The same style of code is used for some of the other manager classes in Able Core.

Let's say you want the URL test/url to go to the action_test_url function in the callbacks/test_callback.php file. Here's what your code would look like:

<?php

    function mymodule_menu()
    {
        return AbleCore\Modules\PathManager::init()
            ->define('test/url', 'test_callback@test_url', 'Test URL Page')
            ->fin();
    }

?>

Here's the breakdown of arguments:

Using Arguments

Drupal's menu function allows for arguments. Drupal uses percent (%) signs to designate wildcards. Here are some examples of wildcarded paths:

Arguments are automatically stored in variables and passed as arguments to the callback function. For example, path/%/with/%/arguments will yield the following callback function:

<?php

    function action_page($argument_a, $argument_b)
    {
        // $argument_a is the first %
        // $argument_b is the second %
    }

?>

Therefore, going to path/1/with/2/arguments will call the callback like so:

<?php

    action_page(1, 2);

?>