Difference between revisions of "Team:US AFRL CarrollHS/WikiGuide"

Line 165: Line 165:
  
 
</html>
 
</html>
−
 
−
 
−
 
 
</pre>
 
</pre>
 
                     <h2>Combining Elements</h2>
 
                     <h2>Combining Elements</h2>

Revision as of 04:18, 19 July 2019

***We have not finished uploading our current wiki guide draft, please email us (igem@carrollhs.org) for the whole thing!! :D

Introduction

The wiki is a vital part in telling the judges, public, current, and past iGEM teams about your team. Here's another vital iGEM truth - everyone dreads the wiki freeze and many teams are hesitant to begin their wiki. It can be a struggle, but we're here to help.

What are we doing? We're putting together a wiki wealth of knowledge - a comprehensive guide that combines all wiki knowledge from teams past and present, source code that you can use on your wiki, and a YouTube video series where we walk you through all the major things you need to know about everything wiki related.

Who are we looking to help us? Everyone. We need first year teams to give us feedback on if our guide covers all of their questions and how it helped them create their wiki. We need teams to write up a couple bullet points describing how they create their wiki. If you use our guide/video series in any way, please let us know so that we can make sure to thank you on our collaborations page!

What inspired us? We are a third year team who puts many hours into our wiki every year. Our very first year, we collaborated with a team who answered a lot of our initial questions about how to code our wiki; this helped us immensely. Our team has spent many hours trying to get our code to function properly when the fix was simple. We want teams to combine their knowledge into one, easy to find place for current and future teams to use. Additionally, the individuals that work on each team’s wiki may change from year to year. With this guide, they do not have to completely start from scratch; they can build off of previous years’ experience.

Instagram, Twitter, and Facebook - @iGEMLabPats

YouTube Channel - US AFRL Carroll HS

GitHub - https://github.com/us-afrl-carrollhs

Email - igem@carrollhs.org

Collaboration Credits

A huge thank you to all the teams who have collaborated with us (this far) to create this guide:

  • iGEM TAU
  • iGEM Thessaly
  • OhioState
  • Nottingham iGEM
  • Edinburgh
  • ASIJ Tokyo
  • Stockholm (memes coming soon!)
  • Aux Marseille
  • uOttawa
  • NCTU Formosa
  • iGEM AMU
  • Gothenburg
  • TU_Dresden
  • UCL
  • iGEM NCKU-Tainan
  • OUC-China
  • Ruperto Carola
  • UNSW Australia
  • MSP
  • IISER Pune
  • Manchester
  • Your team! Our list is growing everyday :)

Wiki 101

Becoming Familiar with the iGEM Wiki

What is it? Hosted on the iGEM server, every iGEM team is given a wiki page to create for your team. It is essentially your team’s website to document, not only your lab work, but your entire iGEM project. The judges review it before going to your presentation. It is essential that all work is explained on the wiki as clearly as possible to ensure that judges (and the public) understand your project.

Logging In and Finding Your Team's Wiki

Screen shot of video tutorial on YouTube. Linked to video; link comes later too.

Click here to view a video tutorial about how to login to your iGEM account and find your team's wiki

Planning

Decide on your involvement with the wiki

Basic Understanding - using iGEM’s template and altering it to accommodate content

It is recommended that several/almost all team members have a basic understanding of the wiki. This way, they can edit content and basic formatting.

Advanced Understanding - in depth knowledge of web development. Not only editing content, but creating HTML structures and more detailed CSS customization

It is recommended that at least 2-3 team members have some sort of deeper knowledge of how HTML/CSS coding works. This way multiple team members can develop code, along with fix errors in code. If your team is lacking members who are able to dedicate this much time to understanding the wiki, or if additional help is needed, collaborate with another team who can help.

Basic Understanding Guide

Getting Started

Begin by reading iGEM's wiki how-to (https://2019.igem.org/Competition/Deliverables/Wiki). The main things to pay attention to are:

THE WIKI FREEZE!!! The wiki freeze is final. Keep in mind that the iGEM server may crash due to everyone trying to finish their wikis. The wiki on the last day, especially the last couple of hours, is noticeably slower and not all changes save.

Screen shot of iGEM headquarter's statement about the wiki freeze

Read the wiki rules. Main highlights will be covered in the Advanced Understanding Guide, but anyone working on the wiki should understand the basic rules.

Working With the Wiki

Read over all Wiki documentation provided by iGEM:

https://2019.igem.org/Resources/Wiki_Editing_Help - this describes HTML, CSS, and Javascript use on the wiki, how to create a new page, how to upload a file/video, and how to use templates.

https://2019.igem.org/Resources/Template_Documentation - this shows the default wiki settings. Talk with the people in charge of your wiki to see if this is applicable to your wiki.

How to Navigate the Wiki

Screenshot of YouTube Video; link provided in following text.

