VillageHubertChen
commented
8 years ago Programming the Nav Bar System
- [ ] Move Writing from these Issues: #47 #42 #44 #47
Open VillageHubertChen opened 8 years ago
VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago GitHub Pages is hosted directly from your GitHub repository. Just edit, push and the changes are live. This makes the development and contribution very easy, as we are using the exact same GitHub tools to develop and publish all other V² projects. Hosting of Open Source Projects including their GitHub Pages on GitHub is free.
We worked with Bootstrap in the last year and were very happy with it. But time is moving on. uikit is using a more modern approach that helps us to make our layouts with less code in less time. Pages designed with uikit look modern. When properly designed they work well on any screen size.
Google Material Design is the latest layout framework that we added to our toolbox. So far we like it very much. It comes with good templates, good documentation on templates and design in general. And it is based on Angular as well. Eventually we will need to make a call to pick one of the two frameworks. For now we are using both
Jekyll is developed by GitHub in Ruby. It takes your authored pages, binds it with a template and generates a static html site complete with powerful navigation. You can author your pages in either Markdown or HTML or a mix of both.
We will use Markdown for most pages, since writing in Markdown is so much faster than writing in HTML. But for pages that require a more fancy layout we will begin in Markdown and at a certain point either convert it to HTML completely or inject HTML into passages that can not be expressed in Markdown.
The Authored pages are easy to read and fast to write, since most layout information is removed and placed into the template pages. This makes writing and editing very fast. Similarly useful are include directives for commonly used page parts, such as a navigation header or a footer.
Not to forget that Markdown is intuitive to read even for non developers, making it easy for anybody to contribute a page improvement using GitHub Pull Request.
You can edit your Jekyll Web Site on GitHub just using the GitHub Editor in your web browser. All you need to do is find the file to edit, open it, do your edit and commit the file. Committing the file will trigger the Jekyll compiler of your repository on the GitHub server. It will generate the updated version of your site automatically. Just view it in your browser to make sure the changes are as intended.
Of course you can work local. This provides all advantages that you are already used to when using Git. Pull your repository with a Git Client, such as SmartGit or GitHub Client. Next install Jekyll. Whenever you made changes to files that you want to check in a browser you need to invoke your Jekyll compiler, then view the generated pages in your browser. Once you are satisfied you commit your repository to GitHub. Be sure that you have set GitIgnore of your GitHub Repository to Jekyll. This makes sure that the files which are generated by your local Jekyll compiler are not uploaded to GitHub. The Jekyll compiler on the GitHub server will generate them again.
Even Microsoft uses microsoft.github.io and Twitter uses twitter.github.io. As such V-Squared.github.io follows the same pattern.
Significantly more efficient styling in SASS that compiles into CSS. This is made possible by SASS introducing programming concepts such as procedures and variables to CSS. Jekyll uses SASS.
Liquid is a powerful and efficient language for templates. It allows to code templates that are good looking, are fully responsive and offer powerful navigation. V²Site will be hosted in a mashup of three hosting providers: GitHub, Shopify and a generic one. The first two have Liquid build in, the third one can easily be upgraded to it. This way all parts of the website can use the same template.
We will author most pages in Markdown. This workflow will allow that they will stay in Markdown forever. That means even after the page is published in HTML we can make subsequent changes to the original Markdown file and compile it into an updated HTML page to be published.
All other workflows either do not support Markdown at all, or they start in Markdown and at some point require conversion to HTML with all subsequent edits to be done in HTML.
This is a big deal. We are publishing standards and tutorials. Most of our pages will be of interests for at least 5 years. But they will not be static. Instead they will undergo frequent changes. They will not be big changes, but minor improvements, fixes and updates. Being able to do this in Markdown instead of HTML makes this much faster and convenient!
Note: Markdown has dialects. GitHub Issues use the dialect GitHub Flavored Markdown versus Jekyll uses Kramdown. Usually developing an Article in GitHub Issues and then copy pasting it into a Jekyll page works fine, but occasionally you have the odd glitch that you need to fix. Kramdown ads a few much needed features, such as injecting CSS Styles or add reasonable footnotes.
Now this could not be easier. The hosted pages are in the GitHub repository gh-pages. As with any repository, it can be branched or forked. The contributor can develop and test locally. When he is satisfied with his changes he makes a pull request, that we will test and when quality is satisfactory we will merge it. Just like with any other project on GitHub.
Who uses GitHub takes this for granted. Anybody can contribute changes. But as a user of standards of a Standard Organization this is kind of a new thing: Anybody can easily and efficiently contribute changes with the GitHub Fork → Improve → Pull Request Workflow. And because it is so efficient, we will get back to every Pull Request!
After implementing the new feature / fixing the bug we need to test it before publishing the new version. This is done through Cloud9 IDE. Workflow:
There are powerful editors available, such as StackEdit and Classeur. They allow you to write in the left pane in Markdown and to see the final Page Layout including formatted Tables and Images in the right pane. Cloud9 IDE has such Markdown Previewer built in.
V²Site is made up of static HTML. It can not be much simpler and as such it is very robust. This allows us to spend most time on content development and little to no time on things like updating the SQL data base or updating plugins and subsequently resolving conflicts of plugins.
We also do not need to set up three servers: Development + Integration + Production Server and write a complex handbook on workflow and maintenance.
This is the purpose and strengths of Jekyll. As Author you will write directives, such as which template to use directly into the file together with content and formatting in Markdown. Jekyll will add the formatting drawn from the mentioned template, add the includes and convert it all to nice HTML, linked to the proper css style sheet.
Jekyll is supposed to take care of things like navigation toolbar and footer. We will see how this will work out in real life. But it is from GitHub and as such we expect it to work.
Since the whole site is in a GitHub repository it comes with the very powerful Version Management of Git / GitHub. We use it for all other projects, so nothing new to learn!
Convenient! Less to learn!
When clicking on an entry to the table of contents the article soft-scrolls to the corresponding position. Additionally the URL-Bar in the browser is updated to add a hashtag accordingly. This way the reader can share by sending this URL not only the Article, but also this reading position. → #112
This means all functions are available and actually still fun to use when browsing our site on a small device, such as Mobile and Tablet. To make this happen we need two things:
Responsive web site design accommodates the smaller physical screen sizes of mobile and tablets. This is far more complex than merely scaling down the size of the page and goes beyond the scope of this article. Suffice to say we hand coded the template for our web site using the latest libraries to provide a pleasant user experience on small devices.
A website that has instant response on a desktop could have a lag of several seconds on a mobile device. This is unacceptable to the users. Once we finish coding a new feature we test it on mobile devices and in case it is too slow we optimize the code until the UI feels fast enough to the user.
There are two key reasons: One: Our core development team is located in China, as such we need to be able to access the website that we develop. _Two: _ In Campaign 4 we will work with OEMs, that many of are located in China.
In China two critical parts of the western internet are not available: Social Media: Our marketing relies heavily on web sites such as YouTube, Twitter, Facebook, etc. We need to code the site that it a) still loads fast if these sites are not accessible b) offer an alternative to get the same information.
Nowadays websites load the script librarys from CDNs, which are also not available in China. We need to add code to load the libraries from alternative places. → #101
We tried to develop content on our Joomla site. The process was so complicated that the logistics of Joomla was distracting from creating content. This workflow promises to be so simple that the focus is on creating content.
It is not clear if we will keep the CMS for www.villagetronic.com. Whatever we do, it is expected this new site development and publishing workflow can be used. Either as a replacement or as content development workflow to generate the HTML pages to be published in Joomla.
We are currently testing Shopify. It appears that its monthly fee of $9 or $29 is well worth for us the added features and the reduced maintenance work. So far we prefer it over the Joomla Shop Plugin that we used before.
So far we are using osTicket. We are very happy with it. It is a php + MySQL app that can be easily installed on many hoster with even the lowest cost hosting packaged.
Before we used Kunena on Joomla and were very happy with it. Our research shows that there is a variety of Forum apps that are php + MySQL that are even more powerful than Kunena and can be easily installed on many hoster with even the lowest cost hosting packaged.
So we would end up with minimum three hosting services for our final site:
| Item | Cost |
|---|---|
| Hosting on GitHub | $0 |
| IDE and Tools | $0 |
| Templates & Plugins | $0 |
| Shop Shopify | $9 or $29 / month |
| Standard Hoster | $1 / month |
Out of the box Jekyll and Angular are not compatible. But they can be made to work together easily enough. All our web apps are written in Angular.
Good Navigation on a website with lots of content is very important. V²Site is build with our V²GitHub Template that offers 5 Level Navigation, that remains fast and usable on mobile devices. Table of contents are fast to access and offer deep linking.
VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago This Article was extracted from Article►Introduction to V²Plan System #54, as we now take a different, more simple solution for this kind of page. However, the general approach is still valid. I am storing this Article for later reference. When used, this Article need to be adapted for the specifics of the new page.
Each Article is listed as a Card with the following content:
We need a specific page layout which Kramdown can not deliver. By custom designing this page in HTML with Angular Material Styling we can create a significantly improved user experience.
The Introduction Page in HTML is great to read for the reader, but horrible for the author. This is why all our other pages are written in Kramdown rather than HTML. To make this happen we need to develop a → Jekyll Template for Introduction Page.
Material Design is a visual language complete with theoretical white paper, template, examples, tutorials and training materials. Only announced in summer 2014 it was widely successful and in 2015 most Android Apps already use it. We chose Material Design because it delivers a consistent experience for our V² Site visitor on all of his devices.
All of V² Site's Web Apps are written in Angular. Angular Material is the UI framework implementation of Google Material Design in Angular. Angular Material is well documented, robust and easy to use in development. It also integrates well with Liquid and Jekyll, which are the Template Language and Web Site Compiler that we use to generate V² Site.
We needed a specific page layout which Kramdown could not deliver. Thus we used HTML with custom styling. Now the Introduction Page in HTML is great to read for the reader, but horrible for the author. This is why all our other pages are written in Kramdown rather than HTML.
This is exactly the job of a Liquid page template for Jekyll.
Simply put, it will make Kramdown Source that looks like this:
??? convert the pseudo code below to Kramdown code???
look like that:
??? copy the HTML code from the by then complete HTML Intro Page???
Our V²Site web site is compiled with Jekyll. It uses the Liquid Templating Language. As such we need to develop
Current Front Matter uses the template layout: "page"
---
layout: page
menu: System
title: V² Plan System
---Same Front Matter, but with template layout: "intro"
---
layout: intro
menu: System
title: V² Plan System
---One of the principle objectives of V² Site is to allow anybody to edit any page content with ease! Page source code in complex HTML is counter productive to this goal. Instead Kramdown delivers the easy editing experience we want to deliver to our users!
Because at this time we have learned to create a Jekyll Template for Introduction Page.
VillageHubertChen
commented
8 years ago 
LukasChen
commented
8 years ago VillageHubertChen
commented
8 years ago VillageHubertChen
commented
8 years ago When developing the content for a board we first develop its page structure with a text based tree diagram. This can be done with any text editor when set to mono spaced font, such as Courier. Below is a snapshot of the tree as developed in → Page Structure for V²►Plan #78 .
The three vertical lines represent the three levels of the Book Shelf Metaphor Navigation:
This is the same Page Structure implemented as Navigation System. The top horizontal bar is the top navigation layer (which we call Board-Bar). It is the equivalent to the left most vertical line in previous tree diagram. The next horizontal menu bar is what we call the Book-Bar. It matches with the middle line in previous diagram. Each Book contains one ore many Articles. In this snap shot the Book "System" is selected. You can see its Articles in the Article-Bar which is left to the image
This is the same window, only reduced in width. At the reduced width the menus do not fit any longer and are collapsed to Off Canvas Menu Icons, represented by three horizontal bars. Beside the Icons we spell out which Navigation Level they represent. So in case you ever forgot where the Board Bar and Book-Bar go, simply reduce the screen width.
VillageHubertChen
commented
8 years ago @bcaswelch Please review above documentation and let me know if clear
Workflow
Linked List of Articles about V²Site