diff --git a/theming_example/README.txt b/theming_example/README.txt
new file mode 100644
index 0000000..47c1b98
--- /dev/null
+++ b/theming_example/README.txt
@@ -0,0 +1,47 @@
+The theming_example module attempts to show how module developers can add
+theming functions to their projects so that themers can modify output to
+match the theme they are using.
+
+To this end module developers should to strive to avoid hardwiring any html
+into the output of their code, this should all be done in theme functions.
+
+Starting with the first example, function 'theming_example_page()':
+the output is put into an array $content which is then fed to a theming
+function 'theme_theming_example_page()' which loops over the content,
+wrapping it in html in the process.
+
+In order to get function 'theme_theming_example_page()' recognised it needs
+to be registered with the module theme register function of the
+type 'hook_theme'.
+
+function 'theming_example_theme()' does this for this module.
+for details of what can be done in this hook see the link to api.drupal.org
+
+The functions 'theming_example_list_page()' and theming_example_order_form()
+work in the same way.
+
+In 'theme_theming_example_list_page()' the content is themed as an
+ordered list and given a class attribute 'theming_example_mylist' which
+is defined in theming_example.css
+
+In function 'theme_theming_example_order_form()' the title is loaded into a
+temporary variable '$title', deleted from the $form array and output
+wrapped in html. The rest of the form is wrapped in a div using '#prefix'
+and '#suffix'
+
+The theming functions can be copied to a theme's template.php, renaming
+appropriately, so if you theme is called 'mytheme' you would copy
+function 'theme_theming_example_page()'
+to
+function 'mytheme_theming_example_page()' in template.php and it will be
+used instead of the original.
+
+The fourth example shows the use of a template file
+'theming_example_text_form.tpl.php'
+This file can be copied to a theme's folder and it will be used instead.
+
+This example also shows what can be done using Drupal's
+template_preprocess_HOOK method. In this case it modifies the output so
+that a themer can output the whole form or gain control over some of its
+parts in the template file.
+
diff --git a/theming_example/theming_example.css b/theming_example/theming_example.css
new file mode 100644
index 0000000..b503418
--- /dev/null
+++ b/theming_example/theming_example.css
@@ -0,0 +1,11 @@
+/*
+ * style the list
+ * for OL you can have
+ * decimal | lower-roman | upper-roman | lower-alpha | upper-alpha
+ * for UL you can have
+ * disc | circle | square or an image eg url(x.png)
+ * you can also have 'none'
+ */
+ol.theming_example_mylist {
+  list-style-type: upper-alpha;
+}
diff --git a/theming_example/theming_example.info b/theming_example/theming_example.info
new file mode 100644
index 0000000..73bec9c
--- /dev/null
+++ b/theming_example/theming_example.info
@@ -0,0 +1,5 @@
+name = Theming example
+description = An example module showing how to use theming.
+package = Example modules
+core = 7.x
+;files[] = theming_example.test
diff --git a/theming_example/theming_example.module b/theming_example/theming_example.module
new file mode 100644
index 0000000..f2680f6
--- /dev/null
+++ b/theming_example/theming_example.module
@@ -0,0 +1,254 @@
+<?php
+
+/**
+ * @file
+ * This is an example outlining how a module can use theming
+ * to expose module output so that others can alter things to
+ * suit their needs before rendering to html.
+ */
+
+/** TODO
+ * hook_theme()
+ * theme functions
+ * theme templates
+ * hook_preprocess(),
+ * Keeping content as renderable as long as possible
+ * Theming forms
+ */
+
+/**
+ * Implements hook_menu().
+ *
+ * The @link menu_example.module Menu Example @endlink provides extensive
+ * examples for hook_menu().
+ */
+function theming_example_menu() {
+  $items['examples/theming_example'] = array(
+    'title' => 'Theming Examples',
+    'description' => 'Some theming examples.',
+    'page callback' => 'theming_example_page',
+    'access callback' => TRUE,
+    'access arguments' => array('access content'),
+  );
+  $items['examples/theming_example/theming_example_list_page'] = array(
+    'title' => 'Theming a list Example',
+    'page callback' => 'theming_example_list_page',
+    'access arguments' => array('access content'),
+    'weight' => 1,
+  );
+  $items['examples/theming_example/theming_example_order_form'] = array(
+    'title' => 'Theming a form Example 1',
+    'page callback'    => 'drupal_get_form',
+    'page arguments'   => array('theming_example_order_form'),
+    'access arguments' => array('access content'),
+    'weight' => 2,
+  );
+  $items['examples/theming_example/theming_example_text_form'] = array(
+    'title' => 'Theming a form Example 2',
+    'page callback'    => 'drupal_get_form',
+    'page arguments'   => array('theming_example_text_form'),
+    'access arguments' => array('access content'),
+    'weight' => 3,
+  );
+
+  return $items;
+
+}
+
+/**
+ * Initial landing page
+ *
+ *
+ */
+function theming_example_page() {
+  $content[] = t('Some examples of pages and forms that are run through a theming function.');
+  $content[] = l(t('Simple page with a list'), 'examples/theming_example/theming_example_list_page');
+  $content[] = l(t('Simple form 1'), 'examples/theming_example/theming_example_order_form');
+  $content[] = l(t('Simple form 2'), 'examples/theming_example/theming_example_text_form');
+  return theme('theming_example_page', array('content' => $content));
+}
+
+/**
+ * An example page where the output is supplied as an array which
+ * is themed into a list and styled with css
+ *
+ */
+function theming_example_list_page() {
+  drupal_add_css(drupal_get_path('module', 'theming_example') . '/theming_example.css');
+  $title = t('My list');
+  $list = array(t('Eeny'), t('Meeny'), t('Miny'), t('Mo'));
+  return theme('theming_example_list_page', array('title' => $title, 'content' => $list));
+}
+
+
+/**
+ * A simple form that displays a select box and submit button
+ *
+ *
+ */
+function theming_example_order_form($form, &$form_state) {
+    $orderlist = array(
+    1 => t('Newest first'),
+    2 => t('Newest last'),
+    3 => t('Edited first'),
+    4 => t('Edited last'),
+    5 => t('By name'),
+  );
+  $form['theming_example_order'] = array(
+    '#type' => 'select',
+    '#options' => $orderlist,
+    '#title' => t('Order'),
+  );
+  $form['submit'] = array(
+    '#type' => 'submit',
+    '#value' => t('Go'),
+  );
+  return $form;
+}
+
+/**
+ * A simple form that displays a textfield and submit button
+ *
+ *
+ */
+function theming_example_text_form($form, &$form_state) {
+  $form['theming_example_text'] = array(
+    '#type' => 'textfield',
+    '#title' => t('Some input'),
+    '#required' => TRUE,
+  );
+  $form['text_form_submit'] = array(
+    '#type' => 'submit',
+    '#value' => t('Go'),
+  );
+  return $form;
+
+}
+
+/**
+ * Implements hook_theme().
+ *
+ * see http://api.drupal.org/api/drupal/modules--system--system.api.php/function/hook_theme/7
+ */
+function theming_example_theme() {
+  return array(
+    'theming_example_page' => array(
+      'variables' => array(
+        'content' => NULL,
+      ),
+    ),
+    'theming_example_list_page' => array(
+      'variables' => array(
+        'title' => NULL,
+        'content' => NULL,
+      ),
+    ),
+    'theming_example_order_form'  => array(
+      'render element' => 'form',
+    ),
+    'theming_example_text_form'  => array(
+      'render element' => 'form',
+      'template' => 'theming_example_text_form',
+    ),
+  );
+}
+
+/**
+ * Theming the initial landing page.
+ *
+ *
+ *
+ */
+function theme_theming_example_page($variables) {
+
+  $content = $variables['content'];
+  $output = '';
+  foreach ($content AS $count => $para) {
+    if (! $count) {
+      // first one
+      $output .= '<p><b>' . $para . '</b></p>';
+    }
+    else {
+      $output .= '<p>' . $para . '</p>';
+    }
+  }
+
+  return $output;
+}
+
+/**
+ * Theming the simple list page
+ *
+ *
+ */
+function theme_theming_example_list_page($variables) {
+
+  $title = $variables['title'];
+  $content = $variables['content'];
+
+  /*
+  // simple list, title separate
+  $output = '<h2>' . $title . '</h2>';
+  $output .= theme('item_list',
+    array(
+      'items' => $content,
+    )
+  );
+  */
+
+  // add the title to the list theme and
+  // state the list type. This defaults to 'ul'.
+  // add a css class so that you can modify the list styling
+  $output = theme('item_list',
+    array(
+      'items' => $content,
+      'title' => $title,
+      'type' => 'ol',
+      'attributes' => array('class' => 'theming_example_mylist'),
+    )
+  );
+
+  return $output;
+}
+
+/**
+ * Theming a simple form 1
+ * in this example we collect the title, theme it manually and
+ * empty the form title. We also wrap the form in a div
+ */
+function theme_theming_example_order_form($variables) {
+  $form = $variables['form'];
+  $title = $form['theming_example_order']['#title'];
+  $form['theming_example_order']['#title'] = '';
+  $output = '<b>' . $title . '</b>';
+  $form['theming_example_order']['#prefix'] = '<div class="container-inline">';
+  $form['submit']['#suffix'] = '</div>';
+  $output .= drupal_render_children($form);
+  return $output;
+}
+
+
+/**
+ * Theming a simple form 2
+ * in this example the form is preprocessed ready for output in
+ * theming_example_text_form.tpl.php
+ */
+function template_preprocess_theming_example_text_form(&$variables) {
+  $variables['text_form_content'] = array();
+  $text_form_hidden = array();
+  // Provide variables named after form keys so themers can print each element independently.
+  foreach (element_children($variables['form']) as $key) {
+    $type = $variables['form'][$key]['#type'];
+    if ($type == 'hidden' || $type == 'token') {
+      $text_form_hidden[] = drupal_render($variables['form'][$key]);
+    }
+    else {
+      $variables['text_form_content'][$key] = drupal_render($variables['form'][$key]);
+    }
+  }
+  // Hidden form elements have no value to themers. No need for separation.
+  $variables['text_form_content']['hidden'] = implode($text_form_hidden);
+  // Collect all form elements to make it easier to print the whole form.
+  $variables['text_form'] = implode($variables['text_form_content']);
+
+}
diff --git a/theming_example/theming_example_text_form.tpl.php b/theming_example/theming_example_text_form.tpl.php
new file mode 100644
index 0000000..649887c
--- /dev/null
+++ b/theming_example/theming_example_text_form.tpl.php
@@ -0,0 +1,17 @@
+<?php
+/**
+ * @file
+ * Template file for theming_example_text_form
+ *
+ * The array $text_form_content contains the individual form components
+ * To view them in the source html use this
+ *
+ * <?php print '<!--' . print_r($text_form_content, TRUE) . '-->'; ?>
+ *
+ */
+?>
+<!-- theming_example_text_form template -->
+<div class="container-inline">
+<?php  print $text_form; ?>
+</div>
+<!-- /theming_example_text_form template -->