README
Ember OSF
master Build Status: 
develop Build Status: 
This repo contains code for interacting with the OSF APIv2 inside of an Ember app. See addon API Docs for a list of what this addon provides.
Contributing
Please read the CONTRIBUTING.md
Installing tools to develop and modify this addon
See the yarn docs for installing and using yarn. These instructions will prepare your environment if you plan to modify and test this addon in isolation.
git clonethis repositoryyarn install --frozen-lockfilebower install
Using this addon in another Ember app
For production use
Other applications that wish to consume this addon should add the following line manually to the consuming Ember app's
package.json file, then run yarn install and bower install inside that app.
"ember-osf": "git+https://github.com/CenterForOpenScience/ember-osf.git#NewestCommitHashGoesHere",
In the future, we will provide an installable npm package to simplify this process.
For local development
- Clone the repository:
git clone https://github.com/CenterForOpenScience/ember-osf.git - From the consuming Ember app:
- install the addon and it's dependencies:
ember install ../ember-osf- this generates a config/local.yml file (see 'Configuration' below)
- link the app for local development:
npm link ../ember-osf - Import code from ember-osf like:
import Ember from 'ember';
import OsfTokenLoginRouteMixin from 'ember-osf/mixins/osf-token-login-route';
export default Ember.Route.extend(OsfLoginRouteMixin);
Note: Running ember install will automatically install many bower and npm dependencies for ember-osf.
Configuration
Specifying configuration information
local.yml settings
If for some reason you don't have a config/local.yml you can generate one. To do this:
ember generate ember-osf
Ember-osf needs certain configuration variables to run. This is usually done via a config file structured as follows:
OAUTH_SCOPES: osf.full_write
REDIRECT_URI: http://localhost:4200/login
CLIENT_ID: null
PERSONAL_ACCESS_TOKEN: null
You will need to fill out options for each backend you want to use (see 'Running' below). We recommend using the 'test' backend for development and testing as it is the most stable of our environments. When configuring your application, make sure that your login redirect uri is correct. If it needs a trailing slash, be sure to include a trailing slash!
Edit the new file (installed in the config directory) and set:
CLIENT_IDto the client id of your developer applicationPERSONAL_ACCESS_TOKENto the newly generated token (Only required or recognized for the LOCAL backend; do not set this value for staging, production, or test backends)REDIRECT_URI: Must exactly match the redirect URI used to register the OAuth developer application. Default value is appropriate for local development usingember server, with a login page at/login
Because of the potential for this file to include sensitive information, we strongly recommend adding this file to
.gitignore for your project.
Alternate option: Environment variables
If you do not wish to use file-based configuration, any of the settings above can be overridden individually as environment variables with the same name as appears in the config file. Eg
BACKEND=test CLIENT_ID=gibberish ember server
If you provide a setting in both the config file and an environment variable, the environment variables take precedence.
You can always override auth-related settings, but attempts to override server URLs will be ignored unless you
explicitly specify BACKEND=env (see "Running" for example).
Using the API
Most apps that use this addon will authorize requests via OAuth2. As may be apparent from the CLIENT_ID and
REDIRECT_URI settings above, you will need to create a developer application
on the relevant version of the OSF, and provide the appropriate settings for your app.
Advanced usage: Selecting an authorization type
We expect that most projects based on ember-osf will authenticate via OAuth 2.0 ("Token Login"); the addon is
configured to use this out of the box, so long as you provide your own login page based on the appropriate mixins.
This is the most effective way for third-party applications to work with our services.
If you are developing an application that will be hosted under the osf.io domain, you may wish to use cookie-based
authentication instead. In that rare case, add the following lines to your config/environment.js file:
var authorizationType = 'cookie';
ENV.authorizationType = authorizationType;
ENV['ember-simple-auth'] = {
authorizer: `authorizer:osf-${authorizationType}`,
authenticator: `authenticator:osf-${authorizationType}`
};
Running the OSF Locally (optional)
For local development, you will need to be running the OSF APIv2.
To connect to the APIv2 while using fakecas, you
will need to generate a personal access token on your local OSF instance here-
go ahead and grant full privilege access to all scopes (the osf.full_write option).
Using this addon
Ember Data: Using the OSF models
The models, serializers, adapters bundled in this addon with be available to you automatically. For example, simply do:
this.store.findAll('node')
to fetch all nodes (or at least the first page of results). If you need to fetch many results, see the API docs for information about how to handle pagination. Ember-osf also provides support for paginated relationship requests via a third-party addon.
MathJax
We use MathJax to make math look pretty in all browsers. If you want this in your application, copy this section into the <head> element of your index.html file:
<script type="text/javascript"
src="//cdnjs.cloudflare.com/ajax/libs/mathjax/2.6.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {inlineMath: [['