Editing twitter URL share parameters with Ghost' share.hbs handlebars page

Previously, when sharing a post, only the post-title and the post-url parameters were being passed.

Curious on how to change it, I decided to investigate what was being used by my ghost theme Grimmoire to handle the sharing - turns out I had just copied over the standard links from the primary, default ghost template.

Let's take a close look at the code inside share.hbs:

<div class="post-meta">
Share this on <a id="twitter" href="http://twitter.com/share?text={{encode title}}&amp;url={{url absolute='true'}}">Twitter</a>, <a id="facebook" href="https://www.facebook.com/sharer/sharer.php?u={{url absolute='true'}}">Facebook</a> or <a id="google-plus" href="https://plus.google.com/share?url={{url absolute='true'}}">Google+</a>.
</div>

The twitter link (what is contained inside the "" after href=) is what I'm interested in. Let's start by examining the first part of the link:

http://twitter.com/share? 

That is calling the Twitter Tweet Web Intent API (I believe that this indeed an API, but if anybody wants to correct my terminology and tell me what it actually is I would appreciate it).

As explained on the Tweet Web Intent documentation page, using this API allows developers or publishers to pre-populate a tweet with text (like the title of the page) and hashtags, pass a URL, and identify Twitter accounts related to the page.

In the URL reference handled by my Ghost.org Theme, the call to Tweet Web Intent http://twitter.com/share? is populated with the following references:

• text optional • in our url, the text is controlled by the following: text={{encode title}}

As is explained in the Ghost.org docs on encode :

{{encode}} is a simple output helper which will encode a given string so that it can be used in a URL.

A title often has characters that may break whatever scripts are parsing the characters being fed through the URL - the {{encode}} makes sure that even if your title has @ or ♄ it can still be processed as a valied URL and transfer the title faithfully.

• url optional • in our url, the url is controlled by the following: &url={{url absolute='true'}}

What is that &? That's the HTML code (or, more properly, & is an HTML entity) that appears as & in the browser's GUI or on the webpage.

Just as & means "and", in the references being passed to Twitter, that & is signaling Twitter's API that another variable is being referenced.

{{url absolute=true}} is Ghost shorthand telling the website theme to input the current page's absolute (or complete) URL - so for the home page of example.com, it will give http://example.com/home and not just /home.

So, to add the twitter parameter via @gersandelf to the tweet created by this process, this is what we'll do!

I open up share.hbs and look at the code:

I add the following: &via="gersandelf", hoping that it will work.

It doesn't work!

When I click on the button to test it, this is what happens:

What happened to the ="gersandelf" that I specified? Well, clearly, the Twitter API that handles these URL parameters completely ignored it.

I go to check the docs once more:

A Twitter username to associate with the Tweet, such as your site’s Twitter account. The provided username will be appended to the end of the Tweet with the text “via @username”.

Is the "" (usually used to delineate a string) messing up the query? Looking at the previous {{encode title}} and {{url absolute=true}} I gather that they don't have the "" explicitely written. I decide to remove the quotes to check.

And now it works beautifully!

Lessons learned in this small adventure:

• Read documentation carefully
• Be extremely careful with quotation marks "" in information passed through URL parameters.
• I solved this problem well within 30 minutes, while making this blog post concurrently. As long as the docs are clearly written, figuring out what to do is made much, much easier.