ng-zendesk-orm
v0.1.2
Published
A Zendesk API interaction wrapper for Angular applications.
Downloads
9
Readme
Angular Zendesk ORM
A Zendesk API interaction wrapper for Angular applications.
This currently only supports creating new Zendesk request objects.
Requires Angular 6.0.0 or later.
License: GPL 2.0 or later.
How to Use
1. Install the module
First, install the module in your Angular 6.x or later project with npm install --save 'ng-zendesk-orm'
.
Then import the ZendeskORMModule
in your root module. Get the symbol with import { ZendeskORMModule } from 'ng-zendesk-orm';
.
2. Configure the module for your Zendesk Account
Second, configure the module for your own Zendesk integration. Do this by providing an object that implements the ZendeskConfig
interface in your application's root module, using the ZENDESK_CONFIG
injection token.
This can seem a bit confusing... I recommend simply copy-pasting from the example below and replacing the three object properties with your own values.
// Not included in excerpt: The rest of your root module's imports list
import {
ZENDESK_CONFIG,
ZendeskConfig,
} from 'ng-zendesk-orm';
const MyZendeskConfig: ZendeskConfig = {
simulateAPI: 'no',
// your subdomain e.g. "example" in "example.zendesk.com"
subdomain: 'my-zendesk-subdomain',
// your secret API token
token: '1234567789';
};
@NgModule({
providers: [
{ provide: ZENDESK_CONFIG, factory: () => new ZendeskConfig() },
],
// additional module metadata
})
export class YourAppModule { /* ... */ }
subdomain
and token
are required properties of your ZendeskConfig
object. simulateAPI
is, as well and can be one of three different string values. Set it to 'no'
to make your application interact directly with Zendesk, as in a production environment. The other two options are useful for debugging: 'succeed'
and 'fail'
will simulate successful responses and error responses, respectively.
3. Create Zendesk requests within your code
Third, import ZendeskORMService
into any service you want to make calls to the Zendesk API from its createRequest()
method like so:
import { Injectable } from '@angular/core';
import {
ZendeskORMService
ZendeskRequestAPIPayload
} from 'ng-zendesk-orm';
@Injectable()
export class MyService {
// inject ZendeskORMService
constructor( zendesk: ZendeskORMService ) {}
// A method called when user submits a form that should generate
// a Zendesk request object
submitForm() {
this.zendesk.createRequest(
12345, // your ZenDesk form ID
'Jane Doe', // requester name
'[email protected]', // requester email
'subject', // subject of the request
'I have a question. Please get back to me.', // request body
this.mySuccessCallback, // success handler
this.myErrorCallback, // error handler
['array', 'of', 'tags'], // optional
[ // optional array of custom field objects with id/value properties
{
id: 12345 // custom field id
value: 'value' // value to set
},
{
id: 54321 // custom field id
value: 'another value' // value to set
},
]
);
}
// A callback for successful request creation
mySuccessCallback(dataSent: ZendeskRequestAPIPayload, dataReceived: any) {
/* do stuff with response */
}
// A callback for UNsuccessful request creation
myErrorCallback(dataSent: ZendeskRequestAPIPayload, dataReceived: any) {
/* do stuff with error */
}
}
What's Included
ZendeskORMModule
is this module. Include it in your Angular application to use its functionality.ZendeskORMService
is an injectable Angular service. Interact with this to create Zendesk requests.ZENDESK_CONFIG
is an injection token that allows referring to configuration objects.ZendeskConfig
is an interface describing the shape of configuration objects for this module. Provide an object that implements this interface with theZENDESK_CONFIG
injection toekn as described above to configure the module for your own Zendesk account, as described above.ZendeskRequestAPIPayload
is an interface that describes the shape of payloads sent to Zendesk's "request" API. Your success and error callback methods will need to use this in their call signature.
The module also includes ZendeskAPIService
for internal use, to interact directly with Zendesk's APIs. (ZendeskORMService
is a more application-friendly wrapper that uses ZendeskAPIService
under the hood.) This isn't exported by the module because it is intended for internal private use, so it won't be available to your application.
Roadmap
Nice-to-have features:
- Add test coverage!
- Fully support all 'request' payload interface members
- Add support for HTTP request types beyond 'POST' for "requests"
- Extend support beyond Zendesk requests
- Maybe support Angular
4.x
and later, instead of6.x
and later?- Upgrading from
4.x
to6.x
isn't terribly onerous in most cases, so I'll only work on this if I get requests for it.
- Upgrading from
Maintenance
Build
Run ng build ng-zendesk-orm --prod
to build the library. The build artifacts will be stored in the dist/
directory. Use the --prod
flag for a production build.
Publish updates to NPM
# manually increment version in package.json
# avoid git tags since we're publishing from `dist/` later
npm --no-git-tag-version -f version [major|minor|patch]
# build
ng build ng-zendesk-orm --prod
# switch to built package
cd dist/ng-zendesk-orm/
# publish update npm
npm publish
Run tests
There currently are no tests!
- Run
ng test
to execute the unit tests via Karma. - Run
ng e2e
to execute the end-to-end tests via Protractor.