Ember Custom Actions is a package for defining custom API actions, dedicated for Ember 2.8 (and higher) applications.
Before you will start with documentation check our demo app: [Ember-Custom-Actions Website][43255946] [43255946]: https://exelord.github.io/ember-custom-actions/ "Website - Demo App"
ember install ember-custom-actions
To define custom action like: posts/1/publish
you can use
modelAction(path, options)
method with arguments:
path
- the url of the action (in our case it'spublish
)options
- optional parameter which will overwrite the configuration options
import Model from 'ember-data/model';
import { modelAction } from 'ember-custom-actions';
export default Model.extend({
publish: modelAction('publish', { pushToStore: false }),
});
let user = this.get('currentUser');
let postToPublish = this.get('store').findRecord('post', 1);
let payload = { publisher: user };
postToPublish.publish(payload, /*{ custom options }*/).then((status) => {
alert(`Post has been: ${status}`)
}).catch((error) => {
console.log('Here are you serialized model errors', error.serializedErrors);
});
To a define custom action like: posts/favorites
you can use
resourceAction(path, options)
method with arguments:
path
- the url of the action (in our case it'sfavorites
)options
- optional parameter which will overwrite the configuration options
import Model from 'ember-data/model';
import { resourceAction } from 'ember-custom-actions';
export default Model.extend({
favorites: resourceAction('favorites', { type: 'GET' }),
});
let user = this.get('currentUser');
let emptyPost = this.get('store').createRecord('post');
let payload = { user };
emptyPost.favorites(payload, /*{ custom options }*/).then((favoritesPosts) => {
console.log(favoritesPosts);
}).finally(()=>{
emptyPost.deleteRecord();
});
You can define your custom options in your config/environment.js
file
module.exports = function(environment) {
var ENV = {
'emberCustomActions': {
type: 'PUT',
ajaxOptions: {},
pushToStore: false,
normalizeOperation: '',
promiseType: null
},
};
return ENV;
}
Default type of the request (GET, PUT, POST, DELETE, etc..)
Base of the URL which is generated for the action. If not defined, urlType
is equal to the type
option
Your own ajax options (e.g. headers)
If you want to push the received data to the store, set this option to true
and change your application serializer:
- If you are using
JSONAPISerializer
:
// app/serializers/application.js
import { JSONAPISerializer } from 'ember-custom-actions';
export default JSONAPISerializer.extend();
- If you are using
RESTSerializer
:
// app/serializers/application.js
import { RESTSerializer } from 'ember-custom-actions';
export default RESTSerializer.extend();
You can define how your outgoing data should be serialized
Exemplary data:
{
firstParam: 'My Name',
colors: { rubyRed: 1, blueFish: 3 }
}
After using a dasherize
transformer our request data will turn into:
{
first-param: 'My Name',
colors: { ruby-red: 1, blue-fish: 3 }
}
It's great for API with request data format restrictions
Available transformers:
- camelize
- capitalize
- classify
- dasherize
- decamelize
- underscore
You can easily observe a returned model by changing promiseType to array
or object
according to what type of data
your server will return.
When array
:
model.customAction({}, { promiseType: 'array' }) // returns DS.PromiseArray
When object
:
model.customAction({}, { promiseType: 'object' }) // returns DS.PromiseObject
When null
(default):
model.customAction({}, { promiseType: null }) // returns Promise
null
is useful if you don't care about the response or just want to use then
on the promise without using binding
or display it in the template.
You can pass a query params for a request by passing an {}
with properties, eg: { include: 'owner' }
** Remember: Query params are not normalized! You have to pass it in the correct format. **
git clone https://github.com/Exelord/ember-custom-actions.git
cd ember-custom-actions
npm install
bower install
ember serve
- Visit your app at http://localhost:4200.
npm test
(Runsember try:each
to test your addon against multiple Ember versions)ember test
ember test --server
ember build
For more information on using ember-cli, visit https://ember-cli.com/.
Big thanks to Mike North and his Project for the initial concept.
Bug reports and pull requests are welcome on GitHub at https://github.com/exelord/ember-custom-actions. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
This version of the package is available as open source under the terms of the MIT License.