Day of the Jekyll

I’ve never seen the film or read the book, just wanted to make a terrible pun.

My new project is to make a new blog! Now you can tell that this hasn’t got very far by the fact I’m posting this on my WordPress.com blog. The new one is still only hosted locally on my laptop, but should be up on Github Pages soon. I’ll probably keep posting here anyway until I’m reasonably happy with the new one…

The idea for the new blog is to host it on Jekyll, a static site generator which allows you to write new posts in Markdown and add them straight to your blog. Because the end result is a pre-generated static site, it loads very quickly and can also be hosted cheaply or for free. In particular, Github offers
free hosting for Jekyll sites. I’ve been planning to learn to use git properly for a while now, and this is should motivate me to do it. Plus I should get more useful practice with HTML, CSS, terminal commands and whatever else comes up.

I’d seen a few Jekyll blogs around and liked the look of them: the default seems to be a clean, minimal design that’s easily customisable (here are some examples). I was particularly inspired by this blog by W. Caleb McDaniel, which turned up on Hacker News at some point and is about a hundred times nicer than most academics’ blogs. Interesting that a history professor has out-geeked all the physicists and mathematicians. Reading up a bit more, I realised that he’s actually gone a good level further than I was planning and his site is not actually Jekyll but a static site generator he wrote himself, but the end result is definitely in the same style.

I was also very taken with his blog’s colour scheme Solarized by Ethan Schoonover. I get occasional severe migraines and almost always have disturbances to my vision, like flickering and blind spots, before the headache starts. I think this has made me hyper-aware of flickering and afterimages in my normal vision, because I now find it hard to read off a bright white screen for any length of time. I’ve installed a browser plugin, Change Colors, to convert websites to light grey text on a dark grey background, and find this much easier to read (as an added bonus, it’s useful when I come across a really eye-wateringly garish site). The Solarized colour scheme, however, is extremely readable, probably the best light colour scheme I’ve come across, and is very pretty too! So this is another thing I plan to take inspiration from for my own blog.

My final reason for trying Jekyll is that I already really like Markdown. I used LaTeX throughout my PhD, so I’m very used to writing documents in a text file. LaTeX is great when you actually need it (i.e., when you’re typing out hundreds of equations), but is massive overkill for a simple text document, so when I discovered Markdown I was really pleased with it. It’s also a lot more fun to type than HTML with all its irritating <s and >s. For me, the best thing is that adding links is so simple and frictionless that I’m much more motivated to reference things carefully and acknowledge all the sources I use. Typing out a load of HTML or LaTeX, or clicking buttons in a GUI feels like such a pain in comparison! Currently I write my posts in Markdown, and then copy and paste them into the WordPress.com editor. It’s rather a clunky system, and I don’t really need the bloated set of features on WordPress.com, so something simpler that I can customise as I go may suit me better.

So, that’s the plan anyway! I’m already running into a fair bit of hassle doing the blog migration, so I may be less optimistic about the process soon… As with the Zyring project, I plan to write up notes as I go, covering installing Jekyll, migrating my old blog, hosting on Github and customising the blog. This is mostly for my own benefit, for writing practice and future reference, but it may possibly be helpful to others.

I have no idea how fast this will progress, because everything’s a bit up in the air for me at the moment – my new job’s been put back from August to October, and I’ve got to figure out what the hell I do until then. I definitely don’t want to be paying two extra months’ rent without a job! So at the moment I have loads of spare time, but I have no idea how that is going to change. Anyway I’ll tack on a contents page to the end of this introductory post as and when I add new material.

Advertisements

I dun it! Zyring project summary…

Well, after a lot of blogging, coding, gawping at the console, googling obscure errors and swearing at my laptop, I’ve finally (almost) finished the Zyring Apartment Finder project! Normally I find American startups go a bit overboard on the “WOO! AWESOME JOB!” every time you fill in a text box or whatever, but this time after finishing this ~40 hour project I got this:

The rather low-key end of the project.

CONGRATULATIONS!!! PARTY TIME!!!

That’s a bit low-key even for my British tastes.

Anyway, it’s now time to look back on my introductory post and have a think about how things went…

General thoughts

Overall, I’m really impressed! Having a structure for the project made it much easier to stay motivated. Having no idea whatsoever how to do things gets demoralising fast. I’d never used the Angular framework before so I was worried that the tutorials would become impossible to follow… well, it definitely made things harder, and I had to do a bit of extra reading up, but it wasn’t a serious problem. I’m pleased that I was able to wire up a complex app myself, and I got to see a lot of new things on the way: communicating with the backend server, the MVC pattern, using an external API like Google Maps.

