Gratipay Widgets + API
JavaScript HTML Nginx Other
Latest commit e48a57e Jul 15, 2016 @mattbk mattbk committed on GitHub Merge pull request #148 from gratipay/fix-amount-format
Fix amount formatting
Permalink
Failed to load latest commit information.
bin remove www from gratipay.com urls Aug 29, 2014
infra Remove links to GitHub tickets Jul 14, 2016
lib Fix amount formatting (#110 & #140) Jul 14, 2016
test Update nomenclature in tests Jun 30, 2016
www index.html: Link to examples is more useful Feb 2, 2015
.editorconfig Update .editorconfig to match www.gittip.com Apr 2, 2014
.gitignore Ignore bower_components Jan 5, 2014
.jshintrc Enforce 4-space indentation Aug 31, 2014
.travis.yml
COPYING Find and replace gittip, Gittip, gttp Aug 29, 2014
Gruntfile.js Update Blogger widget for v2 Jun 30, 2016
Makefile Rename command 'deploy' -> 'build' Mar 9, 2015
README.md
package.json Change author in package.json Jun 14, 2016

README.md

grtp.co Builds

Gratipay widgets + widget 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>

Other Widgets

Shields.io:

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

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 a Digital Ocean VPS (called droplet) accessible through SSH. It runs nginx and the publishing root is /home/grtp.co/production/www.

To access the server, you need someone who already has access to add your key to /home/grtp.co/.ssh/authorized_keys

Look in the infra/ directory in this repo for deployment files. In production, infra/nginx.conf in symlinked to /etc/nginx/sites-enabled/grtp.co, and infra/post-receive to /home/grtp.co/production/.git/hooks/post-receive.

Initial Server Setup

The system-application layout is following:

/etc/nginx/sites-enabled/grtp.co  - nginx config
/home/grtp.co/production          - code checkout
                .git/hooks/post-receive
                                  - auto-update script

Then use root/sudo to create user grtp with home at grtp.co and install required packages - nginx, git.

adduser grtp --home=/home/grtp.co --disabled-password --gecos ""
apt-get install nginx git

# now log into grtp user
su grtp

With new grtp user:

cd ~
git clone https://github.com/gratipay/grtp.co.git production
cd production

Setup automatic update on push:

cp infra/post-receive .git/hooks/
chmod +x .git/hooks/post-receive

Deploy

Bump version in package.json and create new tag.

Add the remote to your own local repo:

git remote add prod grtp@grtp.co:production

Then you can git push prod. The post-receive hook will update the filesystem on the droplet and runs the grunt build task that minifies code and copies files from lib to www, and then it will reload nginx configuration.

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).