Learn how to edit pages, view page history, and upload photos/documents

Video Tutorial Here - https://www.youtube.com/watch?v=IK6JjS_LjQg&list=PLg5B0YEXzgEorRa8vuZPoHah2e1jmgVQ6&index=3

All You Need to Know about HTML/CSS

Videos to come!

HTML/CSS Understanding Guide

Basic Elements

*****THERE WILL BE THREE YOUTUBE VIDEOS GOING OVER THESE EXAMPLES :)

Example code found on our GitHub here - https://github.com/us-afrl-carrollhs/Wiki-Code-Examples

<html>
   <h1>Header 1</h1>
   <h2>Header 2</h2>
   <h3>Header 3</h3>
   <h4>Header 4</h4>
   <h5>Header 5</h5>
   <h6>Header 6</h6>
   <p> Paragraph text</p>
   <p><b>Bold text</b></p>
   <p><i>Italicized text</i></p>
   <a href=“insert url here”>Link text</a>
   <br>
   <img src=“https://2019.igem.org/wiki/images/1/12/T--US_AFRL_CarrollHS--TeamLinearLogo2019.JPG” alt=“text in case image doesn’t appear” style=“width: 50%;  height: auto;”>
   <table>
      <tr>
         <th>Table header 1</th>
         <th>Table header 2</th>
      </tr>
      <tr>
         <td>Table data 1</td>
         <td>Table data 2</td>
      </tr>
   </table>
   <ul>
      <li>Unordered list item 1</li>
      <ol>
         <li>Ordered list item 1</li>
         <li>Ordered list item 2</li>
      </ol>
      <li>Unordered list item 2</li>
      <li>Unordered list item 3</li>
   </ul>
</html>

Using CSS Code

