Step 6. Questions I need to know the answer to!

It is important to understand how the IMu widget configuration settings are organised

Important

If you don't read the explanation below, at least remember this bit:

If you want to make changes to the configuration: do it in:imu/config/local.php !

  1. All configuration information is in imu/config.
  2. There are typically three PHP files that will appear in imu/config:
    • common.php
    • client.php
    • local.php

    Configuration values in local.php override those in client.php which overrides those in common.php.

  3. Much of the config is in imu/config/common.php, which includes:

    server-host

    The machine running the imuserver (this is where EMu data is obtained from).

    server-port

    The used port to connect to the imuserver.

    include-modules

    The set of EMu modules that have anything at all to do with this website.

    search-aliases

    The mapping of generic virtual "columns" (such as the column: "keywords") to one or more "real" columns in each of the modules specified in include-modules. These mappings are used when a cross-module search is performed so we can have a common set of concepts to search on across different modules.

    For example, we can ask things like: 'find the keyword: "shoe" in catalogue, narratives and multimedia'. There may be no actual "keywords" column in any of the database modules in EMu but we can create a concept we call "keywords" and say what actual columns in each module should be treated as belonging to this virtual column "keywords".

    fetch-sets

    Similar to search-aliases except it is a way of creating virtual columns when retrieving data rather than looking for it. It is the mapping of generic virtual "columns" such as "lightbox" to one or more columns in each of the modules specified in include-modules.

    These mappings are used when data is fetched from the server as a result of a cross-module search.

    NB The set of standard viewer widgets (list-viewer, lightbox-viewer, details-viewer, map-viewer, etc.) expect there to be a fetch set defined for their names (i.e. "list", "lightbox", "details", "map" etc.).

  4. imu/config/common.php contains configuration relevant to all installations of the IMu Widget Framework across all customers. This file is controlled by Axiell and should not be edited directly. This is because in a future upgrade the imu/config/common.php file may be replaced by a newer version maintained by Axiell.
  5. The values defined in imu/config/common.php can be overridden in two places:
    1. imu/config/client.php
    2. imu/config/local.php

    The general concept here is as follows:

    • imu/config/common.php includes default settings for any website using the IMu Widget Framework.
    • imu/config/client.php includes settings for a specific website that uses the Widget Framework. In other words general settings that need to override the universal defaults in common and that are not peculiar to the specific machine or infrastructure the website is hosted on (e.g. fetch-sets and search-aliases that apply to a customer's specific EMu installation).
    • imu/config/local.php includes settings specifically for the current instance of the web application (ie the website specifically deployed on a customer's machine - in other words an "instance" of the site). Examples of things placed here might be the server-host and server-port values that define how the website contacts the imuservice and also values that are set by customers if they write their own web pages using the Widget Framework.

    The first two files (common, client) are controlled by Axiell and their contents may be replaced as part of an upgrade to the Widget Framework in future. For this reason these files should not be modified by anyone other than Axiell.

    The last file (local) is not managed by Axiell and Axiell guarantees that a future upgrade will not over-write it.

  6. imu/config/client.php (if it exists) is used for creating configuration settings specific to the current website but suitable for any instance of the website. This is most commonly used to extend the search-aliases and fetch-sets configurations original defined in imu/config/common.php to include columns specific to the particular version of the EMu catalogue module used by the website.

    This file is also controlled by Axiell and should not be modified by others as it may be updated as part of a future upgrade of the Widget Framework.

  7. imu/config/local.php is used to further update the configuration to include any settings specific to the particular instance of this website. This file is not controlled by Axiell and is guaranteed not to be over-written by any future upgrade of the Widget Framework.
  8. Any value set imu/config/local.php will override the corresponding value in imu/config/common.php. For example, we want this instance of the website to use port 40199 to connect to the imuserver. Edit imu/config/local.php and add:
    $config['server-port'] = 40199;

    This will override any value set in imu/config/common.php or imu/config/client.php.

To change the system wide default setting you would add a file imu/config/local.php and specify something like:

                                $config['include-modules'] = array
(
   'enarratives',
   'ecatalogue',
   'eparties',
   'emultimedia'
);

this would make the enarratives, ecatalogue, eparties and emultimedia modules able to participate in the IMu system.

We can specify for each widget, which columns will be returned (depending on module).

If you look in imu/config/common.php you will find entries that define what columns are returned from each module when displayed in a particular widget.

The data is stored in the $config['fetch-sets'] variable.

For example, for the light-box view we have:

$config['fetch-sets'] = array
(
   //...

   'lightbox' => array
   (
       'ecatalogue'=> array
       (
           'irn',
           'title=SummaryData',
           'image'
        ),
        'enarratives' => array
        (
           'irn',
           'title=NarTitle',
           'image'
         ),
         'eparties' => array
         (
            'irn',
            'title=SummaryData',
            'image'
          ),
         'emultimedia' => array
         (
             'irn',
             'title=MulTitle',
             'SummaryData',
             'mimeType=MulMimeType',
             'mimeFormat=MulMimeFormat'
          )
   ),

  // ...
)

(NB the columns listed with an = e.g.: title=SummaryData mean draw data from the SummaryData column but it will be referred to as 'title' within the widget, so we can appear to have a 'title' column in every module rather than having to use a module specific column name in our code).

We can adjust this by overriding the common values.

Important

Make local changes to local.php NOT common.php or client.php.

Rather than editing common.php you add (or edit) a local.php file in imu/config/ (for reasons explained in What configuration information do I need to know?), and override the common values there. This means any IMu upgrades from Axiell (e.g. to add new functionality or fix issues etc.) will not overwrite your local settings.

To add a notes column to each of the reported modules we could add in our imu/config/local.php the following:

$view = &$config['fetch-sets']['lightbox']['ecatalogue'];
$view[] = 'notes=NotNotes';

$view = &$config['fetch-sets']['lightbox']['enarratives'];
$view[] = 'notes=NarDisplayNotes';

$view = &$config['fetch-sets']['lightbox']['eparties'];
$view[] = 'notes=BioBiographicalNotes';

$view = &$config['fetch-sets']['lightbox']['emultimedia'];
$view[] = 'notes=NotNotes';

This overrides the fetch-sets' "lightbox" values adding to the standard columns a new notes column for the modules: ecatalogue, enarratives, eparties and emultimedia.

The local configuration entry:

$view = &$config['fetch-sets']['lightbox']['ecatalogue'];
$view[] = 'notes=NotNotes';

means:

  • Get the default list of catalogue columns that are to be shown when using the lightbox widget and call it $view for convenience.
  • Add the catalogue NotNotes column to the end of that list.
  • Make NotNotes be aliased to the "virtual" column notes.

(by calling it a name like notes rather than the actual column name NotNotes means we could draw columns from other modules but have them all appearing to be called notes irrespective of what the real column name is).

When searching, IMu uses a model that emphasizes the concepts columns are used for rather than needing to always know (and use) specific column names in the front end code.

A mapping of the concepts needed by front end designers, to the actual back-end source of the data is stored in the IMu config directory.

For example, we can define a concept like: 'keywords' for searching and then specify what 'keywords' means depending on the type of data we are talking about, such as:

  • For Catalogue records it might be data in the SummaryData column.
  • For Parties records the First Name and Last Name columns.
  • For Multimedia records the Title and SummaryData columns.
  • For Narrative records the Narrative Title, Subjects and Narrative text columns.

If you look in imu/config/common.php file, it has a 'search alias' configuration. We can change the existing aliases or add new ones if needed.

As mentioned above, if you want to override the standard behaviour, you would make the changes in a local.php file rather than editing the default common settings in imu/config/common.php.

Suppose we want to specify for the keyword-search the columns described above. We would enter a structure in the config/local.php file something like:

$config['search-aliases']['keywords'] = array
(
   'ecatalogue' => array
   (
      'SummaryData'
    ),
   'enarratives' => array
    (
       'DesSubjects_tab',
       'NarNarrative',
       'NarTitle',
    ),
    'eparties' => array
    (
        'NamFirst',
        'NamLast',
     ),
     'emultimedia' => array
     (
         'MulTitle',
         'SummaryData'
      )
);

So we now have an alias called 'keywords' that can be used when searching for records that will look in the specified modules for the given columns.

Once set up we can just refer to 'keywords' in our search code and don't need to worry about what the actual columns in the database are.

You can override the default configured columns programmatically when you configure a specific instance of an IMu Search object. You can make that search return a custom set of columns by calling its newResultSet method.

For example:

var search = new IMu.Request.Search();
var resultSet = search.newResultSet(
      'irn;' +
      'title=SummaryData;' +
      'department=ColDepartment;' +
      'subDepartment=ColSubDepartment', 1);

For example, I want Catalogue records displayed like:

Specimen Details

Summary:

I.44700-013 - Neoglyphidodon melas (Cuvier, 1830) - Australia, Queensland, Lizard Island, out front, Casuarina Beach

Id:

I.44700-013

Scientific Name:

Neoglyphidodon melas (Cuvier, 1830)

Phylum:

Chordata

Family:

Pomacentridae

Genus:

Neoglyphidodon

Species:

melas

Common name:

Blue And Gold Damsel-fish

where I choose the prompts and styles for display for this page (but want other displays for other pages).

See: Custom item display for an example of doing this.

It uses the keyword-search widget to find an item then customizes an IMu Search object to display the data.

For example, I want a results list displayed like:

Specimen Details

IRN Location Family Scientific Name Common Name Thumbnail
123 A1-2 Xidae Xus yus Alphabet Bird  
124 A1-1 Xidae Xus yus Alphabet Bird  
92334 Z4-2 Xidae Xus yus Alphabet Bird  
3214 basement-2 Beidae Aus bus Letter Bird  

See: Custom list display for an example of doing this.

It uses the keyword-search widget to find an item then customizes an IMu Search object to display the data in a similar way to the previous question.

Note: A standard grid-viewer widget is soon to be added to the widget collection that will make doing this easier

See: Custom list display #2 for an example of doing this.

It builds on the example answer to the previous question but keeps track of the position of the current rows displayed.

For example, we want to have a customized list and a customized item display (as we have done above) but both inter-operating together.

See A custom list and item page.

What we are doing in this example is implementing a search object to return the list of matches from a keyword-search and then on clicking a row, implementing another search object to retrieve the individual record.

For example, I want a general search control that works across all modules and also a particular search for just matching Catalogue records.

See: Custom item display for an example of doing this.

The IMu Search object's 'search' method takes an optional second parameter that specifies an array of modules to include in the search.

For example:

search.search(
             [ 'keywords', terms ],
             [ 'ecatalogue', 'emultimedia' ],
             function(hits)
                 {
                     ...
                     ...
                 }

This bit of code would be restricting the search to the 'ecatalogue' and 'emultimedia' modules only.

See: Custom item display for an example of doing this. Basically, if you know the key of the image you can use that to get a URL to the image:

For example:

var key = 12345;
var url = './imu/request.php?request=Multimedia&method=fetch&filter=kind:eq:thumbnail&key=' + key;
jQuery('#image').append('<img src="' + url + '"/>');

Records in EMu have image (and other multimedia) key values stored in the MulMultiMediaRef_tab column. (This is an array of keys.)

In Custom item display we are retrieving the array of attached images and displaying each one.

var resultSet = search.newResultSet(
   'irn;' +
   'title=SummaryData;' +
   'mm=MulMultiMediaRef_tab' // <--- Get the attached image keys
   , 1);
     ...
     ...
   search.search(
      [ 'keywords', terms ],
      [ 'ecatalogue' ],
      function(hits)
         {
            resultSet.get(0,
           function(row)
           {
              jQuery('#title').text(row.title);
             // display each image
             for (var i = 0; i < row.mm.length; i++)
             {
                var ref = row.mm[i];
                var url = './imu/request.php?request=Multimedia&method=fetch&filter=kind:eq:thumbnail&key=' + ref;
                jQuery('#image').append('<img src="' + url + '"/>');
              }
            }
      );
   }
);

When using the request.php?request=Multimedia&method=fetch you can specify the sort of multimedia you want returned. This is done using the filter argument.

Format of the filter argument(s):

\<type\>:\<operator\>:\<value\>[;...]

type values include:

  • height: The height (pixels) of the resource (images only).
  • identifier: The record identifier (MulIdentifier) column.
  • index: The index of the resource in the multimedia record documents & supplementary tables (combined).
  • kind: Specify the (abstract) kind of resource e.g. thumbnail, master, resolution or supplementary.
  • mimeFormat: The media format of the resource.
  • mimeType: The media type of the resource.
  • size: The file size of the resource.
  • width: The width (pixels) of the resource (images only).

operator values:

  • eq: Equals.
  • ne: Not equals.
  • lt: Less than.
  • gt: Greater than.
  • le: Less than or equal to.
  • ge: Greater than or equal to.
  • bf: Best fit. Selects the resource with the closest value.
  • bg: Similar to Best fit. Selects the resource with the closest value greater than or equal to the supplied value.

The lt, gt, le, ge, bf and bg operators can only be used with filter types that support numeric comparison.

Examples:

  • filter=kind:eq:resolution;width:lt:400

    Select a resolution (not master, thumbnail or supplimentary resources) with a width less than 400.

  • filter=width:gt:300;height:gt:300

    Select the first resource with a width and height greater than 300.

  • filter=width:bf:300;height:bf:300

    Select the resource whose width and height values are both closest to 300.

  • filter=kind:eq:thumbnail

    Select the thumbnail image.

  • filter=mimeType:eq:video

    Select the first video resource.

The code passed to the IMu.Request.Search.findTerms() method can include some structure like:

var search = new IMu.Request.Search();
var terms =
   [
      'or',
      [
         [ 'ObjObjectType', 'dog' ],
         [ 'ObjObjectType', 'cat' ]
       ],
        'and',
        [
          [ 'SummaryData', '"fish and chips"']
        ]
    ];

search.findTerms(terms, function(hits)
{
   // ...
});