Skip to content

Commit

Permalink
Merge pull request #36 from keen/release-1.0.0
Browse files Browse the repository at this point in the history 
Release 1.0.0
  • Loading branch information
@aroc
aroc committed Nov 3, 2015
2 parents b2543a8 + aa77991 commit 888653f
Show file tree
Hide file tree
Showing 17 changed files with 97 additions and 761 deletions.
209 changes: 73 additions & 136 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,177 +1,112 @@
# Keen IO Explorer

The Keen Explorer is an open source point-and-click interface for querying and visualizing your event data.

![](https://s3.amazonaws.com/keen-event-images/Screen+Shot+2015-07-22+at+3.25.48+PM.png)

## Quick Setup

### TL;DR

1. `cp demo/example_index.html demo/index.html`
2. Add your Keen IO keys to demo/index.html
3. `npm install`
4. `npm -g install gulp` (if needed)
5. `gulp` or `export PORT=8082; gulp`
6. You can now view the demo locally at `http://localhost:8081/explorer` or your specified port.

### 1. Get your project ID & API keys
If you haven’t done so already, [login to Keen IO to create a project](https://keen.io/add-project) for your app. You'll need a [Keen IO account](https://keen.io/signup?s=explorer) to create a project. The Project ID and API Keys are available on the Project Overview page. You will need these for the next steps.

### 2. Drop in the JavaScript, CSS and images

You can see a complete code example of all these resources being included [in our demo page here.](/demo/example_index.html)

#### CSS

Include a copy of Bootstrap 3, which you can do from the CDN:
The Keen IO Explorer is an open source point-and-click interface for querying and visualizing your event data. It's maintained by the team at [Keen IO](https://keen.io/).

```html
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
```

Include a copy of the Keen.Explorer styling from this project, found under: `dist/keen-explorer.css`.
[Check out the demo here.](http://keen.github.io/explorer/). Read on for instructions on how to use the Explorer on your website or in your web app and how to get set up to develop with the Explorer.

#### HTML
## Table of Contents
1. [How to use Explorer on your site or in your app](#How-to-use-Explorer-on-your-site-or-in-your-app)
2. [How to develop with the Explorer](#How-to-develop-with-the-Explorer)
3. [FAQ](#faq)
4. [Contributing](#contributing)
5. [Tech used in this project](#tech-used-in-this-project)

Have a div with an id that you'll use as the target to render out the app. A simple:
### How to use Explorer on your site or in your app

```html
<div id="content"></div>
```
#### Include the necessary files

will work just fine. All of the interface components will live under this div.
You have three options for including the necessary Explorer files:

#### JavaScript

Include a copy of jQuery, which you can do from the Google CDN:
##### Option 1: Use the hosted assets from our CDN
```html
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<!-- Include Bootstrap from CDN. We use bootstrap as our CSS framework for Explorer -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<!-- Include Explorer CSS from CDN -->
<link rel="stylesheet" href="https://d26b395fwzu5fz.cloudfront.net/apps/keen-explorer-1.0.0.min.css">
<!-- Include jQuery from Google. We use jQuery for a few of our UI components, like calendar pickers. -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<!-- Include keen.js from CDN. This is our Javascript SDK that powers querying and visualizations in Explorer. -->
<script src="https://d26b395fwzu5fz.cloudfront.net/3.2.7/keen.min.js" type="text/javascript"></script>
<!-- Include keen-explorer.js from CDN. -->
<script src="https://d26b395fwzu5fz.cloudfront.net/apps/keen-explorer-1.0.0.min.js"></script>
```

Include a copy of Keen.js, the easiest way is to use our CDN version:
```html
<script src="https://d26b395fwzu5fz.cloudfront.net/3.1.0-beta/keen.min.js" type="text/javascript"></script>
```
##### Option 2: Include the files yourself
You'd need to include all of the same assets as those listed in the CDN example above. You can [download the Explorer source code](https://github.com/keen/explorer/archive/master.zip) to get the `keen-explorer.js` and `keen-explorer.css` files (as well as the minified versions). And you can choose to include jQuery and Bootstrap however you wish, from CDNs or using downloaded copies.

Include a copy of Keen.Explorer from this project, found under: `dist/keen-explorer.js`.
##### Option 3: Install using NPM
This is as easy as `npm install keen-explorer`

### 3. Configure a Keen.js client and initialize the Keen.Explorer app

Initialize a new Keen.js client and then pass that into the initialization of a new Keen.Explorer.App.
#### Get your project ID & API keys
If you haven’t done so already, [login to Keen IO to create a project](https://keen.io/add-project) for your app. You'll need a [Keen IO account](https://keen.io/signup?s=explorer) to create a project. The Project ID and API Keys are available on the Project Overview page. You will need these for the next steps.

#### Configure the Keen.js client and initialize Explorer
Somewhere on the page that you want to show Explorer you'll need to configure a Keen.js client and pass that into the initialization of a new Explorer. Here's how you do it:
```html
<div id="explorer"></div>
<script type="text/javascript">
$(document).ready(function(){
client = new Keen({
projectId: "your_project_id",
readKey: "your_read_key",
masterKey: "your_master_key",
protocol: "https",
host: "api.keen.io/3.0",
requestType: "jsonp"
});
var app = new Keen.Explorer.App({
client: client,
targetId: 'content'
});
app.render(); // Render the app's UI into the targetId provided in the config.
});
</script>
```

If you want the Explorer app to run on a path other than the root, you can pass in the `root` configuration option, eg: `root: '/your/custom/root/path'`.

You can read more about Keen.js here: [The Keen.js client library](https://github.com/keenlabs/keen-js/).

### 3. Optionally include Saved Queries support

Saved query support is optional. If you include it, you can persist the state of the query you're working with to be looked up at a later time. If you do not want to use saved queries, just do not include it in the Keen.Explorer.App initialization, like above.

To include saved queries, just set the `savedQueries` config variable to `true`. You *must* include a master key if you want saved queries support.
// Configure a new Keen.js client with your project ID, read key and master key.
var client = new Keen({
projectId: "YOUR_PROJECT_ID",
readKey: "YOUR_PROJECT_READ_KEY",
masterKey: "YOUR_PROJECT_MASTER_KEY"
});
```html
<script type="text/javascript">
$(document).ready(function(){
client = new Keen({
projectId: "your_project_id",
readKey: "your_read_key",
protocol: "https",
host: "api.keen.io/3.0",
requestType: "xhr"
});
var app = new Keen.Explorer.App({
client: client,
savedQueries: true, // saved queries are supported
targetId: 'content'
});
app.render();
var app = new Keen.Explorer.App({
// Pass that client into a new Explorer
client: client,
// Optionally add in saved queries support:
// Saved queries is entirely optional. If you set it to true, a "saved queries" feature
// will be available and you can save the state of the query you're working
// on so that they can be looked up at a later time.
savedQueries: true,
// The targetId is the id of the DOM Node you want to display Explorer inside.
targetId: 'explorer'
});
app.render();
</script>
```

## Forking the Project to Customizing and Contribute

If you want to customize this project or contribute, here is how to get started:
And that's it. You're done!

* clone the repo
* run `npm install` to install project dependencies
* update the `index.html` with your Project ID and API Keys
### How to develop with the Explorer

```html
<script type="text/javascript">
$(document).ready(function(){
client = new Keen({
projectId: "your_project_id",
readKey: "your_read_key",
masterKey: "your_master_key",
protocol: "https",
host: "api.keen.io/3.0",
requestType: "jsonp"
});
var app = new Keen.Explorer.App({
client: client,
targetId: 'content'
});
app.render();
});
</script>
```
1. `git clone` this repository or [Download the source code](https://github.com/keen/explorer/archive/master.zip)
1. Navigate to the project directory and make a copy of or rename the demo file:
`cp demo/example_index.html demo/index.html` or `mv demo/example_index.html demo/index.html`
2. Configure the Keen.js client in the demo file at demo/index.html with your project ID and Keen IO API keys.
3. Install the dependencies with `npm install`.
4. Run the development script with `npm run dev` or `export PORT=8082; npm run dev`.
5. You can now view the demo locally at `http://localhost:8081/explorer` or your specified port.

### Building the project:
#### Building the project:

The project is built with `Gulp.js`.
The project is built with [Gulp.js](https://github.com/gulpjs/gulp).

* Run `gulp` from the root directory of the project
* The demo app will be running on `http://localhost:8081/explorer`.

### Testing
#### Testing

##### Run Unit Tests
**Run Unit Tests**
* Run `gulp test:unit` to run the unit tests.

##### Run Functional Tests
* Run `gulp test:functional` to run the functional tests.

##### Run In Browser Mocha Unit Tests

**Run In Browser Mocha Unit Tests**
This isn't normally requried, but if you need to, you can run the tests in the browser.

* Run `gulp`
* Run a server on another port, we use [http-server](https://www.npmjs.org/package/http-server) on port `8082`
* See the mocha unit test suite run on `http://localhost:8082/test/unit/`

### Is this open source Keen Explorer different than the one on keen.io?
### FAQ

**Is this open source Keen Explorer different than the one on keen.io?**
Nope! We have recently moved all our development on the Keen Explorer to this open source version.

If you have any questions about using the open source Data Explorer feel free to contact us anytime at [team@keen.io](mailto:team@keen.io).
**I have questions about using the project! Where/who do I ask?**
If you have any questions about using this project, Explorer feel free to contact us anytime at [team@keen.io](mailto:team@keen.io).

### Contributing:
To contribute to this project:
Expand All @@ -180,7 +115,7 @@ To contribute to this project:
* Submit a Pull Request **with** test coverage.
* Follow our PR template, which includes the following sections:

``` markdown
```markdown
# What's this PR do?

# Where should the reviewer start?
Expand All @@ -192,11 +127,13 @@ To contribute to this project:

Would an animated GIF be more informative than a screenshot? Then we recommend [Recordit](http://recordit.co/).

## Tech
### Tech used in this project

These are the major technologies used in the project.

* [ReactJS](http://facebook.github.io/react/) for UI Components & input handling
* [ReactJS](http://facebook.github.io/react/) for UI Components & input handling.
* [Flux](http://facebook.github.io/flux/) for help managing the data model layer.
* [Bootstrap](http://getbootstrap.com/) for our CSS framework.
* [NPM](https://www.npmjs.org/) for dependency management.
* [Browserify](http://browserify.org/) to compile modules for use in the browser
* [GulpJS](http://gulpjs.com/) for a task/build runner
* [Browserify](http://browserify.org/) to compile modules for use in the browser.
* [GulpJS](http://gulpjs.com/) for a task/build runner.
Binary file removed client/fonts/glyphicons-halflings-regular.eot
View file
Binary file not shown.
Loading

0 comments on commit 888653f

Please sign in to comment.