Andreas/tracks
1
0
Fork 0
mirror of https://github.com/TracksApp/tracks.git synced 2026-02-10 17:34:22 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated to svn tags/tracks-1.6

Browse source
This commit is contained in:
bsag 2008-06-03 19:40:22 +01:00
parent 103fcb8049
commit 02496f2d44
2274 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

20
app/views/integrations/_applescript1.rhtml Normal file
View file

@ -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"

79
app/views/integrations/_applescript2.rhtml Normal file
View file

@ -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

15
app/views/integrations/_quicksilver_applescript.rhtml Normal file
View file

@ -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

105
app/views/integrations/index.html.erb Normal file
View file

@ -0,0 +1,105 @@
<% has_contexts = !current_user.contexts.empty? -%>
<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. See also <%= link_to "developer documentation for Tracks' REST API", url_for(:action => 'rest_api') %>.</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>
<% if has_contexts -%>
<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>
<% else %>
<br/><p id="no_context_msg"><i>You do not have any context yet. The script will be available after you add your first context</i></p>
<% end %>
<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>
<% if has_contexts -%>
<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>
<% else %>
<br/><p><i>You do not have any context yet. The script will be available after you add your first context</i></p>
<% end %>
<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>
<% if has_contexts -%>
<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>
<% else %>
<br/><p><i>You do not have any context yet. The script will be available after you add your first context</i></p>
<% end %>
<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 %>todos.txt?due=6&token=<%= current_user.token %>" | /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>

218
app/views/integrations/rest_api.html.erb Normal file
View file