Obviously I’m going to need a lot more practice with these to really know what I’m doing, but I tend to like the learning approach of having lots of new things thrown at me, getting a rough idea of how things work, and then going back and filling in gaps. That last bit is obviously important: I don’t want to become someone who just knows how to paste a bunch of stuff together. I also got plenty of useful general HTML and CSS practice, used Bootstrap a bit more, and got my head round callbacks.

Last but not least, I think it’s helped a bit with me getting a job! In August I’m starting a trainee developer position. It’s at a local software consultancy which trains up graduates with limited programming experience (but generally some kind of technical background I think… lots of maths students at the interview). They seem to work on a very wide range of projects, so it should be a good opportunity to learn quickly and find out what I like doing. And as an extra plus, I can stay in the Bath/Bristol area, which I really like. I don’t have to move to London or Cambridge and tip piles of money into a hole just to afford rent!

I talked about the Zyring project at the interview, and I think that helped counter the interviewer’s natural suspicion that as a PhD graduate I wasn’t really serious about this career switch. It was good to be able to show I was putting my own time into a coding project and enjoying it rather than applying to jobs at random out of necessity, and I think doing something with an obvious real-world application shows that I’m capable of taking an interest in something less esoteric than neutron star physics.

OK, now for a few specifics:

Magic beans test

In my intro post I wrote:

At the start of this project, you download a ‘project scaffolding’ – a rather bewildering number of files and folders, with references to a lot of tools and frameworks – Bower, Grunt, Angular, Bootstrap… Zyring make it very clear that you don’t need to know what everything is from the start, which I’m fine with – I’m happy with approaches that throw you in and allow you to learn as you go.

However, there is a lot of this stuff, which worries me. Zyring say that everything will be explained in later tutorials, which is a key claim as far as I’m concerned. I’m not expecting to come out with particularly high-level knowledge of all this stuff, but if I’m poking around the filesystem at the end of the project and half of it still looks like a bunch of magic beans then I will be disappointed.

So, it’s now time to go through the filesystem systematically and see what I think now I’m at the end of the project. This isn’t just a silly exercise – if I want to make my own project along these lines, I’m going to have to know how to set it up myself.

I mainly care about the main app folder (which I’ll come to in a minute), but let’s look at the other bits hanging around in the project folder:

  • bower_components. This has the various packages I’ve downloaded for this app. There are a lot of them:
Long list of packages

I forgot to include kitchen-sink.js…

There’s a bit of rambling about whether that’s overkill later in this post. Anyway this passes the magic beans test as I recognise the files inside it.

  • node_modules. This pretty much all seems to be to do with grunt, which I still know very little about. On the other hand, this is not the focus of the project.

  • test. Some tests I know nothing about. Probably a fail on the magic beans front.

  • a few other files floating around. bower.json seems to list the app’s dependencies on various packages and appears to have been automatically updated as I added more packages. There’s also package.json which seems to be the same thing for the Node files. Finally there’s gruntfile.js, which seems to be some kind of configuration file for grunt.

OK, now let’s look into the app folder. Here we have:

  • images: this is pretty self-explanatory, just city images I added myself
  • scripts: my controllers and services go here. Again I made these files myself, no problem here
  • styles: my CSS file. Fine.
  • util: ooh, here’s some magic beans! There’s humane.min.js which is apparently ‘a simple, modern, framework-independent, well-tested, unobtrusive, notification system.’ Then there’s libnotify.css, which seems to go along with it. Finally there’s socket.io, which ‘enables real-time bidirectional event-based communication.’ Good to know!┬áAll this stuff seems to be connected to a baffling script at the bottom of index.html full of notifyToasters and socket.emit. I think this is something to do with requesting help… so Zyring-specific, not part of the project as such. I probably don’t have to care about it.

  • views: contains my views. Nothing to see here.

  • Finally we have good old 404.html, index.html and robots.txt.

So overall this isn’t too bad. test and utils are full of magic beans but are not really relevant to the project, everything else pretty much makes sense except maybe some of the grunt stuff, which is still recognisable at least. I think this is OK – my main worry was ending up with a completely incomprehensible project I had no hope of reproducing.

Minor gripes

Now for a few things I’m unsure about:

  • I’ve enjoyed learning the basics of Angular, but I’m still unsure whether it’s a good choice to be teaching noobs like me. I was already vaguely aware that the next version of Angular was going to be different, but now I know a bit about the framework I can see that the planned changes are extremely drastic. That syntax looks very different, and wait, $scopes going? Oh, and controllers are going too? Um, so what exactly is staying?

