[#847] Add extensions CSS tutorial

ckanext/example_theme/v12_custom_css/plugin.py

@@ -0,0 +1 @@
+../v11_extra_public_directory/plugin.py

ckanext/example_theme/v12_custom_css/public/example_theme.css

@@ -0,0 +1,3 @@
+.account-masthead {
+    background-color: rgb(40, 40, 40);
+}

ckanext/example_theme/v12_custom_css/public/promoted-image.jpg

@@ -0,0 +1 @@
+../../v11_extra_public_directory/public/promoted-image.jpg

ckanext/example_theme/v12_custom_css/templates/base.html

@@ -0,0 +1,6 @@
+{% ckan_extends %}
+
+{% block styles %}
+  {{ super() }}
+  <link rel="stylesheet" href="/example_theme.css" />
+{% endblock %}

ckanext/example_theme/v12_custom_css/templates/home

@@ -0,0 +1 @@
+../../v11_extra_public_directory/templates/home

ckanext/example_theme/v12_custom_css/templates/snippets

@@ -0,0 +1 @@
+../../v11_extra_public_directory/templates/snippets

ckanext/example_theme/v13_more_custom_css/plugin.py

@@ -0,0 +1 @@
+../v12_custom_css/plugin.py

ckanext/example_theme/v13_more_custom_css/public/example_theme.css

@@ -0,0 +1,103 @@
+/* =====================================================
+   The "account masthead" bar across the top of the site
+   ===================================================== */
+
+.account-masthead {
+    background-color: rgb(40, 40, 40);
+}
+/* The "bubble" containing the number of new notifications. */
+.account-masthead .account .notifications a span {
+  background-color: black;
+}
+/* The text and icons in the user account info. */
+.account-masthead .account ul li a {
+  color: rgba(255, 255, 255, 0.6);
+}
+/* The user account info text and icons, when the user's pointer is hovering
+   over them. */
+.account-masthead .account ul li a:hover {
+  color: rgba(255, 255, 255, 0.7);
+  background-color: black;
+}
+
+
+/* ========================================================================
+   The main masthead bar that contains the site logo, nav links, and search
+   ======================================================================== */
+
+.masthead {
+  background-color: #3d3d3d;
+}
+/* The "navigation pills" in the masthead (the links to Datasets,
+   Organizations, etc) when the user's pointer hovers over them. */
+.masthead .navigation .nav-pills li a:hover {
+  background-color: rgb(48, 48, 48);
+  color: white;
+}
+/* The "active" navigation pill (for example, when you're on the /dataset page
+   the "Datasets" link is active). */
+.masthead .navigation .nav-pills li.active a {
+  background-color: rgb(74, 74, 74);
+}
+/* The "box shadow" effect that appears around the search box when it
+   has the keyboard cursor's focus. */
+.masthead input[type="text"]:focus {
+  -webkit-box-shadow: inset 0px 0px 2px 0px rgba(0, 0, 0, 0.7);
+  box-shadow: inset 0px 0px 2px 0px rgba(0, 0, 0, 0.7);
+}
+
+
+/* ===========================================
+   The content in the middle of the front page
+   =========================================== */
+
+/* Remove the "box shadow" effect around various boxes on the page. */
+.box {
+  box-shadow: none;
+}
+/* Remove the borders around the "Welcome to CKAN" and "Search Your Data"
+   boxes. */
+.hero .box {
+  border: none;
+}
+/* Change the colors of the "Search Your Data" box. */
+.homepage .module-search .module-content {
+  color: rgb(68, 68, 68);
+  background-color: white;
+}
+/* Change the background color of the "Popular Tags" box. */
+.homepage .module-search .tags {
+  background-color: rgb(61, 61, 61);
+}
+/* Remove some padding. This makes the bottom edges of the "Welcome to CKAN"
+   and "Search Your Data" boxes line up. */
+.module-content:last-child {
+  padding-bottom: 0px;
+}
+.homepage .module-search {
+  padding: 0px;
+}
+/* Add a border line between the top and bottom halves of the front page. */
+.homepage [role="main"] {
+  border-top: 1px solid rgb(204, 204, 204);
+}
+
+
+/* ====================================
+   The footer at the bottom of the site
+   ==================================== */
+
+.site-footer,
+body {
+  background-color: rgb(40, 40, 40);
+}
+/* The text in the footer. */
+.site-footer,
+.site-footer label,
+.site-footer small {
+  color: rgba(255, 255, 255, 0.6);
+}
+/* The link texts in the footer. */
+.site-footer a {
+  color: rgba(255, 255, 255, 0.6);
+}

ckanext/example_theme/v13_more_custom_css/public/promoted-image.jpg

@@ -0,0 +1 @@
+../../v12_custom_css/public/promoted-image.jpg

ckanext/example_theme/v13_more_custom_css/templates

@@ -0,0 +1 @@
+../v12_custom_css/templates

doc/theming.rst

@@ -780,16 +780,64 @@ promoted image replaced with our custom one.
 Customizing CKAN's CSS
 ----------------------
 
-.. Use the styles block in base.html to add a global css file
+Extensions can add their own CSS files to modify or extend CKAN's default CSS.
+Create an ``example_theme.css`` file in your extension's ``public`` directory::
+
+    ckanext-example_theme/
+      public/
+        example_theme.css
+
+Add this CSS into the ``example_theme.css`` file, to change the color of CKAN's
+"account masthead" (the bar across the top of the site that shows the logged-in
+user's account info):
+
+.. literalinclude:: ../ckanext/example_theme/v12_custom_css/public/example_theme.css
+
+If your restart the development web server (kill the server using Ctrl-c, then
+run the ``paster serve`` command again) you should be able to open this file at
+http://127.0.0.1:5000/example_theme.css in a web browser.
+
+To make CKAN use our custom CSS we need to override the ``base.html`` template,
+this is the base template which the templates for all CKAN pages extend, so if
+we include a CSS file in this base template then the file will be included in
+every page of your CKAN site. Create the file::
+
+    ckanext-example_theme/
+      templates/
+        base.html
+
+and put this Jinja code in it:
+
+.. literalinclude:: ../ckanext/example_theme/v12_custom_css/templates/base.html
+
+The default ``base.html`` template defines a ``styles`` block which can be
+extended to link to custom CSS files (any code in the styles block will appear
+in the ``<head>`` of the HTML page).
+
+Restart the development web server, and you should see the background color of
+the account masthead change. This custom color should appear on all pages of
+your CKAN site.
+
+Now that we have CKAN using our CSS file, we can add more CSS rules to the file
+and customize CKAN's CSS as much as we want. There's nothing special about CSS
+in CKAN, you just use the usual tools and techniques to explore and hack the
+CSS.
+
+.. todo:: Link to some tools?
+
+   e.g. Firefox inspector etc (or Chrome? Firebug?)
+
+   e.g. Some online CSS reference.
+
+Let's add a bit more code to our ``example_theme.css`` file. This CSS
+implements a partial imitation of the `datahub.io <http://datahub.io/>`_ theme
+(circa 2013):
+
+.. literalinclude:: ../ckanext/example_theme/v13_more_custom_css/public/example_theme.css
 
 .. todo::
 
-   * Introduce CSS?
-   * Use Fanstatic to add a CSS file
-   * Use Bootstrap's CSS files and CKAN core's
-   * See the CKAN style guide
-   * custom.less: Edit ckan/public/base/less/custom.less and then run ./bin/less
-     or ./bin/less --production
+   We use LESS for the CKAN core CSS. Do we want to mention that here?
 
 
 -----------------------------

setup.py

@@ -90,6 +90,8 @@
         'example_theme_v9 = ckanext.example_theme.v9_custom_snippet.plugin:ExampleThemePlugin',
         'example_theme_v10 = ckanext.example_theme.v10_HTML_and_CSS.plugin:ExampleThemePlugin',
         'example_theme_v11 = ckanext.example_theme.v11_extra_public_directory.plugin:ExampleThemePlugin',
+        'example_theme_v12 = ckanext.example_theme.v12_custom_css.plugin:ExampleThemePlugin',
+        'example_theme_v13 = ckanext.example_theme.v13_more_custom_css.plugin:ExampleThemePlugin',
     ],
     'ckan.system_plugins': [
         'domain_object_mods = ckan.model.modification:DomainObjectModificationExtension',