Pageclip Documentation

Pageclip is a simple way to save information from your website via forms or front-end JavaScript. That is, you can save data from your website without a server—Pageclip is your server.

Pageclip works great when you want the simplicity of a static website, but don't want to setup a server for a form or two. Capture leads on landing pages, use for contact forms, collecting emails for a newsletter, polls, surveys, etc.

Pageclip works anywhere you can put an HTML form. It works with any static site generator e.g. Jekyll, Hugo, Hexo, GitBook, Gatsby and all others. Pageclip also works on any hosting provider, from static hosting providers like GitHub Pages or S3, to Platform-as-a-Service providers like Heroku and Docker, and any other method of hosting you have up your sleeve.

Setup

First thing's first: have a website where you have access to edit the HTML :)

Create a Pageclip account if you haven't already. Once you have created an account, Pageclip will ask you to setup a site.

Sites

A site is a website that has one or more forms you want to save to Pageclip. Give your site a name, and its domains.

  • Name - The name can be anything that helps you remember the site e.g. Personal Blog
  • Domains - Domains are a comma-separated list of domains (with or without subdomains) that can send data to this Pageclip site. For example, example.com,localhost will save data from forms on http://example.com, http://www.example.com, and http://localhost:3000, but reject data from http://www.unicorns.com.

Forms

If you have more than one form on your website that you want to store in Pageclip, you will need to create a named form in Pageclip's UI for each form on your site.

For example, if you have a contact form and a newsletter form, you would create two named forms in Pageclip: contact, and newsletter.

Website Integration

Pageclip provides an HTTPS endpoint that will accept form data for each site and form. After you have created a site in Pageclip, it will show you the code to place on your website.

Step 1: You place a script tag before the </body> tag. This script provides the Pageclip global. By default this script will look for all form.pageclip-form elements on the page, and wrap them.

<script src="https://s.pageclip.co/v1/pageclip.js" charset="utf-8"></script>

Step 2: Next, you add the stylesheet to the <head>. It provides a loading spinner on the submit button and a 'thank you' message shown to the user after they have submitted the form. Feel free to override it with your own styling.

<link rel="stylesheet" href="https://s.pageclip.co/v1/pageclip.css" media="screen">

Step 3: Create your form with the specified form element. The key pieces are the action= attribute and the class="pageclip-form" attribute.

<form action="https://send.pageclip.co/{yourSiteKey}/{formName}" class="pageclip-form" method="post">
  <!-- Add your inputs with your own as you normally would -->
</form>

Add your own <input /> tags with your own form fields, taking care that they have a name="..." attribute. Only fields with a name attribute will be saved to Pageclip.

Using name and email fields, this code will produce the following form:

example

Note that the form is submitted asynchronously and shows a 'thank you' message to the user once successfully submitted.

What data is saved?

Any form <input>, <textarea>, or <select> element with a name attribute is saved into Pageclip. Some notes:

  • Naming inputs with square brackets (e.g. someName[aChildKey]) will save the input under a child object. This is useful for groups of things like checkboxes. e.g. {someName: {aChildKey: true}}
  • Checkboxes (<input type="checkbox">) are stored as booleans. When unchecked, the browser does not send the input in the request, so a checkbox value will either be true, or the key will not exist at all.
  • File inputs (<input type="file">) are ignored, and multipart requests will be rejected.

An example form:

<form action="https://send.pageclip.co/{yourSiteKey}/{formName}" className="pageclip-form" method="post">

  <!-- text field -->
  <input type="email" name="email" value="bob@omg.com"/>

  <select name="heardFrom">
    <option value="ph" selected>Product Hunt</option>
    <option value="hn">Hacker News</option>
  </select>

  <!-- radio buttons -->
  <input type="radio" name="animal" value="tarantula" id="tarantula" checked/>
  <label htmlFor="tarantula">Tarantula</label>

  <input type="radio" name="animal" value="turtle" id="turtle"/>
  <label htmlFor="turtle">Turtle</label>

  <!-- checkboxes -->
  <input type="checkbox" name="likes[pizza]" id="pizza" checked/>
  <label htmlFor="pizza">Pizza 🍕</label>

  <input type="checkbox" name="likes[yams]" id="yams"/>
  <label htmlFor="yams">Sweet Potatos 🍠</label>

  <!-- hidden inputs -->
  <input type="hidden" name="version" value="v1" />
  <button class="pageclip-form__submit" type="button">
    <span>Submit</span>
  </button>
</form>

Will save the following payload:

{
  email: 'bob@omg.com',
  heardFrom: 'ph',
  animal: 'tarantula',
  likes: {
    pizza: true
  },
  version: 'v1'
}

Special fields

