popoto.provider

This package contains the code related to providers.


popoto.provider.linkProvider

The link provider defines all the functions and properties used to generate links on graph or viewers.
This provider can be overridden to customize links rendering.

By default this provider is set to DEFAULT_LINK_PROVIDER.


popoto.provider.taxonomyProvider

The taxonomy provider defines all the functions and properties used to generate taxonomies.
This provider can be overridden to customize taxonomy rendering.

By default this provider is set to DEFAULT_TAXONOMY_PROVIDER.


popoto.provider.nodeProviders

The node providers defines all the functions and properties used to generate nodes on graph or viewers. This provider must contain an entry for each node labels and can be overridden to customize node rendering.

If not set in customized provider all default function will come from DEFAULT_PROVIDER.

Provider example on Neo4j movie dataset sample:
popoto.provider.nodeProviders = {
    "Person": {
        "returnAttributes": ["name", "born"],
        "constraintAttribute": "name"
    },
    "Movie": {
        "returnAttributes": ["title", "released", "tagline"],
        "constraintAttribute": "title"
    }
};

popoto.provider.NodeDisplayTypes

Defines the different type of rendering of a node for a given label.
TEXT: default rendering type, the node will be displayed with an ellipse and a text in it.
IMAGE: the node is displayed as an image using the image tag in the svg graph. In this case an image path is required.
SVG: the node is displayed using a list of svg path, each path can contain its own class.


popoto.provider.DEFAULT_PROVIDER

/**
 * Label provider used by default if none have been defined for a label.
 * This provider can be changed if needed to customize default behavior.
 * If some properties are not found in user customized providers, default
 * values will be extracted from this provider.
 */
