Kapton
A way of using GraphQL (through Apollo Client) in your Polymer 2.0 elements through class mixins.
Kapton is also the name of a polymer used on the Apollo Lunar Module.
A sample application is available at https://github.com/atoy40/kapton-sample
Usage
A schema
This is the GraphQL schema used in the examples below in GraphQL schema language.
type User { uid: String! lastname: String!} type RootQuery { users(limit: Int): [User!]} type RootMutation { addUser(uid: String!, lastname: String!) : User} schema { query: RootQuery mutation: RootMutation}
Configuration
You'll probably use a javascript entry point "packaged" using a tool like webpack or browserify. The following example use webpack
;;; // Create the apollo clientconst apolloClient = networkInterface: // define unique id of User's { return result__typename+'_'+resultuid; }; // get a mixin "factory"const graphql = ; // get a query documentconst USERS_LIST = gql` query myQuery($limit: Int!) { users(limit: $limit) { uid lastname } }`; // get a mutation documentconst ADD_USER = gql` mutation myMutation($uid: String, $lastname: String) { addUser(uid: $uid, lastname: $lastname) { uid lastname } }`; ;
In this example Webpack configuration will use a library "var" output with the library set to "App", so exported variables will be accessible through the global "App" object (for example App.graphql or App['graphql']).
Usage in components
This small example contains a query and a mutation.
{{item.uid}} : {{item.lastname}} Create
Details
In all examples, we'll assume the mixin factory is App.graphql (seeusage example above).
If your element have more than one Kapton mixin, it can be useful to use the helper function createKaptonMixin :
mixin = createKaptonMixin(factory, document, options)
Query or subscription Mixin
Mixin factory can be used this ways :
// using reactive optionsApp;// using static optionsApp;// using default optionsApp;
Subscriptions will require more configuration and set-up you've seen in the example above. Check Apollo graphql-subscriptions and subscriptions-transport-ws project on github. It implements GraphQL subscriptions using websocket.
Query options
The option object can contains the following keys:
- skip : a boolean to subscribe/unsubscribe the apollo observable ("freeze" the query or subscription). Typical usage is to wait a user to be authenticated to fire queries or stop receiving subscription results.
- name : the name of the element property that will get query or subscription result. Default is "data".
- All options availables in the apollo watchQuery() or subscribe() function.
Query result object (default to "data")
The result contains all the keys you'd have found in the data key of the graphql result. It also contains the following keys allowing advanced usages :
- refetch()
- fetchMore()
- updateQuery()
- startPolling()
- stopPolling()
- subscribeToMore()
- variables : an object containing variables used to get this result.
- loading : boolean, useful if you set notifyOnNetworkStatusChange to true in query options.
- networkStatus : the status of the request, useful if you set notifyOnNetworkStatusChange to true in query options
Subscription result object (default to "data")
The result only contains the key(s) you'd have found in the data key of the graphql result.
Mutation Mixin
// without optionsApp;// using static optionsApp;
Mutation options
The option object can contains the following keys:
- name : the name of the function added to the element to call this mutation. Default is "mutate".
The mutation function (aka "mutate") can also contains options (variables, optimisticResponse, updateQueries, ...). See apollo-client documentation.
More complexe examples
the addUser mutation can use more advanced features of Apollo client, for example optimisticResponse and updateQueries. Check Apollo documentation for more informations. In the first example, the addUser result will not be added to the user list. The following code fix this problem :
{ // mutate is the default name of the mutation function added to the // element this;}