<html>

   <!--CSS Code*/--!>
   <style>
      h1 {color: #001389;}
      .div1 h1 {color: #000000;}
      h1.header1 {color: green;}
  </style>

   <h1>Header 3</h1>

   <div class="div1">
      <h1>Header 2</h1>
   </div>

   <h1 class="header1">Header 1</h1>

</html>

Combining Elements

<html>
   <h1>Welcome to our team page!</h1>
   <h2>This page tells you about our team! What a surprise!</h2>
   <div class="column two_thirds_size">
      <p>Paragraph text for the first paragraph. I’m just going to keep typing on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on. There we go.</p>
      <p>Paragraph text for the second paragraph. I’m just going to keep typing on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on. There we go.</p>
   </div>
   <div class="column third_size">
      <p>Paragraph text for the third paragraph. I’m just going to keep typing on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on and on. There we go.</p>
   </div>
</html>

Example (Uploading Your Project Description and Inspirations

Screen shot of YouTube video, link in following text

Video Tutorial Here - https://www.youtube.com/watch?v=orxXYM8Glv4&list=PLg5B0YEXzgEorRa8vuZPoHah2e1jmgVQ6&index=5 

Advanced Understanding Guide

Getting Started

First complete the Basic Understanding Guide to familiarize yourself with the wiki, then learn HTML and CSS in depth

Recommended courses on Codecademy (bolded are highly recommended)

Next you can learn jQuery and JavaScript. This is more optional as many elements already have built in functions and you can easily create your wiki without much knowledge of them; HTML and CSS will be your core. It is helpful to be lightly familiar with them, though. More information about jQuery is later in the guide, and JavaScript information is coming soon. There are also Codecademy courses on both of these.

You will be responsible for knowing the Wiki rules (https://2019.igem.org/Competition/Deliverables/Wiki) and ensuring that your team follows them!Here are the main ones that you may run into:

All content must be hosted on iGEM server (ex: external style sheets cannot be used))

Screen shot of iGEM HQ rule #4: Teams must host ALL content on 2019.igem.org

You cannot alter the iGEM menu bar (narrow bar at very top of screen)

  • iGEM Stockholm 2015 came up with a fix for the iGEM login bar (their purpose: “to restore the original style to the top menu” after Bootstrap). Find here: igem.org/Team:Stockholm/fixbootstrap.css
Screen shot of iGEM HQ rule #1: Teams cannot edit, disable,hide,or alter the iGEM login bar

No plagiarism!!!

Screen shot of iGEM HQ rule #6: Teams cannot use any copyrighted materials on their wiki, included images.

Wiki freeze is final

Screen shot of iGEM HQ rule #7: Teams cannot alter content after the Wiki Freeze deadline

Know How to Upload Your CSS and JavaScript Files

Know How to Upload Your CSS and JavaScript Files

Screen shot of YouTube video; link below.

Video Tutorial Here - https://www.youtube.com/watch?v=YNuSKknqjUA&feature=youtu.be

Importance - these templates are where you are going to put the bulk of your CSS code to style your wiki!

How to Upload a Video to the Wiki

Screenshot of YouTube video; link below.

Video Tutorial Here - https://www.youtube.com/watch?v=wT6djYIBXmE&list=PLg5B0YEXzgEorRa8vuZPoHah2e1jmgVQ6&index=8

Example code found on our GitHub here - https://github.com/us-afrl-carrollhs/Wiki-Code-Examples

  • Credits to iGEM team Edinburgh for requesting this!!!

Decide on how you want to create your wiki

There are two main options:

The simplest way is just to use iGEM's template and alter color/font to customize for your team.

Another option is to remove all iGEM styling from your team's wiki, then upload your own stylesheets and formatting. There are multiple options within this category, but you'll want to start by removing all iGEM default formatting.

From here there are many options on what to do including:

  • Writing your own code (example wiki - http://2017.igem.org/Team:US_AFRL_CarrollHS)
  • Finding open source code online
  • Implementing a program such as Bootstrap
    • More info later in guide
  • Figure out your design! (Info later in guide :)

Another option is to use an outside program

Here's what iGEM TAU (https://2019.igem.org/Team:TAU_Israel) says about their experience with Webflow:

  • Webflow is a website that allows you to design your website while creating a neat code for you.
  • We have currently only done a proof of concept of importing the code to our wiki so there might be more pros or cons
  • Pros
    • You can easily design an amazing website
    • Webflow creates all the necessary files for you - HTML, CSS, JS
    • You don't have to really understand coding for web design
  • Cons
    • The ability for export code files costs money
    • You have to make some adjustments in the code while uploading it to the iGEM servers

Designing Your Team's Wiki

Decide on Branding

(Suggested by UNSW iGEM)

Color Palette - Come up with a team color palette. It's very helpful to put them all in a spreadsheet, with their Hex Color Codes and/or RGB Color Codes next to each color, creating an easy reference for your entire team as you work on your wiki/other branding elements.

Logos - Ensure that you have all team and project logos in the file formats that you need. Upload them to the wiki (how to upload photos available on YouTube :), it's helpful to include the image urls for these images in one location, as finding past uploaded images can be time consuming.

Fonts - Determine the fonts that your team will be using, and if you will need to upload them to your stylesheets. Resources:

Recommended Templates/Elements in Your Wiki

Navbar - this is essential as it allows a user to navigate to all pages of your wiki

  • Video/resources coming soon

Footer -recommended if your team has sponsors, additional links/contact information that you would like your user to easily access

  • Videos coming soon

Template for styling -main template for all pages that includes styling such as: headers, images, background color, etc.

Easiest ways to transfer templates - copy and paste in the template iGEM created for your team. Ex: In the template — {{YourTeamName}} — create multiple templates as needed, such as {{YourTeamName/navbar}} and {{YourTeamName/style}}

  • Note: doesn't work for tempates (such as the footer) that have a specific location on page)
Screen shot of YouTube video; link below

Another way is to decide on all the templates you will use, create them all on one page, then copy and paste them to every page

jQuery

What is it?

Content provided by TU_Dresden

What is it?

Just as with Bootstrap (later section in guide!), jQuery is another major player in the web development industry and it needs to be included in your site for Bootstrap to work properly in your IGEM Wiki.

Imagine that you are in a hair salon. If Bootstrap was the makeup, jQuery would be the tools and gadgets required to make everything work. This is done through a completely different language from CSS or HTML called JAVASCRIPT.

So, what is Javascript? it is the language that your browser (Chrome/Safari) uses to DO STUFF.

Whenever you push a button, most likely you need that button to do something... like send data, change page, bring an alert window or resize an element within the website. Javascript is the language that was created to process these actions, or in our bio-language: to make the website alive!

This used to be a painfully tedious process with javascript alone, so this is where your friend jQuery comes into the play. It is a “layer” built on top of Javascript in order to easily implement actions and content-handling stuff on your Wiki without having to reinvent the wheel.

How to use the newer jQuery and Bootstrap in your Wiki

How to use the newer jQuery and Bootstrap in your Wiki?

This is where things get tricky. The IGEM server will push a VERY old version(1.11.1) of jQuery into whatever content you load into your space. This makes most modern templates and bootstrap versions incompatible with the IGEM MediaWiki by default. You need to use the new versions of both to make your site look like a 2018 website.

This workaround is not mentioned anywherein the Wiki guidelines and it was developed to embed the newest version of jQuery and Bootstrap on top of the annoying old version.

So here it is:

1) Download or open this files with your browser. You will need to copy its contents later.

https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js

https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.js

https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.css

2) Create the following files in your namespace (you must be logged in your igem account)

Template:YOUR_TEAM_NAME/jquery.js

Template:YOUR_TEAM_NAME/bootstrap.js

Template:YOUR_TEAM_NAME/bootstrap.css

To do this, simply navigate to the following addresses (replace YOUR_TEAM_NAME with your namespace): 

https://2019.igem.org/Template:YOUR_TEAM_NAME/jquery.js

https://2019.igem.org/Template:YOUR_TEAM_NAME/bootstrap.js

https://2019.igem.org/Template:YOUR_TEAM_NAME/bootstrap.css

When you open each URL, since the file doesn't exist, you will need to ask mediawiki to create the file for you. Use the link that saysEDIT THIS PAGE.

3) Paste the contents of each file into its corresponding file online.

example: jquery.jsgoes into Template:YOUR_TEAM_NAME/jquery.js

4) Save each file with its corresponding content