From what I’ve read, though, it seems like front end development in general is currently a chaotic mess of competing frameworks, and Zyring can’t really avoid making some kind of controversial choice. Codeacademy seem to have gone the Angular route as well, so I assume there’s some logic behind it? I’m really not in a position to judge, seeing as I know almost nothing about the other frameworks. From what I’ve gathered, Backbone and Knockout are less likely to be torn up and reinvented tomorrow, but also they’re smaller and have to be supplemented with more stuff? I suppose Angular offers beginners the opportunity to get something working fast? On the other hand, it’s not like it’s particularly simple and jargon-free. I have no idea really.

  • Look at that image with the list of libraries again – it’s huge! And a couple of them seem rather frivolous – do I really need that Masonry library with the clever-clever image positioning? I feel that using this massive range of libraries at the stage I’m at is going to get me into pretty bad habits of copying and pasting loads of cool-looking things together without really thinking about whether I need it. On the other hand, that Angular Bootstrap library had some useful features in it, and I suppose it’s good to know what’s out there. It’s not like I have to use it all in my own projects.

  • Some of the tutorials had confusing elements, but I covered those as they came up in the detailed posts.

What will I do next?

Given that I’m going to get all the programming I can eat starting in August, I doubt I’m going to go mad with new projects. Anyway, here’s a few ideas:

  • I may do another Zyring project because I enjoyed the first one, but I doubt I’ll blog about it. It’s definitely been worth doing – the notes are really useful to look back on to remind myself of things – but it does slow me down. The News Reader one looks good to me, as a long-term RSS addict (still mourning Google Reader :().

  • It would also be a good idea to try putting together some minimal CRUD apps with Angular, using this tutorial as a guide, to get more of an idea of the basics. Things that appeal: going through the movie app in the tutorial but doing it for books (this year I’ve started keeping a list of what I read, so I have plenty to go into it); maybe a simple flashcard app for German vocab. I’d have to work out how to make the backend…

  • Before all of this, however, my priority is probably a basic website/blog with Jekyll. I currently write these posts in a text file in Markdown, and then copy and paste them into WordPress, so I think Jekyll would suit me well. It would be a good chance to learn how to use Git properly (used it a bit before, but it was a while ago). Also, free hosting! A static site would still allow me to muck about with visualisations in d3.js if I felt like it.

Final thoughts

Nothing much more to add, just wanted to reiterate that I’m really glad there are companies thinking about this kind of bridge between basic tutorials and working on projects independently. It’s a gap that needs filling, and Zyring’s doing an excellent job!

Zyring Day 19 – Tidying up

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Display information about a single apartment on a page (continued)

Time for a final bit of styling of the indivdual apartments. I added a grey background to the apartment title to be consistent with the styling list of apartments, and did a few other small changes. Again, I don’t want to spend huge amounts of time on styling for this project, that isn’t the focus for me.

I ended up with this:

Grey background to the title for consistency.

Grey background to the title for consistency.

Pedantry

Woohoo! Everything’s done now apart from the page navigation problem from yesterday that I’m going to have to ask about. Now to tidy up a bit… fixing problems, with indentation, comments, adding some ngdocs documentation and renaming my two Angular factories to more informative names. Also cleaned up my mess of a CSS file a bit using tips from this tutorial.

Things I could add

That’s where I’m leaving it for now (apart from the page navigation problem), but I may as well list a few minor annoyances I’d like to fix if I feel like it later:

  • Map displays same area each time: would like to focus in on particular areas
  • Maybe have a map on individual apartment pages as well
  • Add navigation to go back to list of apartments from an individual apartments page
  • Currently if I do this by clicking ‘Back’, it always takes me to page 1 of the list of apartments rather than the one I was on
  • Carousel only works with mouse, not left and right arrow keys
  • Would be good to show the apartment thumbnail for apartments where there are no other images on the backend server
  • Write something more helpful in the ‘About’ view

 

Finally…

I still need to write a big old post summarising how I found the project. Coming soon…

Zyring Day 18 – Off By One Day

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Using the pager element to navigate (cont’d)

OK, I’m awake, reasonably alert, and well-fortified by the supermarket garlic naan I ate cold out of the bag on a bench in the shopping centre. Apparently this is not what the well-dressed ladies of Clifton generally do for breakfast, or so I gather from the odd looks, but hopefully it’s helped put me in the right frame of mind for going back and looking at the off-by-one error I had weeks ago.

First, let’s work out exactly what the problem is. Take Seattle as an example. There are 165 apartments listed, so that should make 18 pages of 9 apartments plus a 19th page with 3 apartments. Looking at the backend data, the first apartment on each page should be:

Page 1: Avalon Kirkland
Page 2: Kerry Park Apartments
Page 3: Lexicon

Page 17: The Dakota at Rainier Court
Page 18: The Century
Page 19: Alcyone

However what’s actually happening is this:

  • On first loading cities/Seattle, I get Avalon Kirkland as expected.
  • But if I now click on page 2, I get Lexicon which should be page 3…
  • …and if I click back to 1 I get Kerry Park Apartments. ­čśŽ
  • Also, the list of pages only goes up to 17, The Dakota. The pages above that are just not displayed.

Same stuff if I click on ‘Next’ and ‘Previous’ instead of the page numbers. So I’m initialising it correctly, which makes sense as I’m explicitly setting $scope.currentPage = 0;, but then it’s off by one after that. Not sure what’s going on with the last pages missing.

Looking at the AngularUI Bootstrap documentation, I see that ng-model expects the first page to be 1, whereas mine start at 0, so that is one of the problems, so I fix that. After fixing this Avalon Kirkland is consistently the first page as expected, which is good, but I now have a “TypeError: Cannot read property ‘push’ of undefined” message, and the pager element loads stuck on page 17, which is still the last page. So I’ve fixed one thing and now something else is broken – progress of a sort.

OK, now I’m having a look at the array of pages $scope.pages. It looks OK before I push any information into it, but then there’s a problem. It should look like [Array[9], Array[9], Array[9],...] but instead there’s an Array[0] at the beginning. Bummer. This might explain why I’m getting the ‘TypeError’ message, though, as there isn’t enough space in the array for everything I want to push to it, so I’m making progress.

Indeed, I find my while loop goes one too high, and I get rid of the TypeError problem and the carousel loads at the first page with Avalon Kirkland as expected. STILL having the problem with the highest pages missing though.

Let’s look at all the cities…

  • Seattle: 165 apartments, should be 19 pages, displaying 17, out by -2
  • Redmond: 65 apartments, should be 8 pages, displaying 7, out by -1
  • Bellevue: 164 apartments, should be 19 pages, displaying 17, out by -2
  • Kirkland: 172 apartments, should be 20 pages, displaying 18, out by -2
  • Tacoma: 141 apartments, should be 16 pages, displaying 15, out by -1
  • Olympia: 52 apartments, should be 6 pages, displaying 6, correct

So it seems to be more wrong the larger the number of apartments, but why is not obvious to me.

I also find another problem, possibly related. When I click on some apartments, the data doesn’t load. Instead I get an empty page like this:

Page with no data loaded

Not very helpful

This happens only with apartments on later pages.

I fiddle about with this all day but cannot work out what the problem is. It might finally be time to ask for help… but I want to finish off the remaining bits of styling first.

Zyring Day 17 – Carousel Success

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Display information about a single apartment on a page (continued)

Boom! Used simonykq‘s solution on this thread and it worked beautifully. Nice to start the day with something working immediately.

I then ran into another issue that needed fixing – a problem with duplicate items in lists when using ng-repeat. This could be fixed by using the track by $index option, tracking by an object’s position in an array rather than its value. I’d seen this error come up before, nice to understand it!

OK, finally time to style the information a bit. I get as far as this:

Example apartment listing.

Example apartment listing.

Next time I plan to make this a bit fancier and more consistent with the styling of the previous pages. And hopefully find that off-by-one error… very close to finishing now!

Zyring Day 16 – Carousel Fail

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Display information about a single apartment on a page

Thought this would be straightforward, but I ended up having a fairly frustrating day of getting things wrong. Annoying when I seem to be so close to the end…

I decided I wanted a layout like this (written on a blank page of a ‘Libraries for the Future’ consultation booklet because I didn’t bring any paper with me):

Layout for my apartment page

Layout for my apartment page

Fairly basic, just a title, a big carousel of images, and a couple of lists of information.

First I was confused for quite a while about why no apartment images were being displayed. I thought that for some reason get wasn’t fetching them, and spent a long time mucking about with callbacks (on the plus side, they started making a lot more sense). Then I realised that the problem was simply that there aren’t any images on the server for most apartments, just an empty array. So I decided to start off just getting the view for the example data to work properly, and then think about what to do for the pages without images later.

For the carousel I tried to use the Angular Bootstrap library. My blog came in handy there: I knew I’d used it before but couldn’t remember what for, so the relevant post was useful. I managed to include a carousel, but the arrows weren’t working properly. I think it probably has something to do with this problem, but by now I’m happy to give this a rest for a while.

Zyring Day 15 – Making pages for each apartment

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Creating new pages for your apartments

This took me a while, as it was some time since I’d done the routing for┬áthe┬ácity pages. I had to create my new view (apartments.html), my new controller (apartments.js) and then sort out the routing in app.js. Then I made links from each apartment in the map and listings to the new page. Think I’m starting to get the hang of how routing works!

Backend endpoints for individual apartment API

Nice short tutorial, just having a look at what information the backend server has for each apartment (quite a lot, as it turns out).

Single apartment factory

This is an odd tutorial. The text looks unfinished, and says ‘Similar to the previous step, create another factory for the last backend call inside the script you created.’ I have no idea what step this is referring to. I decide to go for my standby method of just guessing what to do, and then hoping the next tutorial makes more sense…

My guess is that I need to wire things up to the backend server using the $resource object, as I did for the apartment lists for each city. After a lot of fiddling around trying to remember how to do this, I manage to dump all the apartment data into my view for each apartment:

Data for the single apartment view.

Data for the single apartment view.

Not pretty. But it works!

Getting information for individual apartments

Hang on, turns out that the next tutorial is exactly what I just did. So I’ve now got no idea what the ‘Single Apartment Factory’ tutorial is about. Never mind, if it’s important I’m sure I’ll find out later. I’m also feeling quite smug that I figured out to use a get rather than query method by myself, with no help from the tutorial (it took me a while though).

Wow, there’s only one tutorial left now (as well as going back and working out what my off-by-one problem with ‘Using the pager element to navigate’ is). Will leave this for another day, as I expect it will take some time to do all the styling and so on.

Zyring Day 14 – Masonry and responsive design.

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Install Masonry library

In this tutorial, I install Masonry, a new directive that’s supposed to take care of placing images that are different sizes. I’m not really sure I see the point of this, as all the apartment images seem to be thumbnail images of the same size. Maybe a previous version of the backend data had variable image sizes? Bigger images would also be nicer for styling the pages…

I dutifully install the library anyway, play around with it for a bit, then revert to my previous styling without Masonry. I’ll keep the Masonry stuff commented out in case I need it for a later tutorial.

Make your ‘All Apartments’ page responsive

I.e., check it works OK for different screen sizes. This is actually fine straight off thanks to Bootstrap. If I’m being fussy, the map could do with being centred better, but I should probably muck around with the scaling on that in general some time. At the moment it is zoomed out on the whole Seattle area each time (to cover all six cities), but I should really zoom in on each one.

It was good to play around with the screen sizes in the Developer Tools though and see what it looks like on different phone and tablet screens, never used that before.

Zyring Day 13 – styling the list of apartments.

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

Styling the Apartments List page

Strangely, I wasn’t really enthralled by the prospect of figuring out the off-by-one error from the last tutorial I did three weeks ago, so I decided to ease myself back in by doing a relatively self-contained tutorial on styling. I don’t want to spend ages on styling as it’s really not the focus of what I want to learn right now, but I will at least implement a basic grid of apartments.

I follow the same basic approach as for styling the list of cities, and this is what I end up with:

Basic styling for the list of apartments.

Basic styling for the list of apartments.

Not exciting, but it’ll do for now.

I also decide I don’t like the circles on the Cities page, so I go for ‘beer mats’ throughout:

Images for cities now have rounded corners.

I like beer.

OK, this has hopefully got me back into the right mindset for this project.

Zyring Day 12 – notes from ages ago…

[Note: These are more in-depth (read: tedious) write-ups of my experience with each section of the Zyring project, leading on from my intro post on Zyring. This is mostly for my own benefit but could conceivably be of use to someone doing the project.]

So there’s been a pretty long break in these blog entries – I’m doing some marking for a local university and just got hit by a huge pile of engineering maths exam scripts. That’s over now, and I don’t want to see another Fourier series for a while. Here I’m just writing up a short note I found from before Marking Fest started.

Using the pager element to navigate

Now it’s a case of wiring everything up so that the page selection UI actually does something, using ng-repeat. This took me a little while just to work out what’s going on, but was not actually very complicated in the end. My main annoyance was introducing some kind of off-by-one error so that the first page of apartments was missed off. Need to fix this sometime…