MY NOTEPAD

Develop For Chrome Cast

2015-01-10T00:00:00+11:00

What’s This?

Yesterday I set out on a mission to start writing my first Chromecast app. What I found was a woefully incomplete amount
of documentation via Google and several disaparate little projects that other
developers had worked on. While the task was not insurmountable because of this, I thought why not just write up a simple
Hello World with commentary to make any would be Chromecast Dev’s life easier. So, that’s what this is: a barebones
sender and receiver to help you understand how this all fits together. For now, I only have a Chrome sender. Soon I’ll probably work on the equivalent for Android. But, let’s get started!

Get Yourself Whitelisted

I’m not going to go into too much detail with this, because Google did a pretty good job of outlining this process. You can go here and just follow the instructions. It took me about 12 hours to hear a response. One thing to mention is that to start Chromecast development you’re going to need to host your receiver app somewhere. Github has free pages hosting, but in the long run that would be a little limited. So, look into your options and make the decision that works best for you right now.

An important note: The URL you give Google has to be the exact location of your receiver app’s index.html. If you were to clone this repo and upload it to your server http://mydomain.com then the receiver would be located at http://mydomain.com/receiver. You would have to specify that as your URL when whitelisting. Alternatively, if you just dumped the receiver app at the root directory of your domain, meaning it would found at http://mydomain.com, then you would supply that URL. The way the process works now does not have any support for subdirectories. So you have to make sure you’re specific. Also, if you rename the receiver app from index.html to anything else, you’ll have to specify that in the URL e.g. http://mydomain.com/receiver/sweetapp.html.

Also, while you’re waiting for this you might as well follow the second set of steps on that page and whitelist localhost in the Chromecast extension.

I’m Whitelisted…now What?

Now the fun part! These apps aren’t particularly difficult once you get the hang of it, so don’t sweat it if you were a little confused from Google’s documentation. Right now, it’s not very good!

To start off with, we’re going to go ahead and create our receiver app.

The Receiver

For both the receiver and the sender app I use a little bit of jQuery. I’m just going on the assumption that you understand it, as well as basic HTML, CSS, and Javascript. If not, you may want to start researching and learning those first. Having that base knowledge is important for being able to create useful Chromecast apps.

So, one thing to remember is that all Receiver applications are written in HTML5/CSS/Javascript. For some, this might seem awesome, and for others it might seem limited. Just remember what Chromecast is supposed to be: a media digester. You can still do a lot within these confines, though, so don’t get discouraged if you have big ideas.

Since our receiver is so tiny I’m just going to go ahead and show you the whole source and then make comments:

    <html>
        <head>
            <link rel="stylesheet" type="text/css" href="../css/receiver.css" />
        </head>
    <body>
        <div class="messages">
            <h1>Waiting for Messages...</h1>
        </div>
    </body>
    <script src="http://code.jquery.com/jquery-2.0.3.min.js"></script>
    <script src="https://www.gstatic.com/cast/js/receiver/1.0/cast_receiver.js"></script>
    <script src="messageTypes.js"></script>
    <script>
        $(function() {
            var receiver = new cast.receiver.Receiver('*** YOUR APP ID ****', ['*** YOUR NAMESPACE ***']),
                channelHandler = new cast.receiver.ChannelHandler('*** YOUR NAMESPACE ***'),
                $messages = $('.messages');
    		
            channelHandler.addChannelFactory(
                receiver.createChannelFactory('*** YOUR NAMESPACE ***'));
                
            receiver.start();
            
            channelHandler.addEventListener(cast.receiver.Channel.EventType.MESSAGE, onMessage.bind(this));
            
            function onMessage(event) {
                $messages.html(event.message.type);
            }
        });
    </script>
    </html>

Not so bad, right? Let’s break it down. The HTML chunk should be pretty familiar to you:

  <html>
    <head>
        <link rel="stylesheet" type="text/css" href="../css/receiver.css" />
    </head>
    <body>
        <div class="messages">
            <h1>Waiting for Messages...</h1>
        </div>
    </body>

This just sets up where we’re going to actually be displaying our content. I did some simple css too. You can look at the finished code on Github if you’re interested.

Next comes the scripts. The first just gets us jQuery. The second is what actually gets us access to the Receiver API, so make sure you don’t leave it out! Otherwise, your app isn’t going to work at all.

And then we have our script. Right away you start to see some garbage that mentions cast. As you might have guessed, this is our first Receiver API call:

    var receiver = new cast.receiver.Receiver('*** YOUR APP ID ****', ['*** YOUR NAMESPACE ***']),

This creates a new Receiver object. This is what we’ll be using to facilitate ways of communicating with the client and device.

Oh, and remember when we whitelisted our device? The e-mail you got should have contained your Application ID. That needs to replace *** YOUR APP ID ***. As for your namespace, it can be anything you want, but should probably be related to the application you’re creating. For this tutorial we can use something like HelloWorld. Make sure it doesn’t clash with other namespaces, though, as this is how your Receiver will know what type of messages to listen to and how your Sender will know what type of messages to send. More on that later…or right now:

    channelHandler = new cast.receiver.ChannelHandler('*** YOUR NAMESPACE ***'),

This little guy, as you might have guessed, is what handles our Channels. A Channel in this context is used to send and receive simple JSON messages to and from the Sender application. The ChannelHandler allows us to hook into the events that occur on the various Channels that get created as the application is being used. It also delegates to a ChannelFactory (which you’ll see a little later) to create new Channels. Again, note the namespace. Make sure you use the same one that you defined earlier on in the Receiver. This tells our ChannelHandler to only worry about messages coming from that namespace.

The next line is just there to keep track of our messages div so we can swap out the text later. Following that we create our ChannelFactory:

channelHandler.addChannelFactory(
    receiver.createChannelFactory('*** YOUR NAMESPACE ***'));

That namespace again! Just fill it in like before. Here we’re adding to our ChannelHandler a ChannelFactory. Like I said earlier, this is how Channels actually get created. We use the Receiver to create the ChannelFactory.

Great! We’ve got our Receiver and our ChannelHandler all set up! Does it work yet? Just a little bit more! First we need to tell the receiver to start listening to the world:

receiver.start();

Then we make sure our ChannelHandler is listening for MesssageEvents:

channelHandler.addEventListener(cast.receiver.Channel.EventType.MESSAGE, onMessage.bind(this));

The second parameter, as you should know from your Javascript training, just delegates the onMessage function as our callback when we hear a MessageEvent and binds this as our context. Channels do have other types of events. We can also listen for when the Channel is opened, closed, or when it has an error. For this tutorial we’ll just stick with messages, though.

Last, we actually do something with the MessageEvent:

function onMessage(event) {
    $messages.html(event.message.type);
}

These MessageEvents have several parameters, but the thing that actually gets sent from the Sender application is the message object, which is generally going to be represented as JSON. You’ll see in the next section that we basically define that JSON to look however we want. So there you go. Your first Receiver app! Now let’s make a Sender to do something with it!

Sender

Before we get started writing the sender app, it’d be good to mention that you’ll probably want some way of running a web server on your local machine. Without it you can’t really test this. For pretty much any platform, I suggest Mongoose. It’s a stupid easy web server. You just drop the executable into any directory you want to host, and launch it. You’ll be able to access the folder from localhost:8080.

Now let’s whip up a Sender so our Receiver can actually do something! This one is a little longer, so I won’t paste in the whole source. See my Github page for that.

First we have our HTML portion:

<html data-cast-api-enabled="true">
<head>
    <title>Hello World Chrome Sender</title>
    <link rel="stylesheet" type="text/css" href="../css/sender.css" />
</head>
<body>
    <div class="receiver-div">
        <h3>Choose A Receiver</h3>
        <ul class="receiver-list">
            <li>Looking for receivers...</li>
        </ul>
    </div>
    <button class="kill" disabled>Kill the Connection</button>
</body>
<script src="http://code.jquery.com/jquery-2.0.3.min.js"></script>
<script src="http://underscorejs.org/underscore-min.js"></script>

Something you might notice is that we aren’t importing any scripts for the Sender API. That’s because this is handled by two things. You should remember way back when we were whitelisting our receiver that we also whitelisted localhost in the Chromecast Extension for Chrome. This basically tells the extension that on the localhost domain we are allowing the extension to inject the Sender API into any page. However, it won’t just inject it all willy nilly. Our sender pages require this line:

<html data-cast-api-enabled="true">

to tell the extension that we want the API injected on this page. Make sure you don’t forget it!

Everything else in the HTML section should be pretty clear. We have a container which will list out all the receivers that get found and a button to disconnect from the receiver. We import jQuery and Underscore…sorry I snuck that one in there. If you don’t know about Underscore, you should check it out. It’s a really great little ‘functional’ library for Javascript. I only use it for one thing here and I’ll describe what’s happening when we get there.

I’ve also done a little styling for this page, which you can look at on the Github. Moving right along, we’ll jump into our
script. We declare our variables and then add some odd looking listener to our window object:

var cast_api,
    cv_activity,
    receiverList,
    $killSwitch = $('.kill');
    
    window.addEventListener('message', function(event) {
        if (event.source === window && event.data &&
                event.data.source === 'CastApi' &&
                event.data.event === 'Hello') {
            initializeApi();
        }
    });

The event listener isn’t too crazy. One of the consequences of the way the Sender API gets injected into our pages is that
we don’t really have any control over when it happens. But, the Google Devs were smart and gave us a way of finding out
exactly when we can start interacting with it. After the Sender API is loaded, it emits a MessageEvent to tell us so.
So, we listen for this event. The if block checks to make sure the contents of the MessageEvent match what we’re looking
for. As per Google’s docs, this event looks like this:

{
    source: 'CastApi',
    event: 'Hello',
    api_version: [x, y]
}

The version number basically lets our Sender decide if it’s compatible with this version of the API. Besides that, we
just make sure that the data in the MessageEvent matches the source and event described. Then we initialize our API:

initializeApi = function() {
    if (!cast_api) {
        cast_api = new cast.Api();
        cast_api.addReceiverListener('*** YOUR APP ID ****', onReceiverList);
    }
};

I’ve added a check in here which makes sure we aren’t calling this if we all ready have an API. So, we create a new CastApi
object and attach a ReceiverListener to it. This will simply tell the CastApi that there are receivers which are listening
for our…what’s that? Oh our App Id!

Bet you were wondering when that’d show up. In case you hadn’t figured it out by now, the way this whole App Id business
works is Google registers your device to listen for your App Id when you whitelist it. That App Id is tied to
a particular website (the one you supplied when you whitelisted your device). This is how the Receiver knows
which URL to hit when it gets a launch request…but now we’re getting ahead of ourselves.

The second parameter to addReceiverListener is what callback to use when we get a list of valid receivers. Which brings
us to…

onReceiverList = function(list) {
    if (list.length > 0) {
        receiverList = list;
        $('.receiver-list').empty();
        receiverList.forEach(function(receiver) {
            $listItem = $('<li><a href="#" data-id="' + receiver.id + '">' + receiver.name + '</a></li>');
            $listItem.on('click', receiverClicked);
            $('.receiver-list').append($listItem);
        });
    }
};

According to Google’s documentation the ReceiverListener fires at least once, regardless of if it’s found anything, once
you register it. So, we start with a check to make sure we actually have receivers. Then we just take that list and
dump it out in our receiver list element. We store the id of the receiver in a data attribute on the anchor tag so we can
reference it later. Then we attach click handlers to the list items:

receiverClicked = function(e) {
    e.preventDefault();
    
    var $target = $(e.target),
        receiver = _.find(receiverList, function(receiver) {
            return receiver.id === $target.data('id');
        });
    
    doLaunch(receiver);
};

