Handling Categories, Facets and entries

Mashup : Appendix - Mashup Expression Language : Handling Categories, Facets and entries

About Relative access in a given context

Sample data

Facet and Category access

Entry access

Result set access

Feed access

Request, Cookie and Session MEL Manipulation

Use cases

The MEL syntax lets you handle categories, facets and entries to return values. You can access these in both:

• an absolute way, for example, in a custom HTML widget;

• and a relative way, within a specific context set by the widget, for example, in a chart widget that requires the setting of a facet.

About Relative access in a given context

When manipulating MEL, you are in a given context. For example, in widgets, you are most of the time in a ''feed'' context, so you don't need to give the beginning of the context in your MEL expression as the widget already has set the context for you.

In the contextual menu listing all available Values on the left, select elements from Contextual feed to add them in a "feed" context in your MEL expression.

For example, a Result List widget iterates over each entry (hit) for each feed, so you can use the relative access to the entries meta as you are scoped at the ''entry'' level. In MEL, this is written as ${entry.***} rather than ${page.feed.entry} as written in an absolute way.

The following diagram represents a tree view of the MEL relative context.

Note: You can enter at any level in the context, but you cannot skip sub-context elements.

Sample data

The following data will be used to illustrate the use of the MEL syntax for facet aggregation.

First Result Hit

Name	Type	Value
title	Meta	The hitchhiker's guide to the galaxy
author	Meta	Douglas Adams
price	Meta	42
date	Category	Top/date/2011/02/01

Facet synthesis sample

Type		Count	Income
Date	Facet	25
2011	Category	16
01	Category	10
01	Category	2
03	Category	3
05	Category	5
02	Category	6
01	Category	1
06	Category	2
07	Category	3
2012	Category	9	125000
02	Category	9	125000
09	Category	9	125000

Facet and Category access

Absolute access

• Access to a specific facet

◦ Syntax: ${feeds["feedName"].facets[facetId].attributes}

