Step 3. Interacting with EMu Databases

At this point we are ready to use the widget to communicate with a back-end EMu database.

Some background

We will be using the IMu Search object. It is an object that knows how to search for and obtain data from the back-end EMu database system.

It can do things like: search for data matching certain criteria, get the 'Nth' record in a set of matches etc.

IMu widgets can be configured to use the IMu Search object to obtain and display appropriate data.

We will take our keyword-search widget and add a search object to do things when the keyword-search onSearch handler is activated.

First off, let's do something simple: find out how many records match the criteria in the keyword-search request.

Summary of the process

We need to:

1. Create an IMu search object.
2. Configure the search object to look for terms entered in the keyword-search widget, in the EMu database.
3. Configure the search object to act on the results of the search.

Details of what needs to be done

Using our existing page, change the keyword-search widget's onSearch callback from displaying an alert dialog to instead create and configure an IMu search object. This search object will then run the search.

                var keySearch = $('#example-keyword-search').IMu('keyword-search',
   {
       showLabel: true,
       showSubmit: true,

        onSearch: function(terms)
        {
            // make a new search object
            var search = new IMu.Request.Search();

            // configure the search object
            search.search(['keywords', terms], function(hits)
            {
                alert('Searched: ' + hits.modules.length + " modules\n" +
                       'Found: ' + hits.total + ' matches');
            });
        }
    }
keySearch.setTerms('The');

In the above code we are:

1. Creating a search object in the keyword-search widget's onSearch handler.
2. Configuring the search object to:
   1. Search for the entered terms (looking for matching keywords in the EMu database)
   2. On return from the search, display some summary details of the results of doing that search.

Example page

example 5

What should happen

When we click the Go button, it should look up the entered terms in EMu and display information about how many matches it finds. It is quite possible however that nothing will happen. Don't Panic!

If it doesn't work

It is quite likely that your IMu web environment isn't configured appropriately to access the database. This is potentially a good thing as it will show us some techniques that will come in useful later when debugging IMu systems.

1. Open your browser's Developer Tools Page.
2. Refresh your HTML page in the browser.
3. Look for any errors in the console. If any found, address them.
4. Assuming it is all working to this point, press the keyword-search widget's Go button.
5. Again check the console for errors. If any found address these.

Most likely you will see an error indicating a call to the back-end IMu service failed. e.g. something like:

POST http://HOSTNAME/web/tutorial/imu/request.php 500 (Internal Server Error)

If so, look at the Developer Tool Network logs for that call and view the response. If you get an error like:

Error: SessionConnect (localhost,40000,Connection refused) [500] (500)

Then it is stating that the IMu widget environment was unable to connect to the back-end IMu server process. It was trying to connect to the localhost server, on port number 40000 but the connection was refused for some reason.

Fixing connection refused errors

There should be a configuration file in the IMu web environment that specifies how it connects to the IMu service.

It is located at: imu/config/local.php

A typical PHP configuration file will look something like:

<?php
$config['server-host'] = 'localhost';
$config['server-port'] = 40136;
?>

1. Find out if the back-end IMu service is running and verify the host and port number it is running on. You may need to contact the EMu administrator to get this information.
2. If the service is running, verify you have the IMu front end configured to access that service.
   1. Is there a file: imu/config/local.php? If not, create it.
   2. Are the values in that file correct?

Before proceeding

In the following steps, we will be adding more functionality to our page. If it doesn't work now then you will not really be able to proceed further with the tutorial.

If it does work first off

BREAK IT! :)

It is important you are comfortable diagnosing problems that you may encounter doing IMu page development.

1. Edit the imu/config/local.php and change a parameter. Retry the page display (it hopefully now won't work). Follow the steps above to see how you could diagnose the problem.
2. Rename the imu/config/local.php file to something like local.php.NOT and retest the page and go through the diagnosis procedures above.

Things to try

Try putting a console.log(hits) statement in the code after the alert statement. Run a search and then using your browser's Developer Tools console, examine the structure of the returned 'hits' object.

function(hits)
{
   alert('Searched: ' + hits.modules.length + " modules\n" +
       'Found: ' + hits.total + ' matches');
   console.log(hits);
}