5) When you have created all 3 files, the sources for the updated versions of bootstrap and jQuery will be available within the IGEM server without violating any guidelines.

You can then include the files in your wiki template by calling them with the following URL within your site Template: “https://2019.igem.org/wiki/index.php?title=Template:YOUR_TEAM_NAME/filename.js&action=raw&ctype=text/javascript”

Note that the URL is instructing the iGEM's mediawiki engine to deliver the file in RAW format and using the text/javascriptor text/cssMIME types. This is very important for the browser to be able to download and execute the imported content without mediawiki adding its annoying html entities (your computer guys will understand what we mean).

And Voila! We have jQuery 3.4.1 running on our IGEM Wiki! 

It took us a while in TU_Dresden to figure out how to do this on our own from reading the fine letters of MediaWiki; given that the IT people of IGEM didn't know how to support this kind of setup.

Bootstrap

What is it?

Major benefits include an easier way to make your wiki mobile friendly, along with a large component library built into the system.

Example of Bootstrap in Action (Credit: TU_Dresden)

(in HTML without bootstrap):

<button id=”button1”> I’m a Button, push me</button>

Button image in HTML

(in HTML, with bootstrap):

<button id=”button1” class=”btn btn-primary btn-lg”> I’m a Button, push me </ button>

Button image with Bootstrap

Note how the aspect of the button changed only by adding 3 classes to the HTML element (bin, btn-primary, bin-lg). This is possible to do with EVERY SINGLE COMPONENT OF YOUR WIKI, as long as you go through the documentation of bootstrap and understand how to use its classes. This is super useful to make your content layout “responsive” and well organized.

The entire documentation of Bootstrap can be reached here: https://getbootstrap.com/

Using Bootstrap in your Wiki (Credit: TU_Dresden)

Currently, Bootstrap is on its 4th version. Earlier versions are very similar but not quite, so bear in mind if you use an earlier version the class names will slightly change from version 4.

You should note that the MediaWiki engine of the IGEM server implements a VERY old bootstrap version that renders all modern templates useless.

For the purpose of your Wiki, it is recommended you upload the newer version of bootstrap into your namespace as template files. Normally, this means to upload the bootstrap JS file and a CSS files that you will later import into your pages.

Have in mind that, as per IGEM guidelines, YOU CAN NOT IMPORT SOURCES FROM AN EXTERNAL SERVER, as usually done in many sites. You need to get the sources yourself and upload them as explained later in this guide.

Why is it difficult?

iGEM expressly states that all wiki content/code must be hosted on the iGEM server!!! Although Bootstrap has many ways to implement their code on a website, many of them link to external stylesheets on the Bootstrap website. iGEM states that this is a form of cheating. Even when all stylesheets are copied from Bootstrap and hosted on the iGEM server, there is a segment of JavaScript in one of the stylesheets that inhibits the menu bar from working, which is also against iGEM’s wiki rules. If you still have trouble with this, iGEM team ASIJ Tokyo brought this fix to our attention (http://2015.igem.org/Team:Stockholm/fixbootstrap.css? fbclid=IwAR1ZxdFtMx6XJPS8KJ6dpLoQ4hAsnlBNp2rP6R- w9dR_7e2LoGz4miFWAmc)

Screenshot of YouTube video; link below

Video tutorial here -https://www.youtube.com/watch? v=IK6JjS_LjQg&list=PLg5B0YEXzgEorRa8vuZPoHah2e1jmgVQ6&index=4&t= 0s

GitHub Code here - https://github.com/us-afrl-carrollhs

Helpful Hints

Look at past team’s wiki pages. Look at their code, you can even use pieces of it on your team’s wiki (just make sure to cite it).

Google is your best friend. Whether you are trying to find some example code or find a solution to your problem, Google will help.

Many teams suggest writing your code in external editors. Here’s what they use:

Contact Other Contributing Teams

Do you have specific questions about what teams wrote about? Either contact the US_AFRL_CarrollHS team (and we’ll either answer or redirect your questions for you) or, if a team has been cited on a section, find their information below.

  • TU_Dresden - We hope it serves a good purpose for all teams that require to use the latest technology into their websites. Kindly address ANY questions on this matter to tudigem2019@gmail.com