Difference between revisions of "Team:Peshawar/Wiki"

Line 1: Line 1:
<!DOCTYPE html>
 
 
<html>
 
<html>
  

Revision as of 17:43, 18 October 2016

Wiki Design 101 - iGEM Peshawar 2016

iGEM Wiki Design 101


Although iGEM provides a basic skeleton for the wiki — that can be easily filled by anyone who has some basic knowledge of HTML and CSS — most teams prefer to completely redesign the look and feel of their wiki. For first timers, completely redesigning the wiki could be an overwhelmingly difficult experience, partly due to the scant information available on how to do it exactly.

Here, we present some of the lessons we learned while completely redesigning our iGEM wiki for the first time in the hope that some teams in the coming years will find it useful.


1. Design your wiki to be responsive

A responsive wiki adjusts its content to different screen-sizes by tweaking its layout so that the main content is always visible clearly without the user needing to zoom-in or scroll horizontally.

It is important to make the wiki responsive because your wiki visitors may be using a mobile phone, or a tablet, or a laptop — all with different screen sizes and resolutions. A wiki designed only for the laptops will be difficult to browse on a smartphone because the elements of the webpage would then be squished to fit the phone. The user will then need to zoom-in to view the text, and consequently scroll horizontally every now and then to view the entire page — not exactly a pleasant experience.

A responsive website adjusts its layout according to the size of the device it is being viewed on. In the above illustration of our responsive wiki, the picture and bio get re-arranged depending on the size of the window.

In a responsive web design, the website tweaks its layout for different screen sizes for best user experience. The screen resolution at which the website tweaks its layout is called a breakpoint. The default iGEM wiki template for the year 2016 uses a breakpoint of 1000px. For screen widths above 1000px, the iGEM wiki lays out the menu vertically as a sidebar. And for screen widths below 1000px, the menu is stacked vertically and the page content is appended below it. This is done so that the page's main text can be displayed conveniently on smaller-sized screens. Furthermore, the mobile menu has links that have wider padding so that the user can easily touch them with their fingers and go to the desired page.

Your custom–designed wiki can have as many breakpoint as you like, but we think that a single breakpoint, around 1000px, is enough. Managing too many breakpoints may become a bit difficult for first timers.


2. Use a grid framework

Grid frameworks make it easy to design a responsive website. There are three major grid frameworks you could choose from:

If you use Bootstrap or Foundation, you will litter your HTML markup with presentation classes from these frameworks, which is not a good practice; the content should always be separate from its presentation.


<!-- Columns are always 50% wide, on mobile and desktop -->
<!-- Example of Bootstrap -->
<div class="row">
  <div class="col-xs-6">Column 1 text</div>
  <div class="col-xs-6">Column 2 text</div>
</div>

This is how you would use Bootstrap if you wanted to have two columns of text on both smartphones and desktop each 50% wide. col-xs-6 is a presentation class from Bootstrap framework, and it is controlling how the content of the div would appear on the page. But CSS should control how the content would look. Using Bootstrap and Foundation you will litter you HTML markup with these presentation classes. The boundry between content and its presentation get all mixed up when using Bootstrap and Foundation.

<!-- Columns are always 50% wide, on mobile and desktop -->
<!-- Example of Neat -->
<div class="container">
  <div>Column 1 text</div>
  <div>Column 2 text</div>
</div>

Clean markup when using Neat. HTML will now contains only the page's content. It's styling and responsive layout is being controlled using CSS. No there is a clear divide between content and its presentation.

Neat avoids this littering by providing a semantic grid framework that respects the boundary between content and presentation. You won't need to use any presentation classes in your HTML markup if you use the Neat grid framework. You will end up having a clean HTML markup.

Furthermore, Bootstrap and Foundation are bloated. A wiki using them will be slower than the one using Neat, which is a minimalistic and light weight framework — all the more reasons to start using Neat in your next wiki or web design project.


3. Develop your wiki locally

iGEM provides a very basic editor to edit your Team's wiki pages, but using it is a real pain. The editor has no syntax highlighting, does not support code indentation or code completion; in short, all the perks of a modern integrated development environment (IDE) are missing from it. Don't waste your time and energy developing your wiki online using the iGEM wiki editor.

Instead make your wiki locally first just like a normal website, and then copy and paste the HTML and CSS code on your team's iGEM pages.

Developing wiki online on iGEM servers is a pain. We developed our wiki locally using Sublime and CodeKit. We then dumped all the HTML, CSS, and JavaScript files at the very last hour on to the iGEM server.

But you must take care of a few things if you want to follow this approach:

