<

Create a free website using git and polymer

Published on
4,061 Points
861 Views
2 Endorsements
Last Modified:
Brandon Lyon
Brandon has over 12 years of professional experience developing software. He's also a designer & photographer with a degree in architecture.
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.

 

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>

Open in new window

image.gifimage.gif

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.html, rather than /components/polymer01-header.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


  1. In a terminal type sudo apt-get install curl
 

Install node version manager


  1. In a terminal type curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
  2. Close and reopen your terminal to start using nvm
 

Install nodejs 


  1. In a terminal type nvm install stable
  2. 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


  1. In a terminal type npm install -g bower
 

Install git


  1. In a terminal type sudo apt-get install git
 

Signup for Bitbucket


  1. Open a browser and navigate to https://bitbucket.org/account/signup/
    • Note that whatever username you choose will be in your public URL
  2. Verify your email
  3. Create a new repository
    • Name the repository mybitbucketusername.bitbucket.org
  4. 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.

  1. In a terminal type cd /var/
  2. In a terminal type sudo mkdir /www/
  3. To take ownership of the directory, in a terminal type sudo chown -R mylinuxusername /var/www/
    • Don't forget, this is case sensitive!
  4. In a terminal type mkdir /var/www/mybitbucketusername.bitbucket.org
 

Initialize git locally, add your remote repository, and specify your username


  1. In a terminal type cd /var/www/mybitbucketusername.bitbucket.org
  2. To initialize git, in a terminal type git init .
    • Don't forget to add the trailing period
  3. 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​​
  4. In a terminal type git config user.email "theemailaddressisignedupforbitbucketwith@domain.tld"
  5. 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.

  1. 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.
  2. 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.
 
  1. To stage all of your local files into your local repository, in a terminal type git add -A .

    • Don't forget the trailing period!
  2. 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".
  3. 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

Open in new window

image.gifimage.gif

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>

Open in new window

image.gifimage.gif
  • 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/eeplmr01-header.html with the following code:
 
<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>

Open in new window

image.gifimage.gif
  • 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/eeplmr01-footer.html and place the following code inside it. The structure should be very similar to the header.
 
<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>
        &copy; 2016 <a href="mailto:emailaddress@domain.tld">Username</a>
      </footer>
    </div>
  </template>
  <script>
    Polymer({
      is: "eeplmr01-footer"
    });
  </script>
</dom-module>

Open in new window

image.gifimage.gif

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/eeplmr01-components.html with the following code:
 
<!-- 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">

Open in new window

image.gifimage.gif


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-homepage.html with the following code:
 
<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>

Open in new window

image.gifimage.gifNote 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-about.html with the following code:
 
<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>

Open in new window

image.gifimage.gif

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/eeplmr01-routes.html with the following code:
 
<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>

Open in new window


image.gifimage.gif
  • 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/mybitbucketusername.bitbucket.org/index.html
 

READY 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.
If you want to implement custom javascript on a component, you can do it in the polymer function at the bottom of a component. Here is an example:
 
</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>

Open in new window

 

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.
2
Comment
0 Comments

Featured Post

Free Tool: Subnet Calculator

The subnet calculator helps you design networks by taking an IP address and network mask and returning information such as network, broadcast address, and host range.

One of a set of tools we're offering as a way of saying thank you for being a part of the community.

Join & Write a Comment

The viewer will get a basic understanding of what section 508 compliance can entail, learn about skip navigation links, alt text, transcripts, and font size controls.
How to create a branch, fetch changes, and merge them into another branch using the EGit plugin for Eclipse.

Keep in touch with Experts Exchange

Tech news and trends delivered to your inbox every month