@ -0,0 +1,218 @@
<h1>REST API Documentation for Developers</h1>
<h2>Introduction</h2>
<p>Tracks is designed to be integrated with scripts, web services, and third-party applications. This page serves as the documentation of our REST API.</p>
<h2>Tracks REST API</h2>
<p>The Tracks REST API allows developers to integrate Tracks into their applications. It allows applications to access and modify Tracks data, and is implemented as Vanilla XML over HTTP.</p>
<p>The API is a <a href="http://en.wikipedia.org/wiki/REST">RESTful</a> service. All data is available through the API as a resource to which can be referred using a unique identifier. It responds to a number of the HTTP methods, specifically GET, PUT, POST and UPDATE, and all responses from the API are in a simple XML format encoded as UTF-8.</p>
<h2>Authentication</h2>
<p>Authentication is handled using <a href="http://en.wikipedia.org/wiki/Basic_authentication">Basic HTTP authentication</a>. Your Tracks username and password is used as the authentication credentials for the API. Note that in Basic HTTP authentication, your password is sent in clear text. If you need a more secure authentication solution, you should configure your web server to run Tracks under HTTPS.</p>
<h2>Retrieving data from the API</h2>
<p>To retrieve data you only need to do an HTTP GET on a resource identifier. For example, if you want to get all the contexts with <a href="http://en.wikipedia.org/wiki/CURL">cURL</a>:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
<%= home_url %>contexts.xml
&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;contexts&gt;...&lt;/contexts&gt;
</code>
</pre>
<p>Getting a single context:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
<%= home_url %>contexts/51.xml
&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;context&gt;...&lt;/context&gt;
</code>
</pre>
<p>Getting the todos within a context:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
<%= home_url %>contexts/51/todos.xml
&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;todos type="array"&gt;...&lt;/todos&gt;
</code>
</pre>
<p>You also can apply the pattern shown above with projects instead of contexts.</p>
<p>All data is available according to the following resource paths:</p>
<ul>
<li>/todos.xml</li>
<li>/todos/<code>ID</code>.xml</li>
<li>/contexts.xml</li>
<li>/contexts/<code>ID</code>.xml</li>
<li>/contexts/<code>ID</code>/todos.xml</li>
<li>/projects.xml</li>
<li>/projects/<code>ID</code>.xml</li>
<li>/projects/<code>ID</code>/todos.xml</li>
</ul>
<h2>Writing to the API</h2>
<p>The API provides mechanisms for adding, updating and deleting resources using the HTTP methods <code>PUT</code>, <code>POST</code> and <code>DELETE</code> in combination with the content.</p>
<p>Creating a new project, using curl:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
-d "project[name]=Build a treehouse for the kids" \
<%= home_url %>projects.xml -i
&gt;&gt; HTTP/1.1 201 Created
Location: <%= home_url %>projects/65.xml
...
</code>
</pre>
<p>The response is an <code>HTTP/1.1 201 Created</code> with <code>Location</code> header indicating where the new project resource can be found. Now we can add a todo to this project, using curl:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
-d "todo[description]=Model treehouse in SketchUp&#38;todo[context_id]=2&#38;todo[project_id]=65" \
<%= home_url %>todos.xml -i
&gt;&gt; HTTP/1.1 201 Created
Location: <%= home_url %>todos/452.xml
...
</code>
</pre>
<p>The response is a again an <code>HTTP/1.1 201 Created</code> with <code>Location</code> header indicating where the new todo resource can be found. Changing the todo notes, again using curl:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd -X PUT \
-d "todo[notes]=use maple texture" \
<%= home_url %>todos/452.xml -i
&gt;&gt; HTTP/1.1 200 OK
...
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;todo&gt;
...
&lt;description&gt;Model treehouse in SketchUp&lt;/description&gt;
&lt;notes&gt;use maple texture&lt;/notes&gt;
...
&lt;/todo&gt;
</code>
</pre>
<p>The response is an <code>HTTP/1.1 200 OK</code> with in the body the XML representation of the updated todo. We provide a shorcut method to toggle a todo done or undone without having to perform the update with the right field values:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd -X PUT \
<%= home_url %>todos/452/toggle_check.xml -i
&gt;&gt; HTTP/1.1 200 OK
...
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;todo&gt;
...
&lt;completed-at type=\"datetime\"&gt;2007-12-05T06:43:25Z&lt;/completed-at&gt;
&lt;state&gt;completed&lt;/state&gt;
...
&lt;/todo&gt;
</code>
</pre>
<p>If we want to delete that todo we can call its unique resource identifier (the URL) with the HTTP method <code>DELETE</code>, again with curl:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd -X DELETE \
<%= home_url %>todos/452.xml -i
&gt;&gt; HTTP/1.1 200 OK
...
</code>
</pre>
<p>The API returns an <code>HTTP/1.1 200 OK</code> and the todo is now deleted.</p>
<h2>Dealing with the response and response status</h2>
<p>All successful operations respond with a status code of <code>200 OK</code> or <code>201 Created</code> depending on the operation. Sometimes a list, say <code>GET /contexts/2/todos.xml</code> will not have any items, it will return an empty list.</p>
<p>The XML for empty list responses look like this, again with curl:</p>
<pre>
<code>
$ curl -u username:p4ssw0rd \
<%= home_url %>contexts/2/todos.xml
&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;nil-classes type="array"/&gt;
</code>
</pre>
<h2>Consuming the API with ActiveResource</h2>
<p><a href="http://weblog.rubyonrails.org/2007/9/30/rails-2-0-0-preview-release">ActiveResource</a> is a thin but powerful wrapper around RESTful services exposed by <a href="http://www.rubyonrails.org">Ruby on Rails</a>. It will be part of Rails 2.0 but until then you can get it with <code>gem install activeresource --source http://gems.rubyonrails.org --include-dependencies</code>.</p>
<pre>
<code>
$ script/console
Loading development environment (Rails 1.2.4)
&gt;&gt; class Context &lt; ActiveResource::Base; end
=&gt; nil
&gt;&gt; Context.site = "<%= home_url %>"
=&gt; "<%= home_url %>"
&gt;&gt; Context.site.user = "username"
=&gt; "username"
&gt;&gt; Context.site.password = CGI.escape "p4ssw0rd"
=&gt; "p4ssw0rd"
&gt;&gt; Context.find :first
=&gt; #&lt;Context:0x262396c @prefix_options={}, @attributes={...}&gt;
&gt;&gt; &gt;&gt; Context.find :all
=&gt; [#&lt;Context:0x274cfc8 @prefix_options={}, @attributes={...}, ...]
</code>
</pre>
<p>Inspired by <a href="http://www.37signals.com">37 Signals</a> &#8217;s Highrise wrapper, we&#8217;ve put together a small ruby wrapper (find it in the doc/ directory) for the API which sets up the ActiveResource models for you to play with in an IRB session:</p>
<pre>
<code>
$ SITE="http://username:p4ssw0rd@<%= request.host_with_port %>" irb \
-r tracks_api_wrapper.rb
irb(main):001:0&gt; inbox = Tracks::Context.find :first
irb(main):002:0&gt; inbox.name
=&gt; "@inbox"
irb(main):003:0&gt;
</code>
</pre>
<h3>Notes about the documentation</h3>
<p>A few conventions have been applied in the documentation, these are:</p>
<ul>
<li><code>ID</code>&#8217;s in a resource <span class="caps">URL</span> indicate that the resource&#8217;s unique ID needs to be inserted there</li>
<li><code>...</code> indicates that unimportant bits of response data have been removed to eliminate noise from the documentation</li>
</ul>
<p>All examples make use of <a href="http://en.wikipedia.org/wiki/CURL">cURL</a> .</p></div>