Add an Integrations page, with assistance for implementing AppleScripts and cron jobs that integrate with Tracks.

git-svn-id: http://www.rousette.org.uk/svn/tracks-repos/trunk@619 a4c988fc-2ded-0310-b66e-134b36920a42

tracks/app/controllers/integrations_controller.rb

@@ -0,0 +1,21 @@
+class IntegrationsController < ApplicationController
+
+  def index
+    @page_title = 'TRACKS::Integrations'
+  end
+  
+  def get_quicksilver_applescript
+    context = current_user.contexts.find params[:context_id]
+    render :partial => 'quicksilver_applescript', :locals => { :context => context }
+  end
+
+  def get_applescript1
+    context = current_user.contexts.find params[:context_id]
+    render :partial => 'applescript1', :locals => { :context => context }
+  end
+
+  def get_applescript2
+    context = current_user.contexts.find params[:context_id]
+    render :partial => 'applescript2', :locals => { :context => context }
+  end
+end

tracks/app/helpers/integrations_helper.rb

@@ -0,0 +1,2 @@
+module IntegrationsHelper
+end

tracks/app/views/integrations/_applescript1.rhtml

@@ -0,0 +1,20 @@
+(* Pops up a dialog box in which you enter a description for a next action.
+   It then creates that next action in Tracks in the context specified below.
+ *)
+
+set myUsername to "<%= current_user.login %>"
+set myToken to "<%= current_user.token %>"
+set myContextID to <%= context.id %> (* <%= context.name %> *)
+
+-- Display dialog to enter your description 
+display dialog "Description of next action:" default answer ""
+set myDesc to text returned of the result
+
+-- Now send all that info to Tracks
+-- Edit the URL of your Tracks installation if necessary"
+tell application "<%= home_url %>backend/api"
+	set returnValue to call xmlrpc {method name:"NewTodo", parameters:{myUsername, myToken, myContextID, myDesc}}
+end tell
+
+-- Show the ID of the newly created next action
+display dialog "New next action with id " & returnValue & " created"

tracks/app/views/integrations/_applescript2.rhtml

