Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Instructions for the integration of the GUF system (based on the NiMMbus service) in your resources

This page provides general instructions for the GUF integration with your resources. They can be part of your catalogue or can be individual web pages. A "resource" can be anything that has an identifier in the web. Nevertheless, it is expected that your resources have some spatial component. In this page we explain two ways to integrate the Geospatial User Feedback in your web application:

  • The first one offers a JavaScript API and a widget that is very simple to integrate but, in contrast, provides a relative low level of flexibility. People with basic knowledge on JavaScript should select this one first. Basic knowledge on how to call a JavaScript function and include a library is required.

  • The second one offers access to the Javascript for the Web API where the programmer retrieves directly the feedback items encoded in XML and should generate a presentation himself/herself. It provides full control on how the content is shown in the screen but it requires considerable more knowledge on JavaScript programming, including XML parsing and AJAX calls.

There is a more complex and flexible possibility based on communicating with the server directly using the Web API. That will require to build a GUI for providing feedback that can take many days to build. For more information about the Web API see: Web API.

Since the first level is build on top of second level, you can investigate how to use the second level by inspecting the JavaScript code provided in the libraries used in the first level. You can create your own intermediate levels by reusing some part of this code in your own application.

What do you need to know before integrating the GUF

The integration offered in this page assumes that you want to provide feedback about a single resource. Provide feedback about several resources in a single page is also possible but you might require to call the widget several times or from several places.

To be able to start working with the integration, you need to have your resources uniquely identified in your system using a "code" (a.k.a. an identifier). Only identified resources can be associated to feedback items. This "code" needs to be unique in a "codespace". The combination of "code" and "codespace" should provide an identifier that can be considered unique and global. If you do not use the concept of "codespace" or "namespace", we recommend that you use the URL of your web service as the "codespace". Generally, the "codespace" is common to all your resources and can be hardcoded in your application.

Option 1: JavaScript API and widget

You can see this procedure in action in the following working examples:

  • integration with the ECOPotential: click on a dataset name and select Feedback. A new window with previous feedback items and a button to add new ones is shown.
  • integration with the ENEON Graph: click on an element on the network and below you will see its characteristics as well as a link to see and add feedback items about it.

The integration is extremely simple.

Step 1: Include the JavaScript library in your HTML page

The modular library is composed of several JavaScript files and a style sheet that should be included in your Javascript application at the beginning of you web page, commonly in the section. To ease the integration only the main JavaScript file and the CSS need to be directly included pointing to the full URL:

<link rel="stylesheet" href="">
<script language="JavaScript" src=""></script>

Alternatively you get the files from here and point them with a relative URL. Be aware that more than those two files need to be downloaded, as they are indirectly included by guf.js:

  • guf.css
  • guf.js
  • guf_locale.js
  • Nmmblang.js
  • owc_atom.js
  • wps_iso_guf.js
  • xml.js

The inclusion of a style sheet (guf.css) is needed in order to have a special style for the detailed description in publications. This detailed description is initially not displayed, and can be shown by clicking on a "Click to show/hide more information" text in the description. You can modify how this extended description is displayed (e.g. different background color) if including a class ".no_display.user" in your style sheet. Please check the following examples to see how these styles are used (both test pages are showing feedback items for the same resource):

Step 2: Define a division in your HTML page

The GUF widget will be shown in the area of the page you want. You should define a division using relative position. In case of a relative division, the size will be redimensioned automatically when it is populated and what is below the division will be moved down to avoid overlapping with the GUF widget.

<div id="div_guf" style="position: relative; width: 60%"></div>

In the example we create a division with the identifier "div_guf". For the moment, the division is small and it is not visible to the user because it has no content.

Step 3: Fill the division with the GUF widget

This will require that you call a JavaScript function with the name: GUFShowFeedbackInHTMLDiv().

This function has the following parameters in sequence:

  • elem: The object that points to the division created in step 2. To get the object you can call a common JavaScript procedure: document.getElementById("div_guf").
  • seed_div_id: A prefix for some divisions that are going to be created inside the widget. Having this name will allow you get access to the text created in the division or even to manipulate it.
  • rsc_type: A text that is shown as the name of the resource. You can use "resource", "dataset" or a more concrete text for this resource in particular.
  • title: If there is no previous feedback about this resource, a citation is created in the GUF system that includes this "title".
  • code: A unique identifier of the resource in your system.
  • codespace: A "codespace" where the "code" is considered unique. A codespace should be a global identifier (e.g. a URI). If you do not use the concept of "codespace" or "namespace", we recommend that you use the URL of your web service as the "codespace".
  • lang: The language used in the HTML page. You can select among "cat", "spa" or "eng" for Catalan, Spanish or English respectively.

