NAV
javascript php

Overview - advanced topics

Advanced topics.

Custom Strings

//Custom String object example:
var customStringsObject = {
  id: "validId",
  title: {
    en: "EDM beer"
  },
  items: [
    {
       replacer: "##Svijany##",
       label: "good beer 1"      
    },
    {
       replacer: "##Poutník##",
       label: {
          en: "good beer 2"
       }
    }
  ]
};

The custom strings are an option to provide predefined texts to your users what they can insert while editing text contents. You can add custom strings to - all of your users - to specified users - or to users of a specified group.

The custom strings can be added by bunch of custom string items. Each bunch contains a title what will be displayed as the label of the drop-down list in the text editor, and an id, what provides the identification. By this id it will be possible to remove the bunch. The id can not contain any special characters, the title is a string or a localization object. In case of localization object it what must contain ‘en’ property. Within an item the label property has the same rules.

Add Custom Strings to all of the users of the apiClientInstance

Type

Route

Parameters (you should post):

Response

Http status code 200 - id {String} the saved custom strings id - customStrings {Object} the saved custom stings object - overwritten {Boolean} describes if the save updated an existing bunch or created a new one

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Add Custom Strings to specified users

Type

Route

Parameters (you should post):

Response

Http status code 200 - updatedUsers {Array} list of objects with the property of: - id {String} the user id - updated {Boolean} describes if the save updated an existing bunch or created a new one - id {String} the saved custom strings id - customStrings {Object} the saved custom stings object

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Add Custom Strings to specified groups of the apiClientInstance

Type

Route

Parameters (you should post):

Response

Http status code 200 - id {String} the saved custom strings id - customStrings {Object} the saved custom stings object - overwritten {Boolean} describes if the save updated an existing bunch or created a new one

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get Custom Strings of all of the users of the apiClientInstance

Type

Route

Parameters (you should post):

no parameters needed

Response

Http status code 200 - err {null} null value - the custom string objects as the property names are the id of the custom strings bunch

