From 061536c3e294b0e66ab3cfdba68b3ea11f35c53b Mon Sep 17 00:00:00 2001 From: Artem Sapegin Date: Thu, 10 Apr 2014 11:01:30 +0400 Subject: [PATCH] Tweak readme and contributing guidelines. --- Contributing.md | 7 ++-- Readme.md | 99 +++++++++++++++++++++++++------------------------ 2 files changed, 55 insertions(+), 51 deletions(-) diff --git a/Contributing.md b/Contributing.md index 2405ca1..0d27d3f 100644 --- a/Contributing.md +++ b/Contributing.md @@ -6,7 +6,7 @@ I love pull requests. And following this simple guidelines will make your pull r ## Submitting pull requests 1. Create a new branch, please don’t work in master directly. -2. Add failing tests (if there’re any tests in project) for the change you want to make. Run tests (usually `grunt` or `npm test`) to see the tests fail. +2. Add failing tests (if there’re any tests in project) for the change you want to make. Run tests (see below) to see the tests fail. 3. Hack on. 4. Run tests to see if the tests pass. Repeat steps 2–4 until done. 5. Update the documentation to reflect any changes. @@ -60,13 +60,14 @@ function foo(bar, fum) { - Feel free to [ask me](http://sapegin.me/contacts) anything you need. -## How to build / test +## Building and running tests `cd` to `src` folder first. Install dependencies: ```bash +npm install grunt-cli -g npm install ``` @@ -76,7 +77,7 @@ Hack on: grunt watch ``` -Build: +Build / run tests: ```bash grunt diff --git a/Readme.md b/Readme.md index d5a2a26..6e9ef72 100644 --- a/Readme.md +++ b/Readme.md @@ -3,13 +3,13 @@ [![Bower version](https://badge.fury.io/bo/social-likes.png)](http://badge.fury.io/bo/social-likes) [![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/) -Beautiful “like” buttons with counters for popular social networks: Facebook, Twitter, LiveJournal, etc. Uses jQuery. +Beautiful share buttons with counters for popular social networks: Facebook, Twitter, Google+, Pinterest, Vkontakte, etc. Uses jQuery. ## Features - Easy to install. -- Beautiful and all in one style. +- Beautiful and all in one style (with three different skins). - Won’t explode your page’s layout. @@ -19,6 +19,7 @@ Use [interactive builder](http://sapegin.github.io/social-likes/) to generate th Or install via [Bower](http://bower.io/): `$ bower install social-likes`. + ## Advanced configuration ### Layout @@ -28,10 +29,10 @@ Or install via [Bower](http://bower.io/): `$ bower install social-likes`. All buttons in a row. ``` - + ``` #### Vertical @@ -39,10 +40,10 @@ All buttons in a row. All buttons in a column. ``` - + ``` #### Single button @@ -50,10 +51,10 @@ All buttons in a column. One button with a counter (summ of all the networks). Opens popup with like buttons in vertical layout. Use `data-single-title` attribute to change button title. ``` - + ``` #### Icons only @@ -61,10 +62,10 @@ One button with a counter (summ of all the networks). Opens popup with like butt If you want to remove button titles add `social-likes_notext` class to make it looks better. ``` - + ``` @@ -72,10 +73,6 @@ If you want to remove button titles add `social-likes_notext` class to make it l Options define via HTML data attributes or JavaScript parameters object. -`service` - -Setup service from data instead of class name. From class name by default. - `url` URL of shareable page. Current page by default. @@ -103,15 +100,15 @@ Share button title for “single button” mode. Default: “Share”. Examples: ```html - + ``` ```html - + ``` ```js @@ -123,22 +120,23 @@ $('.social-likes').socialLikes({ }); ``` + ### Services specific options #### Twitter -You can specify `via` (site’s Twitter) and `related` (any other Twitter you want to advertise) values for `
  • `: +You can specify `via` (site’s or your own Twitter) and `related` (any other Twitter you want to advertise) values for `
  • Twitter
    • +
    Twitter
    ``` #### Pinterest -You should specify an image URL via data-media attribute on `
  • `: +You should specify an image URL via data-media attribute on `
    `: ```html -
  • Pinterest
    • +
    Pinterest
    ``` ### Manual initialization @@ -146,25 +144,26 @@ You should specify an image URL via data-media attribute on `
  • -
  • Facebook
    • +
    + ... - +
    ``` ```javascript $('#share').socialLikes(); ``` + ### Dynamic URL changing You can dynamically replace URL, title and Pinterest image without reinitialization. ```html - + ``` ```javascript @@ -177,9 +176,10 @@ $('#share2').socialLikes({ }); ``` + ### Refreshing counters -By default counters for any uniqe URL requested only once. You can force new request with `forceUpdate` option: +By default counters for any unique URL requested only once. You can force new request with `forceUpdate` option: ```javascript $('#share2').socialLikes({ @@ -230,11 +230,12 @@ $('.social-likes').on('popup_closed.social-likes', function(event, service) { }); ``` + ### Adding your own button -You can find some custom buttons in `contrib` folder. +You can find some custom buttons in `contrib` folder. -Define `socialLikesButtons` hash: +Define `socialLikesButtons` object: ```javascript var socialLikesButtons = { @@ -246,7 +247,7 @@ var socialLikesButtons = { }; ``` -If you know the social network search page's url, you can make a link to results of searching in this network. There are search urls for Twitter and VKontakte by default. +If you know the social network search page's URL, you can make a link to results of searching in this network. There are search URLs for Twitter and VKontakte by default. ```javascript var socialLikesButtons = { @@ -255,7 +256,7 @@ var socialLikesButtons = { searchUrl: 'https://twitter.com/search?src=typd&q={url}' } }; -``` +``` Add some CSS: @@ -270,15 +271,23 @@ Add some CSS: } ``` -And use in like any other button: +And use it like any other button: ```html -
  • Surf
    • +
    Surf
    ``` See sources (`src` folder) for available options and class names and `contrib` folder for custom buttons examples. +## FAQ + +### Likes or shares? + +This plugin allows your users to “share” the content of your website. (Un)fortunately¹ real “likes” are possible only when you use original Facebook, Google+, etc. buttons. + +¹ I believe that “shares” are much better and valuable than “likes” because they’re more visible in feed and users could add they’re own comments to links they share. “Like” costs nothing. + ### How to change title, description and image You can use [Open Graph](http://ogp.me/). It works for [Facebook](http://davidwalsh.name/facebook-meta-tags), Twitter, [Google+](https://developers.google.com/+/web/snippet/), [Pinterest](http://developers.pinterest.com/rich_pins/) and [Vkontakte](http://vk.com/dev/widget_like)). @@ -296,7 +305,7 @@ You can add additional Twitter data using [Twitter Card](https://dev.twitter.com ``` -If you’re experincing any problems with meta data try [Open Graph Debugger](https://developers.facebook.com/tools/debug/) and [Twitter Card Validator](https://dev.twitter.com/docs/cards/validation/validator). +If you’re experiencing any problems with meta data try [Open Graph Debugger](https://developers.facebook.com/tools/debug/) and [Twitter Card Validator](https://dev.twitter.com/docs/cards/validation/validator). ### How to use Social Likes with Wordpress, etc. @@ -304,17 +313,11 @@ If you’re experincing any problems with meta data try [Open Graph Debugger](ht See [wiki](https://github.com/sapegin/social-likes/wiki/How-to-use-Social-Likes-with-Wordpress,-etc.). -## Troubleshooting and FAQ - -### Likes or shares? - -This plugin allows your users to “share” the content of your website. (Un)fortunately¹ real “likes” are possible only when you use original Facebook, Google+, etc. buttons. - -¹ I believe that “shares” are much better and valuable than “likes” because they’re more visible in feed and users could add they’re own comments to links they share. “Like” costs nothing. +## Troubleshooting ### Counters don’t work -In most cases if you don’t see counters it’s because social networks APIs return zeroes. You could check API requests results in Network tab in your browser’s developer tools: +In most cases if you don’t see counters it’s because social networks APIs return zeros. You could check API requests results in Network tab in your browser’s developer tools: ![](http://cl.ly/image/013x2M01021N/Image%202014-03-06%20at%205.33.14%20%D0%BF%D0%BE%D1%81%D0%BB%D0%B5%20%D0%BF%D0%BE%D0%BB%D1%83%D0%B4%D0%BD%D1%8F.png)