For example, a call to this function could be:

			"CORINE map",

You can call the function directly or you can provide a button or link to "activate" the widget when the user requests it. This can be done with this code:

<a href="javascript:void();" onClick='GUFShowFeedbackInHTMLDiv(document.getElementById("div_guf"), "div_guf_internal", "resource",
"CORINE map", "1234-5678-901234567", "", "eng";'>Add user feedback or review previous feedback</a>"

You can see all elements together in a general example (using a button) here or applied to the Corine Land Cover 2012 metadata page (using a link) here.

Option 2: JavaScript for the Web API

You can see this procedure in action in the following working examples:

Step 1: Include a button to add feedback for resource (e.g. a catalogue entry)

For each entry in a catalogue, a button with a text [Add feedback] is expected, at the end of the general description of the resource.

The button will start another window with the NiMMbus interface (href target=_blank). To ease the process to the user, the link to NiMMbus can be populated with the target_code and target_codespace of the catalogue entry (a target_title is also recommended).

To create the URL please follow the template:{target_title}&target_code={target_code}&target_codespace={target_codespace}&page=ADDFEEDBACK&share_borrower_1=Anonymous&access_token_type={SSO_system}

At the moment, Single-Sign-On systems available are: NextGEOSS, LandSense, Google or NiMMbus (being "NiMMbus" the default value).

For more details go to this example that allows you to create new feedback items of a certain resource (the citation of the resource is automatically created if needed).

How to open the "add feedback" page in a new window

You can use the Javascript function to open the new window. Once the user clicks on save, the window will be closed and the focus will return to the main page."", "Feedback",'toolbar=no,status=no,scrollbars=yes,location=no,menubar=no,directories=no,resizable=yes,width=800,height=700');

The use of the JavaScript function GUFAfegirFeedbackCapa(title, code, codespace, lang) (in guf.js) can simplify this task.

Step 2: Request feedback about a catalogue entry

For each entry in the catalogue, a list of previous user feedback items is expected to be shown. To do that the NiMMbus API allows for an easy retrieval of this information as an ATOM file format.

To create the URL please follow the ENUMERATE template:{catalogue_id}&TRG_OPR_1=EQ&TRG_NXS_1=AND&TRG_TYPE_2=CITATION&TRG_FLD_2=NAMESPACE&TRG_VL_2={catalogue_namespace}&TRG_OPR_2=EQ

To submit a request to the server with a URL without losing the current page content you can use the loadFile() function (in xml.js) that will retrieve the xml document asynchronously.

Example of successful response:

<?xml version="1.0" encoding="iso-8859-1"?>
<feed xmlns="" xmlns:dc="" xmlns:georss="" xmlns:gml="" xmlns:owc="" xmlns:opensearch="" xml:lang="ca">
    <link rel="profile" href="" title="This file is compliant with version 1.0 of OGC Context"/>
    <title>NiMMbus resources response</title>
    <subtitle type="text">Resources [1, 1] of 1 shared with "Anonymous" user</subtitle>
    <generator uri="" version="1.0">
         NiMMbus: MiraMon Cloud Service NB_RESOURCE:ENUMERATE
    <link rel="self" type="application/atom+xml" href=";REQUEST=EXECUTE&amp;IDENTIFIER=NB_RESOURCE:ENUMERATE&amp;LANGUAGE=eng"/>
        <title>Used to extract forest areas</title>
        <link href=";REQUEST=EXECUTE&amp;IDENTIFIER=NB_RESOURCE:RETRIEVE&amp;LANGUAGE=cat&amp;RESOURCE=664U89X4ICLG1SZM1268VNI6723QS0D43048IVE6AJ97RCX&amp;USER=Anonymous"/>
            <name>Alaitz Zabala (AlaitzZabala)</name>
        <category scheme="" term="FEEDBACK" label="a user feedback item" />
        <content type="text">We are reporting this for other to be able to generalise the methodology around the world.</content>

Parsing XML in JavaScript is not an easy task. We recommend that you use the following function to convert the ATOM XML encoding to a JavaScript object that follows the OWS Context JSON encoding.

	var owc=ParseOWSContextAtom(doc.documentElement);
	for (var i=0; i<owc.features.length; i++)

See the function CarregaFeedbacksAnteriors() for more details on how to do that.

To get more information about a specific feedback item you have two alternatives:

Step 3a: Get more information about a specific feedback item all in once

The simpler (but not necessarily appropriate) alternative is to modify the above request to add CONTENT=full. By doing so the full content of the element is inserted in the "content" element of the atom file.

Step 3b: Get more information about a specific feedback item one by one

