give_away

GiveAway is a simple, extensible library for generating social media sharing URLs.


Keywords
elixir, media, sharing, social, uris, urls
License
Apache-2.0

Documentation

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.