@@ -0,0 +1,79 @@
+(* 
+Script to grab the sender and subject of the selected
+Mail message(s), and create new next action(s) with description
+"Email [sender] about [subject]"
+
+If you have Growl, it pops a notification up with the id of
+the newly created action. 
+*)
+
+(* Edit appropriately for your setup *)
+property myUsername to "<%= current_user.login %>"
+property myToken to "<%= current_user.token %>"
+property myContextID to <%= context.id %> (* <%= context.name %> *)
+
+-- this string is used when the message subject is empty
+property emptySubject : "No Subject Specified"
+
+-- Get the selected email in Mail
+tell application "Mail"
+	set theSelection to the selection
+	if the length of theSelection is less than 1 then
+		display dialog "One or more messages must be selected." buttons {"OK"} default button 1 with icon caution
+	else
+		repeat with theMessage in theSelection
+			my importMessage(theMessage)
+		end repeat
+	end if
+end tell
+
+on importMessage(theMessage)
+	
+	-- Get the info from the email message
+	tell application "Mail"
+		try
+			set theSender to the sender of theMessage
+			set theSubject to subject of theMessage
+			if theSubject is equal to "" then set theSubject to emptySubject
+			
+			-- Construct the description string from the email info
+			set myDesc to "Email " & theSender & " about " & theSubject
+			-- Trim the string to 100 characters otherwise it won't validate
+			if length of myDesc > 100 then
+				set myDesc to characters 1 thru 100 of myDesc
+			end if
+		end try
+	end tell
+	
+	-- Now send all that info to Tracks
+	-- Edit the URL of your Tracks installation if necessary"
+	tell application "<%= home_url %>backend/api"
+		set returnValue to call xmlrpc {method name:"NewTodo", parameters:{myUsername, myToken, myContextID, myDesc}}
+	end tell
+	
+	(* Growl support - comment out or delete this section if 
+	   you don't have Growl *)
+	tell application "GrowlHelperApp"
+		set the allNotificationsList to ¬
+			{"Tracks Notification"}
+		
+		-- Make a list of the notifications 
+		-- that will be enabled by default.      
+		-- Those not enabled by default can be enabled later 
+		-- in the 'Applications' tab of the growl prefpane.
+		set the enabledNotificationsList to ¬
+			{"Tracks Notification"}
+		
+		-- Register our script with growl.
+		-- You can optionally (as here) set a default icon 
+		-- for this script's notifications.
+		register as application ¬
+			"Tracks Applescript" all notifications allNotificationsList ¬
+			default notifications enabledNotificationsList ¬
+			icon of application "Script Editor"
+		set growlDescription to "Action with ID " & returnValue & " was created."
+		notify with name "Tracks Notification" title "New action sent to Tracks" description growlDescription application name "Tracks Applescript" icon of application "Script Editor.app"
+	end tell
+	(* End of Growl section *)
+	
+end importMessage

tracks/app/views/integrations/_quicksilver_applescript.rhtml

@@ -0,0 +1,15 @@
+using terms from application "Quicksilver"
+	on process text ThisClipping
+		
+		set myUsername to "<%= current_user.login %>"
+		set myToken to "<%= current_user.token %>"
+		set myContextID to <%= context.id %> (* <%= context.name %> *)
+		
+		tell application "<%= home_url %>backend/api"
+			set returnValue to call xmlrpc {method name:"NewTodo", parameters:{myUsername, myToken, myContextID, ThisClipping}}
+		end tell
+		tell application "Quicksilver"
+			show notification "Tracks: action added."
+		end tell
+	end process text
+end using terms from

tracks/app/views/integrations/index.rhtml

@@ -0,0 +1,92 @@
+<h1>Integrations</h1>
+<p>Tracks can be integrated with a number of other tools... whatever it takes to help you get things done! This page has information on setting up some of these. Not all of these are applicable to all platforms, and some require more technical knowledge than others.</p>
+<p>Contents:
+	<ol>
+	<li><a href="#applescript1-section">Add an Action with Applescript</a></li>
+	<li><a href="#applescript2-section">Add an Action with Applescript based on the currently selected Email in Mail.app</a></li>
+	<li><a href="#quicksilver-applescript-section">Add Actions with Quicksilver and Applescript</a></li>
+	<li><a href="#email-cron-section">Automatically Email Yourself Upcoming Actions</a></li>
+</ol><br />
+</p>
+<p>Do you have one of your own to add? <a href="http://www.rousette.org.uk/projects/forums/viewforum/10/" title="Tracks | Tips and Tricks">Tell us about it in our Tips and Tricks forum
+</a> and we may include it on this page in a future versions of Tracks.</p>
+
+<a name="applescript1-section"> </a>
+<h2>Add an Action with Applescript</h2>
+<p>This is a simple script that pops up a dialog box asking for a description, and then sends that to Tracks with a hard-coded context.</p>
+
+<ol>
+	<li>Choose the context you want to add actions to: <select name="applescript1-contexts" id="applescript1-contexts"><%= options_from_collection_for_select(current_user.contexts, "id", "name", current_user.contexts.first.id) %></select>
+		<%= observe_field "applescript1-contexts", :update => "applescript1",
+		:with => 'context_id',
+		:url => { :controller => "integrations", :action => "get_applescript1" },
+		:before => "$('applescript1').startWaiting()",
+	    :complete => "$('applescript1').stopWaiting()"
+	     %>
+	</li>
+	<li>Copy the Applescript below to the clipboard.<br />
+	
+	<textarea id="applescript1" name="applescript1" rows="15"><%= render :partial => 'applescript1', :locals => { :context => current_user.contexts.first } %></textarea>
+	</li>
+ 	<li>Open Script Editor and paste the script into a new document.</li>
+ 	<li>Compile and save the script. Run it as necessary.</li>
+</ol>
+
+<a name="applescript2-section"> </a>
+<h2>Add an Action with Applescript based on the currently selected Email in Mail.app</h2>
+<p>This script takes the sender and subject of the selected email(s) in Mail and creates a new action for each one, with the description, "Email [sender] about [subject]". The description gets truncated to 100 characters (the validation limit for the field) if it is longer than that. It also has Growl notifications if you have Growl installed.</p>
+
+<ol>
+	<li>Choose the context you want to add actions to: <select name="applescript2-contexts" id="applescript2-contexts"><%= options_from_collection_for_select(current_user.contexts, "id", "name", current_user.contexts.first.id) %></select>
+		<%= observe_field "applescript2-contexts", :update => "applescript2",
+		:with => 'context_id',
+		:url => { :controller => "integrations", :action => "get_applescript2" },
+		:before => "$('applescript2').startWaiting()",
+	    :complete => "$('applescript2').stopWaiting()"
+	     %>
+	</li>
+	<li>Copy the Applescript below to the clipboard.<br />
+	
+	<textarea id="applescript2" name="applescript2" rows="15"><%= render :partial => 'applescript2', :locals => { :context => current_user.contexts.first } %></textarea>
+	</li>
+ 	<li>Open Script Editor and paste the script into a new document.</li>
+ 	<li>Compile and save the script to the ~/Library/Scriipts/Mail Scripts directory.</li>
+	<li>For more information on using AppleScript with Mail.app, see <a href="http://www.apple.com/applescript/mail/" title="Scriptable Applications: Mail">this overview</a>.
+</ol>
+
+<a name="quicksilver-applescript-section"></a>
+<h2>Add Actions with Quicksilver and Applescript</h2>
+
+<p>This integration will allow you to add actions to Tracks via <a href="http://quicksilver.blacktree.com/">Quicksilver</a>.</p>
+
+<ol>
+	<li>Choose the context you want to add actions to: <select name="quicksilver-contexts" id="quicksilver-contexts"><%= options_from_collection_for_select(current_user.contexts, "id", "name", current_user.contexts.first.id) %></select>
+		<%= observe_field "quicksilver-contexts", :update => "quicksilver",
+		:with => 'context_id',
+		:url => { :controller => "integrations", :action => "get_quicksilver_applescript" },
+		:before => "$('quicksilver').startWaiting()",
+	    :complete => "$('quicksilver').stopWaiting()"
+	     %>
+</li>
+<li>Copy the Applescript below to the clipboard.<br />
+	
+<textarea id="quicksilver" name="quicksilver" rows="15"><%= render :partial => 'quicksilver_applescript', :locals => { :context => current_user.contexts.first } %></textarea>
+</li>
+	<li>Open Script Editor and paste the script into a new document.</li>
+ <li>Compile and save the script as "Add to Tracks.scpt" in ~/Library/Application Support/Quicksilver/Actions/ (you may need to create the Actions directory)</li>
+ <li>Restart Quicksilver</li>
+ <li>Activate Quicksilver (Ctrl+Space by default)</li>
+ <li>Press "." to put quicksilver into text mode</li>
+ <li>Type the description of the next action you want to add</li>
+ <li>Press tab to switch to the action pane.</li>
+ <li>By typing or scrolling, choose the "Add to Tracks" action.</li>
+</ol>
+
+<a name="email-cron-section"> </a>
+<h2>Automatically Email Yourself Upcoming Actions</h2>
+
+<p>If you enter the following entry to your crontab, you will receive email every day around 5 AM with a list of the upcoming actions which are due within the next 7 days.</p>
+
+<textarea id="cron" name="cron">0 5 * * * /usr/bin/curl -0 <%= home_url %>/feed/text/<%= current_user.login %>/<%= current_user.token %>?due=6 | /usr/bin/mail -E -s 'Tracks actions due in the next 7 days' youremail@yourdomain.com</textarea>
+
+<p>You can of course use other text <%= link_to 'feeds provided by Tracks', feeds_path %> -- why not email a list of next actions in a particular project to a group of colleagues who are working on the project?</p>

tracks/app/views/sidebar/sidebar.rhtml

@@ -25,5 +25,7 @@
 	           :locals => { :list_name => 'Hidden Contexts',
 	           				:contexts => @contexts.select{|c| c.hide? } } -%>
 	<% end -%>
+	
+	<div class="integrations-link"><%= link_to 'Integrate Tracks', integrations_path %></div>
 
 </div>

tracks/config/routes.rb

@@ -1,7 +1,6 @@
 ActionController::Routing::Routes.draw do |map|
   UJS::routes
   
-  # Login Routes
   map.with_options :controller => 'login' do |login|
     login.login 'login', :action => 'login'
     login.formatted_login 'login.:format', :action => 'login'
@@ -21,17 +20,14 @@ ActionController::Routing::Routes.draw do |map|
     users.signup 'signup', :action => "new"
   end
 
-  # Context Routes
   map.resources :contexts, :collection => {:order => :post} do |contexts|
     contexts.resources :todos, :name_prefix => "context_"
   end
 
-  # Projects Routes
   map.resources :projects, :collection => {:order => :post, :alphabetize => :post} do |projects|
     projects.resources :todos, :name_prefix => "project_"
   end
 
-    # ToDo Routes
   map.resources :todos,
                 :member => {:toggle_check => :put, :toggle_star => :put},
                 :collection => {:check_deferred => :post, :filter_to_context => :post, :filter_to_project => :post}
@@ -46,13 +42,11 @@ ActionController::Routing::Routes.draw do |map|
     todos.mobile_abbrev_new 'm/new', :action => "new", :format => 'm'
   end
   
-  # Notes Routes
   map.resources :notes
-
-  # Feed Routes
-  map.connect 'feeds', :controller => 'feedlist', :action => 'index'
+  map.feeds 'feeds', :controller => 'feedlist', :action => 'index'
   
   map.preferences 'preferences', :controller => 'preferences', :action => 'index'
+  map.integrations 'integrations', :controller => 'integrations', :action => 'index'
 
   # Install the default route as the lowest priority.
   map.connect ':controller/:action/:id'

tracks/public/stylesheets/standard.css

@@ -549,6 +549,11 @@ li {
 #sidebar li {
       padding: auto;
       }
+#sidebar .integrations-link {
+	margin-top:10px;
+	padding-top:10px;
+	font-size: 0.8em;
+}
 .sortable_row {
       background: #fff;
       _background: transparent;
@@ -1049,4 +1054,24 @@ button.positive, .widgets a.positive{
 	clear:both;
 	margin-top:15px;
 	margin-bottom:15px;
+}
+body.integrations h2 {
+	margin-top:40px;
+	padding-top:20px;
+	margin-bottom:10px;
+	border-top:1px solid #ccc;
+}
+body.integrations p, body.integrations li {
+	font-size:1.0em;
+}
+body.integrations li {
+	list-style-type: disc;
+	list-style-position: inside;
+	margin-left:30px;	
+}
+body.integrations textarea {
+	margin:10px;
+	padding:3px;
+	width:80%;
+	background-color:#ddd;
 }

tracks/test/functional/integrations_controller_test.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/../test_helper'
+require 'integrations_controller'
+
+# Re-raise errors caught by the controller.
+class IntegrationsController; def rescue_action(e) raise e end; end
+
+class IntegrationsControllerTest < Test::Unit::TestCase
+  def setup
+    @controller = IntegrationsController.new
+    @request    = ActionController::TestRequest.new
+    @response   = ActionController::TestResponse.new
+  end
+
+  # Replace this with your real tests.
+  def test_truth
+    assert true
+  end
+end