Wednesday, December 10, 2014

A Prettier Wikibooks Design That Could Work

If you have not yet seen the Edge80 MediaWiki Publishing solution, have a look at the landing page. That will give you the right context for what this post is all about. I’m going to highlight the steps it took to adapt a set of standard MediaWiki pages into a modern responsive public site. 

To keep the demo fairly straightforward, I chose a Wikibook as the source content - essentially a smaller subset of standard Wikipedia pages. Our Wikibook textbook is High School Earth Science with a predictable content structure the very thoughtful authors stuck to. Compare the before and after versions. 

Original Wikibook Source
Desktop and Tablet views

Visit the Original Site
Adapted Wikibook
Desktop and Tablet views

Visit the Published Site


What was changed:
  • Converted to Bootstrap 3 Grid
  • Customised Adapted Pages 
  • Transformed Tables
  • CSS Style Changes 


Converted to a Bootstrap 3 Grid Layout

This was super easy. The Edge80 MediaWiki publisher does most of the work. The setup provides a choice of 3 responsive templates and I picked the Bootstrap 3 one. Following the steps in the process, I ended up with a new project folder that included a set of files under my account.  If you don’t have an account already, you can set one up as part of the process. 

The publisher also points you to the Customization Guide. Now would be a good time for beginners to scan that page. Some points from that guide will be included here.

At this point I had a project I re-named WikiBookTest that contained all my files (including Bootstrap CSS and Javascript) and the Domains tab showed me the URL where I could view the site under my sandbox runs80.com domain.  It was ok, but not quite what I wanted.



Customised Adapted Pages by Moving, Adding and Removing Elements

