GiveAway
GiveAway is a small, modularly extensible library for generating social media sharing URLs. It offers a simple API that can be used to add new channels easily.
To generate sharing urls, you'll need a URL to share in the first place. However, the parameter names differ for different services and imlementations. For example, the url parameter for Facebook and Instapaper is u
, but in Twitter and pocket it's called url
. The only parameters you really need for sharing are the URL, a title and/or description and sometimes an image (not everybody uses open graph tags. That's why GiveAway declares url
, title
, description
and image
as the default parameters that are simply translated to the actual parameter name in the channel module.
An example
This is how the Twitter module that GiveAway ships with is implemented:
defmodule Twitter do
use GiveAway.Channel
def base_uri do
"https://twitter.com/intent/tweet"
end
def valid_params do
~w([url text hashtags via related in_reply_to)
end
def parse_param(tuple) do
case tuple do
{"title", value} -> {"text", value}
tuple -> tuple
end
end
end
You can create a working sharing URL for this channel by calling:
GiveAway.url(Twitter, %{
"url" => "http://example.com",
"title" => "Look at this:"
})
This yields:
"https://twitter.com/intent/tweet?text=Look+at+this%3A&url=http%3A%2F%2Fexample.com"
This works, because we translated our generalized parameter title
to text
, a valid URL parameter in the Twitter sharing URL.
We could have translated description
to text
, but descriptions
are supposed to be longer and are thus more likely to exceed the 140 character limit along with the value for the url
parameter, which we didn't translate, because it's a valid Twitter sharing URL parameter.
As you can see, every new channel module starts with use GiveAway.Channel
and implements the following three simple functions:
base_uri
As its name says, base_uri
function that returns the base uri for the sharing URL.
valid_params
A function that returns a list of valid parameter names for this channel as strings.
parse_param
The function that translates our generalized paramters to valid sharing URL parameters, as described above.
Create your own channel module
Assuming we want to create new sharing channel module for Pinterest. The base URL is https://pinterest.com/pin/create/bookmarklet
and the paramters we need are url
, which is the URL to share, media
which is a URL to an image and description
. That's all the information we need to implement the module:
defmodule Pinterest do
use GiveAway.Channel
def base_uri do
"https://pinterest.com/pin/create/bookmarklet"
end
def valid_params do
~w(url media description)
end
def parse_param(tuple) do
case tuple do
{"image", value} -> {"media", value}
tuple -> tuple
end
end
end
We don't need to remap url
and description
, but image
can be mapped to media
and all three parameters will work.
We can now get the URL like this:
GiveAway.url(Pinterest, %{
"url" => "http://example.com",
"description" => "Look at this image",
"image" => "http://placehold.it/400x300"
})
or, since every Module that uses GiveAway.Channel
gets assigned uri/0
implicitly, get the sharing URL directly via the channel module:
Pinterest.uri(%{
"url" => "http://example.com",
"description" => "Look at this image",
"image" => "http://placehold.it/400x300"
})
Which should give the same result.
Create a list of URLs
You can create a whole list of URLs with GiveAway.urls/2
:
channels = [pinterest: Pinterest, facebook: Facebook, twitter: Twitter]
parameters = %{
"url" => "https://elixir-lang.org/",
"title" => "The Elixir Programming Language",
"description" => "",
"image" => "http://placehold.it/400x300"
}
GiveAway.urls(channels, parameters)
This yields:
[pinterest: "https://pinterest.com/pin/create/bookmarklet?description=&media=http%3A%2F%2Fplacehold.it%2F400x300&url=https%3A%2F%2Felixir-lang.org%2F",
facebook: "https://www.facebook.com/sharer/sharer.php?description=&picture=http%3A%2F%2Fplacehold.it%2F400x300&title=The+Elixir+Programming+Language&u=https%3A%2F%2Felixir-lang.org%2F",
twitter: "https://twitter.com/intent/tweet?text=The+Elixir+Programming+Language&url=https%3A%2F%2Felixir-lang.org%2F"]
Done
And there you have it! Questions? Ideas? Am I doing something wrong? Improvements? Drop me a line or send me a pull request.