Report Bug

Zarino Interface Guidelines

You’re making a tool, that’s brilliant! Our UX guru, Zarino, has worked out some of the hard details so you don’t have to.


Naming your tool

Tool names should start with a verb

Examples of good tool names include:

  • Upload a spreadsheet
  • Code in your browser
  • Search for Tweets
  • Import LinkedIn connections

Try to keep the name short (3-4 words max). You can always expand more in the description (10 words max).

Try not to use the verb "scrape". "Import", "search" and even plain old "get" are far clearer.

Use sentence case. i.e. Only capitalise the first word, and any proper nouns.

Tool descriptions have no full stop

For example put "Sort, search and page through your data" not "Sort, search and page through your data."

When writing descriptions, think about what the user will want to know first about the tool. If you find you have lots of sentences, your description is too long.


SQL

QuickCode tools currently store data in SQLite databases.

A convention has developed whereby you can signal to other tools that a table or column should not be shown to end-users: prefixing the table or column name with an underscore.

  CREATE TABLE "example" (first_name, last_name, _ignore_this_column)
  CREATE TABLE "_hide_this_table" (log_id, log_text)

In this way, the tables and columns are still available to tool developers and power-users, but typical end-users won’t see them.


HTML & CSS

When in doubt, use Bootstrap

Bootstrap is a CSS and Javascript framework that makes it easy to build good-looking interfaces using a handful of tags and classes. All of the Bootstrap CSS Classes and more Advanced Components are supported in QuickCode.

Remember to include Bootstrap and the QuickCode stylesheet in your HTML <head>, as described in the Documentation.

<link rel="stylesheet" href="//scraperwiki.com/vendor/style/bootstrap.min.css">
<link rel="stylesheet" href="//scraperwiki.com/style/scraperwiki.css">
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"></script>
<script src="//scraperwiki.com/vendor/js/bootstrap.min.js"></script>

Button loading state

Where a user clicks a button in your tool, and their information is sent to the server for processing, you should add a loading class to the button, so the user knows what’s happening. You may also want to disable the button so further clicks are ignored. For example:

$('#mybutton').on('click', function(){
  $(this).attr('disabled', true)  // Disable further clicks.
  $(this).addClass('loading').html('Loading&hellip;')  // Spinny loader.
})

Here’s what it might look like: Loading…