The adapted main page was the first thing I customized. This is done by editing the main rules.xml file in my project. Elements on the page are identified by using xpath (see: https://developer.mozilla.org/en-US/docs/Web/XPath). 

A text note to let visitors know they were viewing an adapted version of the original book was inserted.  Then, it seems to be popular these days to have a BIG hero image on the home page.  So, for tablet display, we arranged some of the elements and moved the main page image into the bootstrap hero title row. I also removed the links to downloadable PDF files. 

In rules.xml, there is a commented section where you can make edits to specific pages. Here is the Edge80 rule I added for the main page customisation: 

<rule match-path="*/High_School_Earth_Science">
    <apply name="framework.proxy_edited"/>
        <compose priority="3000">
            <!-- Add a class to identify the home page for CSS styling -->
            <modify xpath="body">

                <attribute action="class-add" name="class" value="main-page" />
            </modify>
            <!-- Insert a text note above the TOC list -->
            <insert xpath="//*[@id='Table_of_Contents']/.." action="before"
            with="literal">
                <div class="note"><strong>Note:</strong> This version of 
                    <em>High School Earth Science</em> is for demonstration
                    purposes.  The <a
                    href="http://en.wikibooks.org/wiki/High_School_Earth_Science" 
                    target="_blank">original WikiBook</a> 
                    is part of <a href="http://en.wikibooks.org/wiki/Main_Page"
                    target="_blank">Wikibooks</a>.  
                    The author's content is unchanged, but the presentation 
                    and display have been dynamically adapted and published to 
                    a transformed version of the textbook.
                </div>                    
            </insert>
            <!-- Rearrange and clean up elements on the page -->
            <remove xpath="//*[@id='status-icon']" />
            <cut xpath="//*[@id='title-row']/div/div/div/h1" 
                into-buffer="hero-title" />
           <cut xpath="//*[@id='mw-content-text']/div/img" 
                into-buffer="hero-img"/>
            <replace xpath="//*[@id='title-row']/div[1]" buffer="hero-img" />
            <insert xpath="//*[@id='title-row']/img" action="before" 
                with="buffer" buffer="hero-title" /> 
            <remove xpath="//*[@id='Resources']/..|//*[@id='mw-content-text']/ul"/>
         
        </compose>
</rule>

Assuming this published site could be used as a real High School textbook, I did not want to display some of the top-level Wikibook menus or allow students to edit content - that’s for the authors.  So I made other customisations that are used on all pages of the adapted site. 

For this project, I removed all default table widths and reduced the font size. (More on tables later.) Site-wide, I cleaned up the page title display, removed some clutter, and wrapped the bottom navigation in divs to make styling easier. 

Back in rules.xml, there is a commented section where you can make general edits to all pages. Here is that rule:

<rule name="user.page_edits">
    <!-- Tweaks after the whole page is constructed. -->
        <compose priority="4000">
            <!-- Replaced the text for link to book Categories to Index --> 
            <modify xpath="//*[@id='mw-normal-catlinks']/ul/li[2]/a" >
                <text value="Index" />
            </modify>
            <!-- Remove the width for thumbnail images -->
            <modify xpath="//div[@class='thumbinner']">
            <attribute action="style-remove" value="width" />
            </modify>
            <!-- Remove the width for tables and change font size-->
            <modify xpath="//table">
                <attribute action="style-remove" value="width" />
                <attribute action="style-add" value="font-size: 75%;"  />
            </modify>
            <!-- Clean up page titles -->
            <replace regex="&lt;h1&gt;(.*?)/(.*)&lt;/h1&gt;"
                value="&lt;h1&gt;${2}&lt;/h1&gt;" />            
            <cut xpath="//*[@id='mw-normal-catlinks']/ul/li[2]/a" 
                into-buffer="book-cat" />           
            <replace xpath="//*[@id='mw-normal-catlinks']" buffer="book-cat" />
            <remove xpath="//*[@id='mw-hidden-catlinks']" />
            <remove xpath="//li[@id='footer-places-mobileview']" />
            <remove xpath="//*[@id='top-navigation']" />
            <!-- Remove site EDIT links -->
            <remove xpath="//*[@class='mw-editsection']" />
            <!-- Add container divs to bottom navigation for CSS styling -->
            <remove xpath="//*[@id='bottom-navigation']/span/text()" />
            <wrap xpath="//*[@id='bottom-navigation']" >
                <div id="bottom-container"><wrapped></wrapped></div>
            </wrap>
            <wrap xpath="//*[@id='bottom-navigation']//a">
                <div class="bot-nav"><wrapped></wrapped></div>
            </wrap>
            <wrap xpath="//*[@class='nav navbar-nav']/a" 
                placeholder-tagname="wrapped">
                <li><wrapped></wrapped></li>
            </wrap>
        </compose>
</rule>

Converted Tables

Depending on the site, data and format, deciding on the best table strategy for a totally responsive display can be tricky. Sometimes, a table just needs to be - well, tabular. The Edge80 publisher applied default bootstrap styles to tables, but MediaWiki tables often have a fixed width defined which can be a challenge for a mobile-first responsive layout.  I removed the width attribute across the board which worked reasonably well, but there are usually exceptions.  I found one page that needed special treatment:  

What are Minerals?

Figure 3.1 consists of three tables nested in a containing table.  There are a lot of approaches to handle this situation, but for this example I converted all the elements for table, tr, and td tags to divs and added class names. This allowed me to style them for responsive display with css.  There was another rule added to the specific page section in rules.xml

<rule match-path="*/High_School_Earth_Science/What_are_Minerals%3F" >
    <apply name="framework.proxy_edited"/>
        
<compose priority="3100">
        <modify xpath="//table[2]">
<tagname value="div"/>
<attribute action="strip"/>
<attribute action="class-add" value="table minerals" />
</modify>
        <modify xpath="//table">
            <tagname value="div"/>
            <attribute action="strip"/>
            <attribute action="class-add" value="table" />
        </modify>
        <modify xpath="//tr">
<tagname value="div"/>
<attribute action="strip"/>
<attribute action="class-add" value="tablerow" />
</modify>
        <modify xpath="//td">
<tagname value="div"/>
<attribute action="strip"/>
            <attribute action="class-add" value="tablecell" />
</modify>  
    </compose>
</rule>

Adapted responsive version of What are Minerals?


CSS Changes for Responsive Displays and Easier Reading Layouts


After all the changes were made to manipulate what content to display, I added custom css styles in my project.  The MediaWiki publisher provides a blank file for custom styling in the project static/css folder. 

Probably the single biggest layout change is the default wiki super-wide text, into a narrower, easy to read column.  Additional readability changes were done in the media query styles for responsive break points. 


But why?

Now, I hear you saying that’s all fine, but why would you bother doing all this to adapt a WikiBook for responsive design?  Fair point - there is already a very nice Mobile view, and the wonderful Wikimedia Foundation has an evolved strategy to deal with multiple devices and screen sizes. 

This Wikibook is a convenient set of pages to illustrate just one example of what Edge80 MediaWiki Publisher can be used for.  

Consider a few possible reasons why this makes a lot of sense: 
  •  MediaWiki can be used as a robust content management system backend
  •  Edit links, talk pages and history can be removed from your public site (or textbook)
  •  No need for an m-dot site for mobile, which can hurt SEO
  •  Modify, tailor and style content for public-only viewing
  •  Cache your public site on a high-performance global network
  •  Protect your wiki server from traffic spikes and malicious attacks