grtp.co

Gratipay Widgets + API

Getting Started with Development

Quickstart:

$ git clone git@github.com:gratipay/grtp.co.git
$ cd grtp.co
$ make run

Then visit http://localhost:9537/test/. For more details, read Development section below.

Documentation

For now documentation for widgets API is present in JSDoc comments, but not generated into more readable format.

Configuration options:

• window.grtpAPI - Where to look for the grtp.co API
  • defaults to https://grtp.co/v2/
• window.gratipayURI - Where to look for Gratipay
  • defaults to https://gratipay.com/

Examples

In the following examples, just switch out my-team with your Gratipay Team slug.

Standard Widgets

<script data-gratipay-teamslug="my-team"
  src="https://grtp.co/v2.js" async></script>

Custom Widgets

You can create your own widgets by adding data-gratipay-widget="custom" to your widget's HTML, and the following classes:

• Text
  • gratipay-teamslug - the Team's slug
  • gratipay-receiving - dollar-sign prefixed value of receiving
• Links
  • gratipay-profile-link - sets the href attribute to the Team's profile link
  • gratipay-link - sets the href attribute to https://gratipay.com/
• Misc styling

<div data-gratipay-teamslug="my-team" data-gratipay-widget="custom">
  I receive <a class="gratipay-profile-link">
    <span class="gratipay-receiving">$0.00</span> / wk
  </a>
  on <a class="gratipay-link">Gratipay</a>.
</div>
<script src="https://grtp.co/v2.js"></script>

Shields.io

Shields can be created for ~users or projects:

Projects

<img src="http://img.shields.io/gratipay/team/Gratipay.svg">

[![](http://img.shields.io/gratipay/team/Gratipay.svg)]()

(Shields.io still uses "team" rather than "project.")

~users

<img src="http://img.shields.io/gratipay/user/zzzeek.svg">

[![](http://img.shields.io/gratipay/user/zzzeek.svg)]()

Other Widgets

Google Gadget for Blogger.

Development

https://grtp.co/ is a static site. But it is generated from sources.

Typical site like https://gratipay.com/ is divided into backend and frontend. backend is Python code that runs on server side. frontend is HTML+CSS+Javascript that is processed by browser.

https://grtp.co/ is pure frontend, but its HTML+CSS+Javascript sources from repository are not what is being run on the site. Before sources can be deployed, they need to be minified, tested and, if you write styles in SASS, the .sass files need to be compiled into CSS. So repository layout looks like:

lib/   - source files that need to be compiled
www/   - static files that are copied as-is

Javascript tools to build, lint and test source are similar to Python tools. This can be matched approximately as this:

JavaScript     |  Python
--------------------------------------------------------
npm            |  pip
package.json   |  setup.py, setup.cfg, requirements.txt
Grunt          |  make, fabric, SCons
Gruntfile.js   |  Makefile, fabfile.py, SConstruct

Grunt is popular JS build systems, and there are many others, like Gulp for example. It should be noted that npm itself has some kind of dependency management, so you may not need Grunt at all.

http://blog.keithcirkel.co.uk/why-we-should-stop-using-grunt/

Release and Deployment

Grtp.co is hosted on Heroku.

Deploy

Bump version in package.json and create new tag.

Add the Heroku remote to your own local repo:

git remote add heroku https://git.heroku.com/grtp.git

Then you can git push heroku master. The heroku/nodejs buildpack will then npm build the sources and save them in www/. heroku-buildpack-static takes over and serves web requests from the www directory.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

To help keep a consistent style, we also recommend using EditorConfig.

License

Released into the public domain (per CC0).