Pageclip can send you an email for each form submission and there are two specially named fields that make those emails easier to use:

  • email - the user's email. This will be used in the reply-to field of the email that Pageclip sends you. So all you have to do is hit 'Reply' in your email client to respond to the user.
  • subject - This will set the subject of the email that Pageclip sends you for each submission.

These fields are useful when you setup contact forms. An example contact form:

<form action="https://send.pageclip.co/{yourSiteKey}/{formName}" className="pageclip-form" method="post">

  <!-- This will be used in the email's reply-to field. Must have name="email" -->
  <input type="email" name="email" value="bob@omg.com"/>

  <!-- This will be used in the email's subject. Must have name="subject" -->
  <input type="text" name="subject" value="Email subject"/>

  <textarea name="body">Email body</textarea>

  <button class="pageclip-form__submit" type="button">
    <span>Submit</span>
  </button>
</form>

Bare minimum integration

You do not need to use the default asynchronous submission behavior. The absolute minimum you need to do is have your form POST to your site URL:

<form method="post" action="https://send.pageclip.co/{yourSiteKey}">
  <input type="text" name="name" value="Billy Jean"/>
  <input type="text" name="email" value="billy@example.com"/>
  <input type="submit" value="Send">
</form>

With this form, Pageclip will save the data, then redirect back to the originating page.

Using the loading spinner

Pageclip can overlay a loading spinner on your submit button with some special markup. You must have a <button> element with the .pageclip-form__submit and a <span> child.

<form>
  ...
  <button class="button pageclip-form__submit" type="submit">
    <span>Submit</span>
  </button>
</form>

Styling the spinner

By default the spinner is white. You can change it to black by adding the pageclip-form__submit--dark-loader class to the button.

default button
using the `dark-loader` class

You can specify a custom color by styling the border

.pageclip-form__submit::after {
  border-color: rgba(0, 255, 0, 0.8);
  border-left-color: blue;
}
very attractive custom loader

Loading spinner details

When a form is submitted, the <button> will go through a few CSS class states. These classes provide CSS animations.

  • .pageclip-form__submit--start-loading: fades the <span> text out, and pops the loader into view
  • .pageclip-form__submit--loading: spins the loader
  • .pageclip-form__submit--end-loading: hides the loader, and fades the <span> text back in.

Some notes:

  • If the inner <span> is not specified, it will just overlay the spinner on the text.
  • If an <input type="submit" /> is used, the loading spinner will not work. A button must be used as the loading spinner is rendered in the ::after pseudo element.
  • The start and animations can be removed from the button. If animations do not exist, the JS will detect it and only add the .pageclip-form__submit--loading class to the button.

Form validation

Pageclip does not provide form validation built in. You can use your favorite form validation library, or you can use built-in HTML5 validation. HTML5 validation is very rich these days, and has good browser support.

A basic example enforcing required attributes

<!-- Note the `required` attributes in inputs! -->
<form method="post" action="https://send.pageclip.co/{yourSiteKey}">
  <input type="text" name="name" required />
  <input type="text" name="email" required />
  <input type="submit" value="Send">
</form>

Form Validation Resources

Saving data to a specific form

By default, your site URL will save data to the 'default' form

# Saves to the default form
https://send.pageclip.co/{yourSiteKey}

# e.g. This URL saves to the default form
https://send.pageclip.co/1WoHHQWPLiWnR7IzGKwW9PROHL2G51BP

After you setup a named form in the Pageclip UI, you can save to that named form by appending the formName onto the end of your site's URL:

# Saves to the default form
https://send.pageclip.co/{yourSiteKey}/{formName}

# e.g. This URL saves to the 'newsletter' form
https://send.pageclip.co/1WoHHQWPLiWnR7IzGKwW9PROHL2G51BP/newsletter

Advanced integration (pageclip.js)

When https://s.pageclip.co/v1/pageclip.js is included on the page, a window.Pageclip object is created. With it, you can hook into form submission, or send data to pageclip without a form at all.

Pageclip.form(form[, options])

Pageclip.form(...) wraps a form, submits the data to Pageclip asynchronously, and gives you a couple hooks into the lifecycle. You can use these for things like validation or displaying messages to the user. By default, any forms with class pageclip-form will be automatically wrapped with Pageclip.form(...).

  • form:HTMLFormElement - the <form /> element to submit to Pageclip. It must have an action pointing to your Pageclip site.
  • options:Object - (optional)
    • onSubmit:Function - returning false from this will prevent submission to Pageclip
    • onResponse:Function - returning false from this will prevent showing the successTemplate to the user
    • successTemplate:String
var form = document.querySelector('.pageclip-form')
Pageclip.form(form, {
  onSubmit: function (event) { },
  onResponse: function (error, response) { },
  successTemplate: '<span>Thank you!</span>'
})

Pageclip.send(siteKey, formName, data, callback)

