caracol 4 chrome - extends browser integration of the caracol app

Table of Contents

• Description
• Installing
• The Code
• Challenges
• License

##Description

Caracol's greatest feature is its ability to bubble-up content relevant to the interest of the user. This extension offers several features for the user, which extend the features of the Caracol web directly into the browser.

This extension overrides the default new-tab behavior in Google chrome. When a user opens a new tab, they'll receive their Caracol recommendations. It also provides a handy way for them to interact with Caracol through the Icon, positioned to the right of the Omnibar.

On the first run, the extension will prompt a user to decide which bookmarks to upload to Caracol for archive. After they submit their bookmarks, they will be provided an easy interface to their Caracol Clippings as well as their Caracol Recommendations.

##Installing

Make sure to log-in in to your Caracol account. Then use git to clone the repo:

git clone https://github.com/MrSpothawk/caracol-4-chrome.git

Open your Chrome browser. Head to the settings page for extensions.

Make sure you've checked "Developer Mode" on the upper right corner. Then "Load unpacked extension..." and open the app directory in your newly cloned repo.

When you see the handome orange snail, you'll know you've successfully installed the extension.

##The Code

Chrome will load the contents of the app directory according to the instructions provided in manifest.json. If you're unfamiliar with Chrome Extensions, you can find a good primer on the manifest at their developer page.

When the Icon Button is pressed Chrome will loadpopup.html. That page points to scripts/main-popup.js, which contains all the information about ui-routing and to the various .state configs and controllers necessary to provide the Popup view.

Likewise, when a new tab is opened tab.html & scripts/main-tab.js are to blame for the html of the resulting new tab.

The various templates supporting the Views can be found in the views/* directory. And you'll find scripts/controllers.js & scripts/services.js contain the DRY code.

This extension is built with AngularJS. I also mixed in Angular-UI & Angular-Bootstrap.

##Challenges

• Since this is a browser extension, there are no files served to the user. So, I used angular-ui to enable $stateProvider based UI routing & nested views without $route.
• Using Multiple Named Views enabled a lot of flexibility in the way the page was loaded, but I think there's a long way to go in terms of minimizing the code. It may be the case that there's a dynamic way to initialize state in the popup & newtab views, but I haven't found a better solution yet.
• Chrome provides access to the browser method chrome.bookmarks asynchronously. This made handling the views a little bit harder until I found used a clever trick to pass $state and $scope around the code much more easily.
• I used the ui-sref directive to enable the user to choose their .state in the header of the popup. Here's some info about state links.
• Mixing Angular, Angular-UI-Router, and Bootstrap for Angular turned out to complicate things a lot. In the end, it certainly turned out to be a worthwhile exercise for the flexibility it provided.

##License

The MIT License (MIT)

Copyright © 2014 Jesse F. LaRue

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.