Theme Component Library - Draft

component.php

<?php

/** Disclaimer: in-progress **/

/**
 * The component function. c().
 * Usage:
 * c($component_name, $data, [$attributes], [$options]);
 */

?>

<ol>
  <li>first</li>
  <li>second</li>
  <li>third</li>
</ol>

<?php

c('ol',
  array(
    'first',
    'second',
    'third',
  ),
);

?>

<!-- ====================================================================== -->
<!-- ====================================================================== -->
<!-- ====================================================================== -->

<ol id="id-x">
  <li id="id-first">first</li>
  <li>second</li>
  <li>third</li>
</ol>

<?php

c('ol',
  array(
    c('li', 'first', array('id' => 'id-first')),
    'second',
    'third',
  ),
  array('id' => 'x')
);

// Would be equivalent to the render array:

array(
  '#theme' => 'ol', // We will use ol.html.twig
  items => array(
    array(
      '#theme' => 'li', // Will use li.html.twig
      'text' => 'first',
      'attributes' => array('id' => 'id-first')
    ),
    'second',
    'third',
  ),
  'attributes' => array('id' => 'id-x')
);

// ...which would be equivalent to the render array:

array(
  '#theme' => 'ol', // We will use ol.html.twig
  items => array(
    array(
      '#theme' => 'li', // Will use li.html.twig
      'text' => 'first',
      'attributes' => array('id' => 'id-first')
    ),
    array(
      '#theme' => 'li', // Will use li.html.twig
      'text' => 'second',
      'attributes' => array()
    ),
    array(
      '#theme' => 'li', // Will use li.html.twig
      'text' => 'third',
      'attributes' => array()
    ),
  ),
  'attributes' => array('id' => 'id-x')
);

// ============================================
// Plumbing, everything below is outside of DX.
// ============================================

// Suppose we have defined ol.html.twig, but we have not defined li.html.twig
// and we are not invoking any preprocessors or alter hooks. We can just
// generate the markup directly for the list items. @see _html_tag()

render(array(
  '#theme' => 'ol', // We will use ol.html.twig
  items => array(
    array(
      '#markup' => _html_tag('li', 'first', array('id' => 'id-first')),
      'text' => 'first',
      'attributes' => array('id' => 'id-first')
    ),
    array(
      '#markup' => _html_tag('li', 'second'),
      'text' => 'second',
      'attributes' => array()
    ),
    array(
      '#markup' => _html_tag('li', 'third'),
      'text' => 'third',
      'attributes' => array()
    ),
  ),
  'attributes' => array('id' => 'id-x')
));


// Suppose neither ol.html.twig nor li.html.twig exist
// and we are not invoking any preprocessors or alter hooks.

render(array(
  '#markup' => _html_tag('ol', render(array(
    array(
      '#markup' => _html_tag('li', 'first', array('id' => 'id-first')),
      'text' => 'first',
      'attributes' => array('id' => 'id-first')
    ),
    array(
      '#markup' => _html_tag('li', 'second'),
      'text' => 'second',
      'attributes' => array()
    ),
    array(
      '#markup' => _html_tag('li', 'third'),
      'text' => 'third',
      'attributes' => array()
    ),
  )), array('id' => 'id-x'));
  items => array(
    array(
      '#markup' => _html_tag('li', 'first', array('id' => 'id-first')),
      'text' => 'first',
      'attributes' => array('id' => 'id-first')
    ),
    array(
      '#markup' => _html_tag('li', 'second'),
      'text' => 'second',
      'attributes' => array()
    ),
    array(
      '#markup' => _html_tag('li', 'third'),
      'text' => 'third',
      'attributes' => array()
    ),
  ),
  'attributes' => array('id' => 'id-x')
));


/**
 * Theme-less HTML tag builder helper. This isn't designed to be called directly.
 * @param $tag
 *   The name of the tag.
 * @param $value
 *   The inner value of the tag.
 * @param $attributes
 *   Array of HTML attributes to be built as Attribute object.
 * @param $cdata
 *   Whether to wrap the tag inner value with CDATA parameters.
 * @return Built HTML tag.
 */
function _html_tag($tag, $inner = NULL, $attributes = array(), $cdata = FALSE) {

  $attributes = !empty($attributes) ? new Attribute($attributes) : '';

  // Always use CDATA for script tags.
  if ($tag == 'script') {
    $cdata = TRUE;
  }

  if (isset($value)) {
    // Open tag.
    $output = '<' . $tag . $attributes . '>';
    // Consider CDATA.
    $output .= $cdata ? "\n<!--/*--><![CDATA[/*><!--*/\n" . $inner . "\n/*]]>*/-->\n" : $inner;
    // Close tag.
    $output .= '</' . $tag . ">\n";
    return $output;
  }
  else {
    // No inner value.
    return '<' . $tag . $attributes . " />\n";
  }
}

function render() {
  // TBD
}