A Simplistic Explanation to EmberData Polymorphism

I have been implementing Ember data for one of my projects and one of the most interesting handy features that ember data has is polymorphic models. As the name suggests, this is ember data’s implementation of polymorphism. The first time I use ember data however, requires me spending a lot of time researching for the proper implementations. Official documentation on ember data’s polymorphism is pretty scarce that I had to scrounge the internet looking for example usages.

Although there are great examples out there, most of them are quite complicated and can be quite daunting for beginners. Therefore the aim of the article today is to show you the most simplistic implementation of ember data with polymorphism in hope that beginners will have less frustrations or no frustrations at all understanding.

Please note that this article is written with assumptions that you have understood ember data itself.

Case Study and Design

In order to illustrate our explanation today, we will use a very simple case study. Basically we want to display a list of drivers and their “special car”. Keeping things simple, each drivers will only have one car. Each cars have similar characteristics such as the make, drivetrain and image; however since these are “special” cars there are things that are unique to each of them, hence we need to rely on polymorphism so that ember data instantiates the correct car type. You may of course argue that these “special” properties does not require inheritance and polymorphism, but let’s keep that aside as we only want to demonstrate polymorphism.

As usual, the best way to understand what we want to do is by creating a simple design diagram.

Looking at the design, our implementation will be very simple. Each driver has one car and each car can be either an RxSeven (RX7), AeHachiRoku (AE86) or WRX. The three cars derivative will be instantiated by ember data automatically based on the data returned by the server.

Implementations

The libraries that we will use are:

1. jQuery
2. Handlebars
3. Ember
4. Ember-data
5. jQuery Mockjax (for mocking ajax requests)

We will now go through the javascript codes sections by sections. The full code is available at the end of this article for your learning usages.

HTML

The HTML codes are quite simple. Basically we load up all of our required libraries then render out the template for “index” route. Once the data is received, we loop over the drivers record and display their information and their car. In addition we also check for the specific car attributes such as “engineSwap” or “powerModifications”  to see if they exist. These attributes are the “special” attributes that we are talking about for this case study.

JS

Let’s run through the javascript code for our little example application.

First we create the basic index route so that as soon as the javascript runs, the code will fetch all drivers from  the store. The template above will take care of the rendering of the data returned.

Also notice that we are using ActiveModelAdapter, this means our JSON data from the server should be formatted using underscore and not camelCase. To learn more about active model adapter, visit Ember’s official documentation.

Now we define the classes for the drivers and the cars. Let’s start with the driver.

The most important thing to look at the above is the relationship between Driver and SpecialCar. Notice that we establish the one to one relationship between Driver and SpecialCar through their properties. Driver has a property specialCar which belongs to a SpecialCar object. On the other side, SpecialCar has a property driver which belongs to a Driver object. Think of this as a handshake that establishes the one  to one relationship.

In addition to the “DS.belongsTo” relationship, the Driver class also defines that its specialCar property is a polymorphic object. This means when the data is loaded ember-data should instantiate the correct SpecialCar object based on the “type” included in the data. The async settings means that ember-data won’t try to load the data until requested.

Further to the things above, also notice that we have extended the SpecialCar class three times into more specific type of SpecialCars.They are: AeHachiRoku, RxSeven and Wrx classes; each of these classes have non-standard properties.

Let’s continue on with our  data, this is probably the most important thing to get this working.

Data

Remember that we are using mockjax, this is simply so that we can fake remote requests. This is a simple example after all so there are no backend API server involved at all.

The request above is executed as soon as the application hits the index route. by telling the store to find “driver” ember data automatically looks to find those data from the API since it’s not cached yet.

In terms of initiating the polymorphism feature, take a look at the special_car attribute in the above data for each of the drivers. It is an object with an attribute type. This is the exact attribute that tells ember data what kind of SpecialCar derivatives to instantiate. Note that we use underscore for special_car (due to active model adapter) and the type value always starts with lower-case. Type value also retains the camel-casing as it has to match the name of the the derivative class.

What caught myself and most people when learning about ember-data and polymorphism is the naming convention and choice between camel-case and underscores. Pay attention on what this example is doing.

Continuing on, while looping through the drivers in the template, we are requesting to display car information such as make, drivetrain, etc. This will in turn triggers ember data to fetch more information for each of the specialCar attributes. Thus more remote requests to the API are triggered.

The codes above defines what data should be returned when ember-data requests each car types of a particular ID. An interesting thing to note here is that ember-data also takes care of pluralisation in the remote request. Notice that ae_hachi_roku becomes ae_hachi_rokus in the remote request. This is done automatically and for the purpose of the example we assume our API follows ember-data convention 100%.

Results

Below is the result of our codes written in jsFiddle. EmberJS polymorphism is quite simple and easy to use once you understand how to establish the handshake between object relationships to define polymorphic properties as well the results formatting required from the JSON API.

Conclusion

I hope that this short article helps you to start understanding polymorphic features of Ember Data. This is of course just a very small sub-set of the application of polymorphism and object relations. All we are doing in this example is determining one-to-one relationships. Next time I will write more examples using different kinds of object relationships.

Have fun with Ember! As usual, if you have any questions, leave some message. I will do my best to answer them and if I cannot answer them I hope that others more knowledgable will contribute as well.

Full Codes

Here are the JS full codes in JSFiddle.

Categorised in: Coding, CSS, Javascript