The second alternative is to extract the resource_id from the atom response entry and follow the RETRIEVE template:{resource_id}.

Please note that this URL is provided directly in each entry of the atom feed in a link element.

Example of a successful feedback retrieval:

<?xml version="1.0" encoding="iso-8859-1"?>
<wps:ExecuteResponse xmlns:wps="" xmlns:ows=""
          xmlns:xlink="" xmlns:xsi=""
          service="WPS" version="1.0.0"
          serviceInstance=";REQUEST=GetCapabilities" xml:lang="en-US">
  <wps:Process wps:processVersion="1">
  <wps:Status creationTime="2017-08-07T07:19:01.625Z">
    <wps:ProcessSucceeded />
      <ows:Title>Resource internal Identifier</ows:Title>
      <ows:Title>Resource creation time</ows:Title>
      <ows:Title>Resource last modification time</ows:Title>
      <ows:Title>Resource type</ows:Title>
      <ows:Title>User Rights</ows:Title>
      <ows:Title>Owner user</ows:Title>
      <ows:Title>Resource title</ows:Title>
            <wps:LiteralData>Good map server</wps:LiteralData>
      <ows:Title>Motivation for this entry</ows:Title>
            <wps:LiteralData>Inform about a comparison problem</wps:LiteralData>
      <ows:Title>Feedback item</ows:Title>
          <wps:ComplexData xmlns:mcc="" xmlns:mdq="" xmlns:mri="" xmlns:cit="" xmlns:gco="" xmlns:qcm="" xmlns:gcx="" xmlns:guf="" xmlns:xsi="" xmlns:xlink="">
							<gcx:Anchor xlink:href="">ResourceID</gcx:Anchor>
							<gco:CharacterString>Good map server</gco:CharacterString>
					<gco:CharacterString>Corine is difficult to compare with my product</gco:CharacterString>
					<guf:GUF_UserRoleCode codeListValue="researchEndUser" codeList=""/>
							<cit:CI_DateTypeCode codeList="" codeListValue="creation"/>
							<guf:GUF_RatingCode codeListValue="4" codeList=""/>
									<gcx:Anchor xlink:href="">UserID</gcx:Anchor>
									<gco:CharacterString>Joan Maso</gco:CharacterString>
							<gco:CharacterString>I'm NextGEOSS full time.</gco:CharacterString>
							<gco:CharacterString>Corine is difficult to compare with my product because it has low resolution</gco:CharacterString>
							<guf:GUF_MotivationCode codeListValue="comment" codeList=""/>
                   	<gco:CharacterString>Corine Land Cover 2012</gco:CharacterString>
							<gcx:Anchor xlink:href="">ResourceID</gcx:Anchor>
            	       		<gco:CharacterString>View the data on a web browser</gco:CharacterString>
							<guf:GUF_TargetRoleCode codeListValue="primary" codeList=""/>

Normally the application will extract the needed values to show to the user. This are the xPath of the most common values to extract. title: wps:ExecuteResponse/wps:ProcessOutputs/wps:Output[ows:Identifier="feedback"]/wps:Data/wps:ComplexData/guf:GUF_FeedbackItem/guf:itemIdentifier/mcc:MD_Identifier/mcc:description/gco:CharacterString

abstract: wps:ExecuteResponse/wps:ProcessOutputs/wps:Output[ows:Identifier="feedback"]/wps:Data/wps:ComplexData/guf:GUF_FeedbackItem/guf:abstract/gco:CharacterString

Rating: wps:ExecuteResponse/wps:ProcessOutputs/wps:Output[ows:Identifier="feedback"]/wps:Data/wps:ComplexData/guf:GUF_FeedbackItem/guf:rating/guf:GUF_Rating/guf:rating/guf:GUF_RatingCode/@codeListValue

Comment: wps:ExecuteResponse/wps:ProcessOutputs/wps:Output[ows:Identifier="feedback"]/wps:Data/wps:ComplexData/guf:GUF_FeedbackItem/guf:userComment/guf:GUF_UserComment/guf:comment/gco:CharacterString

Comment motivation: wps:ExecuteResponse/wps:ProcessOutputs/wps:Output[ows:Identifier="feedback"]/wps:Data/wps:ComplexData/guf:GUF_FeedbackItem/guf:userComment/guf:GUF_UserComment/guf:motivation/guf:GUF_MotivationCode/@codeListValue

Parsing XML is not easy in JavaScript is not easy. We recommend that you use the GetRetrieveResourceFeedbackOutputs() function to convert the XML encoding to a JavaScript object that easier to use.

	var guf=GetRetrieveResourceFeedbackOutputs(doc.documentElement);
	if (guf.comment)
You can’t perform that action at this time.