This topic explains how to configure the content, activation, and positioning of the igPopover
™ control.
The following topics are prerequisites to understanding this topic:
igPopover Overview: This topic provides an overview of the igPopover
control and its main features and functionality.
Adding igPopover: This topic explains, with code examples, how to add the igPopover
control to an HTML page in either JavaScript or ASP.NET MVC.
This topic contains the following sections:
The igPopover
control is functional with its defaults settings, but if you want to customize its default behavior and appearance, there is a set of with which can configure the header and the body of the control with a set of properties. You can also manage the activation of the popover (the triggering event), the dimensions, the positioning and the display of the pointer arrow.
The following table explains briefly the configurable aspects of the igPopover
control and maps them to the properties that configure them. The aspects about which further details are available in this help as code examples, are highlighted in green in the table.
Configurable aspect | Details | Properties | |
---|---|---|---|
Content | Header | The header is configurable. The title of the header may be HTML string or empty. In the latter case, the header is not displayed. The header can optionally render a Close button. | |
Body |
The body of the igPopover content can be customized.
It can be :
|
||
Target | By default, igPopover is initialized over a single element. Multiple targets can be configured by setting them in the selectors option. | ||
Activation | The event on which the popover is shown is configurable. | ||
Positioning | Direction | The position of the popover relative to the target element. The direction is the side of the target where the popover container will be shown. | |
Position | The position of the popover relative to the target element in case the popover is larger than the target. If the popover is smaller, it will always be shown in the middle of the visible area. | ||
Containment | Containment works by specifying an object (like DIV container, for example) whose boundaries will serve to restrict the area within which the popover can be shown. | ||
Size and dimensions | The container of the popover can have a defined width and height. If it hasn’t, maximum width and height can be set. | ||
Pointer |
The size and the color of the popover pointer arrow are configurable. The pointer has no options, it is managed through CSS classes:
|
By default, the header of igPopover
is not shown. The header displays a string designed to serve as a title and, optionally, a Close button. The header is managed by setting the headerTemplate.title property which accepts HTML content. Further customization of the look-and-feel of the header and the close button can be achieved through CSS classes (See Styling igPopover.)
The following table maps the desired configuration to the property settings that manage it.
In order to: | Use this property: | And set it to: |
---|---|---|
Display a title of the popover | headerTemplate.title | The desired value as string of HTML |
Display the Close button | headerTemplate.closeButton | true |
Hide the Close button | headerTemplate.closeButton | false |
The screenshot below demonstrates how the igPopover
would look as a result of the following settings:
Property | Value |
---|---|
headerTemplate.closeButton | true |
headerTemplate.title | “We’re social” |
Following is the code that implements this example.
In JavaScript:
$( '#popoverTooltip' ).igPopover( {
headerTemplate:{
closeButton: true,
title: 'We’re social'
},
closeOnBlur: false
} );
By default, the igPopover
control displays as its body content the title attribute of the target element. To display customized content, use the contentTemplate
option. The setting of this can be :
This allows for a wide range of usage scenarios, like providing context menus, tables, images, dynamic content, etc.
The following table maps the desired configuration to the property settings that manage it.
In order to configure: | Use this property: | And set it to: |
---|---|---|
Content of the body of the popover | contentTemplate | Either of the following:
|
The screenshot below demonstrates how the igPopover
looks as a result of setting its content to a function that uses template and the value attribute of the target DOM element in order to substitute the template data and return the final content as an HTML string.
Property | Value |
---|---|
contentTemplate | In JavaScript: function contentFunction(){...} |
Following is the code that implements this example.
In JavaScript:
$( '#popoverTooltip' ).igPopover( {
..
maxHeight: null,
maxWidth: 260,
contentTemplate: function contentFunction()
{
var imgTemplate = "<img class='map' alt='${value}' src='http://maps.google.com/maps/api/staticmap?zoom=10&size=250x250&maptype=terrain&sensor=false¢er=${value}'>";
var data = [{ value: $( this )[0].value }];
return $.ig.tmpl( imgTemplate, data );
}
} );
The user action on which the popover is shown is configurable. This is managed by feeding the respective event as the value of the showOn property. The default value is “mouseenter” which means that the popover will appear when the user points the target element with the mouse.
Note: In touch environment you cannot control the activating event: the control always shows on the tap user action, no matter what event has been set as activating (i.e. the setting of the showOn option is ignored).
The following table maps the desired configuration to the property settings that manage it.
In order to show the popover when the user: | Use this property: | And set it to: |
---|---|---|
Points the target element with the mouse | showOn | “mouseenter” |
Clicks the target element | showOn | “click” |
Shifts the focusing to the target element | showOn | “focus” |
The screenshot below demonstrates how the igPopover
behaves as a result of the following settings:
Property | Value |
---|---|
showOn | “focus” |
Following is the code that implements this example.
In JavaScript:
$( '#popoverTooltip' ).igPopover( {
selectors: "[title]",
showOn: "focus"
} );
The positioning of the popover is managed with the direction property. It allows you to display the popover on the left, right, top or bottom sections of the target element.
By default and when the popover is smaller than the target element, it displays in the middle that visible area.
When the popover is larger than the target element, then the popover can be positioned at the beginning, in the middle or at the end along the target element's side set as direction
This finer positioning of the popover along the side of the target element is managed with the position property.
The following table maps the desired configuration to the property settings that manage it.
In order to position the popover: | Use this property: | And set it to: |
---|---|---|
Automatically on the most appropriate part of the visible area of the target element (the order of preference is bottom-> right-> top-> left) | direction | “auto” |
On the left part of the visible area the target element | direction | “left” |
On the right part of the visible area the target element | direction | “right” |
On the upper part of the visible area the target element | direction | “top” |
On the bottom part of the visible area the target element | direction | “bottom” |
Automatically (“balanced” setting is chosen in most cases). It is applied always when the popover size is smaller than the target. | position | "auto" |
At the middle of the target element side set as direction | position | “balanced” |
At the beginning of the target element side set as direction.(The beginning of the side is considered its left-hand section at “top”/“bottom” directions and its upper section at “left”/“right” directions.) | position | “start” |
At the end of the target element side set as direction.(The end of the side is considered its right-hand section at “top”/“bottom” directions and its lower section at “left”/“right” directions.) | position | “end” |
The screenshot below demonstrates an igPopover
larger than the target element. The popover is set to display at the right sideof the target input field and is shown in the beginning (in the case, in the top) of the DOM element as a result of the following settings:
Following is the code that implements this example.
In JavaScript:
$( '#popoverTooltip' ).igPopover( {
direction: "right",
position: "start",
headerTemplate:{
closeButton: true,
title: 'Location of the city using Google maps'
},
closeOnBlur: false,
showOn: "focus"
} );
“Containment” means restricting the positioning of popover within a specified area. Containment works by specifying an object (like DIV container for example) whose boundaries will serve to restrict the area within which the popover can be shown.
The following table maps the desired configuration to the property settings that manage it.
In order to: | Use this property: | And set it to: |
---|---|---|
Restrict the area where the popover should be shown | containment | The jQuery object of the element that is restricting the area where the popover will be shown. |
The screenshot below demonstrates a popover configured to display content related to the anchor elements (the blue circles). However, because the popover has been restricted to display only inside the containment <div>
element (indicated by dotted borders), it displays beneath the target element. This happens as a result of the following settings:
Property | Value |
---|---|
containment | $( '#popoverContainment' ) |
Following is the code that implements this example.
In JavaScript:
$( '#bodyParts' ).igPopover( {
direction: "auto",
position: "auto",
closeOnBlur: false,
animationDuration: 150,
maxHeight: 300,
selectors: "a",
containment: $("#bodyParts"),
headerTemplate: {
closeButton: true,
title: "Body parts"
},
showOn: "mouseenter"
} );
The following topics provide additional information related to this topic.
Handling Events (igPopover): This topic explains the events of the igPopover
control and provides some code examples of their use.
Styling igPopover: This topic explains, with code examples, how to configure the look-and-feel of the igPopover
control using CSS. This includes setting the background color of the content, the visibility and color of the pointer, the color of the header and the appearance of the Close button.
The following samples provide additional information related to this topic.
Basic Usage: This sample demonstrates the basic initialization scenarios (on a single target element and on multiple target elements) of igPopover
in JavaScript.
ASP.NET MVC Usage: This sample demonstrates the igPopover
control in an ASP.NET MVC scenario. The control is initialized in the View using chaining syntax.
View on GitHub