popoto.provider.DEFAULT_PROVIDER = Object.freeze(
{
	/**********************************************************************
	 * Label specific parameters:
	 *
	 * These attributes are specific to a node label and will be used for
	 * every node having this label.
	 **********************************************************************/

	/**
	 * Defines whether this label can be used as root element of the graph
	 * query builder.
	 * This property is also used to determine whether the label can be
	 * displayed in the taxonomy filter.
	 *
	 * The default value is true.
	 */
	"isSearchable": true,

	/**
	 * Defines whether this label will automatically expend its relations
	 * when displayed on graph.
	 * If set to true, once displayed additional request will be sent on
	 * the database to retrieve its relations.
	 *
	 * The default value is false.
	 */
	"autoExpandRelations": false,

	/**
	 * Defines the list of attribute to return for node of this label.
	 * All the attributes listed here will be added in generated cypher
	 * queries and available in result list and in node provider's
	 * functions.
	 *
	 * The default value contains only the Neo4j internal id.
	 * This id is used by default because it is a convenient way to identify
	 * a node when nothing is known about its attributes.
	 * But you should really consider using your application attributes
	 * instead, it is a bad practice to rely on this attribute.
	 */
	"returnAttributes": [popoto.query.NEO4J_INTERNAL_ID],

	/**
	 * Defines the attribute used to order the value displayed on node.
	 *
	 * Default value is "count" attribute.
	 */
	"valueOrderByAttribute": "count",

	/**
	 * Defines whether the value query order by is ascending, if false order
	 * by will be descending.
	 *
	 * Default value is false (descending)
	 */
	"isValueOrderAscending": false,

	/**
	 * Defines the attribute used to order the results.
	 *
	 * Default value is "null" to disable order by.
	 */
	"resultOrderByAttribute": null,

	/**
	 * Defines whether the result query order by is ascending, if false
	 * order by will be descending.
	 *
	 * Default value is true (ascending)
	 */
	"isResultOrderAscending": true,

	/**
	 * Defines the attribute of the node to use in query constraint for
	 * nodes of this label.
	 * This attribute is used in the generated cypher query to build the
	 * constraints with selected values.
	 *
	 * The default value is the Neo4j internal id.
	 * This id is used by default because it is a convenient way to
	 * identify a node when nothing is known about its attributes.
	 * But you should really consider using your application attributes
	 * instead, it is a bad practice to rely on this attribute.
	 */
	"constraintAttribute": popoto.query.NEO4J_INTERNAL_ID,

	/**
	 * Return the list of predefined constraints to add for the given label.
	 * These constraints will be added in every generated Cypher query.
	 *
	 * For example if the returned list contain ["$identifier.born > 1976"]
	 * for "Person" nodes everywhere in popoto.js the generated Cypher
	 * query will add the constraint "WHERE person.born > 1976"
	 *
	 * @returns {Array}
	 */
	"getPredefinedConstraints": function () {
		return [];
	},

	/**
	 * Filters the query generated to retrieve the queries.
	 *
	 * @param initialQuery contains the query as an object structure.
	 * @returns {*}
	 */
	"filterResultQuery" : function(initialQuery){
		return initialQuery;
	},

	/**********************************************************************
	 * Node specific parameters:
	 *
	 * These attributes are specific to nodes (in graph or query viewer)
	 * for a given label.
	 * But they can be customized for nodes of the same label.
	 * The parameters are defined by a function that will be called with
	 * the node as parameter.
	 * In this function the node internal attributes can be used to
	 * customize the value to return.
	 **********************************************************************/

	/**
	 * Function returning the display type of a node.
	 * This type defines how the node will be drawn in the graph.
	 *
	 * The result must be one of the following values:
	 *
	 * popoto.provider.NodeDisplayTypes.IMAGE
	 *  In this case the node will be drawn as an image and "getImagePath"
	 *  function is required to return the node image path.
	 *
	 * popoto.provider.NodeDisplayTypes.SVG
	 *  In this case the node will be drawn as SVG paths and "getSVGPaths"
	 *
	 * popoto.provider.NodeDisplayTypes.TEXT
	 *  In this case the node will be drawn as a simple ellipse.
	 *
	 * Default value is TEXT.
	 *
	 * @param node the node to extract its type.
	 * @returns {number} one value from popoto.provider.NodeDisplayTypes
	 */
	"getDisplayType": function (node) {
		return popoto.provider.NodeDisplayTypes.TEXT;
	},

	/**
	 * Function defining whether the node is a group node.
	 * In this case no count are displayed and no value can be selected on
	 * the node.
	 *
	 * Default value is false.
	 */
	"getIsGroup": function (node) {
		return false;
	},

	/**
	 * Function defining whether the node text representation must be
	 * displayed on graph.
	 * If true the value returned for getTextValue on node will be displayed
	 * on graph.
	 *
	 * This text will be added in addition to the getDisplayType
	 * representation.
	 * It can be displayed on all type of node display, images, SVG or text.
	 *
	 * Default value is true
	 *
	 * @param node the node to display on graph.
	 * @returns {boolean} true if text must be displayed on graph for the
	 * node.
	 */
	"getIsTextDisplayed": function (node) {
		return true;
	},

	/**
	 * Function used to return the text representation of a node.
	 *
	 * The default behavior is to return the label of the node
	 * or the value of constraint attribute of the node if it contains
	 * value.
	 *
	 * The returned value is truncated using
	 * popoto.graph.node.NODE_MAX_CHARS property.
	 *
	 * @param node the node to represent as text.
	 * @returns {string} the text representation of the node.
	 */
	"getTextValue": function (node) {
		var text;
		var constraintAttr = popoto.provider.getProperty(node.label, "constraintAttribute");
		if (node.type === popoto.graph.node.NodeTypes.VALUE) {
			if (constraintAttr === popoto.query.NEO4J_INTERNAL_ID) {
				text = "" + node.internalID;
			} else {
				text = "" + node.attributes[constraintAttr];
			}
		} else {
			if (node.value === undefined) {
				text = node.label;
			} else {
				if (constraintAttr === popoto.query.NEO4J_INTERNAL_ID) {
					text = "" + node.value.internalID;
				} else {
					text = "" + node.value.attributes[constraintAttr];
				}
			}
		}
		// Text is truncated to fill the ellipse
		return text.substring(0, popoto.graph.node.NODE_MAX_CHARS);
	},

	/**
	 * Function used to return a descriptive text representation of a link.
	 * This representation should be more complete than getTextValue and can
	 * contain semantic data.
	 * This function is used for example to generate the label in the query
	 * viewer.
	 *
	 * The default behavior is to return the getTextValue not truncated.
	 *
	 * @param node the node to represent as text.
	 * @returns {string} the text semantic representation of the node.
	 */
	"getSemanticValue": function (node) {
		var text;
		var constraintAttr = popoto.provider.getProperty(node.label, "constraintAttribute");
		if (node.type === popoto.graph.node.NodeTypes.VALUE) {
			if (constraintAttr === popoto.query.NEO4J_INTERNAL_ID) {
				text = "" + node.internalID;
			} else {
				text = "" + node.attributes[constraintAttr];
			}
		} else {
			if (node.value === undefined) {
				text = node.label;
			} else {
				if (constraintAttr === popoto.query.NEO4J_INTERNAL_ID) {
					text = "" + node.value.internalID;
				} else {
					text = "" + node.value.attributes[constraintAttr];
				}
			}
		}
		return text;
	},

	/**
	 * Function returning the image file path to use for a node.
	 * This function is only used for popoto.provider.NodeDisplayTypes.IMAGE
	 * type nodes.
	 *
	 * @param node
	 * @returns {string}
	 */
	"getImagePath": function (node) {
		if (node.type === popoto.graph.node.NodeTypes.VALUE) {
			return "css/image/node-yellow.png";
		} else {
			if (node.value === undefined) {
				if (node.type === popoto.graph.node.NodeTypes.ROOT) {
					return "css/image/node-blue.png";
				}
				if (node.type === popoto.graph.node.NodeTypes.CHOOSE) {
					return "css/image/node-green.png";
				}
				if (node.type === popoto.graph.node.NodeTypes.GROUP) {
					return "css/image/node-black.png";
				}
			} else {
				return "css/image/node-orange.png";
			}
		}
	},

	/**
	 * Function returning the image width of the node.
	 * This function is only used for popoto.provider.NodeDisplayTypes.IMAGE
	 * type nodes.
	 *
	 * @param node
	 * @returns {number}
	 */
	"getImageWidth": function (node) {
		return 125;
	},

	/**
	 * Function returning the image height of the node.
	 * This function is only used for popoto.provider.NodeDisplayTypes.IMAGE
	 * type nodes.
	 *
	 * @param node
	 * @returns {number}
	 */
	"getImageHeight": function (node) {
		return 125;
	},

	/**
	 * Filters the query generated to retrieve the values on a node.
	 *
	 * @param node
	 * @param initialQuery contains the query as an object structure.
	 * @returns {*}
	 */
	"filterNodeValueQuery": function (node, initialQuery) {
		return initialQuery;
	},
	/**
	 * Filters the query generated to retrieve the values on a node.
	 *
	 * @param node
	 * @param initialQuery contains the query as an object structure.
	 * @returns {*}
	 */
	"filterNodeCountQuery": function (node, initialQuery) {
		return initialQuery;
	},
	/**
	 * Filters the query used to retrieve the values on a node.
	 *
	 * @param node
	 * @param initialQuery contains the query as an object structure.
	 * @returns {*}
	 */
	"filterNodeRelationQuery": function (node, initialQuery) {
		return initialQuery;
	},

	/**********************************************************************
	 * Results specific parameters:
	 *
	 * These attributes are specific to result display.
	 **********************************************************************/

	/**
	 * Generate the result entry content using d3.js mechanisms.
	 *
	 * The parameter of the function is the <p> selected with d3.js
	 *
	 * The default behavior is to generate a <table> containing all
	 * the return attributes in a <th> and their value in a <td>.
	 *
	 * @param pElmt the <p> element generated in the result list.
	 */
	"displayResults": function (pElmt) {
		var result = pElmt.data()[0];

		var returnAttributes = popoto.provider.getReturnAttributes(result.label);

		var table = pElmt.append("table").attr("class", "ppt-result-table");

		returnAttributes.forEach(function (attribute) {
			var attributeName = attribute;

			if (popoto.query.NEO4J_INTERNAL_ID === attribute) {
				attributeName = popoto.query.NEO4J_INTERNAL_ID.queryInternalName;
			}

			var tr = table.append("tr");
			tr.append("th").text(function () {
				if (attribute === popoto.query.NEO4J_INTERNAL_ID) {
					return "internal ID:"
				} else {
					return attribute + ":";
				}
			});
			if (result.attributes[attributeName] !== undefined) {
				tr.append("td").text(function (result) {
					return result.attributes[attributeName];
				});
			}
		});
	}
});