Pageclip.send(...) allows you to send arbitrary JSON data via XHR to a Pageclip form.

  • siteKey:String - Your public siteKey; a unique token give to each site.
  • formName:String - The name of the form to save to. If you wish to send to a default form, formName must be 'default'.
  • data:Object - The actual data to save. JSON.stringify() will be called on this object before submission.
  • callback:Function - Called when submission is finished
    • error:Error - null when the request succeeds; Object with .message on failure.
    • response:Object - {"data":"ok"}
var data = {
  name: 'Billy Jean',
  email: 'billy@example.com'
}
Pageclip.send('...yourSiteKey...', 'contact', data, function (error, response) {
  console.log('saved?', !!error, '; response:', error || response)
})

REST API

The REST API allows you to send and fetch data from a Pageclip site/form. You can use the API from a script, server, or anywhere other than a browser that can make HTTP requests.

API Keys

The API uses a private API key that is different from the siteKey. siteKeys are write only, while your API keys are read and write. It is important not to share your API keys or place them on your website. You can tell API keys and siteKeys apart by the prefix; API keys are prefixed with api_.

# An example. API keys are prefixed with `api_`. Keep this key private!
api_FP1We0oW9OcXlVurbLMxk1iGQrtGBR1W

At this time, each site you create in Pageclip gets its own private API key. i.e. There is no single API key for your account that works across all of your sites.

API Version

The Pageclip REST API is currently version v1. Version is specified via the HTTP Accept header. Please use this value in the Accept header

application/vnd.pageclip.v1+json

If you do not set this value in the header, future API version changes could break your client.

API Clients

At this time, there is a node API client.

npm install --save pageclip
import Pageclip from 'pageclip'
const pageclipAPIKey = 'api_abc123abc123...'
const pageclip = new Pageclip(pageclipAPIKey)

pageclip.send({some: 'data'}).then((response) => {
  console.log(response.status, response.data) // => 200, [Item, Item]
}).then(() => {
  return pageclip.fetch()
}).then((response) => {
  console.log(response.status, response.data) // => 200, [Item, Item]
})

See the node API client GitHub page for documentation.

Authentication

Pageclip uses HTTP Basic Auth. Your API key is sent as the username, and there is no password. The API key must be base64 encoded.

curl --user {yourAPIKey}: https://api.pageclip.co/...

# Example. curl will base64 encode the username by default
curl --user 01rhIN80DZkv1aTwtvqI1Yqe6P0mUK2E: https://api.pageclip.co/...

Errors

API errors will return a JSON response with an errors key that contains an Array of objects:

{
  errors: [{
    message: 'Name is required',
    property: 'name' // If the error is associated with a property
  }, ...]
}

Endpoints

PUT /api/data/[formName]

Save JSON data to a form. Allows submitting one or many items.

Returns a JSON object with the form name, and an Array of the Items that were saved.

  • formName is optional; when formName is omitted, it will save to the default form.
{
  form: 'formName',
  data: [Item]
}
# Save one object
curl \
  -X PUT \
  -u 01rhIN80DZkv1aTwtvqI1Yqe6P0mUK2E:
  -H 'Content-Type: application/vnd.pageclip.v1+json' \
  -d '{"name":"bob"}' \
  https://api.pageclip.co/data/newsletter
#=> {"form": "newsletter", "data": [Item({name: 'bob'})]}

# Save multiple objects
curl \
  -X PUT \
  -u 01rhIN80DZkv1aTwtvqI1Yqe6P0mUK2E:
  -H 'Content-Type: application/vnd.pageclip.v1+json' \
  -d '[{"name":"bob"}, {"name":"sally"}]' \
  https://api.pageclip.co/data/newsletter
#=> {"form": "newsletter", "data": [Item({name: 'bob'}), Item({name: 'sally'})]}

GET /api/data/[formName]

Fetch items from a form.

Returns a JSON object with the form name, data type of data, and an Array of Items. At this time, GET returns all items in a form.

  • formName is optional; when formName is omitted, it will retrieve items from the default form.
// /api/data/newsletter
{
  form: 'newsletter',
  dataType: 'json',
  data: [Item, Item]
}

You can request CSV data with the dataType query parameter:

// /api/data/newsletter?dataType=csv
{
  form: 'newsletter',
  dataType: 'csv',
  data: 'name,email\nbob,bob@omg.com'
}
curl \
  -X GET \
  -u 01rhIN80DZkv1aTwtvqI1Yqe6P0mUK2E:
  -H 'Accept: application/vnd.pageclip.v1+json' \
  https://api.pageclip.co/data/newsletter
#=> {"form": "newsletter", "dataType": "json", "data": [Item, Item, ...]}

Items

All Item objects returned by the API will have the following shape:

{
  itemEid: 'abc123ABC123abc123abc123abc12345',
  createdAt: '1983-06-29T14:48:00Z', // ISO date
  payload: {
    // the data from the user
  }
}