Use online assets in your offline website

Usually, when web developers develop websites locally — i.e., offline — they use all assets locally. For example, they place all fonts in a fonts folder, and images in an img folder, and then use relative paths in the code to access these assets in their CSS or HTML code.

When designing an iGEM wiki, you must not use local resources. Instead, you should first upload them to iGEM servers, and then use the absolute path of these assets in your CSS or HTML. This will make your life so much easier.


img:hover {
    content: url(https://static.igem.org/mediawiki/2016/3/3d/T--Peshawar--bourbon.png);
}   

Example of use of absolute path of assets. Always used absolute paths of your assets when developing your iGEM wiki offline.

img:hover {
    content: url('./img/footer/T--Peshawar--bourbon.png');
}   

Example of use of relative path of assets. Don't use relative paths of your assets when developing your iGEM wiki offline.
After you are done developing the wiki, all you need to do to make your "offline" wiki "online" is to just copy and paste your HTML, CSS, and JavaScript code on your iGEM Team pages. Off course, you would have to do a few minors tweaks to link your CSS and JavaScript files, but no major changes would be needed.

Use Allow CORS and Cache Killer Chrome extensions during development

When you are working on a local website which is using online assets, the assets will fail to load in your web-browser. You will need to enable Cross-origin resource sharing (CORS) using Allow CORS Chrome extension.

Furthermore, you would also need to empty your cache every time you reload a page because you made some changes in it. Use the Cache Killer Chrome extension to purge the cache every time you refresh your webpage.

Use Live Reload to automatically refresh the webpage you are currently developing

Every time you make changes in HTML, CSS, or JavaScript files, you will need to save these changes and then refresh your webpage to view the changes take effect. This may become very time consuming considering that you would repeat this process more than a thousand times a day.

Either use Codekit's Preview feature or use Live Reload software to refresh the webpage automatically whenever you make any changes in your HTML, CSS, or JavaScript files. Live Reload can work on both Windows and Mac whereas, Codekit is a Mac-only software.


4. Reuse code snippets using .kit language

While developing your website locally, use .kit language to reuse your code snippet across many different pages. For instance, you will use header, footer, and menu on almost all pages. You can opt to write code for all these elements in each and every page, but it's cumbersome — not to mention difficult to maintain in future. Instead, you should make separate HTML files for these reusable elements of the website, and then use the .kit language to import them in your pages as needed — super convenient if you ask me.

To use the .kit language you will need to use Codekit. Codekit will compile the files for you so that the separate snippets are included inline in the final HTML output.

   
<!DOCTYPE html>
<html>

<head>
    <title>iGEM Peshawar 2016
    <link rel="stylesheet" type="text/css" href="css/main.css">
</head>

<body>
    <div class="outermost-box">
        <!--@import "_floating_button_wrapper.kit"-->
        <!--@import "_off_canvas_slidebar_nav.kit"-->
        <div canvas="container">
            <section class="inner-container">
                <!--@import "_header.kit"-->
                <!--@import "_inlineJS_menu_button.kit"-->

                <div class="full-content-wrapper-container">
                    <div class="full-width-content-wrapper">
                    </div>
                    <!--End of full-width-content-wrapper-->
                </div>
                <!--End of full-width-content-wrapper-container-->
                
                <!--@import "_all_in_one_footer.kit"-->
            </section>
            <!--End of inner-container-->
        </div>
        <!--End of on-canvas container for all the content-->
    </div>
    <!--End of outermost box-->
    <script src="js/script-min.js" type="text/javascript"></script>
    <!--@import "_statcounter.kit"-->
</body>

</html>

An example of how to reuse code snippets by writing them in separate files and then importing them using .kit language's @import statement. For example, _header.kit file contains HTML code for the header section of our wiki pages and we are importing the contents of this file in the code above. Similarly, _all_in_one_footer.kit file contains HTML code for the footer of the website. Any text file can be imported inline using kit langauge's @import command.

5. Compress your resources

The load time of a webpage can make or break the user experience of a website. Images play a key role in loading speed of a page. Large high resolution pictures will take an unnecessarily long time to load. Your wiki visitors are an impatient lot. You would be lucky if your average visitor spends more than 10 seconds on any page of the wiki. You are fighting for every millisecond here. Therefore, you must compress all your images before uploading them on the iGEM server. We found that Compressor.io provides the highest lossless compression. Its only downside is that it compresses only one image at a time. If you have multiple images to compress, you may want to use Compress PNG.

Compress your images so that the webpage loads faster. The animation above shows a comparison of the compressed and uncompressed image. The compressed image is 64% smaller in size than the uncompressed version. Both look the same however.

You should also minify your CSS and JavaScript. Minifying removes white spaces from these files making them smaller in size. The smaller the size, the faster the webpage will load.

Moreover, combine all your CSS files into single CSS file, and all your JavaScript files (except MathJax.js) into a single JavaScript file. Once you've done that, include the consolidated CSS and JavaScript files in your Wiki pages. Single CSS and JavaScript files will require single http requests; the smaller the number of http requests, the faster the website is going to load.

We have combined all our individual CSS files (shown on the right) into a single minified CSS file (main.css) using CodeKit. This reduces the number of http requests a webpage has to make to fetch the styling, thereby reducing the page load times.

6. Use readymade code snippets from CodePen

Searching responsive menus on CodePen churns out a whole catalog of menus that you could choose from and use in your wiki.

Do you want a cool menu in your wiki? Search responsive menu on CodePen and will find code for a ton of responsive menus - all free to use. Similarly, you can find code for parallex, background banner video etc. You don't have to reinvent the wheel.


7. Typography is important

Typography plays a key role in the look and feel of a website. Sometime you would come across a nice website and you would want to know what font it's using. One of the easiest way to find it out is to use the FontFaceNinja extension in Chrome to identify the fonts used on different elements of a websites. You can then use these fonts on your wiki as well.

FontFaceNinja could be used to identify fonts on any element of a webpage.
You must also take care of the font size, line height, and measure of your text so that everything is easily readable and looks nice at the same time. You can use the girdlover tool to choose the size of your h and p elements that follow the Golden ratio.

8. Learn from your Analytics

Once you design you wiki, you would want to know how many visitors are visiting your website, and how much time they are spending on any particular page. StatCounter can help you get this information, and much more. By adding StatCounter's tracking code, you can track not only how many visitors are visiting your wiki each day, but you can also get the finer details, such as their country, their browser and operating system, their screen resolution, the referring link, the view time, and duration. All this information can provide you with valuable insights that you can then use to improve your current wiki, or the one next year. For example, if you buried your Notebook page in third-level submenu, your visitors might not find the link. You will quickly find it out using the Statcounter's analytics because none of your visitors will be opening this Notebook page, and it won't get registered in the Statcounter logs.

Using StatCounter you can get useful statistics on your wiki visitors: You can view their IP addresses, the browser they were using, their screen resolution and operating system, the pages they visited, and how long they remained on any particular page. Internet is a snitch, isn't it?

You can view our Statcounter visitor logs by visiting the links below:

StatCounter Summary

StatCounter Detailed log


9. Have someone in your team with CS background for wiki design

When choosing the team, do have one or two people with a CS background. Developing a killer wiki would need skills in HTML, CSS, Javascript, JQuery, and Sass. So have someone who is already experienced in these skills or willing to learn them. Don't expect someone with a biology background and zero programming experience to be able to redesign the wiki.

In case you happen to end up in a team in which no one has any programming or web development experience, then it's probably better that you stick with default iGEM wiki template and tinker with its styling to improve it or customize to your taste. But don't opt for a complete redesign because — in all likelihood — it would turn out to be a bite too big to chew.


10. Miscellaneous

CSS code to make the iGEM's right-side menus and other annoyances disappear

Once you have made your offline website, you will then paste its HTML code on your team's page, and link the CSS and JavaScript files (which you would also have to upload to iGEM). But you will find that the iGEM right-side menu will be still there, and your layout will be all messed up.

We went through this and spent a fair amount of time solving it. Just add the following code at the top of your CSS to make all the annoyances disappear.


//Override iGEM wiki settings
#sideMenu,
#top_title {
    display: none;
}

#content {
    width: 100vw;
    padding: 0px;
    border: none;
    color: black;
    margin-left: auto;
    margin-right: auto;
    background-color: #fff;
    position: relative;
}

#globalWrapper {
    font-size: inherit;
    padding-bottom: 0;
}

#top_menu_under {
    height: 0px;
}

ul {
    list-style-image: none; //removes the iGEM wiki bullets
}

MathJax CSS hack to remove annoyning right-side spans


.MathJax nobr>span.math>span {
    border-left-width: 0 !important;
}

MathJax hack to make inline equations work

MathJax's inline equations using $..$ does not work out-of-the-box. You need to add the following code to you head section to make it work.


<script type="text/x-mathjax-config">
    MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [ ['$','$'], ["\\(","\\)"] ],
      processEscapes: true
    }
    });
</script>