While I was working through the Ruby course, I could not help question why they had started The Flatiron School in Ruby. I always had this idea that it was most beneficial to learn Javascript first then move to other widely used programming languages.
As the graphic above states, based on jobs needed and languages required, Ruby should be fairly low on the totem pole in terms of necessity to learn. Even at my last job none of the other developers knew Ruby….
So why does this course involve such an in-depth dive into Ruby?
The answer that I came up with is; beats me. So I did what any rational person did and jumped ahead and checked out the javascript courses. What I found was that there is not a huge difference between different OO programming language. Sure there is always semantics that makes a language unique. But for the most part, I can understand what most Javascript methods are doing without knowing a whole lot about Javascript. Once you know a programming language, most of what you know can be transferred to another. Then you just need to understand the semantics of the new language and how it operates, and you can pick it up fairly quickly.
I remember talking to my friend Wyatt. He was just hired on as lead project architect building software for a company with Ruby. I asked him how he was with Ruby and he said he had never used it…. But he said that he took a look at it and it java mixed with a few others and should be able to pick it up within a month. This is the conclusion I came to as well. Knowing your first programming language is the hardest part of becoming a programmer. Once you have mastered one, the others can come to you rather quickly.
Once I understood this, I was a little more content with the courses.
Iteration and Abstractions:
So there are four types of loops:
Loops
Times
While
Until
Looping occurs when you tell your program to do something a certain number of times.
Iterations occur when you have a collection of data (array), and you operate on each member of that collection.
“You don’t use three to four lines to express iterations, you use on word.” – Kent Beck
“Being abstract is something profoundly different than being vague… the purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise.” – Edsger Dijkstra
An iteration is a word referred to each step or each execution of a block. It is the singular execution of a sequence of code (we call a block) within a loop. Each yields elements one at a time to every iteration of the block.
The each method takes each element of the brother array one at a time and passes or yields it into the block between the do/end keywords. Each yield each item of the collection on which it is called to the block with which it is called. Each doesn’t need a separate counter variable and manual incrementation of that variable to know how many times to do something instead they use the number of items in a collection. The each method will always return the collection on which it was called as well.
So if you would like to iterate over an array and change some things, you will need to then pass that newly formed data into a new array.
Using loops and iterations are like the meat of Ruby. I feel like every lesson I have completed for the past week has been iteration after iteration. Once you dive into the code yourself, you will understand just how important these are to master and to be very familiar with.
Building a product from scratch isn’t easy, but it can be a very rewarding process. When I had the idea for Revue, I decided to act on it immediately. Two years later, and with 20,000 users and 2 million emails per month, I can safely say that building on impulse was one of the best choices I’ve ever made. I started quickly and made a lot of stuff up along the way, but I learned many lessons which I will reflect on in this article.
In fact, I was inspired to share my lessons after appearing on The App Guy Podcast; a show hosted by my good friend Paul Kemp, a tech entrepreneur himself. We spoke about my journey with Revue and both agreed to co-author this article to unravel the design secrets I learned on my journey with Revue. So, here we go…
1. Just launch
The design might not be perfect. Sometimes, it can never be perfect. Perfectionism is often the enemy in this case. Don’t get me wrong, aiming to create something beautiful and functional is the ultimate top priority. However, for perfectionists, the day of launching might never come. I’ve seen startups fail because they put too much effort into perfecting something that doesn’t need to be perfect in the first place.
I’ve seen startups fail because they put too much effort into perfecting something that doesn’t need to be perfect
You’ll have plenty of time to improve and make your product better later on. People can always find something that’s wrong with your product, so wasting time on perfecting it is useless. Functionality and a good idea can take you a long way in the beginning. That’s how you can see if there’s a market for your product and if people are actually interested in it.
2. A listening ear can go a long way
If you’ve successfully launched, I can tell you that this lesson is probably the most essential thing to get right. Listening to the people on Revue has been something that helped my product get kickstarted. One of the main ways we reached 20,000 users is by listening to the valuable feedback we received from curators. Our mission was to try and make their user journey as useful and pleasant as possible. In fact, you should definitely take feedback into account; especially if you are going deeper into designing your own product and executing features that your clients have frequently requested. Make listening to your users’ feedback a top priority every day.
Nevertheless, don’t attempt to satisfy every single request you get. Pick your updates, changes and improvements wisely based on all the feedback you get. This means, at the very least, you need to be listening to every single request you get. Then, make your own mind up on what to do with this feedback.
getting feedback from users is crucial to the design process
We even maintain a spreadsheet where we list all the features that people have asked for over time. Recently, we even opened up our feature roadmap for 2017 and invited users to join in and vote on what they want to see next. It helps us listen to what their pains are and what they think are the features most essential with regard to future updates. In summary, getting feedback from users is crucial to the design process. Who better to help you out in the making of your product than the people who actively use it and know your product’s strengths and weaknesses?
3. Be aware of what is happening in your industry
In the email world, things are complicated. We have to take this into account when designing for email. For example, it’s very different to design for email than it is to design for the web. Also, email has often been overlooked by many developers over the years. The truth is, email is not going away anytime soon. It’s simply changing and evolving over time. I believe the same is happening to many other industries around the world.
More specifically, we’ve identified that newsletters have really changed over the years. There’s an obvious shift in the way people are digesting their curated content. Early on, we wanted to reflect these industry changes in our product by taking on more of a editorial (magazine-like) look for the newsletters. This is why we designed and launched themes for Revue and it has been a solid step towards progress. Staying current and on top of industry trends is an absolute must in the design process.
4. Don’t be afraid to kill things
Sometimes you spend countless hours building a feature or working on a project that you think will be extremely beneficial for your product and your users. And sometimes, this turns out to not be true at all. The thing is, every now and then, a time comes where you just have to kill things off. I’ve seen a lot of entrepreneurs struggling to know when to end a product (including myself). It’s great to have ideas and execute on them straight away, but it might take too much of your time and not be worth it at the end of the day.
This doesn’t mean disregarding your instincts and plans, but rather knowing where to direct your attention going forward. I often ask myself the simple question “why?” at least three times throughout the project. If every time the answer is the same, and it makes me confident that this is indeed worth it, I continue with the project. If the answer is a lacklustre no, I just kill the project completely and take my losses.
5. Look at your data
This one is a ‘no-brainer’. Gleaning knowledge your data is essential nowadays, more so than ever before! A while back, we were wondering how to improve our onboarding process. For example, when people signed up, we would encourage them to start using the product immediately. So, we looked at our data and made some decisions to improve the onboarding. The results were astonishing. We made only small product changes, yet activations skyrocketed! Hence, my biggest lesson learned from this result is to regularly look at your data and note when something has to be done.
6. Don’t follow the herd
Revue started off as a side-project and it aimed to make newsletters personal again. It does this by stimulating people’s expression of thought, and opinions. As it happened, I didn’t want to follow the herd. For example, the world did not need another Mailchimp. Nevertheless, this wasn’t always obvious, and along the way I had many opportunities to recreate features you get on Mailchimp.
the right people will find you, and that’s what counts
In an age where everything is about automated copy, 140 character Twitter limitations, SEO and so on, being personal with your readers is just so difficult. This is why my team and I set out to reinvent the newsletter. If you follow your bliss with your product, not everyone will understand where you are going. Nevertheless, the right people will find you, and that’s what counts.
7. Success is the sum of details
Attention to detail can really set you apart from everyone else. I spend a lot of time thinking how to make certain UI elements better. In fact, I’ve done this throughout the entire building process. Actually, just launching your product or service is a tremendously powerful step (as I’ve already mentioned above). However, before you launch, you should take into account an important aspect. Don’t overlook the details. Details are very important to achieve success. I’d say to myself: “if I just go that extra mile, it’ll make the world of difference”.
Now, I regularly get positive feedback from users who are really impressed with Revue’s WYSIWYG editor and how easy it is to use. Going the extra mile may cost you some time, but it can create miracles for your business.
8. Functionality trumps attractiveness
Focusing on making your product work well is more important than the overall beauty and design. Making your product functional and efficient is essential because your customers prefer it. For example, customers won’t use something that is pretty if it doesn’t actually work. Of course, the aesthetics are crucial, but functionality trumps attractiveness every time. When it comes to the design, you can always focus initially on making something simple by sticking to the basics. Improving the look of a product can be done later.
9. Try out new things
Recently, we introduced a new theme, which was one of the most requested features from our users. This meant we really had to step up to the plate and deliver something beautiful. Unfortunately, the development of HTML for email is quite slow, so designing requires a slightly different skill set. Yet, innovation is what we aim for whether it has to do with newsletters or design. This is why I decided to take MJML for a spin when it came to the implementation process. As it happens, the results were remarkable. In addition, it really made the whole process much easier. So, don’t be afraid to poke around unexplored territories.
don’t be afraid to poke around unexplored territories
10. Learn from your mistakes
This will sound like a very basic cliche. Yet, it’s a cliche for a reason. In design, you will undoubtedly make mistakes. However, you also have the power to fix these mistakes—quickly and efficiently. It might happen that you design and build a feature that is not particularly useful or doesn’t bring as much value to people as you first thought. It’s not a big deal! Just look at what you did wrong and try again. Finally, I believe learning to get the most out of your mishaps is a mindset that can really help designers move forward with regard to creating and building things.
As JavaScript developers, we often forget that not everyone has the same knowledge as us. It’s called the curse of knowledge: When we’re an expert on something, we cannot remember how confused we felt as newbies. We overestimate what people will find easy.
Therefore, we think that requiring a bunch of JavaScript to initialize or configure the libraries we write is OK. Meanwhile, some of our users struggle to use them, frantically copying and pasting examples from the documentation, tweaking them at random until they work.
When it comes to staying competitive on the market in terms of business, a lot of firms have devised plans and strategies to make sure they stay atop of their game. There are some important advantages to be use such as promotion a business by owning a website which makes sure that every customer is
WP-VR-View is a WordPress plugin that allows you to embed 360-degree videos, and photospheres into your site. Once done, you can show your visitors VR elements on desktop as well as on mobile devices. Google’s Cardboard is also supported.
WP-VR-View is Based on the Google Library VR View
WP-VR-View by Alexander Tumanov, a developer from Bishkek in the Kirghizian Republic, is an add-on for the Google library VR View. Thus you can be sure that all sources from the library specification will work as well in WP-VR-View.
Alexander provides a short video that shows all application cases, as well as the respective procedures:
The integration of photospheres or 360-degree videos is done via shortcode. The plugin takes care of the rest. If you don’t want to, or can’t remember the shortcodes, just use the respective buttons in the visual editor TinyMCE.
Buttons in TinyMCE. (Screenshot: Alexander Tumanov)
Clicking one of the two buttons opens a dialogue window that lets you define some basic settings. All that is required is the URL to the VR content. Keep in mind that content that already exists in your media library can not be added as usual. Instead, you have to copy the content URL from your media library and paste it into the options dialog.
Options Dialog for the Integration of VR Elements. (Screenshot: Alexander Tumanov)
WP-VR-View: Controls Via Mouse and Gestures
On the desktop, the content is controlled via mouse. At the bottom right of each element, you’ll find a plus icon that allows you to switch to full-screen mode. To the left, there’s an icon to change to Cardboard mode. This splits the video into two windows, one meant for the left, and one for the right eye, respectively.
Example Content With Control Symbols on the Bottom Right
In Cardboard mode, and generally, when viewing via smartphone, you’re moving within the virtual realities by moving the smartphone itself. Moving the smartphone to the right will make the field of view move accordingly. Aside from the reaction lag, which depends on the performance of the viewer device, this creates the impression of actually looking into a different direction.
WP-VR-View is Available Via WordPress and Github
If you already want to experiment with VR in WordPress, WP-VR-View is the means of choice. The plugin is distributed under GPL as open source. In the WordPress plugin index, the older version 1.6 is provided, while on Github, you’ll already find the recent version 2.1, which Alexander completed only two weeks ago.
If you want it to be as simple as possible, install the plugin from the backend via install plugins. Here, type the term wp-vr-view into the search bar, and click enter. In the following search result, click the first plugin in the top left. You’ll see that there are other plugins that also use Google’s library to some extent. However, none of them get close to the number of installations that WP-VR-View has gained already. After you’ve installed, and activated the plugin in version 1.6, simply wait for the update notification to version 2.1.
The majority of the content that website visitors come across on the web is written content, copy or text that either informs or sells something. Other parts of content include images, videos and graphics. How web designers arrange all of this content has a massive impact on how visitors read and retain all of this information.
Formatting is yet another consideration that should be front and center in the minds of designers. Through the technique know as chunking, you’ll succeed in arranging the content to encourage easier reading in your visitors and, therefore, a better user experience.
When you consider how the average person “reads” on the web (hint: it’s not really reading at all) you’ll see exactly why chunking is vital to organizing web content.
How exactly do people read on the web?
If you think that people read most or even half of the written content on the web, you’re giving them too much credit. Study after study that’s looked at web-reading habits concludes that people simply don’t take the time to properly read every single word, paragraph or page on the web.
Instead, they’re fond of skimming or scanning your content.
A classic study on this subject is the Nielsen Norman Groups F-shaped pattern study from more than a decade ago, which established that users don’t read word-for-word and just scan copy. A much more recent study from 2013 looking at this phenomenon concluded the same thing, namely that users don’t read word-for-word, don’t finish reading the entire article, and stop reading about halfway through.
Looking at these landmark studies, what can we conclude, then?
A lot of your content doesn’t get read—whether that’s ad or business copy or information in a news article—and most people will, at best, just skim or scan your written text.
So what are designers to do, faced with this seeming dilemma?
They have to faithfully start chunking their content. Here’s how:
Using smaller and shorter paragraphs
When you’re arranging content on your client’s webpages, be sure to go with smaller and shorter paragraphs. Both of the studies above specifically found that your visitors won’t be reading word-for-word and instead love to skim and scan.
Content that’s formatted into thicker and longer paragraphs isn’t conducive to easy eye scanning and skimming. When paragraphs are longer, readers will be discouraged from staying on the page and have the tendency to bounce. This ties into how they naturally read on the web, which is by scanning and skimming.
When readers scan and skim, they’re trying to pull out bits of information from content that can help them decide if they want to continue reading on. Longer paragraphs don’t let them do this, but shorter paragraphs—which readers can more quickly scan through—allow them to get a better sense of what the content on the whole page will be like.
For an example of a site with shorter paragraphs, we look to National Geographic. Its articles rarely contain paragraphs with more than three sentences. It’s skimming perfection.
Using bullet points
The beauty of bullet points is that they draw the eye to pithy pieces of info that are easy to read and retain. Because they’re presented in short and consecutive fashion, they’re ideal in supporting how your visitors read content.
It’s all about the brevity. Since people already don’t read thoroughly on the web, you need to present them with content whose big takeaways they can understand in a matter of moments. Bullet points fulfill this to a tee.
It also should be stressed that bullet points shouldn’t be long, as in you shouldn’t include long sentences or pieces of info for each bullet point, as that defeats its purpose of brevity. The shorter the bullet point, the better for reading.
One of the best places to observe bullet points used successfully is usually on ecommerce sites like Flipkart. On this page for the Samsung Galaxy J5-6, note the use of bullet points to quickly communicate the phone’s features.
Using headlines and subheadings
These are excellent for breaking up content into more easily readable and digestible sections. In addition, headlines and subheadings also work as short “previews” of the next section of content, thereby enabling readers to immediately understand what the upcoming section will talk about and decide on whether or not to keep reading.
Studies have shown as well that many web readers are headline-readers, for the most part. This complements the above studies exposing that people are, for the most part, just skimmers and scanners on the web.
The Washington Post reports that approximately 60% of Americans just read the headlines on the web, whether they’re reading on desktop or mobile.
This ties in perfectly to the short-attention span behavior of your visitors, leads, readers and customers. When many just read the headlines, it’s your job as a designer to ensure that your content’s headline clearly spells out what readers can expect—otherwise, they may decide not to delve into your content deeper to read more.
An example of a site that lives and dies by the headline is Listverse, the listicle compiler of all things strange, shocking and sensational. In its article on strangeness at Disneyland, note how the site uses a crystal-clear headline that explicitly previews what the content will be about. When one scrolls down, note how each subheading also makes it very clear what each section will cover, therefore making reading and retaining this info a breeze.
Help UX by always chunking your content
The key to showing your visitors better content is presenting them said content in the way that they already naturally absorb it. That means chunking. Since your content is going to face an uphill battle on the web to be read anyway, not chunking your content virtually assures that very few people will read it.
This means fewer leads, conversions and customers, as someone not reading your sales copy to the end can mean a lost sale, or another visitor refusing to read your blog post thoroughly can mean lost signups and lead captures. In short, not chunking your content on the web leads to bad outcomes.
Chunking encourages people to read content on the web how they’re already naturally inclined to read it, which is by skimming and scanning. Don’t fight it! Don’t bunch your content together in longer paragraphs, expecting the quality of your content to persuade people to read word-for-word.
The truth of the matter is that people just don’t spend that much time reading content on the web. And your job as a designer is to take this short attention span and get them to read and retain as much of it as possible. You’ll do that only by chunking.
The virtual realm is uncharted territory for many designers. In the last few years, we’ve witnessed an explosion in virtual reality (VR) hardware and applications. VR experiences range from the mundane to the wondrous, their complexity and utility varying greatly.
Taking your first steps into VR as a UX or UI designer can be daunting. We know because we’ve been there. But fear not! In this article, we’ll share a process for designing VR apps that we hope you’ll use to start designing for VR yourself. You don’t need to be an expert in VR; you just need to be willing to apply your skills to a new domain. Ultimately, as a community working together, we can accelerate VR to reach its full potential faster.
WordPress is used to power an estimated 27.4 percent of all websites, and templates in general are popular across all sites. In other words, the search for templates and themes that are compatible with WordPress is very prevalent among professional and hobbyist designers. In the past, this led to a long and boring list of template options that could only be tweaked in minor ways.
Although this was a huge success story at first as it allowed people to break away from doing their own HTML coding, the reality is that the look and feel of many of these templates is no longer up to par. Fortunately, Themify offers a new way of looking at the popular website building option. Instead of being stuck with the exact layout of the theme you choose, you now have an unprecedented level of control.
Themify Ultra Takes Things to a New Level
Themify Ultra is by far the most powerful WordPress creation that the Themify team has developed. Designers of all skill levels will enjoy the vast selection of choices that transform the basic theme into a professional looking and fully responsive website. This theme is alterable through the easy to use drag and drop builder.
Have you ever found a template you adored but wanted to tweak the header, background or footer? Perhaps you’ve also encountered issues getting the layout to cooperate for single posts and archives. With Themify Ultra, you’ll gain access to a robust list of customizable layout choices that will enable you to truly make the resulting website unique.
Header/Page Styles
First up is the impressive list of header/page styles. Your theme can be altered to feature any of 15 styles that range from the Header Magazine look to a Header that slides out from the left or right-hand side of the page. You can also choose no header at all, which is ideal for any landing pages that you are planning to build.
Header Background Options
Next, there are six header background options to improve upon the header you select. Again, you can choose between a nice array of looks such as an image, a slider or animating colors. You can even upload a video, which is a nice feature that is a lot of fun to work with.
Footer Layouts
It would be odd to have so many customizations available for the header without also giving some love to the footer. Themify provides six footer styles, and each style can be further altered with widgets, a menu, credit text and visibility toggling.
Single Post Layouts
Themify Ultra comes with a default single post layout, but it doesn’t end there. Users have four more layouts to choose from, including gallery style and split.
Archive Layouts
An archive is something that most website template designers have given little to no thought to. This is evidenced by the complete lack of a designated archive layout that is found within most website builders. Themify has again stepped up to provide users with yet another useful way to set their site apart from the competition. Choose from six archive layouts that can each be further customized through visibility toggling of several components.
Introducing: Section Scrolling
One of Themify’s newest features is also among the most exciting! Section scrolling has been designed to allow website visitors to scroll one row at a time through your entire page design. This mimics the concept of a presentation slideshow and can be extremely useful for a wide variety of online businesses. Unsurprisingly, Themify took this beyond the basics by offering six ways to configure section scrolling so that it fits in the best with the rest of your layout.
Pre-Designed Layouts Offer Simplicity
All of the cool stuff that Themify can do is only going to be as useful as your level of skill and patience. For example, if you don’t want to make a bunch of decisions about the layout of your site, you’re probably not going to spend a lot of time tweaking things such as your footer and header. However, website owners who still want to end up with the best possible appearance can select from more than 60 pre-designed layouts.
Much like every other pre-designed template that is offered by website builders, you’ll be able to look through your options, pick your favorite and plug your own words and images into the provided boxes. Unlike most pre-designed layouts, Themify has impressive parallax landing pages available for their layouts. This helps ensure an end result that doesn’t look like it was quickly put together with an existing layout. Instead, users get professional quality results without needing to hire a website designer.
Of course, even if you are working with a professional, Themify is a great way to get a look and feel you truly like. If this is what you’re planning to do, though, it makes the most sense to give the website designer access to Themify Ultra so that they can tweak your site more extensively.
Free Bonus Builder Addons
The Ultra theme becomes an even better bang for your buck when you take advantage of the builder add-ons. With a simple click, you can access and add elements to your website that include a pricing table, a contact form, a map, a progress bar and a timeline. Themify values this add-on pack at $100, but they toss it in free of charge with Ultra.
Image Filters
We’re living in an Instagram world, which means that images need to be hip in order to capture attention. Themify removes the need to purchase expensive editing software such as Photoshop by offering built-in filters. There’s also a portfolio feature and you can utilize website alterations such as overlays, animated colors and gradient colors to make your site truly pop!
What We Love
Now that we’ve provided a breakdown of some of Themify’s best features, it’s time to look at what really works for us. We absolutely love all of the layout customizations that come with Themify Ultra. The pre-designed layouts, add-ons and image features are also a nice touch, as is the easy to work with WooCommerce Shop.
What We Don’t Love
There’s nothing about Themify that we actively dislike, but it would be nice if the image customizations offered more filter choices. Additionally, the long list of custom options that can be used with Ultra is almost too long! People who are indecisive by nature may take a while to make their final selections as a result.
Final Thoughts
Themify is one of the most powerful WordPress compatible website builders we’ve ever encountered. The ability to change almost every single detail of a layout without needing to know HTML or CSS coding is a game changer, and we suspect most intermediate to advanced users will choose to make a lot of alterations. This couldn’t possibly be easier thanks to the drag and drop technology.
Those who want a very quick and simple way to build a website can’t go wrong with the pre-built templates, although upgrading to Themify Ultra’s wonderful level of creative control will offer a much more unique result. Ultimately, we love and highly recommend Themify for a wide variety of website needs!
I talk a lot about static site generators, but always about using static site generators. In most cases, it may seem like a black box. I create a template and some Markdown and out comes a fully formed HTML page. Magic!
But what exactly is a static site generator? What goes on inside that black box? What kind of voodoo is this?
In this post, I want to explore all of the parts that make up a static site generator. First, we’ll discuss these in a general fashion, but then we’ll take a closer look at some actual code by delving deep inside HarpJS. So, put your adventurer’s cap on and let’s start exploring.
Why Harp? For two reasons. The first is that HarpJS is, by design, a very simple static site generator. It doesn’t have a lot of the features that might cause us to get lost exploring a more comprehensively full-featured static site generator (like Jekyll for instance). The second, much more practical, reason is that I know JavaScript and don’t know Ruby very well.
The Basics of a Static Site Generator
The truth is, a static site generator is a pretty simple concept. The key ingredients to a static site generator are typically:
A template language(s) for creating page/post templates
A lightweight markup language (typically Markdown) for authoring content
A structure and markup (often YAML) for providing configuration and metadata (e.g. “front matter“)
A set of rules or structure for organizing and naming files that are exported/compiled, files that are not and how these files will be handled (e.g. frequently prefacing a file or folder with an underscore means that it is not exported into the final site files or all posts go in a posts folder)
A means of compiling templates and markup into HTML (frequently support for CSS or JavaScript preprocessors is also included)
A local server for testing.
That’s it. If you’re thinking, “Hey… I could build that!” you are probably correct. Things start to get complicated though when you start to expand the functionality, as most static site generators do.
So, let’s look at how Harp handles this.
Getting to the Harp of the Matter
Let’s look at the basics of how Harp handles the key ingredients described above. Harp offers more than this handful of functionality, but, for the sake of our examination, we’ll stick to those items.
First, let’s discuss the basics of Harp.
Harp Basics
Harp supports Jade and EJS (for templating) and Markdown as its lightweight markup language (for content). Note that while Jade is now called Pug, Harp has not officially transitioned in their documentation or code, so we’ll stick with Jade here. Harp also offers support for other preprocessing such as Less, Sass, and Stylus for CSS and CoffeeScript for JavaScript.
By default Harp does not require much in the way of configuration or metadata. It tends to favor convention over configuration. However, it allows for specific metadata and configuration using JSON. It differs from many other static site generators in that file metadata is contained outside of the actual file within a `_data.json` file.
While it is configurable to a degree, Harp has certain established guidelines for how to structure files. For example, in a typical application, the files that are served fall within a public directory. Also, any file or folder prefaced by an underscore will not be served.
Lastly, Harp offers a basic local web server for testing that includes some configurable options. And, of course, it will compile the finished HTML, CSS and JavaScript files for deployment.
Let’s Look at Harp’s Actual Source Code
Since much of what makes a static site generator are rules and conventions, the code centers around the actual serving and compiling (for the most part). Let’s dig in.
The Server Function
In Harp, serving your project is usually done by executing harp server from the command line. Let’s look at the code for that function:
While the function looks simple, obviously there is a ton going on within middleware that isn’t illustrated here.
The rest of this function opens up a server with the options you specify (if any). Those options include a port, an IP to bind to and a directory. By default the port is 9000 (not 9966 as you might guess by the code), the directory is the current one (i.e. the one Harp is running in) and the IP is 0.0.0.0.
Staying within index.js, let’s take a look at the compile function next.
exports.compile = function(projectPath, outputPath, callback){
/**
* Both projectPath and outputPath are optional
*/
if(!callback){
callback = outputPath
outputPath = "www"
}
if(!outputPath){
outputPath = "www"
}
/**
* Setup all the paths and collect all the data
*/
try{
outputPath = path.resolve(projectPath, outputPath)
var setup = helpers.setup(projectPath, "production")
var terra = terraform.root(setup.publicPath, setup.config.globals)
}catch(err){
return callback(err)
}
/**
* Protect the user (as much as possible) from compiling up the tree
* resulting in the project deleting its own source code.
*/
if(!helpers.willAllow(projectPath, outputPath)){
return callback({
type: "Invalid Output Path",
message: "Output path cannot be greater then one level up from project path and must be in directory starting with `_` (underscore).",
projectPath: projectPath,
outputPath: outputPath
})
}
/**
* Compile and save file
*/
var compileFile = function(file, done){
process.nextTick(function () {
terra.render(file, function(error, body){
if(error){
done(error)
}else{
if(body){
var dest = path.resolve(outputPath, terraform.helpers.outputPath(file))
fs.mkdirp(path.dirname(dest), function(err){
fs.writeFile(dest, body, done)
})
}else{
done()
}
}
})
})
}
/**
* Copy File
*
* TODO: reference ignore extensions from a terraform helper.
*/
var copyFile = function(file, done){
var ext = path.extname(file)
if(!terraform.helpers.shouldIgnore(file) && [".jade", ".ejs", ".md", ".styl", ".less", ".scss", ".sass", ".coffee"].indexOf(ext) === -1){
var localPath = path.resolve(outputPath, file)
fs.mkdirp(path.dirname(localPath), function(err){
fs.copy(path.resolve(setup.publicPath, file), localPath, done)
})
}else{
done()
}
}
/**
* Scan dir, Compile Less and Jade, Copy the others
*/
helpers.prime(outputPath, { ignore: projectPath }, function(err){
if(err) console.log(err)
helpers.ls(setup.publicPath, function(err, results){
async.each(results, compileFile, function(err){
if(err){
callback(err)
}else{
async.each(results, copyFile, function(err){
setup.config['harp_version'] = pkg.version
delete setup.config.globals
callback(null, setup.config)
})
}
})
})
})
}
The first portion defines the output path as specified by the call to harp compile via the command line (source here). The default, as you can see, is www. The callback is a callback function passed by the command line utility which is not configurable.
The next part starts by calling the setup function in the helpers module. For the sake of brevity, we won’t go into the specific code of the function (feel free to look for yourself), but essentially it reads the site configuration (i.e. harp.json).
You may also notice a call to something called terraform. This will come up again within this function. Terraform is actually a separate project required by Harp that is the basis of its asset pipeline. The asset pipeline is where the hard work of compiling and building the finished site gets done (we’ll look at Terraform code in a little bit).
The next portion of code, as it states, tries to prevent you from specifying an output directory that would inadvertently overwrite your source code (which would be bad as you’d lose any work since your last commit).
The compileFile and copyFile functions are fairly self-explanatory. The compileFile function relies on Terraform to do the actual compilation. Both of these functions drive the prime function which uses a helper function (fs) to walk the directories, compiling or copying files as necessary in the process.
Terraform
As I discussed, Terraform does the grunt work for compiling the Jade, Markdown, Sass and CoffeeScript into HTML, CSS and JavaScript (and assembling these pieces as defined by Harp). Terraform is made up of a number of files that define its processors for JavaScript, CSS/stylesheets, and templates (which, in this case, includes Markdown).
Within each of these folders is a processors folder that contains the code for each specific processor that Terraform (i.e. Harp) supports. For example, in the templates folder are files that form the basis for compiling EJS, Jade, and Markdown files.
I won’t delve into the code for each of these, but, for the most part, they rely upon external npm modules that handle the supported processor. For example, for Markdown support, it depends upon Marked.
The core logic of Terraform is contained in its render function.
/**
* Render
*
* This is the main method to to render a view. This function is
* responsible to for figuring out the layout to use and sets the
* `current` object.
*
*/
render: function(filePath, locals, callback){
// get rid of leading slash (windows)
filePath = filePath.replace(/^/g, '')
// locals are optional
if(!callback){
callback = locals
locals = {}
}
/**
* We ignore files that start with underscore
*/
if(helpers.shouldIgnore(filePath)) return callback(null, null)
/**
* If template file we need to set current and other locals
*/
if(helpers.isTemplate(filePath)) {
/**
* Current
*/
locals._ = lodash
locals.current = helpers.getCurrent(filePath)
/**
* Layout Priority:
*
* 1. passed into partial() function.
* 2. in `_data.json` file.
* 3. default layout.
* 4. no layout
*/
// 1. check for layout passed in
if(!locals.hasOwnProperty('layout')){
// 2. _data.json layout
// TODO: Change this lookup relative to path.
var templateLocals = helpers.walkData(locals.current.path, data)
if(templateLocals && templateLocals.hasOwnProperty('layout')){
if(templateLocals['layout'] === false){
locals['layout'] = null
} else if(templateLocals['layout'] !== true){
// relative path
var dirname = path.dirname(filePath)
var layoutPriorityList = helpers.buildPriorityList(path.join(dirname, templateLocals['layout'] || ""))
// absolute path (fallback)
layoutPriorityList.push(templateLocals['layout'])
// return first existing file
// TODO: Throw error if null
locals['layout'] = helpers.findFirstFile(root, layoutPriorityList)
}
}
// 3. default _layout file
if(!locals.hasOwnProperty('layout')){
locals['layout'] = helpers.findDefaultLayout(root, filePath)
}
// 4. no layout (do nothing)
}
/**
* TODO: understand again why we are doing this.
*/
try{
var error = null
var output = template(root, templateObject).partial(filePath, locals)
}catch(e){
var error = e
var output = null
}finally{
callback(error, output)
}
}else if(helpers.isStylesheet(filePath)){
stylesheet(root, filePath, callback)
}else if(helpers.isJavaScript(filePath)){
javascript(root, filePath, callback)
}else{
callback(null, null)
}
}
(If you were reading all this code closely, you likely noticed TODO’s, typos, and even a funny “understand again why we are doing this” comment. That’s real life coding!)
The majority of the code in the render function is about handling templates. Things like CoffeeScript and Sass fundamentally render on a one-to-one basis. For example, style.scss will render to style.css. Even if it has includes, that is handled by the renderer. The very end of the render function deals with these types of files.
Layouts in Harp, on the other hand, are nested within each other in a variety of manners that can even depend upon configuration. For example, about.md might be rendered within the default _layout.jade (where, exactly, is determined by the use of != yield within that layout). However, _layout.jade might include multiple other layouts within itself by way of the partial support in Harp.
Partials are a way of splitting up a template into multiple files. They are especially useful for code reuse. For instance, I might put the site header inside a partial. Partials are important for making layouts within a static site generator maintainable but they also add a good deal of complexity to the logic of compiling templates. This complexity is handled within the partial function of the templates processor.
Finally, you could override the default layout by specifying a specific layout or no layout at all for a particular file within the _data.json configuration file. All of these scenarios are handled (and even numbered) within the logic of the render function.
That’s Not So Complicated, Is It?
To make this digestible, I’ve skipped over a ton of additional detail. At its core, every static site generator I’ve ever used (and I’ve used a bunch) functions similarly: a set of rules, conventions, and configuration that is run through compilers for the various supported markups. Perhaps that is why there are a ridiculous number of static site generators out there.
That being said, I wouldn’t want to build my own!
My Report & Book
If you are interested in learning how to build sites using a static site generator, I’ve authored a report and co-authored a book for O’Reilly that might interest you. My report, simply titled Static Site Generators is free and attempts to establish the history, landscape, and basics behind static site generators.
The book that I co-authored with Raymond Camden is called Working with Static Sites and is available as an early release, but should be available in print soon.
The browser’s reload button exists to allow the user to get an updated version of the current page. In order to meet this goal, when you reload, browsers revalidate the page that you are currently on, even if that page hasn’t expired yet. However, they also go a step further and revalidate all sub-resources on the page — things like images and JavaScript files.
So even if you’ve set proper expires headers for resources, hitting that reload button (which people must do a ton at Facebook) still requires server round trips to revalidate assets (sometimes).
They worked with Chrome:
After fixing this, Chrome went from having 63% of its requests being conditional to 24% of them being conditional.
And Firefox:
Firefox implemented a proposal from one of our engineers to add a new cache-control header for some resources in order to tell the browser that this resource should never be revalidated.
So if you’re using URLs for assets that never change (if they change, they’ll be at a new URL) in Chrome you’ll benefit automatically, and in Firefox you should use their new header.