example: { err: null, customStringID1: { title: { en: 'csTitle’ }, items: [ …items of custom string Objects…. ] } }

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get Custom Strings of a specified user

Type

Route

Parameters (you should post):

Response

Http status code 200 - err {null} null value - the custom string objects as the property names are the id of the custom strings bunch

example: { err: null, customStringID1: { title: { en: 'csTitle’ }, items: [ …items of custom string Objects…. ] } }

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get Custom Strings of a specified group

Type

Route

Parameters (you should post):

Response

Http status code 200 - err {null} null value - the custom string objects as the property names are the id of the custom strings bunch

example: { err: null, customStringID1: { title: { en: 'csTitle’ }, items: [ …items of custom string Objects…. ] } }

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Remove a general Custom Strings by it’s id

Type

Route

Parameters (you should post):

Response

Http status code 200 - id {String} the id of the deleted custom strings bunch Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Remove a user’s Custom Strings by it’s id

Type

Route

Parameters (you should post):

Response

Http status code 200 - id {String} the id of the deleted custom strings bunch - userId {Sting} the id of the user what you removed from Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Remove a group’s Custom Strings by it’s id

Type

Route

Parameters (you should post):

Response

Http status code 200 - id {String} the id of the deleted custom strings bunch - group {Sting} the id of the group what you removed from Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Group handling

You have to generate an admin token!

Group - list

edmDesignerApi.listGroups(callback, onErrorCB)

Lists the groups you have

Parameters:

List groups

Lists the groups you have

Type
Route

Or in case of of limit and skip parameters sent an Object consists of: - totalCount {Number} The length of the full list - result {Array} The list of the groups, same as above

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Group - create

initEDMdesignerPlugin("TestAdmin", function(edmDesignerApi) {
  edmDesignerApi.createGroup({name: "exampleGroup", featureSwitch: {exampleFeature1: true, exampleFeature3: true}}, function(result) {
    //the resultGroup is an object with
    //name {String} (the new group's name)
    //_id  {String} (the new group's id) and
    //featureSwitch {Object} (the group's features) properties
    console.log(result);
  }, onErrorCB);
});

function onErrorCB(error) {
  console.log(error);
}

edmDesignerApi.createGroup(data, callback, onErrorCB)

Creates a new group

Parameters:

Create group

Creates a new group

Type
Route

Parameters (you should post):

Response

An object containing the MongoDB _id of the newly created group: - _id {String}

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Group - get one

initEDMdesignerPlugin("TestAdmin", function(edmDesignerApi) {
  edmDesignerApi.createGroup({name: "exampleGroup", featureSwitch: {}}, function(result) {

    edmDesignerApi.getGroup(result._id, function(resultGroup) { 
      //the resultGroup is an object with
      //name {String} (the new group's name)
      //_id  {String} (the new group's id) and
      //featureSwitch {Object} (the group's features) properties
      //customData {Object} The custom infromations you saved for this group
      console.log(resultGroup);
    }, onErrorCB);

  }, onErrorCB);
});

function onErrorCB(error) {
  console.log(error);
}

edmDesignerApi.getGroup(groupId, callback, onErrorCB)

Gets a specified group

Parameters:

Get one group

Gets a specified group

Type
Route

Parameters (in the route):

Response:

A group object: - _id {String} MongoDB id of the group - featureSwitch {Object} The features that are available for users belong to this group.There is an ever-expanding list of possible features which you can choose from. - name {String} The name of the group - customData {Object} The custom informations you saved for this group

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Group - update

initEDMdesignerPlugin("TestAdmin", function(edmDesignerApi) {
  edmDesignerApi.createGroup({name: "exampleGroup", featureSwitch: {feature1: true}}, function(result) {

    edmDesignerApi.updateGroup(result._id, {name: "newName"}, function(resultGroup) { 
      //the resultGroup is an object with
      //success {Boolean} or err {String} property
      console.log(resultGroup);
    }, onErrorCB);

  }, onErrorCB);

  edmDesignerApi.createGroup({name: "exampleGroup2", featureSwitch: {feature1: true}}, function(result) {

    edmDesignerApi.updateGroup(result._id, {featureSwitch: {feature1: true, newFeature: true}}, function(resultGroup) { 
      //the resultGroup is an object with
      //success {Boolean} or err {String} property
      console.log(resultGroup);
    }, onErrorCB);

  }, onErrorCB);

  edmDesignerApi.createGroup({name: "exampleGroup3", featureSwitch: {feature1: true}}, function(result) {

    edmDesignerApi.updateGroup(result._id, {name: "newExampleName", featureSwitch: {feature1: true, newFeature: true, customData: {foo: "BAR"}}}, function(resultGroup) { 
      //the resultGroup is an object with
      //success {Boolean} or err {String} property
      console.log(resultGroup);
    }, onErrorCB);

  }, onErrorCB);

  function onErrorCB(error) {
    console.log(error);
  }
});

edmDesignerApi.updateGroup(groupId, data, callback, onErrorCB)

Updates a specified group’s name or the features it provides or both of these two at the same time. You can even add custom informations to the group.

Parameters:

Update one group

Updates a specified group’s name or the features it provides or both of these two at the same time. You can even add custom informations to the group.

Type
Route

Parameters (you should post):

Response:

An object: - success {Boolean} It should be true if the update was successful

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Feature Switch

You can allow or forbid some features of our application to a group of your users. The list of the features you can set at the moment:
- gallery {Object}: contains the features of the gallery - noUpload {Boolean} If you set this parameter true then the users belong to this group cannot use the upload functionality. If you configured the gallery noUploadText (see gallery config) text then it will appear on the upload tab, otherwise a default text will be used. - noUrl {Bollean} If you set this parameter true, then the users of this group cannot use any image not hosted by you. The image from url tab of the gallery will disappear if the feature does not allowed. - limit {Number} The number of images the user can upload. If you do not want to set any limit then leave this parameter undefined. If a user reach the limit, then he won’t be able to upload any more image and if you configured the gallery limitReached (see gallery config) text then it will be displayed otherwise a default text will be used. Please note that the 0 limit and the noUpload are almost equivalent except a different message will appear on the upload tab if you use one or the other.

This list is constantly expanding with time!

Feature configuration

This is a new development which will be used everywhere from the next api version. Right now it is only used in a few features texteditor buttons. It is quite similar to the feater switch, but it is a little bit “smarter”. Here you can configure the features on four different level. Each level inherits the upper levels configuration but has greater priority. Basicly the configurationions are merged into each other, but the lower levels always override the inherited configurations, if they have different configuration, but not everything, only the affected settings. The inheritance chain is the following:

apiClient -> apiClientInstance(apiKey) -> group -> user.

For example, we have a configuration named “feature” on apiClient level with value 5. We have to users with different groups, in one of this two groups we override this feature with value 8. So the user who belongs to this group will get a feature configuration with feature 8 (he inherited 5 from the apiClient, but his group overrided it to 8, so in the en he inherited feature 8) while the other user will get feature 5 (he inherited it from the apiClient’s feature configuration).

If you want to disable a feature on one of this four levels, you have to give the feature a false value. (it is do not give any value to a feature then that feauter will be inherited from the upper levels, so it is important to give the feature a false value).

For example, we have a configuration named “feature” on apiClient level with value {“number”: 5}. We have to users with different groups, in one of this two groups we override this feature with value false. So the user who belongs to this group won’t get the feature configuration (he inherited {“number”: 5} from the apiClient, but his group overrided it to false, so in the en he does not inherited this feature. this basicly means that this user cannot use the given feature) while the other user will get feature {“number”: 5} (he inherited it from the apiClient’s feature configuration, so he can use this feature).

Favorite elements

The complex elem is a possible tool to save a BOX or MULITCOLL element with all of it contents to be able to reuse it. This feature is created for make the template editing more fast so more effective. A complex elem can binded to a user, to a group of users or to all of the users. When a user uses the editor these binding displays all together and can be used all of them.

The administrator of the application can upload complex elems to all of the above possibilities. The user of the editor can save complex elems only for him/herself, those will be added to the admin defined items. The editor users can also delete those complex elems what are binded to him/herself as a user.

These are the 3 ways to upload complex elems as an admin: - to all your user (general complexElems upload) - to a specified group (upload complexElems to group) - to specified user or users (upload complexElems to user)

Structure

The representing object for a Complex elem should have the following properties:
- doc {Object} /REQUIRED/ it should be a json object (which represent our templates) - type /REQUIRED/ It must be “BOX”, “MULTICOLUMN” or “FULLWIDTH_CONTAINER” - generalSettings - id {String} /optional/ this id is what will identify the item for you if you would like to manage it via admin - title {Object} /optional/ it should contains language code - title string pairs. For example: 'en’: 'Green-white complexElem’. If you miss to give it, we it will receive a default name. The title will appear on the list of the complex element. If you don’t want to use any other localization then please use the 'en’ language code, the default will always be the 'en’ regardless of the actual language!

Localization

It is possible to use different localization with the same complex elem but not required. You can localize the title of the complex elem. The title of a complex elem will appear on the list, where the user will be able to choose from.
If you want to support more than one language you just have to put the language code - text pair to the title object (see structure). An example title object:

title: { 'en’: 'example title’, 'hu’: 'példa cím’ /… }

Upload Complex Elems to a Group

Upload a list of Complex elems to the specified group. Every user who belongs to this group will be able to use these Complex elems. Please note that every upload will overwrite the previous uploads!
If you want to know what is a Complex elem, please read the complexElements part of the documentation!

Type
Route

Parameters (you should post):

Response:

An object with 3 child objects: - result {Array} list of the complex elems which were successfully added to the group - fails {Array} if some of the items failed it contains the reason, if none of them failed it is null - err {String} If there is any reason why the whole process failed otherwise null

Upload Complex elems to specified users

Upload a list of Complex elems to a specified user or users. Please note that every upload will overwrite the previous uploads!
If you want to know what a Complex elem is good for, please read the complexElements part of the documentation!

Type
Route

Parameters (you should post):

Response:

An object: - error {String} If the whole process is failed, otherwise null. - fails {Array} If a part of the items failed to insert, if all items inserted, it is null.

Upload Complex elems to all users

Upload a list of Complex elems to all users. Please note that every upload will overwrite the previous uploads!
If you want to know what a Complex elem is good for, please read the complexElements part of the documentation!

Type
Route

Parameters (you should post):

Response:

An object: - error {String} If the whole process is failed, otherwise null. - fails {Array} If a part of the items failed to insert, if all items inserted, it is null. - result {Array} List of all inserted Complex elems

Project handler admin routes

Create to

Creates a project/template to a specified user

Type
Route

Parameters (you should post):

Response:

Project object: - _id {String} MongoDB _id of the newly created project

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Create from to

Creates a project/template to a specified user using an another template

Type
Route

Parameters (you should post):

Response:

Project object: - _id {String} MongoDB _id of the newly created project

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Create from to with images

It is quiet similar to the create from to route, basic with this route you can do the same thing except, here not only the project will be copied, but the images (which are used in the template) too. If you want to use this route, first you need to implement a copy route on your server side and config it’s address to the gallery.

Type
Route

Parameters (you should post):

Response:

Project object: - _id {String} MongoDB _id of the newly created project

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get Project

Get a specified project as json. The result will contain almost every information about the selected project.

Type
Route

Parameters (in the route):

Response:

Project object: - _id {String} MongoDB _id of the newly created project - title {String} The title of the project. - description {String} Description about the project - createdOn {String} Creation time - lastModified {String} Time of the last modification - document {Object} The json format of the template - usedColors {Array} List of the colors which are used in the template - generalSettings {Object} The default settings of the template - root {Object} The actual structure of the template - header {Object} The header of the template - footer {Object} The footer of the template - customData {Object} Your custom data

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Set Project

Sets the root of a selected user’s selected project’s document.

Type
Route

Parameters (you should post):

Response:

Success object: - success {boolean}

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Download as Zip

It is possible to export your template as a zip. You can use a simple user level token.

Type
Route

Parameters (in the route):

Configuration

You can set which files you want to have in your exported zip and how you want to export them. To set some configuration you need to put a config json to the data property in the query part of your request. Your config json should have the following properties: - needHtml {Boolean} if it is false then there will be no template.html in your exported zip - needJson {Boolean} if it is false then there will be no project.json in your exported zip - withoutSanitizing {Boolean} if it is true then the template.html won’t be sanitized.

Example: - the config json: {“config”: {“needHtml”: true, “needJson”: false, “withoutSanitizing”: false} } - example request: //api.edmdesigner.com/json_v1.0.0/apiKey/yourapikey/user/youruserid/project/projectId/downloadAsZip?user=youruserid&token=youruserleveltoken&data={“config”: {“needHtml”: true, “needJson”: false, “withoutSanitizing”: false} }

Response:

A zip which can contain the followings (it depends on the configuration, by default it will contain everything): - template.html {file} The html code of the template. It can be a sanitized version or not, it depends of your configuration. By default it will be sanitized. - project.json {file} The json version of the project. - images folder with the images of the template. Please note that every images source (href, src, etc.) in the json and html file are replaced with the paths of the images in the images folder.

Custom Data

If you want to save any kind of plus information for some of your data you can do it with using the customData field You can save custom informations to:
- yourself /apiClientInstance/ (addCustomData) - users (update user server side or client side) - groups (update group server side or client side) - project (update project server side or client side)

Add Custom Data to yourself

You can save any kind of custom information to your apiClientInstance database entry

Type

Route

Parameters (you should post):

Response

Http status code 200

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get my custom data

You can get the custom informations you previously saved for yourself

Type

Route

Response

An object containing your custom data - customData {Object} The custom informations you saved for yourself

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

API key management

API key - list

Lists your api keys

Type
Route

Parameters

Response:

An array of your api keys. Every item is an object with this parameters: - _id {String} MongoDB id of the api key - featureSwitch {Object} The features that are available for users belong to this apikey. There is an ever-expanding list of possible features which you can choose from. - name {String} The name of the api key - customData {Object} Th custom informations you saved for the api key - magic {String} the magic word of the api key - galleryUploadRoute {String} the upload route of the api key - galleryDeleteRoute {String} the delete route of the api key - galleryCopyRoute {String} the copy route of the api key - apiKey {String} the id of the api key

Or in case of of limit and skip parameters sent an Object consists of: - totalCount {Number} The length of the full list - result {Array} The list of the api keys, same as above

Or it can be an error object: - err Description of the error {String} or an error code {Number}.

API key - create

Create new api keys

Type
Route

Parameters

Response:

API key - update

Updating skins of existing api key

Type
Route

Parameters

Tutorials

Tutorial Description
The Basics In this tutorial you will learn about our dashboard, the access token generation and the very basic functionalities, like creating and opening projects.
Admin Functionalities The biggest take away of this tutorial that you will see how to create new users in our system, so you will be able to associate one user for each of users in your system.
Old Built-in Gallery Configuration In this tutorial you will learn about how to set up the gallery properly, how to implement the hooks on your side and you will also learn about the security of these hooks.

Other documentations

Document Description
Basics This documentation covers the very basics of the integration, like:
  • generating an access token
  • making API calls
  • managing and opening projects
  • managing users
  • gallery handling
Advanced This documentation covers more advanced topics. Probably you will only need some of these functionalities.
  • Group handling
  • String placeholders
  • Dynamic data
  • Favorite elements’ management
  • Working with custom data
  • Advanced project handling
  • API key management
postMessage API By reading this documentation you can learn about how to manipulate the editor itself from the client side. Basically this client side API is based on the postMessage function with which you can send messages between frames from different domains.
  • Basic messages and responses (eg. manual save)
  • Hooking on editor events (eg. using your own gallery instead of the built-in one)
  • Dynamic data
  • Setting elements’ properties
Element descriptors A detailed description of our element types used in projects and favorite elements. We generate all of our outputs based on these JSON descriptors.
Old built-in gallery Don’t use it. Use the new postMessage based solution.
Migrating to the CDN based editor In this article you will learn about how to migrate from the good old version of the editor to the superfast and robust CDN based version.

Example implementations

Our PHP examples are very well maintained, but the others are probably not up-to-date. Still, they can be a good starting point, but you might want to take a look at the PHP examples as well in the meanwhile.

If you have another example implementation, please let us know, we will fork it and will put a link here.

javascript php