Create a free website using git and polymer
Brandon has over 12 years of professional experience developing software. He's also a designer & photographer with a degree in architecture.
Published:
Browse All Articles > Create a free website using git and polymer
In this article you will learn how to create a free basic website on Bitbucket, a git service provider. Polymer creates dynamic HTML components, which allow more flexibility than static HTML. This tutorial uses Ubuntu Linux but can also be done on Windows.
BEFORE WE BEGIN
HTML isn't dynamic enough to do much. Free hosting usually doesn't allow dynamic languages. In this article we will learn to use Polymer HTML plugins to create a free website with fewer limitations.
This tutorial assumes familiarity with git and a terminal. I am not an expert at Polymer and have only used it for one project. There are many things here which could be done better.
WHY POLYMER?
- Polymer can import partial HTML files. This is similar to PHP includes or javascript async pages.
- Polymer can use any common web server since it's plain HTML & javascript.
- Polymer can create custom HTML elements.
- Polymer can use HTML template tags.
- Polymer preemptively implements the future of HTML and web components in a way that old browsers can understand.
WHY BITBUCKET?
- Bitbucket has free private repositories whereas Github does not.
- Bitbucket hosted pages can use whatever HTML you want but Github uses Jekyll.
- IMO Bitbucket and Github are much easier to use than alternative git providers.
TOOLS NEEDED
These version numbers are whatever was current at the time I wrote the article. You probably do not need to use these specific versions.- https://github.com/creatio
nix/nvm (whatever the latest version is) - https://nodejs.org 4.3.2 (solely for developing, not for serving)
- https://bitbucket.org/
- http://bower.io 1.7.6
- https://www.polymer-projec
t.org version 1.0 - https://erikringsmuth.gith
ub.io/app- 2.6.1router/
WHAT ARE WEB COMPONENTS?
Web components are HTML elements which call an HTML template. These elements are often small, self-contained parts of a webpage. Some examples are headers, footers, articles, image sliders, advertisements, popups, paginated lists, etc.Example:
<website-header></website-header>
<!--
That is a custom HTML element which we can add to our pages.
It's just one simple tag! It represents the markup below...
-->
<dom-module id="website-header">
<template>
<header>
<img class="logo" src="../../public/images/logo.png" />
<nav>
<ul>
<li><a href="#">Page 1</a></li>
<li><a href="#">Page 2</a></li>
<li><a href="#">Page 3</a></li>
</ul>
</nav>
</header>
</template>
</dom-module>
<!--
FOR EXAMPLE,
-->
<html>
<body>
<website-header></website-header>
</body>
</html>
<!--
WOULD RENDER IN THE BROWSER AS:
-->
<html>
<body>
<header>
<img class="logo" src="../../public/images/logo.png" />
<nav>
<ul>
<li><a href="#">Page 1</a></li>
<li><a href="#">Page 2</a></li>
<li><a href="#">Page 3</a></li>
</ul>
</nav>
</header>
</body>
</html>
WHAT IS POLYMER?
Polymer is a Google created toolkit which makes development easier when working with web-components. It also helps older browsers implement web-components. There are competing toolkits such as X-TAG or Bosinic, but I find Polymer the easiest and best to work with.THINGS TO BE AWARE OF
1. Polymer does not have a good SEO solution yet. If you need search engine optimization on your website, you may want to use a different framework. Search engine bots are currently not great at understanding and crawling the javascript necessary to render a Polymer page.2. Polymer uses what is referred to as a "shadow DOM". A shadow DOM localizes most of one's changes (as opposed to effecting the entire webpage). This can be good but it can also add complexity. Either way, it's something one should be aware of when building a Polymer app. Scoping DOM elements is a popular technique with many javascript frameworks such as Angular.
OTHER THINGS TO KNOW
- Polymer doesn't care how you name or structure your files or folders. Best practices indicate that it's good to create a short project name prefix so that you know where the files originated.
- example: polymer01-header.html
- I suggest creating folders for the following:
- /public/ : This is where you store downloadable files like images, PDF, etc.
- /pages/ : This is where you store pages
- /components/ : This is where you store components
- When you are working locally and without a webserver (as we will for this tutorial), I recommend using fully relative file paths such as ../../components/polymer01
-header.ht ml, rather than /components/polymer01-head er.html. Otherwise your local filesystem may have trouble determining the root directory because you're not using a webserver. - In general when working on a project it's best practice to choose a prefix. This name will be used throughout the code. Keep it short because you will be repeating it a lot. For the purpose of this tutorial, we will be using the prefix "eeplmr01" (EE Polymer 01, where EE is short for Experts Exchange). Feel free to substitute your own prefix.
SETING UP THE TOOLS
Install curl
- In a terminal type sudo apt-get install curl
Install node version manager
- In a terminal type curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
- Close and reopen your terminal to start using nvm
Install nodejs
- In a terminal type nvm install stable
- That command will install whatever the latest stable version of nodejs is. For installing a specific version, you can enter that version number.
Install bower
- In a terminal type npm install -g bower
Install git
- In a terminal type sudo apt-get install git
Signup for Bitbucket
- Open a browser and navigate to https://bitbucket.org/account/signup/
- Note that whatever username you choose will be in your public URL
- Verify your email
- Create a new repository
- Name the repository mybitbucketusername.bitbuc
ket.org
- Name the repository mybitbucketusername.bitbuc
- Note that normally one would not work in the master branch of a repository. We're doing that here for speed of development in a new single-user repository.
Create a local development directory
Note that you don't have to use these directory locations, they can be anywhere.- In a terminal type cd /var/
- In a terminal type sudo mkdir /www/
- To take ownership of the directory, in a terminal type sudo chown -R mylinuxusername /var/www/
- Don't forget, this is case sensitive!
- In a terminal type mkdir /var/www/mybitbucketuserna
me.bitbuck et.org
Initialize git locally, add your remote repository, and specify your username
- In a terminal type cd /var/www/mybitbucketuserna
me.bitbuck et.org - To initialize git, in a terminal type git init .
- Don't forget to add the trailing period
- To add your remote repository to this directory, in a terminal type git remote add origin https://mybitbucketusername@bitbucket.org/mybitbucketusername/mybitbucketusername.bitbucket.org.git
- In a terminal type git config user.email "theemailaddressisignedupf
orbitbucke twith@doma in.tld" - In a terminal type git config user.name "mybitbucketusername"
Checkout Polymer
In order to build a website using polymer, we have to install some files into our project using bower.- In a terminal type bower init
- You will be prompted for info, but can skip by pressing enter until it is finished asking for info.
- In a terminal type bower install --save Polymer/polymer
Commit and push your content
At this point it is a good idea to commit your content. Think of a commit as saving your files, which one wants to do frequently.- To stage all of your local files into your local repository, in a terminal type git add -A .
- Don't forget the trailing period!
- To commit your local files to the local repository, in a terminal type git commit -m "Hello World" This will generate a commit message of "Hello World".
- To push your local commit to the remote repository, in a terminal type git push origin master
LET'S GET STARTED
From this point on, except for git commits, we will not need a terminal window anymore. For the rest of the tutorial I will just say "commit your changes" and you will repeat the three steps below.
To begin, you should make the following folders and files:
/pages/
/pages/eeplmr01/
/components/
/components/eeplmr01/
/public/
/public/images/
/styles/
/styles/eeplmr01/
index.html
style.css
CREATE THE INDEX PAGE
Think of the index page as a blank shell where everything will go. This contains the DOCTYPE, HTML tag, HEAD, BODY, and closing tags. Create a file named /index.html with the following code:<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
<title>Hello World</title>
<link rel="stylesheet" href="style.css">
<script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
<link rel="import" href="bower_components/app-router/app-router.html">
<link rel="import" href="components/eeplmr01/eeplmr01-components.html">
</head>
<body unresolved>
<eeplmr01-header></eeplmr01-header>
<div id="contentMain">
<main>
<eeplmr01-routes></eeplmr01-routes>
</main>
</div>
<eeplmr01-footer></eeplmr01-footer>
</body>
</html>
- The body's unresolved attribute means that the page will appear blank until the components are ready. This prevents unwanted flashes of unformatted content.
- There are a few items in the markup which mention Bower. Those files are installed by default when you initialize Bower and checkout Polymer. You still need to declare in your HTML file that you will be using those tools.
- There are several strange looking HTML elements we have not created yet. We will get to those soon. Those are what we refer to as components.
- Since the header, footer, and router are present on all pages, we're combining them into the link import file eeplmr01-components.html. More on that later.
- If you are unfamiliar with the meta viewport attributes, those tell a mobile device how to behave for responsive design purposes. Those aren't necessary but are highly recommended.
BUILD SOME COMPONENTS
CREATE THE HEADER
Most headers contain the navigation elements. Let's create a file named /components/eeplrm01/eeplm
<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="eeplmr01-header">
<template>
<style>
/*
THIS IS CSS RELATED TO THE HEADER COMPONENT.
POLYMER SCOPES ITS COMPONENTS.
*/
#headerMain {
color: green;
}
</style>
<div id="headerMain">
<header>
<nav>
<ul>
<li><a href="#!/">Home</a></li>
<li><a href="#!/about/">About</a></li>
<li><a href="#!/contact/">Contact</a></li>
</ul>
</nav>
</header>
</div>
</template>
<script>
Polymer({
is: "eeplmr01-header"
});
</script>
</dom-module>
- The link import at the top of the file tells Bower that this file contains Polymer functionality.
- The dom-module tag is how polymer defines components. Make sure this id matches the one in the script tag at the end of the dom-module.
- The template tag is a fairly new but common part of HTML. It is used for content which isn't immediately present in the DOM but might be fetched later by javascript. For more info, you may see this link. All that you need to know for this tutorial is that every component has a template tag.
- We are using hashbang URLs because we are serving this from Bitbucket which doesn't support pushstate.
CREATE THE FOOTER
This footer will just contain the copyright info and a contact link. You can put whatever you want in here of course. Create a file named /components/eeplmr01/eeplm<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="eeplmr01-footer">
<template>
<style>
/*
THIS IS CSS RELATED TO THE FOOTER COMPONENT.
*/
#footerMain {
color: blue;
}
</style>
<div id="footerMain">
<footer>
© 2016 <a href="mailto:emailaddress@domain.tld">Username</a>
</footer>
</div>
</template>
<script>
Polymer({
is: "eeplmr01-footer"
});
</script>
</dom-module>
CREATE THE COMPONENT LIST
As I mentioned earlier in the article, there is a list of components which are included on every page. Rather than add 3 link imports to every page, we shall combine them into one file. Using one file makes it less likely that we will create errors by: typo, forgetting includes, updating filenames, adding new components, removing old ones, etc.Create a file named /components/eeplmr01/eeplm
<!-- components/eeplmr01/index.html -->
<link rel="import" href="eeplmr01-routes.html">
<link rel="import" href="eeplmr01-header.html">
<link rel="import" href="eeplmr01-footer.html">
BUILD YOUR FIRST PAGE
You might be wondering why index.html isn't your first page. Index.html is the blank framework where we insert pages. Create a file named /pages/eeplmr01/eeplmr01-h
<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="eeplmr01-homepage">
<template>
<style>
/*
THIS IS CSS RELATED TO THE HOMEPAGE.
*/
</style>
<div class="homepage">
<p>This is the homepage!</p>
</div>
</template>
<script>
Polymer({
is: "eeplmr01-homepage"
});
</script>
</dom-module>
Note that this looks very similar to the components we have already built. The differences are mostly organizational. Pages are primarily used to to dictate what content and components are loaded. Think of pages as reference points for the router and components as reference points for the page.
BUILD YOUR SECOND PAGE
In order to test certain things like navigation elements or import files, we have to create a second page. For the purpose of this demo, let's create an "about" page. Create a file named /pages/eeplmr01/eeplmr01-a<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="eeplmr01-about">
<template>
<style>
/*
THIS IS CSS RELATED TO THE ABOUT PAGE.
*/
</style>
<div class="about">
<p>
This is the about page!
</p>
</div>
</template>
<script>
Polymer({
is: "eeplmr01-about"
});
</script>
</dom-module>
BUILD THE ROUTER
When using a javascript framework, you often have to implement what is called a "router". This tells your pages what happens when you navigate to certain URLs or click on certain links. There are many different routers out there which will work just fine. For this tutorial we will be using one named App Router.In order to add the router to your app, from your project directory in a terminal type bower install app-router --save
Now that you have App Router installed, create a file named /components/eeplmr01/eeplm
<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="eeplmr01-routes">
<template>
<app-router>
<app-route path="/" import="pages/eeplmr01/eeplmr01-homepage.html"></app-route>
<app-route path="/about/" import="pages/eeplmr01/eeplmr01-about.html"></app-route>
</app-router>
</template>
<script>
Polymer({
is: "eeplmr01-routes"
});
</script>
</dom-module>
- The app-route tags are elements which tell the App Router plugin what to do with designated URLs.
READY TO TEST
At this point you can load the page into your browser and it should work. Open a browser and navigate to file:///var/www/mybitbuckeREADY TO PUBLISH
Now that you know everything works, you can push your content to bitbucket. Commit and push your work using the methods outlined earlier in the article. Open up a browser window to http://mybitbucketusername.bitbucket.org/index.html. You should see your shiny new website!NOTES ABOUT CSS & JS
There are three different ways CSS & JS can be inserted into your website. Polymer scopes items appropriately.- You can add them everywhere by adding them to the index.html link calls in the header.
- You can add them on a per-page basis by adding a tag on whatever page you're working on.
- You can add them on a per-component basis by adding a tag on whatever component you're working on.
</template>
<script>
Polymer({
is: "eeplmr01-footer",
ready: function() {
// Do something on footer ready
// (That's like document ready, but just for the footer component)!
}
});
</script>
</dom-module>
FINAL THOUGHTS
If you've made it this far then you have a free website. From here you'll want to add more pages with more content and then add lots of CSS. Feel free to ask followup questions and I'll answer them the best I can. If you enjoyed this tutorial please share it and vote it as good content.
Brandon has over 12 years of professional experience developing software. He's also a designer & photographer with a degree in architecture.
Have a question about something in this article? You can receive help directly from the article author. Sign up for a free trial to get started.
Comments (0)