This isn’t too out there…all standard Javascript/jQuery. This is where I end up using Underscore: _.find(receiverList....
It should be pretty easy to figure out what’s going on there. Underscore has a find function that takes two parameters:
the list you want to try to find something in, and a function to execute on each item in the list. find works by looping
through the list until the supplied function returns true. In our case, this is when we have found the receiver whose
id matches that of the link we clicked. Simple enough. After we’ve found the right receiver, we launch our application
on it:

doLaunch = function(receiver) {
    if (!cv_activity) {
        var request = new cast.LaunchRequest('*** YOUR APP ID ***', receiver);
        
        $killSwitch.prop('disabled', false);
        
        cast_api.launch(request, onLaunch);
    }
};

First we check to make sure we don’t already have an Activity launched on the receiver. While nothing bad would happen if
we tried to launch another activity before closing out the first, I figured I’d put that check in there. As long
as that passes, we use the Cast API and create a LaunchRequest. There’s that App Id again. Like I said
before, this is how your receiver knows which URL to launch. We also pass in which receiver the LaunchRequest should
go to. We then enable our kill switch and finally send our LaunchRequest to the receiver. The second parameter of the launch function is the callback function for when the launch is succesful.

At this point if you just added an empty onLaunch function, had your receiver hosted, and were running a server on your
local machine, you’d be able to open up this page in your browser, click on the link to your receiver, and your app should
launch. Exciting, right? We’ll just add a couple more things to show off some other interactions with the receiver. First,
that onLaunch function:

onLaunch = function(activity) {
    if (activity.status === 'running') {
        cv_activity = activity;
        
        cast_api.sendMessage(cv_activity.activityId, '*** YOUR NAMESPACE ***', {type: 'HelloWorld'});
    }
};

Once our application gets launched on the receiver, why don’t we say something to it? First we check the ActivityStatus
that we got back from the launch function from before is in the running state. You can think of the ActivityStatus
as representing what our connection to the receiver is doing. It also contains the id of the Activity, which we use
to communicate with the recevier, as you can see in the next line.

Here we use the Cast API to send a message to our receiver. This function is one of two types of interactions you
can have with your receiver, and as far as I can tell, it isn’t even documented! The other deals with MediaRequests,
but that’s getting out of scope of this tutorial.

The first parameter to the sendMessage, again, is that Activity id. The second parameter is your namespace. If you
think way back to the receiver section of the tutorial, you’ll remember that this is how the receiver knows which
messages to actually listen to. If you defined your namespace as HelloWorld use that here. Otherwise, just use
whatever you had before. Last we actually have the object which represents our message. You can literally put
whatever you want in here; it’s just a freeform JSON object. For now we’ll just include a type attribute and
say this is a HelloWorld type message.

So, now if you reloaded your sender application and clicked on your receiver link you should see the placeholder text ‘Waiting for messages…’ change to ‘HelloWorld’ on your TV. Hey! Look at that! We made our TV do something!

Just one more thing to do and then the tutorial is over. Hooray! Let’s add a click handler that will actually end
our session with the receiver:

$killSwitch.on('click', function() {
    cast_api.stopActivity(cv_activity.activityId, function(){
        cv_activity = null;
    
        $killSwitch.prop('disabled', true);
    });
});

This one is pretty straight forward. When we click on the kill switch, we call stopActivity on the Cast API. This does
exactly what it sounds like. We pass it the Activity id from our active activity and it tells the receiver we’re done.
The second parameter is just a callback function for when the receiver tells us it successfully closed the app. When
that’s done we null out our activity, so we can start a new one if we want, and disable the kill switch.

That’s it! If you reload your sender you should now be able to

Launch your activity on your receiver
Observe the text on your TV changing
Close out the application
Rinse and repeat

Look at that! Your first end to end Chromecast app! Go forth and be merry and show all your friends that you can control
your TV with a web browser…but maybe do something a little more interesting with the app first. The sky is the limit now!

Closing Thoughts

I hope this has been useful for you. But this is only the tip of the iceberg…well maybe not iceberg. This device certainly
doesn’t do everything, but it isn’t supposed to. Really the depth from this device is going to be in the interesting
HTML5 apps people make that work with this thing. The interaction with the device itself, as you can see, is pretty simple.
It’s just figuring out how to use the interaction model to make cool, useful apps.

However, this tutorial does not cover the other half of development on the Chromecast: media. There is a whole section of
the API for the sender and receiver which covers media interaction, from playing/pausing to volume control. The same
principles we’ve talked about here apply, but the functions and objects you use are a little different in some places.
Perhaps in a future tutorial I’ll cover that stuff. For now you should be able to muddle through the documentation
Google has provided.

Thanks for reading!

Develop For Chrome Cast was originally published by Katie Ball at MY NOTEPAD on January 10, 2015.

Organize Outlook With Rules

2015-01-01T00:00:00+11:00

If you are an Outlook.com user, you may be interested to know that setting up rules to manage your incoming and outgoing emails can make your life a whole lot simpler.

What are rules?

In their simplest form, Outlook rules are actions that your email account will automatically perform based on the guidelines that you have specified. There are two main categories of rules that you can create. These are organizational rules and notification based rules. These rules will are not retroactive, which means that they will only apply to unread messages.

Organize your Emails – These rules focus on filing and organizing messages based on senders, subject keywords, and folders in your Outlook account. These are helpful for putting emails into relevant folders or categories.
Keep current – These rules will send you notifications based on your incoming messages. These are useful if you want to get notifications of new emails to your mobile devices.

Creating New Rules in Outlook.com

Once you are logged into your Outlook.com email account, click on the Settings button, then on the Manage Rules option to create a new rule.

Now, click on the New button to create your first rule. As you can see, there are two main sections. On the left, you will assign a condition or multiple conditions to identify the emails to which your new rule will apply. The right side is where you will define what action Outlook will take with your emails.

For this example, we will choose two of the nine conditions that the email must meet, as well as two of the eight actions.

CONDITIONS ACTIONS

We will first click on the conditions link to add a second condition. Let us say that any emails from Sender@emailaddress.com that have the word apple in the subject line should be sent to a folder called “Apple Emails” and must be categorized as IMPORTANT!!!

Do this by editing your rule till the two sections look like the images below.

Lastly, click on Create Rule and let it take effect. From now on, any emails from Sender@emailaddress.com that have the word apple in them will be classified as important and moved to your Apple Emails folder.

If you want to edit any of your previously created rules, all you need to do is click on the rule and edit it in the window that pops up. To delete a rule, simply click on the small recycle bin next to the rule.

Create Rules from Email Messages

The Manage Rules page is not the only way to create rules for your emails. Alternatively, if you want to create a rule based on an email you received, simply find it in your Inbox and right-click on it. Next, select the “Create Rule” option.

Alternatively, you can click on the email to open it and create a rule by selecting the option from the “Extended Menu.”

Once you have done this, you will see a popup window as shown below, in which you can customize the rule as needed.

Organizing your Rules

It is important to remember that Outlook.com will automatically select the rules you define and implement them based on the order in which they appear on your list of rules. This is why it is important to organize your rules by their order of importance. Simply click on the up and down arrows next to the rules to put them in order as needed.

Rule Limits

Now that you know how to create and organize your rules, you need to know that there are also some limitations to the rules in the Outlook.com Web App. There is a limit on how many rules you can create. For some reason, you are only allotted 64 KB for your Outlook.com rules. There is no definitive answer on how many rules you can create since the size of the rules will vary based on the length of the rule and how many conditions and actions you have defined. Once you have reached your limit, Outlook.com will let you know that you cannot create any more rules. This is when you will need to consolidate rules or delete old rules that are no longer needed.

In addition to the limit on the amount of rules you are allowed to create, if you also use the Microsoft Outlook desktop application with rules, you may get a warning that your rules conflict with those on the desktop app. You will need to double check to make sure you can disable the conflicting rules or delete them if necessary.

Congratulations, you now know pretty much everything that you need to know about creating, manipulating, and using rules in the Microsoft Outlook Web App. Have fun managing your digital communication with ease on Outlook.com.

Organize Outlook With Rules was originally published by Katie Ball at MY NOTEPAD on January 01, 2015.

Markdown Styles

2014-12-29T00:00:00+11:00

Features

Ready-made CSS stylesheets for Markdown, just copy the assets folder you want
Bundled with generate-md, a small tool that converts a folder of Markdown documents into a output folder of HTML documents, preserving the directory structure
Use your own custom markup and CSS via --layout.
Support for relative paths to the assets folder via and document table of content generation via.
Support for generic metadata via a meta.json file

## Quickstart

Install generate-md via npm:

sudo npm install -g markdown-styles

Create a markdown file and then convert it to html:

mkdir input/
echo "# Hello world\n YOLO" > input/index.md
generate-md --layout mixu-gray --input ./input --output ./output
google-chrome ./output/index.html

Try out different layouts by changing the --layout parameter; screenshots at the bottom of this page.

If you want to make use of the bundled layouts stylesheets as a basis for your own site, copy the ./assets folder and point --layout to your own layout.

For example:

git clone https://github.com/mixu/markdown-styles.git ./markdown-styles
cp -Rv ./markdown-styles/layouts/mixu-gray ./my-layout
nano ./my-layout/page.html

Now edit the files ./my-layout/page.html and run:

generate-md --layout ./my-layout/page.html --input ./input --output ./output

What’s new in v1.2.x

v1.2.0: Code syntax highlighting has been reworked so that syntax highlighters have become pluggable. See the relevant section below on how to use the new system.

v1.2.1: added the bootstrap3 style, thanks @MrJuliuss!

v1.2.2: added the github style, based on sindresorhus/github-markdown-css.

Just using the stylesheets

Alternatively, if you just want the stylesheets for your own project, you can just copy the ./assets folder from the layout you want.

To preview the styles in the browser, clone this repo locally and then open ./output/index.html or run make preview which opens that page in your default browser.

Using generate-md

This project also includes a small tool for generating HTML files from Markdown files.

The console tool is generate-md, e.g.

generate-md --layout jasonm23-foghorn --output ./test/

Here is an example of how I generated the project docs for Radar using generate-md, a Makefile and a few custom assets.

--input specifies the input directory (default: ./input/).

--output specifies the output directory (default: ./output/).

--layout specifies the layout to use. This can be either one of built in layouts, or a path to a custom template file with a set of custom assets.

--partials specifies the partials directory.

--helpers specifies the helpers directory.

To override the layout, simply create a directory, such as ./my-theme/, with the following structure:

├── my-theme
│   ├── assets
│   │   ├── css
│   │   ├── img
│   │   └── js
│   └── page.html

Then, running a command like:

  generate-md --input ./input/ --layout ./my-theme/page.html --output ./test/

will:

convert all Markdown files in ./input to HTML files under ./test, preserving paths in ./input.
use the template ./my-theme/page.html, replacing values such as , `}` and (see the layouts for examples on this)
(recursively) copy over the assets from ./my-theme/assets to ./test/assets.

This means that you could, for example, point a HTTP server at the root of ./test/ and be done with it.

You can also use the current directory as the output (e.g. for Github pages).

Syntax highlighting support (changed in v1.2.x)

generate-md supports syntax highlighting during the Markdown-to-HTML conversion process.

Supported:

highlight.js via mds-hljs
csv (using highlight.js css classes) via mds-csv

To enable the syntax highlighting support, install the module (e.g. mds-hljs) and then use --highlight (e.g. --highlight mds-hljs) to activate the highlighter.

For example, to use highlight.js to highlight all code blocks:

npm install -g markdown-styles mds-hljs
generate-md --highlight mds-hljs ...

You will also need to include one of the highlight.js CSS style sheets in your assets folder/layout file CSS (e.g. by using a custom --layout file).

Template Evaluation

The handlebars.js template language is used to evaluate both the template and the markdown. Together with the meta.json, partials and helpers both template and markdown can be enhanced.

`meta.json`

You can add a file named meta.json to the folder from which you run generate-md.

The metadata in that directory will be read and replacements will be made for corresponding `` in the template.

The metadata is scoped by the top-level directory in ./input.

For example:

{
  "foo": {
    "repoUrl": "https://github.com/mixu/markdown-styles"
  }
}

would make the metadata value `` available in the template, for all files that are in the directory ./input/foo.

Using handlebars.js we can go event farther. For example, you may add a tags array to the meta.json:

{
  "foo": {
    "tags": ["handlebars", "template"]
  }
}

While in the html you may:

<ul>

    <li></li>

</ul>

Which will result in

<ul>
    <li>handlebars</li>
    <li>template</li>
</ul>

Partials

Partials are html files that can be included via handlebars style. Usually they are .html files. For example, if `footer.html` resides in the partials directory, will be replaced with footer.html’s content. For more advanced topics, see handlebars partials documentation. Don’t use content.html, it is reserved to the html generated from the markdown.

Helpers

Helpers are functions that you can use throughout the template. See handlebars helpers .
For example, add linkTo.js to the specified helpers directory:

var Handlebars = require('handlebars');
module.exports = function(){
  return new Handlebars.SafeString("<a href='" + Handlebars.Utils.escapeExpression(this.url) + "'>" + Handlebars.Utils.escapeExpression(this.body) + "</a>");
};

In your meta.json json { "foo": { "links": [ {"url": "/hello", "body": "Hello"}, {"url": "/world", "body": "World!"} ] } }
Somewhere in your template:
```html


The result:
```html
<ul>
  <li>
    <a href='/hello'>Hello</a>
  </li>
  <li>
    <a href='/world'>World!</a>
  </li>
</ul>

Language-specific syntax highlighting and custom highlighters

You can use --highlight-<language> <module> to override the syntax highlighter for a specific language. <module> can also be a path to a file.

For example, you might use the mds-csv highlighter for csv code blocks. Input code block with language:

```csv
"EmployeeID","EmployeeName","PhoneNumber","ZipCode"
"1048","Jimmy Adams",5559876543,12345
```

Command:

generate-md --highlight-csv mds-csv ...

You can write your own syntax highlighter wrappers. Have a look at mds-hljs and mds-csv for examples. These come in two flavors:

Asynchronous (three parameters):

module.exports = function(code, lang, onDone) {
    return onDone(null, result);
};

Synchronous (two parameters):

module.exports = function(code, lang) {
    return require('highlight.js').highlightAuto(code).value;
};

–command

--command <cmd>: Pipe each Markdown file through a shell command and capture the output before converting. Useful for filtering the file, for example.

–asset-dir

--asset-dir <path>: Normally, the asset directory is assumed to be ./assets/ in the same folder the --layout file is. You can override it to a different asset directory explicitly with --asset-dir, which is useful for builds where several directories use the same layout but different asset directories.

Acknowledgments

I’d like to thank the authors the following CSS stylesheets:

jasonm23-dark, jasonm23-foghorn, jasonm23-markdown and jasonm23-swiss are based on https://github.com/jasonm23/markdown-css-themes by jasonm23
thomasf-solarizedcssdark and thomasf-solarizedcsslight are based on https://github.com/thomasf/solarized-css by thomasf
markedapp-byword is based on the user-contributed stylesheet at http://bywordapp.com/extras/
roryg-ghostwriter is based on https://github.com/roryg/ghostwriter
github is based on sindresorhus/github-markdown-css (sorry, sindresorhus-github is too long to type as a layout name!)

Screenshots of the layouts

Note: these screenshots are generate via cutycapt, so they look worse than they do in a real browser.

roryg-ghostwriter

mixu-bootstrap

mixu-bootstrap-2col

mixu-gray

jasonm23-dark

jasonm23-foghorn

jasonm23-markdown

jasonm23-swiss

markedapp-byword

mixu-book

mixu-page

mixu-radar

thomasf-solarizedcssdark

thomasf-solarizedcsslight

bootstrap3

Adding new styles

Create a new directory under ./output/themename.

If a file called ./layouts/themename/page.html exists, it is used, otherwise the default footer and header in ./layouts/plain/ are used.

The switcher is an old school frameset, you need to add a link in ./output/menu.html.

To regenerate the pages, you need node:

git clone git://github.com/mixu/markdown-styles.git
npm install
make build

To regenerate the screenshots, you need cutycapt (or some other Webkit to image tool) and imagemagic. On Ubuntu / Debian, that’s:

sudo aptitude install cutycapt imagemagick

You also need to install the web fonts locally so that cutycapt will find them, run node font-download.js to get the commands you need to run (basically a series of wget and fc-cache -fv commands).

Finally, run:

make screenshots

Markdown Styles was originally published by Katie Ball at MY NOTEPAD on December 29, 2014.

Quick & Dirty Guide to Vim

2014-12-27T00:00:00+11:00

In the world of text editors, there’s a plethora of options out there. If you’ve ever Googled “how to edit HTML sites” or some such, you know what we mean. Allow us, then, to introduce you to VIM, a free website editor that offers many of the same features as Adobe Dreamweaver, and runs on just about every desktop platform. Specifically, it comes by default on the vast majority of Linux distributions, OS X and commercial Unix systems. (It’s available to install on Windows, too.) And did we mention it’s free? That command line UI isn’t necessarily self-explanatory, though, so join us after the break for a quick crash course to help you get started.

Getting started

If you’re running OS X or Linux, start out by opening a terminal. Now type “vim” et voilÃ : you’re using VIM and you didn’t even install it. Using Windows? Head over here and grab the binaries for Windows. Double-click the installer and you’ll have VIM on Windows in no time.

What’s VIM?

VIM is a file editor that supports multiple formats. It’s been around for two decades and is used by millions of programmers, hackers and system administrators. For starters, let’s get the obvious question answered: “Why would I want to use VIM instead of … ?” Put it this way: if you’re a web programmer and love Dreamweaver and it does everything you need, great. However it’d behoove you to give VIM a shot, because it takes many features offered by Dreamweaver, a $400 product, and offers them for free. As it happens, it’s also easy to use once you get the hang of it. Yes, that command line interface might seem complex at first blush, but as with any complex piece of software, you can learn to use it and use it well.

What am I looking at?

VIM is sometimes referred to as a dual-mode text editor. To put it plainly, VIM has two modes in which you can manipulate files: Edit and GUI mode. Edit mode is the state in which the keys you bang on are actually inserted into your document, whereas the GUI layout allows you to navigate through the document, search and replace text, copy and paste, etc. By default when you open a file, you’re placed in GUI mode.

Basic commands

To navigate VIM you use a cursor, but instead of dragging and clicking your mouse, you’ll have to learn to use the arrow buttons as a kind of crude D-pad. Or, depending on where your hands are resting on the keyboard, you can use the “H, K, J and L” keys to move around. Here’s how it breaks down: “H” moves left; “K” moves up; “L” moves right; “J” moves down. You can, of course, use the arrow keys as well. Got it? Good.

Editing documents

As we said, VIM launches into the GUI mode by default. To switch to edit mode (also called “insert mode”) you need to give VIM a command to tell it to switch modes. There are two ways to do this:

Press “i” to begin inserting text at the current cursor position
Press “a” to begin inserting after the current cursor position.

Getting out of editing mode is a bit more intuitive: just hit “escape.”

Got a handle on those three? Here are some other commands in GUI mode. And remember, these letters are case-sensitive, so take note of those stray capital letters:

“Y” copies a line of text to the buffer.
“P” pastes it to the cursor’s current position.
“dd” will delete the whole line of text. This will also effectively “cut” a line of text as well. When you delete a line, it’s placed in the buffer.
“yy” copies a whole line of text.

Typing commands in GUI mode

So you’ve mastered basic shortcuts in VIM. But what if you want to give the program a more specific command – like, say, copying four lines of text? Here’s what you need to know.

For starters, move the cursor to the beginning of where you’d like to copy. (Remember that you can use the arrow keys or the “H, K, J and L” buttons.) Press the “:” button to bring up the command line in the bottom of your VIM window. Type “y4” and press “enter.”

VIM will tell you “4 lines yanked.”

Move the cursor to where you want to begin your paste, then press “P”. Basically, that breaks down as “yN” where “N” equals the number of lines you wish to copy. You can do the same thing with the delete command, “d”.

Search and replace

Moving on, if you want to search and replace from GUI mode, start off by hitting the “:” button once again to bring up that familiar prompt at the bottom of the editor. Then type “%s/text to search for/text to replace/g”.

Let’s replace all instances of “Jack” with “John” in the example below.

Type “:%s/Jack/John/g”.

And that’s it: all instances of “Jack” are now replaced with “John”.

Undo

Let’s scrap what we just did and search and replace on one line. You naturally need an “undo” function in a modern-day editor. Don’t worry, VIM has one. To reverse some edit you made, make sure you’re in GUI mode and hit “u”.

Now, say you only want to replace something on a specific line. You can do that quickly without having to hold down an arrow key to move your cursor. Just bring up the command (using the “:” key, of course) and type the line number you wish to go to. For example: “:15”.

Now just search and replace without the percent sign. That “%” symbol essentially means you want to search the whole document; when you don’t use it, you are only searching the line your cursor is currently on.

What if you don’t know the exact line number what you want to search for? You can also just search for a specific term. To trawl the document, make sure you’re in GUI mode and type a forward slash. For example, let’s search for someone who is 9 feet 6 inches tall (9’6”) in our data file. To do this, just type “/9’6”” and press Enter.

This will automatically move your cursor to the first instance of “9’6”” that it finds. Press Enter again and it’ll move to the next instance.

Save your work

To save your work, the most important part of editing files, you’ll need to give VIM the command to do it. From good ol’ GUI mode type “:w” and press enter. File saved. Wanna save and quit VIM at the same time? Typing “:wq” will do the trick.

What if you want to quit without saving? Type “:q!” And remember to include that exclamation point – it’s required because VIM will let you know you’ve made changes to the file, and doesn’t want you to potentially lose any work. By using the exclamation point you’re insisting to VIM that you know what you’re doing.

Syntax highlighting

You aren’t always going to be editing simple text files – maybe, just maybe you’ll whip up that family website everyone’s been asking for. Naturally, you’re going to want a look that’s a bit easier on the eyes. VIM fully supports colored syntax highlighting for multiple programming languages. There are even different color themes.

In the below example we’re going to be looking at a Perl script.

That plain text is hard to see, especially if you’ve been staring at it for a few hours. From GUI mode, type “:syntax on”.

Much better.

Don’t like the current color palette? We can change that as well: VIM comes loaded with a handful of different schemes. To pick one from GUI mode, type “:colorscheme” and press the Tab key repeatedly to cycle through the available schemes. Press Enter when you see one that strikes your fancy.

Editing files remotely

If you’re working with a remote web server and need to edit a file over FTP, VIM supports this.
You can do this via “vim ftp:////”. For example: “vim ftp://172.16.15.73//Users/john/test.pl”. (Note the double “//” in the example.)

VIM will then prompt you for the username and password for the remote file server.

Magically, you’re editing the remote file.

How to save your settings

So you’ve taken the time to pick your color scheme and turn syntax highlighting on. You’ve saved your file, closed VIM and taken a coffee break. Well, when you come back and load up VIM again, your highlighting is gone and you don’t have your favorite color scheme loaded.

You’ll need to save your settings in the VIM config file ( _vimrc on Windows; .vimrc on all other platforms). Place this file in your standard home directory. To find out what your home directory is from within VIM, do this:

From GUI mode type “:echo $home” and press Enter. VIM will then show the full directory path of where you should place your vimrc file.

To save your settings in your vimrc file, simply add the commands you used to set up your VIM environment in that file. For example, to keep syntax highlighting on by default and always use the color scheme “delek,” add this to your vimrc file:

:syntax on
:colorscheme delek

Work complete.

Wrap-up

This quick-and-dirty guide should get you up and running with VIM. There’s much more to this powerful editor, though. We recommend taking the full VIM tutorial by typing “:help” and reading through the VIM guide. If you have even more time on your hands, there are also tons of scripts (read: plugins) available for VIM in case the stock deployment doesn’t do that odd thing you need. You can browse all 4,000-plus. Happy editing!

Quick & Dirty Guide to Vim was originally published by Katie Ball at MY NOTEPAD on December 27, 2014.

GIT Aliases Explained

2014-12-22T00:00:00+11:00

Intro to Git Aliases

An alias is simply a way to add a shorthand for a common Git command or set of Git commands. Some are quite simple. For example, here’s a common one:

git config --global alias.co checkout

This sets co as an alias for checkout. If you open up your .gitconfig file, you can see this in a section named alias.

[alias]
    co = checkout

With this alias, you can checkout a branch by using git co some-branch instead of git checkout some-branch. Since I often edit aliases by hand, I have one that opens the gitconfig file with my default editor.

    ec = config --global -e

These sort of simple aliases only begin to scratch the surface.

GitHub Flow Aliases

Get my working directory up to date.

When I’m ready to start some work, I always do the work in a new branch. But first, I make sure that my working directory is up to date with the origin before I create that branch. Typically, I’ll want to run the following commands:

git pull --rebase --prune
git submodule update --init --recursive

The first command pulls changes from the remote. If I have any local commits, it’ll rebase them to come after the commits I pulled down. The --prune option removes remote-tracking branches that no longer exist on the remote.

This combination is so common, I’ve created an alias up for this.

    up = !git pull --rebase --prune $@ && git submodule update --init --recursive

Note that I’m combining two git commands together. I can use the ! prefix to execute everything after it in the shell. This is why I needed to use the full git commands. Using the ! prefix allows me to use any command and not just git commands in the alias.

Starting new work

At this point, I can start some new work. All new work starts in a branch so I would typically use git checkout -b new-branch. However I alias this to cob to build upon co.

    cob = checkout -b

Note that this simple alias is expanded in place. So to create a branch named “emoji-completion” I simply type git cob emoji-completion which expands to git checkout -b emoji-completion.

With this new branch, I can start writing the crazy codes. As I go along, I try and commit regularly with my cm alias.

    cm = !git add -A && git commit -m

For example, git cm "Making stuff work". This adds all changes including untracked files to the index and then creates a commit with the message “Making Stuff Work”.

Sometimes, I just want to save my work in a commit without having to think of a commit message. I could stash it, but I prefer to write a proper commit which I will change later.

git save or git wip. The first one adds all changes including untracked files and creates a commit. The second one only commits tracked changes. I generally use the first one.

    save = !git add -A && git commit -m 'SAVEPOINT'
    wip = !git add -u && git commit -m "WIP"

When I return to work, I’ll just use git undo which resets the previous commit, but keeps all the changes from that commit in the working directory.

    undo = reset HEAD~1 --mixed

Or, if I merely need to modify the previous commit, I’ll use git amend

    amend = commit -a --amend

The -a adds any modifications and deletions of existing files to the commit but ignores brand new files. The --amend launches your default commit editor (Notepad in my case) and lets you change the commit message of the most recent commit.

A proper reset

There will be times when you explore a promising idea in code and it turns out to be crap. You just want to throw your hands up in disgust and burn all the work in your working directory to the ground and start over.

In an attempt to be helpful, people might recommend: git reset HEAD --hard.

Slap those people in the face. It’s a bad idea. Don’t do it!

That’s basically a delete of your current changes without any undo. As soon as you run that command, Murphy’s law dictates you’ll suddenly remember there was that one gem among the refuse you don’t want to rewrite.

Too bad. If you reset work that you never committed it is gone for good. Hence, the wipe alias.

    wipe = !git add -A && git commit -qm 'WIPE SAVEPOINT' && git reset HEAD~1 --hard

This commits everything in my working directory and then does a hard reset to remove that commit. The nice thing is, the commit is still there, but it’s just unreachable. Unreachable commits are a bit inconvenient to restore, but at least they are still there. You can run the git reflog command and find the SHA of the commit if you realize later that you made a mistake with the reset. The commit message will be “WIPE SAVEPOINT” in this case.

Completing the pull request

While working on a branch, I regularly push my changes to GitHub. At some point, I’ll go to github.com and create a pull request, people will review it, and then it’ll get merged. Once it’s merged, I like to tidy up and delete the branch via the Web UI. At this point, I’m done with this topic branch and I want to clean everything up on my local machine. Here’s where I use one of my more powerful aliases, git bdone.

This alias does the following.

Switches to master (though you can specify a different default branch)
Runs git up to bring master up to speed with the origin
Deletes all branches already merged into master using another alias, git bclean

It’s quite powerful and useful and demonstrates some advanced concepts of git aliases. But first, let me show git bclean. This alias is meant to be run from your master (or default) branch and does the cleanup of merged branches.

bclean = "!f() { git branch --merged ${1-master} | grep -v " ${1-master}$" | xargs -r git branch -d; }; f"

If you’re not used to shell scripts, this looks a bit odd. What it’s doing is defining a function and then calling that function. The general format is !f() { /* git operations */; }; f We define a function named f that encapsulates some git operations, and then we invoke the function at the very end.

What’s cool about this is we can take advantage of arguments to this alias. In fact, we can have optional parameters. For example, the first argument to this alias can be accessed via $1. But suppose you want a default value for this argument if none is provided. That’s where the curly braces come in. Inside the braces you specify the argument index ($0 returns the whole script) followed by a dash and then the default value.

Thus when you type git bclean the expression ${1-master} evaluates to master because no argument was provided. But if you’re working on a GitHub pages repository, you’ll probably want to call git bclean gh-pages in which case the expression ${1-master} evaluates to gh-pages as that’s the first argument to the the alias.

Let’s break down this alias into pieces to understand it.

git branch --merged ${1-master} lists all the branches that have been merged into the specify branch (or master if none is specified). This list is then piped into the grep -v "${1-master}" command. Grep prints out lines matching the pattern. The -v flag inverts the match. So this will list all merged branches that are not master itself. Finally this gets piped into xargs which takes the standard input and executes the git branch -d line for each line in the standard input which is piped in from the previous command.

In other words, it deletes every branch that’s been merged into master except master. I love how we can compose these commands together.

With bclean in place, I can compose my git aliases together and write git bdone.

    bdone = "!f() { git checkout ${1-master} && git up && git bclean ${1-master}; }; f"

I use this one all the time when I’m deep in the GitHub flow. And now, you too can be a GitHub flow master.

The List

Here’s a list of all the aliases together for your convenience.

[alias]
    co = checkout
    ec = config --global -e
    up = !git pull --rebase --prune $@ && git submodule update --init --recursive
    cob = checkout -b
    cm = !git add -A && git commit -m
    save = !git add -A && git commit -m 'SAVEPOINT'
    wip = !git add -u && git commit -m "WIP" 
	undo = reset HEAD~1 --mixed
    amend = commit -a --amend
    wipe = !git add -A && git commit -qm 'WIPE SAVEPOINT' && git reset HEAD~1 --hard
    bclean = "!f() { git branch --merged ${1-master} | grep -v " ${1-master}$" | xargs -r git branch -d; }; f"
    bdone = "!f() { git checkout ${1-master} && git up && git bclean ${1-master}; }; f"

Credits and more reading

It would be impossible to source every git alias I use as many of these are pretty common and I’ve adapted them for my own needs. However, here are a few blog posts that provided helpful information about git aliases that served as my inspiration. I also added a couple posts about how GitHub uses pull requests.

Git Aliases Parameters taught me how to specify a default value for positional parameters.
Delete already merged branches was the inspiration for git bclean.
Aliases Git Wiki Page has a bunch of useful aliases.
How GitHub uses Pull Requests
How GitHub uses GitHub to build GitHub

GIT Aliases Explained was originally published by Katie Ball at MY NOTEPAD on December 22, 2014.

Vim Cheatsheet

2014-12-21T00:00:00+11:00

Movement

By “Word”

w forward to beginning of the next word
W forward to beginning of the next word (whitespace separates)
e forward to end of next word
E forward to end of next word (whitespace separates)
b back to beginning of the previous word
B back to beginning of the previous word (whitespace separates)
ge back to end of the next word
gE back to end of the next word (whitespace separates)

Searching

On current line

fn find and move to the next occurrence of n. You can follow this with a ; to repeat the find/move. You can also use , to go back one match.
tn find and move to (until) the character preceding the next occurrence of n. As above, ; repeats, and , goes back one match.
Fn find and move to the previous occurrence of n. ; repeats, , goes back one match.
Tn find and move to (unTil) the character following the next occurence of n. ; repeats, , goes back one match.

In document

/term search forwards for term
?term search backwards for term

Combining with other commands

cfn - change the text up to where you find the next occurrence of n
cFn - change the text back to where you Find the previous occurrence of n

By page/screen

^f forward a page/screen
^b back a page/screen
^u up half a page/screen
^d down half a page/screen

Positioning within a page/screen

H go to Head (top) or “High point” of screen
M go to Middle of screen
L go to Last line or “Low point” of screen

Positioning within a document/file

gg first line of document
G last line of document
500G line 500
* search forwards for word currently under cursor (use with n and N)
# search backward for word currently under cursor (use with N and n - note that direction is reversed)
% matching bracket, brace, square bracket - see matchit.vim for extended behavior

Marks

ma set position of (book)mark a
:marks list currently defined marks
'a jump to rot for mark a
```a jump to row/column for mark a`

Editing

i insert at cursor
I insert at beginning of line
a append after cursor
A append at end of line
r replace a single character
R replace any number of characters
c<motion> change, e.g. cw is change word
x delete character under cursor
X delete character before cursor
d<motion> delete, e.g. dw is delete word, dd is delete line

Copy/Cut & Paste

See http://vim.wikia.com/wiki/VimTip386 for more detailed info.

press v (for visual mode) to start the selection (or V to select whole lines, or Ctrl-v for a vertical block)
move the cursor to where you want the selection to end
press d for delete (cut) or y for yank (copy)
position the cursor where you want to paste
press P or p for paste before or after cursor, respectively

Buffers

For an excellent tutorial, see http://reefpoints.dockyard.com/2013/10/22/vim-buffers.html

add a buffer: :badd
list open buffers: :ls
switch to alternate (#) buffer: CTRL+6
switch to previous buffer: :bp
switch to next buffer: :bn
switch to buffer x (where x is an integer): :bx
delete (close) current buffer: :bd
delete (close) buffers x and y: :bd x y

Windows

For another excellent tutorial, see http://reefpoints.dockyard.com/2013/11/27/vim-windows.html

split current window: CTRL+w s
split current window vertically: CTRL+w v
switch to window to left: CTRL+w h
switch to window to right: CTRL+w l
switch to window above: CTRL+w k
switch to window below: CTRL+w j
rotate windows: CTRL+w r
rotate windows (opposite direction): CTRL+w R
move current window the far left and use the full height of the screen: CTRL-w H
move current window the far bottom and use the full width of the screen: CTRL-w J
move current window the far top and full width of the screen: CTRL-w K
move current window the far right and full height of the screen: CTRL-w L
resize the windows equally : CTRL-w =
incrementally increase the window to the right: CTRL-w >
takes a parameter, e.g. CTRL-w 20 >
incrementally increase the window to the left: CTRL-w <
takes a parameter, e.g. CTRL-w 20 <
incrementally decrease the window’s height: CTRL-w -
takes a parameter, e.g. CTRL-w 10 -
incrementally increase the window’s height: CTRL-w +
takes a parameter, e.g. CTRL-w 10 +

Vim Cheatsheet was originally published by Katie Ball at MY NOTEPAD on December 21, 2014.

Github Markdown Versus Standard

2014-12-20T00:00:00+11:00

Markdown

GitLab Flavored Markdown

Newlines
Multiple underscores in words
URL autolinking
Code and Syntax Highlighting
Emoji
Special GitLab references
Task lists

Standard Markdown

Headers
Emphasis
Lists
Links
Images
Blockquotes
Inline HTML
Horizontal Rule
Line Breaks
Tables

References

GitLab Flavored Markdown (GFM)

For GitLab we developed something we call “GitLab Flavored Markdown” (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality.

You can use GFM in

commit messages
comments
issues
merge requests
milestones
wiki pages

You can also use other rich text files in GitLab. You might have to install a depency to do so. Please see the github-markup gem readme for more information.

Newlines

GFM honors the markdown specification in how paragraphs and line breaks are handled.

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.:

Roses are red
Violets are blue

Sugar is sweet

Roses are red
Violets are blue

Sugar is sweet

Multiple underscores in words

It is not reasonable to italicize just part of a word, especially when you’re dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words.

perform_complicated_task
do_this_and_do_that_and_another_thing

perform_complicated_task
do_this_and_do_that_and_another_thing

URL autolinking

GFM will autolink standard URLs you copy and paste into your text. So if you want to link to a URL (instead of a textural link), you can simply put the URL in verbatim and it will be turned into a link to that URL.

http://www.google.com

http://www.google.com

Code and Syntax Highlighting

Blocks of code are either fenced by lines with three back-ticks ```, or are indented with four spaces. Only the fenced code blocks support syntax highlighting.

no-highlight Inline `code` has `back-ticks around` it.

Inline code has back-ticks around it.

Example:

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s
```

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

```
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
```

becomes:

var s = "JavaScript syntax highlighting";
alert(s);

def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.

Emoji

Sometimes you want to be a :ninja: and add some :glowing_star: to your <img class='emoji' title=':speech_balloon:' alt=':speech_balloon:' src='https://assets.github.com/images/icons/emoji/unicode/1f4ac.png' height='20' width='20' align='absmiddle' />. Well we have a gift for you:

:high_voltage_sign: You can use emoji anywhere GFM is supported. :victory_hand:

You can use it to point out a <img class='emoji' title=':bug:' alt=':bug:' src='https://assets.github.com/images/icons/emoji/unicode/1f41b.png' height='20' width='20' align='absmiddle' /> or warn about :speak_no_evil_monkey: patches. And if someone improves your really <img class='emoji' title=':snail:' alt=':snail:' src='https://assets.github.com/images/icons/emoji/unicode/1f40c.png' height='20' width='20' align='absmiddle' /> code, send them some <img class='emoji' title=':cake:' alt=':cake:' src='https://assets.github.com/images/icons/emoji/unicode/1f370.png' height='20' width='20' align='absmiddle' />. People will <img class='emoji' title=':heart:' alt=':heart:' src='https://assets.github.com/images/icons/emoji/unicode/2764.png' height='20' width='20' align='absmiddle' /> you for that.

If you are new to this, don't be :fearful_face:. You can easily join the emoji <img class='emoji' title=':family:' alt=':family:' src='https://assets.github.com/images/icons/emoji/unicode/1f46a.png' height='20' width='20' align='absmiddle' />. All you need to do is to look up on the supported codes.

Consult the [Emoji Cheat Sheet](https://www.dropbox.com/s/b9xaqb977s6d8w1/cheat_sheet.pdf) for a list of all supported emoji codes. <img class='emoji' title=':thumbsup:' alt=':thumbsup:' src='https://assets.github.com/images/icons/emoji/unicode/1f44d.png' height='20' width='20' align='absmiddle' />

Sometimes you want to be a :ninja: and add some :glowing_star: to your . Well we have a gift for you:

:high_voltage_sign: You can use emoji anywhere GFM is supported. :victory_hand:

You can use it to point out a or warn about :speak_no_evil_monkey: patches. And if someone improves your really code, send them some . People will you for that.

If you are new to this, don’t be :fearful_face:. You can easily join the emoji . All you need to do is to look up on the supported codes.

Consult the Emoji Cheat Sheet for a list of all supported emoji codes.

Special GitLab References

GFM recognized special references.

You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project.

GFM will turn that reference into a link so you can navigate between them easily.

GFM will recognize the following:

@foo : for team members
@all : for the whole team
123 : for issues
!123 : for merge requests
$123 : for snippets
1234567 : for commits
[file](path/to/file) : for file references

GFM also recognizes references to commits, issues, and merge requests in other projects:

namespace/project#123 : for issues
namespace/project!123 : for merge requests
namespace/project@1234567 : for commits

Task Lists

You can add task lists to merge request and issue descriptions to keep track of to-do items. To create a task, add an unordered list to the description in an issue or merge request, formatted like so:

no-highlight * [x] Completed task * [ ] Unfinished task * [x] Nested task

Task lists can only be created in descriptions, not in titles or comments. Task item state can be managed by editing the description’s Markdown or by clicking the rendered checkboxes.

Standard Markdown

Headers

```no-highlight
# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1

Alt-H2


# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------

### Header IDs and links

All markdown rendered headers automatically get IDs, except for comments.

On hover a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else.

The IDs are generated from the content of the header according to the following rules:

1. remove the heading hashes `#` and process the rest of the line as it would be processed if it were not a header
2. from the result, remove all HTML tags, but keep their inner content
3. convert all characters to lowercase
4. convert all characters except `[a-z0-9_-]` into hyphens `-`
5. transform multiple adjacent hyphens into a single hyphen
6. remove trailing and heading hyphens

For example:

###### ..Ab_c-d. e anchor ..
```

which renders as:

..Ab_c-d. e anchor ..

will first be converted by step 1) into a string like:

..Ab_c-d. e &lt;a href="url">anchor&lt;/a> &lt;img src="url" alt="alt text"/>..

After removing the tags in step 2) we get:

..Ab_c-d. e anchor ..

And applying all the other steps gives the id:

ab_c-d-e-anchor

Note in particular how:

for markdown anchors [text](url), only the text is used
markdown images ![alt](url) are completely ignored

Emphasis

```no-highlight
Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. ~~Scratch this.~~
```

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. ~~Scratch this.~~

Lists

```no-highlight
1. First ordered list item
2. Another item
* Unordered sub-list.
1. Actual numbers don’t matter, just that it’s a number
1. Ordered sub-list
4. And another item.

Some text that should be aligned with the above item.

Unordered list can use asterisks
Or minuses
Or pluses
```

First ordered list item
Another item
- Unordered sub-list.
Actual numbers don’t matter, just that it’s a number
Ordered sub-list
And another item.

Some text that should be aligned with the above item.

Unordered list can use asterisks
Or minuses
Or pluses

Links

There are two ways to create links, inline-style and reference-style.

[I'm an inline-style link](https://www.google.com)

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself][]

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

I’m an inline-style link

I’m a reference-style link

I’m a relative reference to a repository file

You can use numbers for reference-style link definitions

Or leave it empty and use the link text itself

Some text to show that the reference links can follow later.

Note

Relative links do not allow referencing project files in a wiki page or wiki page in a project file. The reason for this is that, in GitLab, wiki is always a separate git repository. For example:

[I'm a reference-style link][style]

will point the link to wikis/style when the link is inside of a wiki markdown file.

Images

Here's our logo (hover to see the title text):

Inline-style:
![alt text](assets/logo-white.png)

Reference-style:
![alt text1][logo]

[logo]: assets/logo-white.png

Here’s our logo:

Inline-style:

Reference-style:

Blockquotes

```no-highlight
> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.
```

Blockquotes are very handy in email to emulate reply text.
This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.

Inline HTML

You can also use raw HTML in your Markdown, and it’ll mostly work pretty well.

```no-highlight

Definition list: Is something people use sometimes.
Markdown in HTML: Does *not* work **very** well. Use HTML tags.


<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>

## Horizontal Rule

Three or more…

Hyphens

Asterisks

Underscores
```

Three or more…

Hyphens

Asterisks

Underscores

Line Breaks

My basic recommendation for learning how line breaks work is to experiment and discover – hit <Enter> once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You’ll soon learn to get what you want. “Markdown Toggle” is your friend.

Here are some things to try out:

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.

Here’s a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also begins a separate paragraph, but…
This line is only separated by a single newline, so it’s a separate line in the same paragraph.

Tables

Tables aren’t part of the core Markdown spec, but they are part of GFM and Markdown Here supports them.

| header 1 | header 2 |
| -------- | -------- |
| cell 1   | cell 2   |
| cell 3   | cell 4   |

Code above produces next output:

header 1	header 2
cell 1	cell 2
cell 3	cell 4

Note

The row of dashes between the table header and body must have at least three dashes in each column.

References

This document leveraged heavily from the Markdown-Cheatsheet.
The Markdown Syntax Guide at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
Dillinger.io is a handy tool for testing standard markdown.

Github Markdown Versus Standard was originally published by Katie Ball at MY NOTEPAD on December 20, 2014.

SSL Upgrades on Rugy Gems

2014-12-18T00:00:00+11:00

SSL upgrades on rubygems.org and RubyInstaller versions

Hello,

If you reached this page, means you’ve hit this SSL error when trying to
pull updates from RubyGems:

SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

This error is produced by changes in rubygems.org infrastructure, please
keep reading to better understand it.

If you’re one of those too long, didn’t read just skip to the guide on how
to workaround it.

Background

For those who are not familiar with SSL and certificates, there are many
parts that make secure serving of content possible.

SSL certificates are used on the website, which are obtained from a
certificate authority (CA) and generated from a private key, along with its
respective signature.

Normally and up until a few months ago, private key signatures used SHA-1
as way to provide a digest (or checksum) of the private key without
distributing the key itself (remember, needs to remain private).

SHA-1 has been encountered weak and lot of web servers and sites have been
upgrading towards SHA-2 (specifically SHA256 or higher) in order to prepare
for the browsers changes.

Specific problem with RubyGems

The particular case of RubyGems (the command line tool) is that it requires
to bundle inside of its code the trust certificates, which allow RubyGems
to establish a connection with the servers even when base operating system
is unable to verify the identity of them.

Up until a few months ago, this certificate was provided by one CA, but
newer certificate is provided by a different one.

Because of this, existing installations of RubyGems would have to been
updated before the switch of the certificate and give enough time for the
change to spread (and people to update).

As what normally happens with software, things might get out of sync and
coordinate such effort, to the size and usage of rubygems.org is almost
impossible.

I’ve described this on Issue #1050

We had discussed also on IRC, and patches and backports were provided to
all major branches of RubyGems: 1.8, 2.0, 2.2 and 2.4

You can find the commits associated with these changes here:

Problem is, only RubyGems 2.4.4 got released, leaving Ruby installation with
1.8, 2.0 and 2.2 in a broken state.

Specially since RubyGems 2.4 is broken on Windows.

Please understand this could happen to anyone. Release multiple versions of any software in a short span of time and be very time sensitive is highly
complicated.

Even if we have official releases of any of the versions that correct the
issue, it will not be possible install those via RubyGems (chicken-egg
problem described before).

Once official releases are out, installation might be simpler. In the
meantime, please proceed using the instructions described below.

Manual solution to SSL issue

If you have read the above detail that describe the issue, thank you.

Now, you want to manually fix the issue with your installation.

Steps are simple:

Step 1: Obtain the new trust certificate
Step 2: Locate RubyGems certificate directory in your installation
Step 3: Copy new trust certificate
Step 4: Profit

Step 1: Obtain the new trust certificate

If you’ve read the previous sections, you will know what this means (and
shame on you if you have not).

We need to download AddTrustExternalCARoot-2048.pem.

Use the above link and place/save this file somewhere you can later find
easily (eg. your Desktop).

IMPORTANT: File must have .pem as extension. Browsers like Chrome will
try to save it as plain text file. Ensure you change the filename to have .pem in it after you have downloaded it.

Step 2: Locate RubyGems certificate directory in your installation

In order for us copy this file, we need to know where to put it.

Depending on where you installed Ruby, the directory will be different.

Take for example the default installation of Ruby 2.1.5, placed in C:\Ruby21

Open a Command Prompt and type in:

C:\>gem which rubygems
C:/Ruby21/lib/ruby/2.1.0/rubygems.rb

Now, let’s locate that directory. From within the same window, enter the path
part up to the file extension, but using backslashes instead:

C:\>start C:\Ruby21\lib\ruby\2.1.0\rubygems

This will open a Explorer window inside the directory we indicated.

Step 3: Copy new trust certificate

Now, locate ssl_certs directory and copy the .pem file we obtained from
previous step inside.

It will be listed with other files like GeoTrustGlobalCA.pem.

Step 4: Profit

There is actually no step 4. You should be able to install Ruby gems without
issues now.

SSL Upgrades on Rugy Gems was originally published by Katie Ball at MY NOTEPAD on December 18, 2014.

Robots.txt Please Explain

2014-12-13T00:00:00+11:00

The Web Robots Pages

About /robots.txt

In a nutshell

Web site owners use the /robots.txt file to give instructions about their site to web robots; this is called The Robots Exclusion Protocol.

It works likes this: a robot wants to vists a Web site URL, say http://www.example.com/welcome.html. Before it does so, it firsts checks for http://www.example.com/robots.txt, and finds:

User-agent: *
Disallow: /

The “User-agent: *” means this section applies to all robots. The “Disallow: /” tells the robot that it should not visit any pages on the site.

There are two important considerations when using /robots.txt:

robots can ignore your /robots.txt. Especially malware robots that scan the web for security vulnerabilities, and email address harvesters used by spammers will pay no attention.
the /robots.txt file is a publicly available file. Anyone can see what sections of your server you don’t want robots to use.

So don’t try to use /robots.txt to hide information.

The details

The /robots.txt is a de-facto standard, and is not owned by any standards body. There are two historical descriptions:

In addition there are external resources:

The /robots.txt standard is not actively developed. See What about further development of /robots.txt? for more discussion.

The rest of this page gives an overview of how to use /robots.txt on your server, with some simple recipes. To learn more see also the FAQ.

How to create a /robots.txt file

Where to put it

The short answer: in the top-level directory of your web server.

The longer answer:

When a robot looks for the “/robots.txt” file for URL, it strips the path component from the URL (everything from the first single slash), and puts “/robots.txt” in its place.

For example, for “http://www.example.com/shop/index.html, it will remove the “/shop/index.html”, and replace it with “/robots.txt”, and will end up with “http://www.example.com/robots.txt”.

So, as a web site owner you need to put it in the right place on your web server for that resulting URL to work. Usually that is the same place where you put your web site’s main “index.html” welcome page. Where exactly that is, and how to put the file there, depends on your web server software.

Remember to use all lower case for the filename: “robots.txt”, not “Robots.TXT.

What to put in it

The “/robots.txt” file is a text file, with one or more records. Usually contains a single record looking like this:

User-agent: *
Disallow: /cgi-bin/
Disallow: /tmp/
Disallow: /~joe/

In this example, three directories are excluded.

Note that you need a separate “Disallow” line for every URL prefix you want to exclude – you cannot say “Disallow: /cgi-bin/ /tmp/” on a single line. Also, you may not have blank lines in a record, as they are used to delimit multiple records.

Note also that globbing and regular expression are not supported in either the User-agent or Disallow lines. The ‘’ in the User-agent field is a special value meaning “any robot”. Specifically, you cannot have lines like “User-agent: *bot”, “Disallow: /tmp/*” or “Disallow: *.gif”.

What you want to exclude depends on your server. Everything not explicitly disallowed is considered fair game to retrieve. Here follow some examples:

To exclude all robots from the entire server

User-agent: *
Disallow: /

To allow all robots complete access

User-agent: *
Disallow:

(or just create an empty “/robots.txt” file, or don’t use one at all)

To exclude all robots from part of the server

User-agent: *
Disallow: /cgi-bin/
Disallow: /tmp/
Disallow: /junk/

To exclude a single robot

User-agent: BadBot
Disallow: /

To allow a single robot

User-agent: Google
Disallow:

User-agent: *
Disallow: /

To exclude all files except one

This is currently a bit awkward, as there is no “Allow” field. The easy way is to put all files to be disallowed into a separate directory, say “stuff”, and leave the one file in the level above this directory:

User-agent: *
Disallow: /~joe/stuff/

Alternatively you can explicitly disallow all disallowed pages:

User-agent: *
Disallow: /~joe/junk.html
Disallow: /~joe/foo.html
Disallow: /~joe/bar.html

Source

Robots.txt Please Explain was originally published by Katie Ball at MY NOTEPAD on December 13, 2014.

Build your own Yeoman Generator

2014-12-04T00:00:00+11:00

Build Your Own Yeoman Generator

Yeoman’s generators are what give its platform flexibility, allowing you to reuse the same tool for any kind of project you may be working on, JavaScript or otherwise, and that’s before I mention the enormous library of over 400 community contributed generators. Sometimes though, you may have some specific setup that you like to employ in your own projects and for situations like this, it makes sense to abstract all the boilerplate into your own generator.

In this article, we will be building a Yeoman generator that will allow us to build a single page site, one row at a time, it’s a fairly simple example but it will allow us to cover a lot of the more interesting features Yeoman provides.

Getting Set Up

I am going to assume you have Node.js setup, if not, you can grab the installation from here. Besides that, we will need to have Yeoman installed as well as the generator for creating generators. You can accomplish this via the following command to npm:

npm install -g yo generator-generator

Finally, we need to create the actual project, so navigate to the folder of your choosing and run:

yo generator

This will start the generator and ask you some questions like the project name and your GitHub account, for this article, I am going to name my generator one page.

The File Structure

Don’t be alarmed by the large number of files generated by the command, it will all make sense in just a moment.

The first couple files are dotfiles for various things like Git and Travis CI, we have a package.json file for the generator itself, a readme file and a folder for tests. Besides that, each command in our generator gets a folder with an index.js file and a folder for templates.

The index.js file needs to export the actual generator object which will get run by Yeoman. I am going to clear everything inside the actual generator so we can start from scratch, here is what the file should look like after that:

'use strict';
var util = require('util');
var path = require('path');
var yeoman = require('yeoman-generator');
var chalk = require('chalk');

var OnepageGenerator = yeoman.generators.Base.extend({

});

module.exports = OnepageGenerator;

A Yeoman Generator can extend from two different pre-built options: the Base generator, which you can see this one inherits from, or the NamedBase generator, which is actually the same thing except it adds a single parameter that the user can set when they call your generator. It doesn’t matter too much which one you choose, you can always add parameters manually if you need more.

All that this code is doing is creating this generator object and exporting it out, Yeoman will actually retrieve the exported object and run it. The way it runs, is by first calling the constructor method to set the object up and then it will go through all the methods you create on this object (in the order you created them) and run them one at a time. This means it doesn’t really matter what you call the functions and it gives you the flexibility to name them things that make sense to you.

Now, the other thing you should know is that Yeoman has its own functions for dealing with the file system that really help you out with paths. All the functions you would normally use like mkdir, read, write, copy, etc, have been provided, but Yeoman will use the template directory in this command’s folder as the path for reading data and the folder the user is running your generator as the root path for outputting files. This means you don’t even need to think about the full paths when you work with files, you can merely run copy and yeoman will handle the two different locations for you.

Getting Input

Yeoman allows you to add questions to your generator so that you can receive input from the user and customize the behavior appropriately. We are going to have two questions in our generator. The first being the name of the project and the second being whether or not to include a dummy section as an example.

To accomplish this, we will add a function that will prompt the user for these two pieces of info and then store the results on our object itself:

var OnepageGenerator = yeoman.generators.Base.extend({
    promptUser: function() {
        var done = this.async();

        // have Yeoman greet the user
        console.log(this.yeoman);

        var prompts = [{
            name: 'appName',
            message: 'What is your app's name ?'
        },{
            type: 'confirm',
            name: 'addDemoSection',
            message: 'Would you like to generate a demo section ?',
            default: true
        }];

        this.prompt(prompts, function (props) {
            this.appName = props.appName;
            this.addDemoSection = props.addDemoSection;

            done();
        }.bind(this));
    }
});

The first line inside the function sets a done variable from the object’s async method. Yeoman tries to run your methods in the order that they are defined, but if you run any async code, the function will exit before the actual work gets completed and Yeoman will start the next function early. To get around this, you can call the async method, which will return a callback and then Yeoman will wait to go on to the next function until that callback gets executed, which you can see it does at the end, after prompting the user.

The next line where we just log yeoman, that’s the Yeoman logo which you saw when we ran the Yeoman generator just before. Next, we defined a list of prompts, each prompt has a type, a name and a message. If no type was specified, it will default to ‘input’ which is for standard text entry. There are a lot of cool input types like lists, check boxes and passwords, you can view the full list here. In our application, we are using one text input and one ‘confirm’ (yes/no) type of input.

With the array of questions ready, we can pass it to the prompt method along with a callback function. The first parameter of the callback function is the list of answers received back from the user. We then attach those properties onto our main object and call the done method to go on to the next function.

Scaffolding Our Application

Our application has the outer skeleton, which will include the header, menu, footer and some CSS, and then we have the inner content which will go in its own directory along with a custom CSS file per section. This will allow you to set global properties in the main file and customize each row by itself.

Let’s start with the header file, just create a new file in the templates directory called _header.html with the following:

    http://cdnjs.cloudflare.com/ajax/libs/semantic-ui/0.12.0/css/semantic.min.css" rel="stylesheet">

The file names don’t need to start with an underscore, but it’s a best practice to differentiate the name from the final output name so you can tell which one you are dealing with. Also, you can see that besides for including our main CSS file, I am also including the Semantic UI Library as a grid for rows and for the menu (not to mention the great styling).

Another thing you may have noticed, is I used an EJS-styled placeholder for the title and it will get filled in at runtime. Yeoman uses Underscore templates (well lO dash) and as such you can create your files like this and the data will be generated at runtime.

Next, let’s create the footer (put this in a file named _footer.html in the templates folder):

It just closes the HTML document for us, as we won’t be having any JavaScript in our application. The last HTML file required for the outer scaffold is the menu, we are going to generate the actual links at runtime, but we can write the outer container in a template file called _menu.html:

It’s a plain div with some classes provided by Semantic UI. We will pull in the actual links based on the generated sections later. Next, let’s make the _main.css file:

body{
    margin: 0;
    font-family: "Open Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
}

Just some code to help with the menu positioning and change the font, but this is where you can put any default styles you want on the entire document. Now we have to make templates for the individual sections and their accompanying CSS files, these are pretty basic files as we will leave them pretty blank for the user to customize, so inside of _section.html add the following:

        <%= content %>

Just an outer div with a unique id which we will generate based on the section’s name and a class for the Semantic grid system. Then inside, I just added an H1 tag which again will just contain the section’s name. Next, let’s create the CSS file, so create a file called section.css with the following:

#<%= id %>{
    background: #FFFFFF;
    color: #000;
}

This is more of a placeholder with the same ID as the outer container, but it’s common to change the background of each row to separate the content, so I added that property in for convenience. Now, just for completion’s sake, let’s create a file called _gruntfile.js but we will populate it later and let’s fill in the _package.json file that was provided:

{
    "name": "appname",
    "version": "0.0.0",
    "devDependencies": {
        "grunt": "~0.4.2",
        "grunt-contrib-connect": "~0.6.0",
        "grunt-contrib-concat": "~0.3.0",
        "grunt-contrib-cssmin": "~0.7.0"
    }
}

It’s a little bit of a spoiler as to what we will be doing later, but it’s the dependencies we will need for our Grunt tasks.

With all these files ready, let’s go add the methods to scaffold a new project. So back in our index.js file, right after the promptUser method, let’s add a function to create all the folders we will need:

scaffoldFolders: function(){
    this.mkdir("app");
    this.mkdir("app/css");
    this.mkdir("app/sections");
    this.mkdir("build");
},

I added an app folder and inside, two more directories: css and sections, this is where the end-user would build there application. I also created a build folder which is where the different sections and CSS files will get compiled together and built into a single file.

Next, let’s add another method to copy over some of our templates:

copyMainFiles: function(){
    this.copy("_footer.html", "app/footer.html");
    this.copy("_gruntfile.js", "Gruntfile.js");
    this.copy("_package.json", "package.json");
    this.copy("_main.css", "app/css/main.css");

    var context = {
        site_name: this.appName
    };

    this.template("_header.html", "app/header.html", context);
},

Here we use two new methods, copy and template, which are pretty similar in function. copy will take the file from the templates directory and move it to the output folder, using the provided paths. template does the same thing, except before writing to the output folder it will run it through Underscore’s templating function along with the context in order to fill in the placeholders.

I didn’t copy the menu over yet because for that, we need to generate the links, but we can’t really generate the links until we add the demo section. So the next method we create, will add the demo section:

generateDemoSection: function(){
    if (this.addDemoSection) {
        var context = {
            content: "Demo Section",
            id: this._.classify("Demo Section")
        }

        var fileBase = Date.now() + "_" + this._.underscored("Demo Section");
        var htmlFile = "app/sections/" + fileBase + ".html";
        var cssFile  = "app/css/" + fileBase + ".css";

        this.template("_section.html", htmlFile, context);
        this.template("_section.css", cssFile, context);
    }
},

Another function that you may not be familiar with is the classify function, which is provided to you by Underscore Strings. What it does is it takes a string and it creates a “class” version of it, it will remove things like spaces and create a camel-cased version, suitable for things like HTML classes and IDs; underscored does the same thing except instead of camel-casing it snake-cases them. Besides that, it’s all stuff we have done in the previous function, the only other thing worth mentioning is that we are pre-pending a time-stamp, both to keep the files unique but also for ordering. When we load the files in, they are alphabetized so having the time as the prefix will keep them in order.

The last file that needs to be copied over is the menu.html file but to do that, we need to generate the links. The problem is we don’t really know at this stage which files were generated before or if the user added sections manually. So to build up the menu, we need to read from the output path and after reading the sections that exist there, we need to construct the menu links. There are a handful of new functions that we haven’t used yet, so we will go through it line by line:

generateMenu: function(){
    var menu = this.read("_menu.html");

    var t = '<%= name %>';
    var files = this.expand("app/sections/*.html");

    for (var i = 0; i < files.length; i++) {
        var name = this._.chain(files[i]).strRight("_").strLeftBack(".html").humanize().value();

        var context = {
            name: name,
            id: this._.classify(name)
        };

        var link = this.engine(t, context);
        menu = this.append(menu, "div.menu", link);
    }

    this.write("app/menu.html", menu);
},

The first line reads in the menu’s outer HTML and then I created a template string that we can use for each link. After that, I used the expand function, which accepts a resource path, relative to the folder the generator was called in (the output path) and it returns an array of all the files that match the provided pattern, in our case this will return all the section HTML files.

Then we cycle though the list of files and for each one, we use Underscore Strings to remove the timestamp and file extension so that we are left with just the name of the file. The humanize method will take things that are camel-cased or characters like underscores and dashes and convert them to spaces, so you get a human readable string. It will also capitalize the first letter of the string which will work out great for our menu. With the name separated, we create a context object along with the ID we used before, so that the links will actually take us to the correct sections.

Now we have two new functions we haven’t seen before, engine and append. engine takes a template string as the first parameter and a context object as the second and it will run it through the templating engine and returns the results. append accepts an HTML string as the first parameter, a selector as the second, and something to insert as the third parameter. What it will do is insert the provided content at the end of all the elements that match the selector. Here we are adding the link to the end of the menu div.

Last, but not least, we have the write method which will take our computed HTML string and write it out to the file. Now, just to finish up here, let’s add a method to run npm:

runNpm: function(){
    var done = this.async();
    this.npmInstall("", function(){
        console.log("nEverything Setup !!!n");
        done();
    });
}

The first parameter for npmInstall is the paths, but you can just leave this blank, besides that I am just printing out a message at the end, telling the user the app is ready.

So as a quick recap, when our generator runs, it will ask the user for the project name and whether or not to include a demo section. After that, it will go on to create the folder structure and copy in all the files needed for our project. Once done, it will run npm to install the dependencies we defined and it will display the message we just put in.

This is pretty much all the main generator needs to do, but it’s not that useful without the Grunt tasks. Currently, it’s just a bunch of separate files but in order to properly develop the sections, we need a way to preview them as a single file and we will also need to the ability to build the results. So open _gruntfile.js from the templates directory and let’s get started:

module.exports = function(grunt) {
  grunt.initConfig({
    //task config
  });

  grunt.loadNpmTasks('grunt-contrib-connect');
  grunt.loadNpmTasks('grunt-contrib-cssmin');
  grunt.loadNpmTasks('grunt-contrib-concat');

  grunt.registerTask('serve', ['connect']);
  grunt.registerTask('build', ['concat', 'cssmin']);
  grunt.registerTask('default', ['build']);
};

So far, this is just the standard boilerplate, we need to export a function and inside we include the three dependencies we added to the package.json file, and then we register the tasks. We will have a serve task which will act like a server and let us view the separate files together while we develop our site and then we have the build command which will combine all the HTML and CSS in our app together for deployment. I also added the last line, so if you just run grunt by itself, it will assume you want to build.

Now, let’s start with the configuration for the build command as it’s a lot shorter:

concat: {
    dist: {
        src: ["app/header.html", "app/menu.html", "app/sections/*.html", "app/footer.html"],
        dest: "build/index.html"
    }
},
cssmin: {
    css: {
        files: {
            "build/css/main.css": ["app/css/*.css"]
        }
    }
}

For the HTML, we are just going to concatenate all the HTML files together in the order specified into the build folder under the name index.html. With the CSS, we also want to minify it, so we are using the cssmin plugin and we are specifying that we want to output a file called main.css inside the build/css folder and we want it to include the minified versions of all the CSS files in our project.

Connect Server

Next, we need to add the configuration for the Connect server, connect provides a lot of great middleware for serving static files or directories, but here we need to combine all the files first, so we are going to have to create some custom handlers. To begin, let’s put the base configuration in:

connect: {
    server: {
        options: {
            keepalive: true,
            open: true,
            middleware: function(){
                //custom handlers here
            }
        }
    }
},

The keepalive option tells Grunt to keep the server running, the open option will tell Grunt to open the URL in your browser automatically when you start the server (it’s more of a personal preference though) and the middleware function is meant to return an array of middleware handlers to process the requests.

In our application, there are basically two resources we need to handle, the root resource (our “index.html”) in which case we need to combine all our HTML files and return them and then the “main.css” resource, in which case we would want to return all the CSS files combined together. As for anything else, we can just return a 404.

So let’s start by creating an array for the middleware and let’s add the first one (this goes inside the middleware property’s function, where I placed the comment):

  var middleware = [];

  middleware.push(function(req, res, next) {
      if (req.url !== "/") return next();

      res.setHeader("Content-type", "text/html");
      var html = grunt.file.read("app/header.html");
      html += grunt.file.read("app/menu.html");

      var files = grunt.file.expand("app/sections/*.html");

      for (var i = 0; i < files.length; i++) {
          html += grunt.file.read(files[i]);
      }

      html += grunt.file.read("app/footer.html");
      res.end(html);
  });

We have kind of shifted from Yeoman’s API to Grunt’s, but luckily the command names are almost identical, we are still using read to read files and expand to get the list of files. Besides that, all we are doing is setting the content-type and returning the concatenated version of all the HTML files. If you are unfamiliar with a middleware based server, basically it will run through the middleware stack until somewhere along the line, a function can handle the request.

In the first line, we check if the request is for the root URL, if it is we handle the request, otherwise we call next() which will pass the request down the line onto the next middleware.

Next, we need to hand the request to /css/main.css which, if you remember, is what we set up in the header:

  middleware.push(function(req, res, next){
      if (req.url !== "/css/main.css") return next();

      res.setHeader("Content-type", "text/css");
      var css = "";

      var files = grunt.file.expand("app/css/*.css");
      for (var i = 0; i < files.length; i++) {
           css += grunt.file.read(files[i]);
      }

      res.end(css);
  });

Basically, this is the same function as before except for the CSS files. Last, but not least, I will add a 404 message and return the middleware stack:

  middleware.push(function(req, res){
      res.statusCode = 404;
      res.end("Not Found");
  });

  return middleware;

This means if any requests don’t get handled by the previous two functions, then we will send this 404 message. And that’s all there is to it, we have the generator which will create the project and the Grunt tasks which will allow us to preview and build our app. The last topic I want to cover briefly, is sub generators.

Sub Generators

We have already created the main generator that builds out our application but Yeoman allows you to create as many sub-generators as you want to use after the initial scaffolding. In our application, we need one to generate new sections. To get started, we can actually use a sub generator from the generator:generator to scaffold the file, to do this, just run the following command from inside our onepage folder:

yo generator:subgenerator section

This will create a new folder called section with an index.js file and a templates folder just like our main (app) generator. Let’s empty out the generator like we did last time and you should be left with the following:

'use strict';
var util = require('util');
var yeoman = require('yeoman-generator');

var SectionGenerator = yeoman.generators.NamedBase.extend({

});

module.exports = SectionGenerator;

You may also notice we are extending from the NamedBase not the regular Base, that means you have to supply a name parameter when you call the generator and you can then access that name using this.name. Now this code is essentially the two functions we already wrote in the previous generator: generateDemoSection and generateMenu, so we can just copy those two functions here. I will replace the name of the first one to something more appropriate:

generateSection: function(){
    var context = {
        content: this.name,
        id: this._.classify(this.name)
    }

    var fileBase = Date.now() + "_" + this._.underscored(this.name);
    var htmlFile = "app/sections/" + fileBase + ".html";
    var cssFile  = "app/css/" + fileBase + ".css";

    this.template("_section.html", htmlFile, context);
    this.template("_section.css", cssFile, context);
},

generateMenu: function(){
    var menu = this.read("_menu.html");

    var t = '<%= name %>';
    var files = this.expand("app/sections/*.html");

    for (var i = 0; i < files.length; i++) {
        var name = this._.chain(files[i]).strRight("_").strLeftBack(".html").humanize().value();

        var context = {
            name: name,
            id: this._.classify(name)
        };

        var link = this.engine(t, context);
        menu = this.append(menu, "div.menu", link);
    }

    this.write("app/menu.html", menu);
}

The only difference is instead of entering the name directly, I am using the this.name property. The only other thing is we need to move the template files _sections.html, _section.css and _menu.html from app/templates to section/templates as that is where the template/read commands will look.

Code Duplication

The problem now is code duplication. So back in the app/index.js file, instead of it having the same code as the sub generator, we can just call the sub generator and pass it the name argument. You can remove generateMenu from app/index.js altogether and we will modify generateDemoSection to the following:

generateDemoSection: function() {
      if (this.addDemoSection) {
          var done = this.async();
          this.invoke("onepage:section", {args: ["Demo Section"]}, function(){
              done();
          });
      } else {
          this.write( "app/menu.html", "");
      }
},

So if the user wanted to create the demo section, then we invoke the sub generator passing in the first argument which is the name. If the user did not want the demo post, we still need to create something for the menu because our Grunt tasks will try and read it, so in the last section, we just write an empty string to the menu file.

Our generator is finally complete and we can now test it out.

Testing It Out

The first thing we need to do is install our generator on your system. Instead of installing the gem regularly, we can use the link command to just link the folder into the gem path, that way we can continue to make changes here without needing to re-install it every time. From the project directory, simply run nom link.

The last step is to actually run the generator. Just create a new folder and inside run yo onepage this will run our main generator and install the dependencies via npm. We can then use our Grunt tasks to view the page (grunt serve) or add some more sections with our generator using something like yo onpage:section "Another section" and the new files will be added.

Conclusion

In this article, we covered a lot of the common features but there are still more interesting options to check out. As you can probably tell, there is a bit of boilerplate required when building a generator, but that is kind of the point, you get it all done once and then you’re able to use it throughout all your applications.

I hope you enjoyed reading this article, if you have any questions or comments, feel free to leave them below.

Build your own Yeoman Generator was originally published by Katie Ball at MY NOTEPAD on December 04, 2014.

The Internet - 1966 & beyond

2014-12-02T00:00:00+11:00

Internet Timeline | 1969 ~

Significant milestones, advancements, and major breakthroughs in the development of the Internet.

1969
- ARPA (Advanced Research Projects Agency) goes online in December, connecting four major U.S. universities. Designed for research, education, and government organizations, it provides a communications network linking the country in the event that a military attack destroys conventional communications systems.

1972
- Electronic mail is introduced by Ray Tomlinson, a Cambridge, Mass., computer scientist. He uses the @ to distinguish between the sender’s name and network name in the email address.

1973
- Transmission Control Protocol/Internet Protocol (TCP/IP) is designed and in 1983 it becomes the standard for communicating between computers over the Internet. One of these protocols, FTP (File Transfer Protocol), allows users to log onto a remote computer, list the files on that computer, and download files from that computer.

1976
- Presidential candidate Jimmy Carter and running mate Walter Mondale use email to plan campaign events.

Queen Elizabeth sends her first email. She’s the first state leader to do so.

1982
- The word “Internet” is used for the first time.

1984
- Domain Name System (DNS) is established, with network addresses identified by extensions such as .com, .org, and .edu.

Writer William Gibson coins the term “cyberspace.”

1985
- Quantum Computer Services, which later changes its name to America Online, debuts. It offers email, electronic bulletin boards, news, and other information.

1988
- A virus called the Internet Worm temporarily shuts down about 10% of the world’s Internet servers.

1989
- The World (world.std.com) debuts as the first provider of dial-up Internet access for consumers.

Tim Berners-Lee of CERN (European Laboratory for Particle Physics) develops a new technique for distributing information on the Internet. He calls it the World Wide Web. The Web is based on hypertext, which permits the user to connect from one document to another at different sites on the Internet via hyperlinks (specially programmed words, phrases, buttons, or graphics). Unlike other Internet protocols, such as FTP and email, the Web is accessible through a graphical user interface.

1990
- The first effort to index the Internet is created by Peter Deutsch at McGill University in Montreal, who devises Archie, an archive of FTP sites.

1991
- Gopher, which provides point-and-click navigation, is created at the University of Minnesota and named after the school mascot. Gopher becomes the most popular interface for several years.

Another indexing system, WAIS (Wide Area Information Server), is developed by Brewster Kahle of Thinking Machines Corp.

1993
- Mosaic is developed by Marc Andreeson at the National Center for Supercomputing Applications (NCSA). It becomes the dominant navigating system for the World Wide Web, which at this time accounts for merely 1% of all Internet traffic.

1994
- The White House launches its website, www.whitehouse.gov.

Initial commerce sites are established and mass marketing campaigns are launched via email, introducing the term “spamming” to the Internet vocabulary.
Marc Andreessen and Jim Clark start Netscape Communications. They introduce the Navigator browser.

1995
- CompuServe, America Online, and Prodigy start providing dial-up Internet access.

Sun Microsystems releases the Internet programming language called Java.
The Vatican launches its own website, www.vatican.va.

1996
- Approximately 45 million people are using the Internet, with roughly 30 million of those in North America (United States and Canada), 9 million in Europe, and 6 million in Asia/Pacific (Australia, Japan, etc.). 43.2 million (44%) U.S. households own a personal computer, and 14 million of them are online.

1997
- On July 8, 1997, Internet traffic records are broken as the NASA website broadcasts images taken by Pathfinder on Mars. The broadcast generates 46 million hits in one day.

The term “weblog” is coined. It’s later shortened to “blog.”

1998
- Google opens its first office, in California.

1999
- College student Shawn Fanning invents Napster, a computer application that allows users to swap music over the Internet.
The number of Internet users worldwide reaches 150 million by the beginning of 1999. More than 50% are from the United States. “E-commerce” becomes the new buzzword as Internet shopping rapidly spreads.

MySpace.com is launched.

2000
- To the chagrin of the Internet population, deviant computer programmers begin designing and circulating viruses with greater frequency. “Love Bug” and “Stages” are two examples of self-replicating viruses that send themselves to people listed in a computer user’s email address book. The heavy volume of email messages being sent and received forces many infected companies to temporarily shut down their clogged networks.
The Internet bubble bursts, as the fountain of investment capital dries up and the Nasdaq stock index plunges, causing the initial public offering (IPO) window to slam shut and many dotcoms to close their doors.

America Online buys Time Warner for $16 billion. It’s the biggest merger of all time.

2001
- Napster is dealt a potentially fatal blow when the 9th U.S. Circuit Court of Appeals in San Francisco rules that the company is violating copyright laws and orders it to stop distributing copyrighted music. The file-swapping company says it is developing a subscription-based service.
About 9.8 billion electronic messages are sent daily.

Wikipedia is created.

2002
- As of January, 58.5% of the U.S. population (164.14 million people) uses the Internet. Worldwide there are 544.2 million users.
The death knell tolls for Napster after a bankruptcy judge ruled in September that German media giant Bertelsmann cannot buy the assets of troubled Napster Inc. The ruling prompts Konrad Hilbers, Napster CEO, to resign and lay off his staff.

2003
- It’s estimated that Internet users illegally download about 2.6 billion music files each month.
Spam, unsolicited email, becomes a server-clogging menace. It accounts for about half of all emails. In December, President Bush signs the Controlling the Assault of Non-Solicited Pornography and Marketing Act of 2003 (CAN-SPAM Act), which is intended to help individuals and businesses control the amount of unsolicited email they receive.
Apple Computer introduces Apple iTunes Music Store, which allows people to download songs for 99 cents each.

Spam, unsolicited email, becomes a server-clogging menace. It accounts for about half of all emails.
Apple Computer introduces Apple iTunes Music Store, which allows people to download songs for 99 cents each.

2004
- Internet Worm, called MyDoom or Novarg, spreads through Internet servers. About 1 in 12 email messages are infected.

Online spending reaches a record high—$117 billion in 2004, a 26% increase over 2003.

2005
- YouTube.com is launched.

2006
- There are more than 92 million websites online.

2007
- Legal online music downloads triple to 6.7 million downloads per week.

Colorado Rockies’ computer system crashes when it receives 8.5 million hits within the first 90 minutes of World Series ticket sales.
The online game, World of Warcraft, hits a milestone when it surpasses 9 million subscribers worldwide in July.

2008
- In a move to challenge Google’s dominance of search and advertising on the Internet, software giant Microsoft offers to buy Yahoo for $44.6 billion.

In a San Fransisco federal district court, Judge Jeffrey S. White orders the disabling of Wikileaks.org, a Web site that discloses confidential information. The case was brought by Julius Baer Bank and Trust, located in the Cayman Islands, after a disgruntled ex-employee allegedly provided Wikileaks with stolen documents that implicate the bank in asset hiding, money laundering, and tax evasion. Many web communities, who see the ruling as unconstitutional, publicized alternate addresses for the site and distributed bank documents through their own networks. In response, Judge White issues another order to stop the distribution of bank documents.
Microsoft is fined $1.3 billion by the European Commission for further abusing its dominant market position, and failing to comply to their 2004 judgment, which ordered Microsoft to give competitors information necessary to operate with Windows. Since 2004, Microsoft has been fined a total of $2.5 billion by the Commission for not adhering to their ruling.

2012
- A major protest online in January shakes up Congressional support for anti-Web piracy measures. The protest, including a 24-hour shutdown of the English-language Wikipedia site, is over two bills, the Stop Online Piracy Act in the House and the Protect IP Act in the Senate. The main goal of both bills is to stop illegal downloading and streaming of TV shows and movies online. The tech industry is concerned that the bills will give media companies too much power to shut down websites.

2014
- A coding error discovered in April in OpenSSL, encryption software that makes transactions between a computer and a remote secure, makes users vulnerable to having their usernames, passwords, and personal information stolen. Millions of banks, Internet commerce companies, email services, government sites, and social media sites rely on OpenSSL to conduct secure transactions. The coding error was made in 2012. Computer security experts encourage computer users to change their passwords.

Sources for this timeline include International Data Corporation, the W3C Consortium, Nielsen/NetRatings, and the Internet Society.

The Internet - 1966 & beyond was originally published by Katie Ball at MY NOTEPAD on December 02, 2014.

GitHub Pages Ruby Gem

2014-11-29T00:00:00+11:00

A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a local Jekyll environment in sync with GitHub Pages.

Usage

Run the following command:

gem install github-pages

Alternatively, you can add the following to your project’s Gemfile:

gem 'github-pages'

Note: You are not required to install Jekyll separately. Once the github-pages gem is installed, you can build your site using jekyll build, or preview your site using jekyll serve. For more information about installing Jekyll locally, please see the GitHub Help docs on the matter.

Command line usage

The GitHub Pages gem also comes with several command-line tools, contained within the github-pages command.

List dependency versions

$ github-pages versions
+-----------------------+---------+
| Gem                   | Version |
+-----------------------+---------+
| jekyll                | 2.4.0   |
| jekyll-coffeescript   | 1.0.0   |
| jekyll-sass-converter | 1.2.0   |
| kramdown              | 1.3.1   |
| maruku                | 0.7.0   |
| rdiscount             | 2.1.7   |
| redcarpet             | 3.1.2   |
| RedCloth              | 4.2.9   |
| liquid                | 2.6.1   |
| pygments.rb           | 0.6.0   |
| jemoji                | 0.3.0   |
| jekyll-mentions       | 0.1.3   |
| jekyll-redirect-from  | 0.6.2   |
| jekyll-sitemap        | 0.6.0   |
+-----------------------+---------+

Note, you can also pass the --gemfile flag to get the dependencies listed in a valid Gemfile dependency format.

Health check

Checks your GitHub Pages site for common DNS configuration issues.

$ github-pages health-check
Checking domain foo.invalid...
Uh oh. Looks like something's fishy: A record points to deprecated IP address

See the GitHub Pages Health Check documentation for more information.

Updating

To update to the latest version of Jekyll and associated dependencies, simply run gem update github-pages, or if you’ve installed via Bundler, bundle update github-pages.

Project Goals

The goal of the GitHub Pages gem is to help GitHub Pages users bootstrap and maintain a Jekyll build environment that most closely matches the GitHub pages build environment. The GitHub Pages gem relies on explicit requirements shared between both users’ computers and the build servers to ensure that the result of a user’s local build is consistently also the result of the server’s build.

Additional tools, such as tools that integrate with the GitHub API to make managing GitHub Pages sites easier are not the primary goal, but may be within the project’s scope.

What’s versioned

The GitHub Pages gem seeks to version two aspects of the build environment:

1. Ruby

The version of Ruby with which Jekyll is executed. Although Jekyll itself may be compatible with prior or future versions of Ruby, different execution environments yield different results. Ruby 1.8.7 parses YML differently than 1.9.3, for example, and Kramdown has trouble processing mailto links prior to 1.9.3. In order to ensure that building locally consistently results in the same build as what appears when published, it’s essential that Ruby itself is versioned along side the Gem, despite no known incompatibilities.

Note: If you’re using rbenv, check out ruby-build-github for ruby-build, a collection of GitHub-shipped Ruby versions. If you clone down this repository and run ./install.sh support/2.1.0-github, it should install properly for you.

2. Dependencies

This includes Markdown processors, and any other Jekyll dependency for which version incongruency may produce unexpected results. Traditionally, MaruKu, Kramdown, RedCloth, liquid, rdiscount, and redcarpet have been strictly maintained due to known breaking changes.

Changelog

See all releases.

Releasing

To release a new version of this gem, run script/release from the master branch.

License

Distributed under the MIT License.

GitHub Pages Ruby Gem was originally published by Katie Ball at MY NOTEPAD on November 29, 2014.

Creating a Successful School Digital Citizenship Plan

2014-11-29T00:00:00+11:00

What is Digital Citizenship?

Advances in technology have caused a huge problem in areas of education dealing with copyright laws; in response, educators are implementing programs designed to teach students about digital citizenship.

Digital citizenship in schools was designed to educate students of all ages about their responsibilities to a digital society. When a person becomes a citizen of a nation whether by birth or immigration, they agree to adhere to the rules and regulation set forth by the government or pay a penalty. Simple rules are set in place to protect people’s property, heath, and rights. Digital citizenship works in much the same way.

Digital citizenship in schools has been discussed for years, but recently in June 2010, the Online Safety Working Group sent a letter to Congress entitled Youth Safety on a Living Internet. In this report, the Internet is declared “a living thing” in its form and function. Because of this, it grows and changes, so society must be prepared for these changes and know how to steward what has been given. They decided that the job of promoting online safety should fall to the education system because they have the greatest access to computers and other digital media.That being done, teaching students about digital citizenship in schools is now a requirement in school districts across the nation.

Elements to Create Plan

So what are the needed elements in order to implement a digital citizenship plan? A better question is probably “Where do we start?” With all the media outlets available today, this subject is difficult to address. It is usually better to assume that everything needs to be included.

A good focus question would be to ask an adult and a student how they use technology on a daily basis. By gathering information about technological use, you are better equipped to come up with a plan. These plans need to cover all areas of technology.

Computer and Internet use will obviously be a major topic for discussion with all that is available out there. Students need to know how to properly find information on websites, which websites are reliable, and how to cite their source information. These things cannot be assumed knowledge; a majority of students do now know how to do proper work citations when they enter college. They need to know the gravity of violating copyright laws when it comes to published works of all kinds. Most students do not believe that they will ever get caught plagiarizing, so they need to have a reason not to that is foundation to them.

Finding Lesson Plans

There are many resources available to help teachers and school districts make digital citizenship agreements and lesson plans. A great place to start is by going to www.digitalcitizenship.net and looking at their free online lesson plans. These lesson plans provide activities that give students choices and opportunities to explore real-life scenarios that they may find themselves in one day. It would also be a good idea to download a 21st Century Digital Compass and go through its contents with your students. These resources are easy to find and an invaluable source of information and protection for your students and your school.

Developing a Contract

The main component of becoming digital citizens is the implementation of a contract that must be signed by the student and the parent/guardian of that student before they are allowed any access to digital media of any kind on school grounds. This will protect everyone in the case of misuse of the privilege of living in a digital world. Students will be accountable to their signatures on that contract and their digital citizenship and all the rights and privileges will be realized to a higher degree.

A digital world has changed the face of education, so it is important that school create a world of healthy digital citizens.

Creating a Successful School Digital Citizenship Plan was originally published by Katie Ball at MY NOTEPAD on November 29, 2014.

Get Your Badge On

2014-11-28T00:00:00+11:00

I love adding badges to my projects. It’s an easy way to quickly check dependencies are up to date, and build are passing. Others are just to show what services you use on the project, and others just for fun. So what can you use badges for? Check out the list below for some examples.

What kind of meta data can you convey using badges?

test build status: build | failing
code coverage percentage: coverage | 80%
stable release version: version | 1.2.3
package manager release: gem | 1.2.3
status of third-party dependencies: dependencies | out-of-date
static code analysis GPA: code climate | 3.8
semver version observance: semver | 2.0.0
amount of gittip donations per week: tips | $2/week

Services that give you badges! (using the Shields standard)

Do you Grunt?

Do you use Grunt in a project? If so you should proudly display that in your project README or on your project website? Now you can with the “Built with Grunt” badge!

Built with Grunt

Using the Badge

Just copy the following Markdown code snippet and paste it right underneath the headline in your project README. You can also put it on your project website homepage or footer.

[![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/)

If you need an HTML version, we’ve got you covered.

<a href="http://gruntjs.com/"><img src="https://cdn.gruntjs.com/builtwith.png" alt="Built with Grunt"></a>

Get Your Badge On was originally published by Katie Ball at MY NOTEPAD on November 28, 2014.

The HTML email Boilerplate

2014-11-18T00:00:00+11:00

With web development there are lots of common tasks that we do over and over again. This is where it’s helpful to work with tools that make our lives easier, this can be Server-side frameworks, HTML project boilerplates and HTML email boilerplates.

Some of the most popular boilerplates you would of heard of are Twitter bootstrap and HTML5 boilerplate. These projects are both available on Github for you to fork and modify for your own use and both are very useful projects to use when you first start any new website project.

One of the problems that web developers have is getting email newsletters to look correct in most of email clients. This is where the HTML email boilerplate can be useful, it will provide you with helpful code snippets to aid in developing all your HTML emails. This will take care of the correct doctype to use, how to reset the styling to work in all clients, how to display images correctly and how to style HTML tables to align correctly in your email.

HTML Doctype

While many email clients will strip out the doctype, it’s good practice to add a doctype so that when we are testing we know that the HTML will render correctly. When popular clients remove the doctype from the email it will be replaced by XHTML 1.0 strict doctype, this is why we make sure we set it as XHTML 1.0 strict.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

Images

The HTML boilerplate will help you in setting up your images correctly, if you have links around your images then a border will be placed around the images, adding these styles will remove all borders around your images.

<style>
img {outline:none; text-decoration:none; -ms-interpolation-mode: bicubic;} 
a img {border:none;} 
.image_fix {display:block;}
</style>

<img class="image_fix" src="full path to image" alt="Your alt text" title="Your title text" width="x" height="x" />

Tables

The HTML boilerplate gives you a starting point to deal with tables, this will provide you with a starting point of defaults to use on your table to avoid any formatting problems.

<style>
#backgroundTable {margin:0; padding:0; width:100% !important; line-height: 100% !important;}
</style>

<table cellpadding="0" cellspacing="0" border="0" id="backgroundTable">
    <tr>
        <td>
             <table cellpadding="0" cellspacing="0" border="0" align="center">
                 <tr>
                      <td width="200" valign="top"></td>
                      <td width="200" valign="top"></td>
                      <td width="200" valign="top"></td>
                </tr>
             </table> 
        </td>
    </tr>
</table>

Resetting Your Styles

Use the following snippet to reset the styles in the email clients, this will also help with font sizes on mobile devices.

/* Client-specific Styles */
#outlook a {padding:0;} /* Force Outlook to provide a "view in browser" menu link. */
body{width:100% !important; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; margin:0; padding:0;} 
/* Prevent Webkit and Windows Mobile platforms from changing default font sizes, while not breaking desktop design. */ 
.ExternalClass {width:100%;} /* Force Hotmail to display emails at full width */  
.ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div {line-height: 100%;} /* Force Hotmail to display normal line spacing.  More on that: http://www.emailonacid.com/forum/viewthread/43/ */ 
#backgroundTable {margin:0; padding:0; width:100% !important; line-height: 100% !important;}
p { margin: 1em 0; }
/* End reset */

Use the HTML boilerplate the next time you need to create a HTML email newsletter.

DOWNLOAD THE BOILERPLATE>

Resources and information taken from the HTMLemailboilerplate.com website.

The HTML email Boilerplate was originally published by Katie Ball at MY NOTEPAD on November 18, 2014.

How to Write a Great README

2014-11-17T00:00:00+11:00

As many other have blogged before me, a good README should be simple and succinct, but a great README can save time and encourage developers to look more at your project, especially if it’s for something like command-line parameter parsing library.

Here’s what I think it should include:

name of the projects and all sub-modules and libraries (sometimes they are named different and very confusing to new users)
descriptions of all the project, and all sub-modules and libraries
5-line code snippet on how its used (if it’s a library)
copyright and licensing information (or “Read LICENSE”)
instruction to grab the documentation
instructions to install, configure, and to run the programs
instruction to grab the latest code and detailed instructions to build it (or quick overview and “Read INSTALL”)
list of authors or “Read AUTHORS”
instructions to submit bugs, feature requests, submit patches, join mailing list, get announcements, or join the user or dev community in other forms
other contact info (email address, website, company name, address, etc)
a brief history if it’s a replacement or a fork of something else
legal notices (crypto stuff)

Apache HTTP Server has a simple yet good README. Another good one I found available online is GNU Make’s README.

As per formatting, I would say stick to the Unix traditions as much as possible, and/or use markdown especially for github projects, which renders README.md as html.

ASCII characters only, if the README is written in English
write it in English if possible, and ship translated version with two-letter language code extension like README.ja
80 characters or less per line
single empty line between paragraphs
dashes under the headers
indent using whitespace (0x20) not tab

Putting it all together…

Documentation
GNU make is fully documented in the GNU Make manual, which is contained
in this distribution as the file make.texinfo.  You can also find
on-line and preformatted (PostScript and DVI) versions at the FSF's web
site.  There is information there about ordering hardcopy documentation.

  http://www.gnu.org/
  http://www.gnu.org/doc/doc.html
  http://www.gnu.org/manual/manual.html

Wikipedia defines as:

A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.

and it lists the following contents:

configuration instructions

installation instructions

operating instructions

a file manifest

copyright and licensing information

contact information for the distributor or programmer

known bugs

troubleshooting

credits and acknowledgements

a changelog

That’s it for now, but I have another post about readme file soon. They are very important to the developer and assist with planning and keeping on track.

How to Write a Great README was originally published by Katie Ball at MY NOTEPAD on November 17, 2014.

Organise Gists with GistBox

2014-11-15T00:00:00+11:00

I can across this article and it’s exactly what I wanted to write.

Organise Your Github Gists With GistBox

Do you have a good way of organising and storing all your different code snippets?

Because I use sublime text 3 as my code editor I used to just store all my code snippets as a snippet in sublime, this was fine if your are always working on one computer but what if you code on multiple computers? You won’t be able to take all these code snippets with you.

I’ve started to change this and have been adding to my profile on Gist and using this to store my code snippets, the benefit of using this means that I can have access to all my snippets from any computer I use.

Another benefit is that a Gist uses version control so I can see the changes made to the snippet as I learn a new trick.

As these snippets are open to the public other people have the chance to comment on these code snippets if they know a better way of doing what I’m trying to achieve.

Other people can even fork these snippets so that they have access to this code on their own Gist profile.

View my Gist profile

The problem with Gist is they way you organise and search for your code snippets, there isn’t a good way to do this. GistBox was created to solve that very problem. GistBox can be a desktop application or a Google Chrome application and uses the Gist API to get all your Gists and gives you a nice interface to search and organise them.

GistBox allows you to place labels on your Gists so that you can group them together in any way you want, not just any language but you could group them by framework or by project.

It will allow you to search through your Gists using labels and keywords.

Using the in-built code editor you can create new Gists directly inside the application and it will use the API to update your profile on Gist.

If you use Gist to store your code snippets it really is a nice tool to organise the code, try it out.

GistBox

Organise Gists with GistBox was originally published by Katie Ball at MY NOTEPAD on November 15, 2014.

The JavaScript List

2014-11-15T00:00:00+11:00

Actual JavaScript Engine Performance

JavaScript: The Wrrrld’s Most Misunderstood Programming Language (Chinese Czech French German Italian Japanese Korean Portuguese Russian Serbian Spanish Turkish)

The World’s Most Misunderstood Programming Language Has Become the World’s Most Popular Programming Language (Chinese Spanish)

A Survey of the JavaScript Programming Language (Chinese Korean)

Code Conventions for the JavaScript Programming Language (Belorussian Chinese Russian)

The Little JavaScripter (Italian)

Private Members in JavaScript (Chinese Hebrew Japanese Korean)

Prototypal Inheritance in JavaScript (Belorussian Spanish)

JavaScript and HTML Script Tags (Chinese)

JScript Memory Leaks

Top Down Operator Precedence

The Elements of JavaScript Style, Parts One (Chinese) and Two (Chinese)

Yahoo! User Interface Blog

JSLint: The JavaScript Verifier (Documentation)

JSMin: The JavaScript Minifier

I also have a Big List over on at GitHub. If you have something to add just Fork it and submit a pull request.

The JavaScript List was originally published by Katie Ball at MY NOTEPAD on November 15, 2014.

My Mini GitHub Deployment Workflow with Jekyll

2014-11-14T00:00:00+11:00

Grunt is always running when I’m writing or designing. It handles a few things, as defined in my Gruntfile.

This is my process:
- SVGMin to minify my SVG files and remove unnecessary code
- SVG2PNG to make PNG copies of my SVG files
- Sass to make authoring my stylesheets easier
- Autoprefixer to prefix CSS properties and values as needed
- Jekyll to build my site into static HTML files
- Finally, a “watch” task to watch my files for changes and perform the above tasks

Jekyll builds my site in a _site directory, which is ignored by Git so that I don’t end up with duplicate content and unnecessary bloat on GitHub.

When my post or design changes are in a state I’m happy with, I commit my changes and push to GitHub.

“Simples”
- Meerkat

My Mini GitHub Deployment Workflow with Jekyll was originally published by Katie Ball at MY NOTEPAD on November 14, 2014.

Package Dependencies Done Right

2014-11-13T00:00:00+11:00

“Best practices” is a term that is often misused and thus can be ambiguous in this context. For such reasons, it is important to make clear the goals behind this particular versioning scheme:

Strive to be forwards compatible with node.js (within reason)
Keep the dependencies of multiple installations of the same app cohesive
Reduce the surface area of potential bugs due to breaking changes

Here is a sample package.json that uses the best practices we will discuss:

{
  "name": "best-practices",
  "description": "A package using versioning best-practices",
  "author": "Charlie Robbins <charlie@nodejitsu.com>",
  "dependencies": {
    "colors": "0.x.x",
    "express": "2.3.x",
    "optimist": "0.2.x"
  },
  "devDependencies": {
    "vows": "0.5.x"
  },
  "engine": "node >= 0.4.1"
}

When specifying modules dependencies: use 1.0.x syntax

Until recently, I was guilty of not following this guideline: I continued to use the >= 0.2.0 syntax illustrated above in the naive.package.json example. At first glance there doesn’t seem to be anything wrong with that style. You’re saying “If there are changes in the future I want them.”

The problem arises because authors are conveying meaning in their versions. Not every version will be completely backwards compatible with the particular version you were using when you wrote your application. This is conveyed in the version string:

e.g.: 0.3.18
- Major Version (0)
- Minor Version (3)
- Patch Version (18)

Changes to the major and minor parts of the version mean that changes have happened, although there is no convention to convey they are breaking. Changes to patch versions are used to express that a fix has been made and it is (usually) safe to upgrade.

Conversely, when using the 0.2.x syntax you’re saying: “If there are patch changes in the future I want them, but no minor or major versions.” Given the description of the meaning conveyed by each of the version components above this means you won’t be tearing your hair out over breaking changes in a module you depend on.

__When specifying node versions in apps: use 0.4.x or 0.4.0 syntax
__

As with any sufficiently important problem, there are nuances to dependency management you should be aware of. One such nuance is the difference between specifying dependencies in an application vs. modules.

Module authors encounter a much wider surface area of use cases, and as such should be more liberal in the versions of node.js they accept. On the other hand, application developers typically have no upstream dependencies and should be more explicit about what version of node.js they are expecting on the target system.

Take advantage of devDependencies

The package.json specification used by npm has an additional property for separately listing dependencies which are only required for development purposes. Why separate you might ask? Besides not having to download these dependencies from the registry when running in production, npm it is required if you wish to take advantage of a couple of neat npm features such as test:

$ pwd
  /Users/charlie/GitHub/nconf

  $ npm test
  npm info it worked if it ends with ok
  npm info using npm@1.0.6
  npm info using node@v0.4.8
  npm info pretest nconf@0.1.9
  npm info test nconf@0.1.9

  > nconf@0.1.9 test /Users/Charlie/GitHub/nconf
  > vows test/*-test.js --spec

  (...)

If I had not specified my test library, vows, in the devDependencies section of the package.json for nconf I would have received:

  $ npm test
  npm info it worked if it ends with ok
  npm info using npm@1.0.6
  npm info using node@v0.4.8
  npm info pretest nconf@0.1.9
  npm info test nconf@0.1.9

  > nconf@0.1.9 test /Users/Charlie/GitHub/nconf
  > vows test/*-test.js --spec

  sh: vows: command not found
  npm info nconf@0.1.9 Failed to exec test script
  npm ERR! nconf@0.1.9 test: `vows test/*-test.js --spec`
  npm ERR! `sh "-c" "vows test/*-test.js --spec"` failed with 127
  npm ERR! 
  npm ERR! Failed at the nconf@0.1.9 test script.

  (...)

Conclusion

Node.js is evolving rapidly: it has been less than a month since npm 1.0 was released which dramatically changed the way in which dependencies are handled. More importantly: the modules on-top of node.js critical to building scalable web applications are evolving even faster, making the best practices outlined here that much more important if you want to cope.

Thanks nodejitsu for ask your brilliant info.

Package Dependencies Done Right was originally published by Katie Ball at MY NOTEPAD on November 13, 2014.