popoto.provider.DEFAULT_LINK_PROVIDER

/**
 * Label provider used by default if none have been defined for a label.
 * This provider can be changed if needed to customize default behavior.
 * If some properties are not found in user customized providers, default values
 * will be extracted from this provider.
 */
popoto.provider.DEFAULT_LINK_PROVIDER = Object.freeze(
{
    /**
     * Function used to return the text representation of a link.
     *
     * The default behavior is to return the internal relation name as text for
     * relation links.
     * And return the target node text value for links between a node and its
     * expanded values but only if text is not displayed on value node.
     *
     * @param link the link to represent as text.
     * @returns {string} the text representation of the link.
     */
    "getLinkTextValue": function (link) {
        if (link.type === popoto.graph.link.LinkTypes.VALUE) {
            // Links between node and list of values.

            if (popoto.provider.isTextDisplayed(link.target)) {
                // Don't display text on link if text is displayed on target node
                return "";
            } else {
                // No text is displayed on target node
                // so the text is displayed on link.
                return popoto.provider.getTextValue(link.target);
            }

        } else {

            // Link
            return link.label
        }
    },

    /**
     * Function used to return a descriptive text representation of a link.
     * This representation should be more complete than getLinkTextValue and can
     * contain semantic data.
     * This function is used for example to generate the label in the
     * query viewer.
     *
     * The default behavior is to return the getLinkTextValue.
     *
     * @param link the link to represent as text.
     * @returns {string} the text semantic representation of the link.
     */
    "getLinkSemanticValue": function (link) {
        return popoto.provider.getLinkTextValue(link);
    }
});

popoto.provider.DEFAULT_TAXONOMY_PROVIDER

/**
 * Label provider used by default for taxonomies.
 * This provider can be changed if needed to customize default behavior.
 * If some properties are not found in user customized providers,
 * default values will be extracted from this provider.
 */
popoto.provider.DEFAULT_TAXONOMY_PROVIDER = Object.freeze(
{
    /**
    * Function used to return the text representation of a taxonomy.
    *
    * The default behavior is to return the label without changes.
    *
    * @param label the label used to represent the taxonomy.
    * @returns {string} the text representation of the taxonomy.
    */
    "getTextValue": function (label) {
        return label;
    }
});