Skip to content

Commit

Permalink
Revised the platform README
Browse files Browse the repository at this point in the history
  • Loading branch information
Ryan Bright committed Oct 26, 2012
1 parent 8171b04 commit 3e655d4
Showing 1 changed file with 87 additions and 114 deletions.
201 changes: 87 additions & 114 deletions README.md
View file
@@ -1,23 +1,29 @@
# Platform Documentation
# Harvest Platform Documentation

If you haven't already, you should [watch the video first](http://www.youtube.com/watch?v=5_fVPnH7VBU),
which walks you through the implementation process.
For a brief overview of the Harvest Platform and how it can be implemented,
[watch the video introduction](http://www.youtube.com/watch?v=5_fVPnH7VBU).

## JavaScript include tag
## FAQ

The first step to integrating Harvest time tracking into your app involves
placing our JavaScript include tag into your HTML. The best placement for this
is right at the bottom of your document, just before the closing `</body>` tag.
1. [How can I add the Harvest Platform to my application?](#include)
2. [What configuration options do I need to specify?](#config)
3. [How can I add timers to my items?](#timers)
4. [How can I add timers to new items?](#events)
5. [How can I add custom styles to timers in my application?](#styling)

Here's what the include tag should look like. The
[configuration](#configuration) will need to be altered for your app.
<a id="include"></a>
## How can I add the Harvest Platform to my application?

To add the Harvest Platform to your application, include the following
JavaScript block in your HTML. Be sure to check out the full list of
[configuration options](#config).

```html
<script>
(function() {
window._harvestPlatformConfig = {
"applicationName": "Example App",
"permalink": "http://example.com/projects/%PROJECT_ID%/items/%ITEM_ID%"
"permalink": "http://example.com/%ACCOUNT_ID%/projects/%PROJECT_ID%/items/%ITEM_ID%"
};
var s = document.createElement('script');
s.src = '//platform.harvestapp.com/assets/platform.js';
Expand All @@ -28,50 +34,54 @@ Here's what the include tag should look like. The
</script>
```

**Note:** If you'd like to review the non-minified JavaScript used for the
Harvest Platform before including it on your page, you can reference the
original file [here](https://platform.harvestapp.com/javascripts/generated/platform.js).
**Note:** If you'd like to review the uncompressed JavaScript used for the
Harvest Platform before including it on your page, check out the [original
file](https://platform.harvestapp.com/javascripts/generated/platform.js).

### Configuration
<a id="config"></a>
## What configuration options do I need to specify?

Options:
The following options can be specified when [including the Harvest
Platform](#include) in your application.

- **applicationName** _(string, required)_: The name of your app. This will be
displayed in Harvest to identify the link between Harvest project and your app.

_Example_: "MyTodoApp"
- **applicationName** - name of your application. This is used to identify
associations between your application and projects within Harvest.

- **permalink** _(string, required)_: The permalink structure used for your
app's items when they are displayed in Harvest. We will replace certain variables
(`%ACCOUNT_ID%`, `%PROJECT_ID%`, and `%ITEM_ID%`) from the [data attributes](#data-attributes)
from each item to generate a unique permalink.
- **permalink** _(optional)_ - template used for items in your application. This
is processed along with the [data attributes](#attributes) you provide to
build a unique permalink for each item.

_Example_: `http://exampleapp.com/%ACCOUNT_ID%/projects/%PROJECT_ID%/items/%ITEM_ID%`
- **skipStyling** _(optional)_ - whether or not the use the default
timer styles provided by Harvest. If you wish to [provide your own
styles](#styling), just set this to `true`.

- **skipStyling** _(boolean, optional)_: Whether to use the default Harvest-provided
CSS for the timer elements. Set this to `true` to tell the Harvest Platform that
styling should be skipped. The default value is `false`. Check out [Styling](#styling)
below for help with custom CSS styling.
<a id="timers"></a>
## How can I add timers to my items?

When the Harvest Platform is initialized, it searches for all elements with
class `harvest-timer` and links each to an entry in Harvest.

## HTML
To add timers to your items, insert an HTML element with class
`harvest-timer` wherever you wish you display timers in your application. To
associate the timer with an item, you'll need to specify a few
[attributes](#attributes).

The only HTML element you'll need to insert into your page is a div with the
class of `harvest-timer`. You'll need to insert one wherever you want a timer.
For example, in a todo app, you'd need a `harvest-timer` div for each todo in a
list.
**Note:** Only elements that exist in the DOM when the Harvest Platform is
loaded will be associated. To associate new items, you can [fire a JavaScript
event](#events) containing information about the new element.

<div class="harvest-timer"></div>

You need to add some [data attributes](#data-attributes) to get things fully
working, though.
```html
<div class="harvest-timer"></div>
```

### Data attributes
<a id="attributes"></a>
### Attributes

The timer element requires that both `data-project` and `data-item` attributes
be added in order to properly identify the item associated with the timer. For
services like Basecamp, a `data-account` attribute is also required. All
attributes are represented by a JSON string.
Each timer element contains attributes that allow Harvest to link back to items
in your application using permalinks. For Harvest to properly track time to an
item, both `data-project` and `data-item` attributes are required. For products
in which projects and items exist within the context of an account (e.g.
Basecamp), a `data-account` attribute should also be specified.

```html
<div class="harvest-timer"
Expand All @@ -81,85 +91,48 @@ attributes are represented by a JSON string.
</div>
```

#### data-account

`data-account` is a JSON object with data about the account associated with a
particular timer. This is necessary for products like Basecamp, where all
projects exist within the context of an account.

Attributes:

- **id (string)**: the unique ID associated with a specific user. Used for URL
subsitution.

#### data-project

`data-project` is a JSON object with data about the project associated with a
particular timer.

Attributes:

- **id (string)**: the unique ID of the project. Can be any string (with a
maxlength of 255)
- **name (string)**: the name of the project. Can be any string (with a
maxlength of 255)
<a id="events"></a>
## How can I add timers to new items?

#### data-item
When you add a new item in your application, you'll need to fire a JavaScript
event to let the Harvest Platform know that a new element needs association.
Currently, the platform supports events of type `CustomEvent` and
`jQuery.Event`.

`data-item` is a JSON object with data about the todo item associated with a
particular timer.
```javascript
var harvestEvent = {
type: "harvest-event:timers:add",
element: $(".harvest-timer").last()
}

Attributes:

- **id (string)**: the unique ID of the item. Can be any string (with a
maxlength of 255)
- **name (string)**: the name of the item. Can be any string (with a maxlength
of 255)


### Styling

By default, the platform will automatically style the `.harvest-timer` div, but
if configured to skip that step, you can supply your own CSS.

Applying any CSS styling directly to the `.harvest-timer` elements works. That
will style the timer in its default, non-running state. For the case of a custom
icon, using a CSS-provided `background-image` is the quickest way.

The `.harvest-timer` div will have an additional class of `.running` if a running
timer is found that matches that specific timer.

_Note: if the platform isn't configured to skip styling, all `.harvest-timer`
elements will have the additional class `.styled`._


## Events
$("#harvest-messaging").trigger(harvestEvent);
```

Once the Harvest Platform has been initialized, it becomes reliant on events
from the client in order to render timers to the DOM. All of these events
should be fired through the `#harvest-messaging` element. Currently, the
platform supports events of type `CustomEvent` and `jQuery.Event`.
### Event Types

- **harvest-event:ready** - The `ready` event is fired by the platform itself
and indicates that everything has been initialized. _Note: This event is
fired on the `body` element, since the listening client cannot listen to the
`#harvest-messaging` element until it exists._
- **harvest-event:ready** - fired by the platform itself to acknowledge that
everything has been loaded.

**Note:** This is fired on the `body` element,
since `#harvest-messaging` won't exist until the platform has been
initialized.

- **harvest-event:timers:add** - The `timers:add` event can be used when one or
more `harvest-timer` elements exist in the DOM and require an iframe
listener.
- **harvest-event:timers:add** - used whene one or more `harvest-timer` element
exists in the DOM and requires association. This includes an `element`
attribute to represent the `harvest-timer` object.

Attributes:

- **element**: The HTMLElement that should be treated as a Harvest timer
<a id="styling"></a>
## How can I add custom styles to timers in my application?

Example usage:
The Harvest Platform will provide a default style for `harvest-timer` elements
and the `harvest-timer-icon` embedded within each. This will append a `styled`
class to all timer elements and their children. By specifying the `skipStyling`
attribute in your [configuration](#config), you can use your own styles.

```javascript
var harvestEvent = {
type: "harvest-event:timers:add",
element: $(".harvest-timer").last()
}
Adding a style to the `harvest-timer` class will apply to the timer when it is
not running in Harvest. When the timer is running, the `running` class will be
added to the element representing the running timer and all of its child
elements.

$("#harvest-messaging").trigger(harvestEvent);
```
To provide a custom style for the timer icon, just add a style for the
`harvest-timer-icon` class.

0 comments on commit 3e655d4

Please sign in to comment.