Drupal CMS Integration with e-Business 6.0

This document provides step-by-step instructions for integrating CMS Drupal with Aptify e-Business 6.0.

Drupal is an extremely flexible CMS from both admin and developer perspective.  The noted approaches below covers both outline Admin level integration options.

Explanation of the e-business  6.0 Folder Structure

The e-Business UI folder has everything the front end controls need, to be used within the site as well as example pages showing how to add each control.

Folder Details

• css folder - The css folder contains the .css file for all styling of the controls.

• html folder - The html folder contains the front end HTML code for each control.  Each control is made up of an html file and a js file.
• js folder - The JS folder contains the JS files for each control.  Each control is made up of an html file and a js file.
• img folder - The img folder contains any images used by the controls via HTML of referenced in the css file.  I.E. Credit Card Images or Icons.
• my folder  - With the root of the folder as well as the js and html folders you will see a "my" folder.  This is currently a structure we have put in place for the profile or other logged in Ebiz user-specific controls.  Similar to the Customer Service folder from the old school .net controls.

Outline of code necessary if we need to add a control to a page

The following is all of the code for the page that is necessary to add the login control. The code is detailed in parts and must be executed in an order given below:

1. Loading Dependencies
2. Defining div
3. Call to the Control's Render Function

Loading Dependencies

First, there are the dependency files. These are the files the controls need to have loaded to work. 

Below are the dependency files which needs to be copied over for the controls to load:

• The StyleSheet

<link rel="stylesheet" type="text/css" href="/frontend/css/eb6.css">

It is expected that this will most likely be included in a site-wide template and not on an individual page. Both will work fine though.

• The Jquery Library file

<script src="/UI/js/3rdParty/jquery-3.2.1.min.js"></script>

It is expected that this will most likely be included in a site-wide template and not on an individual page. Both will work fine though.

• The Knockout Library File

<script src="/UI/js/3rdParty/knockout-3.4.2.js"></script>

It is expected that this will most likely be included in a site-wide template and not on an individual page. Both will work fine though.

• The JS file for the specific control to render.  

In this case the login.js file.

<script src="/UI/js/login.js"></script>

This is expected to be a page level dependency based on the control or controls being used and should be added on the page itself and not in a site-wide template.

• The div tag to render our control into.

Next is the div where the control will render.  This is essentially a placeholder for the actual controls HTML.

<div id="login1"></div>

The ID is important and will be used in the next part of the code.

• Call to render the control

This is the javascript that will tell the dependency file to load itself into the div we noted above.

Defining div

var ProfileDomEl = $('#login1')[0];

Note the ID of the div above is used here.

Call to the Control's Render Function

Each control has a render function in the JS file you will need to call.  Pass in the ID of the div to render the control into, define your live instance of the model and then bind the control with its model.

eb_Login.render(loginOptions).done(function () {

eb_Login.live = new eb_Login.loginModel(undefined,loginDomEl,eb_UserContext.live);

ko.applyBindings(eb_Login.live,loginDomEl);//Apply KO bindings, fire up the control

Integration of a Control

Step1: Adding the E-business folder to the  Drupal 

The integration of our front-end controls with the CMS is straightforward. The e-business controls and dependencies are all in a single folder as shown below. 

Place the highlighted UI folder from e-Business 6.0 to the root directory of the Drupal site.

Step 2: Creating control in Drupal

The noted approaches below both outline Admin level integration options.

• Approach 1 (New Text Format)

  • Using Approach 1 

• Approach 2 (New Text Format And Content Type)

  • Using Approach 2

Approach 1 (New Text Format)

Below is the most straightforward integration that uses one field to include all the code necessary to integrate an e-business control onto a Drupal page.

By default, Drupal uses CKEditor to format text or HTML.  This editor does not allow for Javascript, so it is necessary to create a new text format that does allow Javascript.

To create a new Text Format in Drupal that allows Javascript:

1. Click the "Text Formats and editors" option in the "Configuration" tab as shown below.
   
2. Click the 'Add text format' Button. Name the new format with something relevant. to "Aptify Ebiz".
3. Set the permissions appropriately to Administrator only.
4. Make sure all of the filters are not selected. (the goal here is to make sure any filters applied do not translate the javascript code incorrectly.)
   
5. Once the new text format is saved, the necessary code to include e-business control on pages can be added.

Using Approach 1

Add the control code to the page in one area.

Note in this approach the code must be included in the appropriate sequence (Dependencies-->Placeholder Div–>Call to Control Render Function). Check snapshot below.

Approach 2 (New Text Format And Content Type)

This approach will leverage the new Text Format outlined in Approach 1. It creates a new content Type in Drupal to use when creating pages. 

To create a new Content Type:

1. Click on Structure and Content Types. 
   
2. Name the new content type something relevant to "Aptify Control".
3. Select Disabled under "Preview before Submitting".
4. Click Save and "Manage Fields".
5. 
    The Body field will be added by default.  Keep this field and click edit.

This will be the area for the placeholder div tag when creating content.

Make sure the Basic HTML Text Format is enabled and click Save Changes

Click "Add Field" To add the next field necessary for the Content Type.

 Select Text Formatted Long and label this field "Header" and click "Save and Continue".This is the area to include the dependencies for the controls when creating content.

By Default  The "Field settings" tab will open.  Keep these as defaults and click on the "Edit" Tab

Select The Text Format you created in Approach 1 (Aptify Ebiz), enter any desired help text as noted and click "Save Settings"

Click "Add Field" To add the next field necessary for the Content Type.

Select Text Formatted Long and label this field "Footer" and click "Save and Continue".This is the area to include the call to our controls render function when creating content.

By Default , the "Field settings" tab will open.  Keep these as defaults and click on the "Edit" Tab

 Select The Text Format you created in Approach 1 (Aptify Ebiz), enter any desired help text as noted and click "Save Settings"

Click on Manage Display and select Hidden for the new Header and Footer Areas.

(This removes the stock display of these headers from the front end pages when end users see them)

Using Approach 2

We created the control above and now this section explains the way to use the control content type.

Under Content, click Add Content

Step 3: Select the New Aptify Control Content.

Enter the Div (Placeholder), Header (Dependencies) and Footer (Control Render Call) in the appropriate areas,

This is how the control looks in a CMS Admin area for a page.

Required configuration changes

Following changes need to be done in different configuration files of e-Business 6.0 for loading the site:

Updates in ebConfig:

1. Open the ebConfig file from the following path : Root_drupal\drupal\UI\js\configuration.
2. Update SitePath attribute (shown below) to refer to the Drupal site.

Updates in API web.config:

1. Open the API web.config file from the following path <Database Server>\inetpub\wwwroot\AptifyServicesAPI
2. Search for "Aptify.Services.CORS.AllowedDomains" key and update the same as below:
   <add key="Aptify.Services.CORS.AllowedDomains" value="*" />

Load the Drupal CMS site to confirm that the e-Business control loads.