EDMdesigner Integration Tutorial #1 - The Basics

by Gyula Németh

In the following few posts I will talk about integrating EDMdesigner into an arbitrary web-based system. I will provide simple and very typical use-cases, with which you will encounter very likely. By reading the following few posts, you will be able to create a basic integration with gallery handling, using built-in templates, customizing your workflow with custom data and you will be able to use admin related actions. Also, you will be familiar with our dashboard, since in lot of cases it’s more handy to use that.

In this article I will talk about how to start the integration. You will learn about:

  • some of the basic functionalities of our dashboard
  • the basic concepts of token generation
  • you will be able list the projects of a user
  • and finally our app will be able open those projects.

Get access to our dashboard, that is the most important thing. Now, you can write an email to support ~AT~ edmdesigner.com or more preferably to roland ~AT~ edmdesigner.com and we will create an API user for you. Later, we will enable users to register.

Create an API key

Although you will have an API key by default, I suggest you to create one for development purposes, this way there won’t be dummy data under your real API key. When you log in to the dashboard, you will see the following screen:

Your API keys will be listed by default, which you can always reach when you click on “Api instances” in the menu on the left hand side. As you can see, there are a few API keys under my account. You can create as many keys as you want. During these articles, I will use API_GY. I suggest you to create an API key for development purposes. Its name can be YOUR_COMPANY_DEV or something based on that pattern.

The magic word

When you have your brand new API key, the next most important thing is to have the corresponding magic word. You can find it under the “Magic word” menu item on the left. The magic word will be used to generate a token which is the basis of authorization in our API.

On this view, you also can regenerate your magic word, which I already did, so don’t even try to mess with my API key… 😉

Users and the “templater” user

The next thing is to check out the users. By default, there is a special user associated to every API key, and its name is “templater”. You can’t delete this user, because this is the way to create default (or built-in) templates. If this user has templates, every other user in the system is able to create new templates by these. This way you can provide some predefined templates to your users and they don’t have to start always from scratch.

As you can see, “templater” is the only user which is associated to API_GY at the moment. You can create new users on this view, I suggest you to create a user which name is “test”. I will use that user name in my first examples. User names must be unique per API key, so later it is suggested to use your users database id or their email address or something else which is unique.

As you can see it is possible to upload templates to users. (See the upload template button next to each users.) The templates are in a special JSON format, which is defined by us. Also, you can download templates in this format, so if you want to copy a template to a user you can do it by downloading from one and uploading it to another user.

Also, it is possible to purchase templates from us, and you can even order very, very custom templates which we can prepare for you.

If you have reached this point, then everything is set up to start to play around with the API and start coding! In the code examples on the server side I will use PHP, since – almost – everyone can at least read that language.

Code time! Token generation and using the Javascript API

The easiest and the fastest way of integration is to use our Javascript API, which you can reach at https://api.edmdesigner.com/EDMdesignerAPI.js. To make it work you need to add a query property which name is route. The value of this property should be the route where you generate the token. The Javascript file will send a HTTP POST request to this route, and the result should be the token with which will be sent with every request to the API server. So the first thing on the client side would be the following:

In this case we assume, that index.php will generate the token for us when it gets an user id and otherwise it would print the HTML itself. In the example I use http, but it’s also possible to GET the script with through https. Also, api.edmdesigner.com is not the only possibility to get the Javascript file from. It’s also possible to GET them from the following url-s:

  • api-virginia.edmdesigner.com
  • api-ireland.edmdesigner.com
  • api-sydney.edmdesigner.com

This way it’s possible to target the closest api server to your geolocation. Actually, api.edmdesigner.com equals to api-virginia.edmdesigner.com. If you inserted the script tag above to your HTML, a global function called initEDMdesignerPlugin should exist. (Sorry for the naming, it is not really a plugin.) This function accepts two parameters: the first is the user name, the second is a callback. The only parameter of the callback will be an object, lets call it edmDesignerApi, on which you can find various functions to make calls to the API.

So if you want to do something with the “templater” user’s projects – aka. the built-in templates – , you should look like the following:

initEDMdesignerPlugin("templater", function(edmDesignerApi) { //actual calls on edmApi's functions... eg. listing, opening projects, etc. });

The function above will send a post request with the userId to the route specified in the query string in the src of the script tag. In our case it will post the userId (templater) to index.php, which should look something like this:

$publicId, "uid" => $_POST["userId"], "ip" => $ip, "ts" => $timestamp, "hash" => $hash ); // use key 'http' even if you send the request to https://... $options = array( "http" => array( "header" => "Content-type: application/x-www-form-urlencoded\r\n", "method" => "POST", "content" => http_build_query($data), ), ); $context = stream_context_create($options); $result = file_get_contents($url, false, $context); print($result); } else { //print index.html...   In the code snippet above, $publicId should be your API key and the $magic variable should contain the corresponding magic word, which you can find on the dashboard. Basically you have to send to our api server your API key (id), userId of your actual user (uid), your server’s ip address (ip), the actual timestamp (ts) and the md5 hash of the concatenation of your API key, your server’s ip address, the actual timestamp and the magic word. If everything goes well, you will receive a json with a token property in it, otherwise you will receive a 403 HTTP status code. The code snippet above sends back the fetched token to the client side, so EDMdesignerAPI.js can concatenate it to every request. Now you can try to create an empty project to the “templater” user with the following code snippet: ``` ```   You can check out on the dashboard if the project is really created or not. Also, you can break into the callback of initEDMdesignerPlugin with the debugger and check out what kind of functions are there on the edmApi object. An other way to check out if new projects are really created to the “templater” user is to change the code snippet above to the following one: ``` ```   By now, you have probably found out that you can call the initEDMdesignerPlugin function with other user names as well, for example with the one you previously created on dashboard. In my case it’s “test”. You can call all the functions with this user just like you did with “templater”. One very good feature of the “templater” user is that its projects are accessible for all of the users associated with the actual api key. It is possible with the getDefaultTemplates function. ``` ```   This feature is very useful if you use it together with the createFromDefaults function. This way it’s very easy to create a new template based on one of the “templater” user’s templates. One last thing is opening a project. Once you have the _id of the project what you want to open, then it’s easy as a pie. In the following code example we create a project and we open it immediately: ``` ```   In the code above, we directly append an iframe provided by the result object to the end of the body. It is not the only way, there is an src property as well on the result object, making it handy to set the same property of an existing iframe in your dom. That’s for the first post of this series, I hope it was useful. For more details please check out our [API docs](http://api.edmdesigner.com "EDMdesigner-API docs"), and our [example on GitHub](https://github.com/EDMdesigner/EDMdesigner-API-Example-PHP "Example on GitHub").