README.txt in ShURLy 7

ShURLy is a URL shortening service implemented as a module for Drupal. This module was written by Jeff Robbins for [Lullabot](http://lullabot.com)'s URL shortener: <http://lb.cm>

It is intended to be fast, clean, simple, self-contained, user-friendly, flexible, and easy to set up.

New URLs are created by going to /shurly and entering the long URL and an optional custom short URL. Short URLs have ownership and each user can track click statistics for his/her URLs.

To maximize the use of characters, URLs are case sensitive. With the correct permissions, short URLs can either be entered custom or autogenerated. Autogenerated URLs use the character set of A-Z, a-z, 0-9. However the characters "01lIO" are not used since these characters are often ambiguous, particularly in print (thanks to Tantek �elik for this suggestion). Custom URLs may contain any non-reserved characters including UTF8 characters, glyphs, and icons. How fun is that!?

Features
-------------------------
- Case sensitive custom URLs
- Unicode (UTF8) URLs
- URLs can be autogenerated or custom (entered by user)
- Extensive role-based permissions
- Click-to-copy-to-clipboard functionality on short URLs
- "Create a Twitter message with this URL" Twitter integration on result form
- Click tracking on each short URL
- Short URLs are associated with user accounts. Logged-in users can see their URLs history as well as the number of clicks on each.
- "Drag to bookmark bar" Javascript bookmarklet to create URLs quickly from any web page
- [Safari browser extension](http://github.com/downloads/Lullabot/shurly/shurly.safariextz) to create URLs without leaving current web page
- Blocks for URL creation form, bookmarklet, and URL history
- Views integration. Short URLs are displayable objects
- Magic happens during `hook_boot()` for fast, efficient, and early redirection. Doesn't require a full Drupal bootstrap to redirect. Also redirection works even if page caching is turned on. If unsupported short-url characters (such as "/") are part of the incoming URL, ShURLy doesn't even add a database query.
- Web services API to shorten/expand URLs. Data output options: text, JSON, JSONP, XML, PHP serialized array
- Supports configurable per-role rate limiting. Roles can be limited to {X} requests every {Y} minutes to prevent automated misuse of the website or API.
- Per-user API key generation to allow user-associated web services interaction
- `hook_shurly_redirect_before()` and `hook_shurly_redirect_after()` allows other modules to tap in and alter the redirection, or log additional info to the database (IP tracking, anyone?)
- Support Google Safe Browsing API (v4).
- Google Analytics Integration.
- 'Copy to clipboard' button if the clipboardjs module is installed (https://www.drupal.org/project/clipboardjs)

USAGE
----------------------------
1. Place the module in your modules directory and enable.
2. Visit admin/user/permissions to set up permissions for Shurly (see explanation of permissions below).
3. To create a new short URL, visit /shurly or add the "Create a short URL" block to your site.
4. To view your own URLs, visit /myurls or add the 'My URLs' block
5. Administrators can view all users' URLs at admin/structure/shurly
6. To configure rate limiting, visit admin/structure/shurly/settings

Since short URLs are created at the root path of the site (http://example.com/_myURL_), it is recommended that this module be used as the basis for a complete site, not as an add-on to an existing site. That being said, the module does its best to ensure that entered URLs don't conflict with existing menu entries and path aliases in the current Drupal installation. ShURLy should work even if Drupal is installed in a subdirectory or without clean URLs.

Views
----------------------------
ShURLy is completely integrated with the Views module and ShURLy links can be listed/sorted/displayed using Views. Views is a dependency of this module since all listings are created using Views, including the administrative page at admin/structure/shurly. Views also provides a page at /myurls where users with "View own URL stats" can see & sort their URLs.

Views integration also means that you could create new pages/blocks with listings like "most popular URLs", "users with most popular URLs", "most recent URLs", "most recently clicked URLs", or a tab on a user's page to show others their most recent URLs, and that sort of thing.

Blocks
---------------------------
- **Create a short URL**:
    the form to create a URL
- **ShURLy bookmarklet**:
    A block containing a "drag to your bookmarks bar" link. Clicking this
    bookmarklet when on a page bring the user to the the URL shortening 
    site with the URL field filled in for that page.
- **My URLs**:
    This block is created by Views and is basically just a mirror the
    /myurls page. However, by putting this content into a block, you can
    put it into the 'content bottom' region on the /shurly page and get
    a single page with both the entry form and the URL listing

Permissions
----------------------
- **Create short URLs**:
    Allow users in this role to create URLs. This permission also allows users to delete URLs which they have created.
- **Enter custom URLs**:
    Allow users in this role to enter their own short URLs, 
    without this permission all URLs will be autogenerated
- **View own URL stats**:
    Allow users to view the "My URLs" page (at /myurls)
- **Delete own URLs**:
    Users may 'delete' URLs which they have created. For security reasons, 
    these URLs are actually only deactivated. They still exist in the
    database and new URLs are not allowed to be created with the same
    short URL path.
- **Administer short URLs**:
    This permission allows users to edit/delete/view all short URLs by 
    all users. This is the administrative permission and should be 
    used carefully
    
Additional notes
----------------------
- **Short URL reuse**:
  In order to maximize efficiency, autogenerated URLs are reused in the following cases: When a user enters a long-URL without a custom short-URL path *and* that long-URL already exists in the database owned by that user, the previous autogenerated short-URL will be returned and a new short-URL will not be created. This means that if I've created a non-custom short URL for http://www.lullabot.com and I enter that URL it again, ShURLy will return the same short-URL. Also keep in mind that all anonymous users are treated as a single user, so if one anonymous user creates an autogenerated short-URL for a given long-URL, this short-URL will be reused for any other anonymous user who enters that same long-URL. Custom URLs are not reused.
    
Links
---------------------
**GitHub page** (main development version): <http://github.com/Lullabot/shurly>  
**Drupal.org page**: <http://drupal.org/project/shurly>  
**Demo**: <http://lb.cm>  
**Other Demo**: <https://lc.cx>  
**Inspiration**: <http://www.youtube.com/watch?v=Qo7qoonzTCE>  
**Lullabot**: <http://www.lullabot.com>

I *am* serious, and *don't* call me Shurly!