[#1069] First commit for the CKAN style guide

ckan/config/routing.py

@@ -426,6 +426,7 @@ def make_map():
         m.connect('/util/redirect', action='redirect')
         m.connect('/testing/primer', action='primer')
         m.connect('/testing/markup', action='markup')
+        m.connect('style_guide', '/testing/style-guide', action='style_guide')
 
     for plugin in routing_plugins:
         map = plugin.after_map(map)

ckan/controllers/util.py

@@ -17,6 +17,12 @@ def primer(self):
         This is useful for development/styling of ckan. '''
         return base.render('development/primer.html')
 
+    def style_guide(self):
+        ''' Style guide for CKAN '''
+        id = base.request.params.get('id', 'index')
+        template = 'development/style_guide/%s.html' % id
+        return base.render(template)
+
     def markup(self):
         ''' Render all html elements out onto a single page.
         This is useful for development/styling of ckan. '''

ckan/public/base/less/layout.less

@@ -43,24 +43,29 @@
   margin-bottom: 0;
 }
 
-.primary {
-  .primary {
-    float: left;
-    width: 467px;
-    margin-left: 0;
-    margin-bottom: 20px;
-    h1, h2, h3, h4 {
-      &:first-child {
-        margin-top: 0;
-      }
+.primary .primary,
+.has-tertiary {
+  float: left;
+  margin-left: 0;
+  margin-bottom: 20px;
+  h1, h2, h3, h4 {
+    &:first-child {
+      margin-top: 0;
     }
   }
-  .tertiary {
-    float: left;
-    width: 180px;
-    margin-left: 20px;
-    margin-bottom: 20px;
-  }
+}
+.tertiary {
+  float: left;
+  width: 180px;
+  margin-left: 20px;
+  margin-bottom: 20px;
+}
+
+.primary .primary {
+  width: 467px;
+}
+.has-tertiary {
+  width: 670px;
 }
 
 .hero {

ckan/templates/development/style_guide/base.html

@@ -0,0 +1,37 @@
+{% extends 'page.html' %}
+{% import 'development/style_guide/macros.html' as style_guide %}
+
+{% block breadcrumb_content %}
+  <li class="active">{% link_for 'Style Guide', controller='util', action='style_guide' %}</li>
+{% endblock %}
+
+{% block secondary %}{% endblock %}
+
+{% block primary %}
+  {% set has_tertiary = true if self.tertiary() %}
+  <article class="module">
+    {% block page_header %}
+      <header class="module-content page-header">
+        {% if self.content_action() | trim %}
+          <div class="content_action">
+            {% block content_action %}{% endblock %}
+          </div>
+        {% endif %}
+        <ul class="nav nav-tabs">
+          {% block content_primary_nav %}
+            {{ style_guide.tab_item(h, request, _('Overview'), icon='star') }}
+            {{ style_guide.tab_item(h, request, _('Templates'), icon='th-large', id='templates') }}
+          {% endblock %}
+        </ul>
+      </header>
+    {% endblock %}
+    <div class="module-content{{ ' has-tertiary' if has_tertiary }}">
+      {% block primary_content_inner %}{% endblock %}
+    </div>
+    {% if has_tertiary %}
+      <aside class="tertiary">
+        {% block tertiary %}{% endblock %}
+      </aside>
+    {% endif %}
+  </article>
+{% endblock %}

ckan/templates/development/style_guide/index.html

@@ -0,0 +1,54 @@
+{% extends "development/style_guide/base.html" %}
+
+{% block tertiary %}
+  {{ style_guide.page_sections([
+    ('The Principle', 'principle') ])
+  }}
+{% endblock %}
+
+{% block primary_content_inner %}
+
+  <h1 class="hide-heading">Overview</h1>
+
+  <p id="principle" class="lead">
+    <strong>The Principle</strong> &mdash;
+    CKAN adheres to the following three basic tenants of design. It should be
+    <strong>clear</strong>, <strong>consistent</strong> and
+    <strong>concise</strong>.
+  </p>
+
+  <h2>Clear</h2>
+  <p>
+    When a user is interacting with a feature it should be clear to them what
+    that feature does before they perform said action. Furthermore they should
+    be able to take a brief glance at a page and understand what the context of
+    the page is and what their next action is.
+  </p>
+  <p>
+    A user should also be able to visit a page and understand the context of
+    where that page sites within the instance quickly.
+  </p>
+
+  <h2>Consistent</h2>
+  <p>
+    This means that user interface should behave in the similar manner across
+    all of the instance. A user should only have to visit one or two pages in
+    order to understand how to basically get around a CKAN instance.
+  </p>
+  <p>
+    Whenever possible we should re-use user interface items that fit into
+    pre-existing mental models that match users behaviour.
+  </p>
+
+  <h2>Concise</h2>
+  <p>
+    This means that we should apply the philosophy that 'less is more'. A user
+    shouldn't have to read a wiki page in order to understand a feature. It
+    also means that we shouldn't plaster helper messages everywhere as no-one likes to be told how to suck eggs.
+  </p>
+  <p>
+    CKAN core should have a modular re-useable user interface that is made up
+    of a group of simple items that can be applied to different contexts.
+  </p>
+
+{% endblock %}

ckan/templates/development/style_guide/macros.html

@@ -0,0 +1,53 @@
+{#
+Makes a nav for all the page sections of the current page
+
+page_sections - A list of dicts for the current page items
+
+Examples:
+
+  {% import 'development/style_guide/macros.html' as style_guide %}
+  {{ style_guide.page_sections([
+    ('Number #1', '#1'),
+    ('Number #2', '#2') ])
+  }}
+
+#}
+{% macro page_sections(page_sections) %}
+  <section class="module module-narrow">
+    <h2 class="module-heading"><i class="icon-list"></i> On this page</h2>
+    <ul class="nav nav-simple">
+      {% for label, id in page_sections %}
+        <li class="nav-item">
+          <a href="#{{ id }}">{{ label }}</a>
+        </li>
+      {% endfor %}
+    </ul>
+  </section>
+{% endmacro %}
+
+{#
+Make a tab item for the header bar in the style guide
+
+label - The label for the tab
+icon  - The icon for the tab
+id    - The get variable of 'id' that determines the page to render
+
+Examples:
+
+  {% import 'development/style_guide/macros.html' as style_guide %}
+  {% block content_primary_nav %}
+    {{ style_guide.tab_item(_('Page 1'), icon='star', id='1') }}
+    {{ style_guide.tab_item(_('Page 2'), icon='star', id='2') }}
+  {% endblock %}
+
+#}
+{% macro tab_item(h, request, label, icon, id=false) %}
+  {% set is_active = ( id == ( request.params.id if request.params.id else false ) ) %}
+  {% set url = h.url_for('style_guide', id=id) if id else h.url_for('style_guide') %}
+  <li{{ ' class="active"'|safe if is_active }}>
+    <a href="{{ url }}">
+      <i class="icon-{{ icon }}"></i>
+      {{ label }}
+    </a>
+  </li>
+{% endmacro %}