◦ Example: ${feeds["cloudview"].facets["Date"].path --> Top/date

Note: feeds["feedName"] can be replaced by feed to use the context of the current feed.

• Access to a specific category

◦ Syntax:

${feed.facets[facetId]["2012"].attributes}

${feed.facets[facetId]["Top/facet_id/rest/of/the/path"].attributes} // Accessing through a path

◦ Example:

${feed.facets["Date"]["2012"].count} --> 9

${feed.facets["Date"]["Top/2011/01"].count --> 10

• Access to the 5th item of facet leaves

◦ Syntax: ${feed.facets[facetId].leaves[5].attributes}

◦ Example:

${feed.facets["Date"].leaves[5].description} --> 07

${feed.facets["Date"].leaves[5].path} --> Top/date/2011/02/07

${feed.facets["Date"].leaves[5].count} --> 3

Contextual (Relative) access

• Access to a category when in a category context

◦ Syntax: ${category.attributes}

◦ Example: ${category.description} --> 2011

• Access to a facet attributes

◦ Syntax: ${facet.attributes}

◦ Example: ${facet.id} --> date

• Access to a category in a Facet context

◦ Syntax: ${facet["mycat"].attributes}

◦ Example: ${facet["2012"].count} --> 9

◦ Categories can also be returned from a Facet: ${facet.flat} --> 2011,2012 (comma-separated list of categories description)

• Access to an aggregation function of a facet in a Facet context

◦ Syntax: ${facet["2012"].aggrs["aggregation_id"]}

◦ Example: ${facet["2012"].aggrs["income"]} --> 125000

Available attributes

The available attributes come from a direct mapping of the Access API attributes. These are:

• id

• description

• path

• state

• refinable (facet only)

• flat (iteration on first level)

• all (recursive iteration)

• leaves (iteration over leaves)

• count

• score (category only)

• aggrs["aggregation_function_name"]

Elements that return list items can also have a list manipulation variable:

• length

• first

• last

Example: ${facet["2012"].length} --> 1

Entry access

Absolute access

• Access to a given meta of a given entry

◦ Syntax:

${feed.entries[n].metas["metaName"]}

${entries[n].metas["metaName"]} // (as a shortcut for feed.entries[n]...)

◦ Example: ${feed.entries[0].metas["title"]} --> The hitchhiker's guide to the galaxy

• Access to a given facet or category of a given entry

◦ Syntax: ${feed.entries[n].facets["facetId"].attributes}

◦ Example: ${feed.entries[n].facets["Date"].leaves[0].count} --> 1

Contextual (Relative) access

• Access to a given meta

◦ Syntax:

${entry.metas["text"]}

◦ Example: entry.author --> Douglas Adams

• Access to a given facet/category

◦ Syntax: ${entry.facets["facetId"].attributes}

◦ Example: ${entry.facets["Date"].path} --> Top/date/2011/02/01

• Access to entry info

◦ Syntax:

${entry.infos["hitInfos"]} //new way

◦ Example:

${entry.infos["did"]} --> 1

Available attributes

The attributes available for the INFOS are directly mapped to Access API.

They can be one of the following:

• id

• self

• image

• builGroup

• buildGroupSlice

• score

• did

• slice

• url

• nCollapsed

How to use the entry scope with an HTML widget

If you want to use an HTML widget and iterate on multiple feeds to retrieve their results, you must target entry positions.

For example, to make an HTML widget retrieve the results of 3 feeds called clients, technicians and users, we could use the following syntax:

${feeds['clients'].entries[entry.index].metas['address']}
/ ${feeds['technicians'].entries[entry.index].metas['name']}
/ ${feeds['users'].entries[entry.index].metas['userid']}

Result set access

This section shows the syntax for accessing global information regarding the result set.

• Access to result set infos

◦ Syntax: ${feed.infos["resultSetInfo"]}

◦ Example: ${feed.infos["nhits"]} --> 1

Available attributes

resultSetInfo are directly mapped to the Access API. They can be one of the following:

• id

• totalResults

• startIndex

• itemsPerPage

• query

• context

• last

• start

• estimated

• nhits

• autocorrected

• ellql

• nmatches

• unknown parameter provided by a specific feed

Feed access

• Access to parent parameters in a subfeed

◦ Syntax: ${feed.entries[2].subfeeds["subfeedname"].entries[0].metas["title"] --> Title of the subfeed’s first entry of the parent feed’s third entry.

Request, Cookie and Session MEL Manipulation

• request gathers all the parameters of the HTTP request.

◦ ${request["contextPath"]}

◦ ${request["queryString"]}

• cookies gathers all the parameters available in the Mashup UI cookies.

◦ ${cookies["name"]}

• session gathers all the parameters available in the user session.

◦ ${session["username"]}

◦ ${session["name"]}

Use cases

The following examples show typical uses of facet manipulations.

Create a metric-like widget

You can create a metric-like widget using an HTML widget with custom HTML code. MEL allows the widget to interact with facets and calculate aggregations values. In the following example, the HTML code retrieves facet descriptions and aggregations to display average values in a dashboard.

<div class="metric_container">
<div class="metric_single metric_separator">
<span class="metric_value">${feed.facets["area"].aggrs["avg_price"]}</span><br />
<span class="metric_descr">Average Price</span>
</div>
<div class="metric_single metric_separator metric_separator_light">
<span class="metric_value">${feed.facets["area"].aggrs["avg_land_sq_feet"]}</span><br />
<span class="metric_descr">Average Area</span>
</div>
<div class="metric_single metric_separator_light">
<span class="metric_value">${feed.facets["area"].aggrs["avg_year"]}</span><br />
<span class="metric_descr">Average Year Built</span>
</div>
</div>

The HTML widget should display results as shown in the following screenshot.

Format standard facet values

The Standard Facets widget can display categories and facets with an aggregation function.

You can interact with the facet of a category that is defined in the widget.

Iterate over facets in an HTML widget

You can iterate over facets in an HTML widget using custom MEL. For example, you can iterate on a category/ facet to replicate the Standard Facets widget behavior.