URL mapping - Documentation

Purpose

Performing a action base on the url query string after wet-boew is ready.

Use when

When the page need to be modified slightly to improve the content usability. It improve the re-use of fragmented content.

Do not use when

To fully feed your page content, in such situation use a server side solution instead.

Working example

English:

French:

How to implement

The url mapping support three type of action. It is possible to add support for additional action.

Ajaxing

On an element

<div data-wb-urlmapping='{
		"ajxload=1":
			{
				"action": "ajax",
				"url": "ajax/ajax-1.html"
			}
		}'></div>

Where:

ajxload=1: Is the query that must match to apply the related action
"action": "ajax": Will execute an ajax request with the data-ajax plugin.
"url": "ajax/ajax-1.html": URL of the ajax file.

Table filtering

On an element with a source refering to a table or directly on a table element

<table class="wb-tables table" data-wb-urlmapping='{
		"date=jul26":
			{
				"action": "tblfilter",
				"column": 1,
				"value": "2016-07-26"
			}
		}' >

Where:

date=jul26: Is the query that must match to apply the related action
"action": "tblfilter": Will apply a table column filter action by using the data tables plugin.
"column": 1: The filtering will be applied on the column index 1. That is visually the second column of the table.
"value": "2016-07-26": The filter value will be the string "2016-07-26".

Patching

On an element

<div data-wb-urlmapping='{
		"example1a":
			{
				"action": "patch",
				"source": "#jmexample1",
				"patches":
					{
						"op": "add",
						"path": "/city",
						"value": "Gatineau"
					}
				}
			}
		}'></div>

Where:

example1a: Is the query that must match to apply the related action
"action": "patch": Will apply the patch action to an existing JSON manager plugin.
"source": "#jmexample1": The source represent a pointer to the JSON manager. "#jmexample1" is representing the id of the element containing the JSON manager.
"patches": { ... }: Contain a patch or an array of patch. See the JSON manager documentation to know how to create JSON patch operation.

Binding actions to the page query

The following variable can be used to map the query information for ajax url, table filter or patches selector.

{qval} string: Query value in the url required to match a regular expression with match configuration. It can be specified by setting the parameter qval.
{base} string: Only for patches. Define the base string of a JSON pointer. Default value is /. It can be specified by setting the parameter base.

`match` and `default` configuration

If match is defined in your configuration, then the default configuration must be also defined.

For security reason, any value retreived from the page URL always require to configure match that will contain a regular expresion. If there no match or the matching result is an empty string, the default configuration will be used as the value fallback.

When you specify a regular expression, it is recommended to have it prefixed with "^" and suffixed with "$". Be careful to not use regular expression that could compromise the security.

Example 1 - Ajax

data-wb-urlmapping='{ "ajx": { "action": "ajax", "url": "ajax/ajax-{qval}.html", "match": "[A-Z][a-z][A-Z][a-z][A-Z][a-z]", "default": "default" } }'

Means that:

?ajx: Will load ajax file: ajax/ajax-default.html
?ajx=2: Will load ajax file: ajax/ajax-default.html
?ajx=wetboew: Will load ajax file: ajax/ajax-default.html
?ajx=canada: Will load ajax file: ajax/ajax-default.html
?ajx=CaNaDa: Will load ajax file: ajax/ajax-CaNaDa.html

Example 2 - Ajax

data-wb-urlmapping='{ "ajx=2": { "action": "ajax", "url": "ajax/ajax-{qval}.html", "match": "[0-9]", "default": "null" } }'

Means that:

?ajx: Do nothing
?ajx=2: Will load ajax file: ajax/ajax-2.html
?ajx=wetboew: Do nothing
?ajx=CaNaDa: Do nothing
?ajx=5: Do nothing

Example 3 - Ajax

data-wb-urlmapping='{ "ajx": { "action": "ajax", "url": "ajax/ajax-{qval}.html", "qval": "TEST" } }'

Means that:

?ajx: Will load ajax file: ajax/ajax-TEST.html
?ajx=2: Will load ajax file: ajax/ajax-TEST.html
?ajx=wetboew: Will load ajax file: ajax/ajax-TEST.html
?ajx=CaNaDa: Will load ajax file: ajax/ajax-TEST.html

Note: The result of match configuration is ignored when the query value is set.

Example 4 - Table filtering

data-wb-urlmapping='{
	"date-search":
		{
			"action": "tblfilter",
			"source": "#myDataTable",
			"column": 1,
			"value": "{qval}",
			"match": "[1-2][0-9][0-9][0-9]-[0,1][0-9]-[0-3][0-9]",
			"default": "2016-07-23"
		}
	}'

Means that:

?: Will show all result
?date-search: Will show result that match the default "2016-07-23" in the second column.
?date-search=: Will show result that match the default "2016-07-23" in the second column.
?date-search=2016-07-26: Will show result that match the string "2016-07-26" in the second column.
?date-search=YYYY-MM-DD: Will show result that match the default "2016-07-23" in the second column.

Default patch operation

{
	op: "move",
	path: "{base}",
	from: "{base}/{qval}"
}

Configuration options

The data-wb-urlmapping attribute must contain an JSON object where all top level property represent the mapping of the url query. Each of those property will contain an object "{ Mapping object }"defined in the table bellow.

data-wb-urlmapping='
	{
		"urlQueryMapping" : { Mapping object },
		"urlQueryMapping" : { Mapping object },
		"urlQueryMapping" : { Mapping object },
		"urlQueryMapping" : { Mapping object }
	}

Note that only the first "urlQueryMapping" mapping object found will be executed, that restriction can be removed by adding the configuration "multiplequery": true" along with the other urlQueryMapping mapping object.

Option	Description	How to configure	Values
action	Required. Define the action to do. Available for: ajax tblfilter patch addClass removeClass mapfilter selectinput	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "[Name of the action]" } }`	ajax Insert content after the element tblfilter Will apply a column filter to a data table patch Will apply a patch by using a JSON manager addClass Add a class to an element removeClass Remove a class to an element mapfilter Apply a geomap filter
url	Specify the url to load. Ajax filtering is supported. The `{qval}` placeholder can be used to replace it by a value that has match the specified regular expression throug the `match` configuration. Available for: ajax	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html" } }`	URL
trigger	Initiate WET features of the inserted content. Available for: ajax	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "trigger": true } }`	false (default): Content is kept as is true: Will initiate any WET feature that exist in the inserted content. Note that for security reason only the first urlmapping can trigger WET on ajaxed content.
container	Specify the container to use to insert the ajax(ed) content Available for: ajax	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "container": "#jQuerySelector" } }`	jQuery selector (By default the container will be a empty container inserted after the form.)
type	Define how content will be inserted from the container perspective. Available for: ajax	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "type": "replace" } }'`	replace(default) after append before prepend This value map how to call the data-ajax plugin
qval	Define exactly the value of the query parameter to use when replacing with `{qval}`. When explicitly specified, useful during quick testing, it do not need to match the regular expression set by `match`. Available for: ajax tblfilter patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "qval": "[a value]" } }'`	false (default): Will be set as per the mapped query value string: Any value that will be recongnized as the query parameter value
match	Regular expression use to extrac the value from the url parameter. Required when "{qval}" is used as a placeholder, otherwise it will be replaced by the required `default` value. Available for: ajax tblfilter patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "match": "A regular expression", "default": "DefaultValue" } }'`	A valid regular expression that explicitly must start with something and end must end with something.
default	Required when `match` is defined. Default value to use in the case of there is no match when evaluating the regular expression. Available for: ajax tblfilter patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "ajax", "url": "path/to/my/file.html", "match": "A regular expression", "default": "DefaultValue" } }'`	Any valid string that when used as a fallback would work with your content.
source	jQuery selector that refer to an existing element on the page. This configuration option can be omited for a table filtering if the url-mapping is set directly on the table element. This configuration option can also be omited for a selectinput. Available for: tblfilter patch addClass removeClass mapfilter selectinput	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "source": "#jQuerySelector" } }'`	jQuery selector and when the action is set to `tblfilter` the source should refer to a data table enhanced with tables plugin.
column	Required for table filtering, this is specify on which column the filter should be applied Available for: tblfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "column": 5 } }'`	Number Integer representing the column number where the first column of table is the number "0" Column selector A valid DataTable column selector
value	Required for table filtering, this specify on what value the filter should be applied. The `{qval}` placeholder can be used in the value, but it must match the regular expression set by `match` config, otherwise it will be replaced by an empty string. Required for `selectinput`. Every input where their `value` attribute matches this property will be selected. Available for: tblfilter selectinput	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "value": "a value to be filtered about" } }'`	A value that will be searched agains the specified column in order to filter the rows.
regex	Treat the searched value as a regular expression. Enable regular expressions without desabling smart search, as smart search use regular expressions, both might conflict and cause unexpected results. Available for: tblfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "column": 0, "regex":true, "smart":false } }'`	Boolean, default false (as defined in DataTable search() API)
smart	Perform smart search. Note that to perform a smart search, DataTables uses regular expressions, so if enable regular expressions using the regex parameter to this method, you will likely want to disable smart searching as the two regular expressions might otherwise conflict and cause unexpected results. Available for: tblfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "column": 0, "smart":false } }'`	Boolean, default true (as defined in DataTable search() API)
caseinsen	Do case-insensitive matching. Available for: tblfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "tblfilter", "column": 0, "caseinsen":false } }'`	Boolean, default true (as defined in DataTable search() API)
class	CSS Class name. Available for: addClass removeClass	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "addClass", "source": "#id", "class": "myclass" } }'`	A CSS class name
base	Define exactly the value of the query parameter to use when replacing with `{base}`. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "base": "/" } }'`	"/" (default): A slash indicating the root. JSON Pointer: A valid JSON Pointer (RFC6901)
patches	Apply patches. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "patches": [ Patches object supported by the JSON manager ] } }'`	false (default): Will use the following patch `{ op: "move", path: "{base}", from: "{base}/{qval}" }` Array []: The page query placeholder will be replace in each for the property `path`, `value`, `from` then the patch is sent to the JSON manager for processing.
fpath	Define a base path in order to apply a filter. This value is required when either or both configuration `filter` and `filternot` is used. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "fpath": "/data" } }'`	false (default): Filtering is undefined and wont be applied. JSON Pointer: A valid JSON Pointer (RFC6901)
filter	A evaluation object as defined in the JSON manager documentation under the configuration option section When this configuration is used, the `fpath` configuration must be set also. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "fpath": "/data", "filter": "{evaluation object}" } }'`	false (default): Filtering is undefined and wont be applied. Evaluation object: See the JSON manager documentation under the configuration option section
filternot	A evaluation object as defined in the JSON manager documentation under the configuration option section When this configuration is used, the `fpath` configuration must be set also. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "fpath": "/data", "filternot": "{evaluation object}" } }'`	false (default): Filtering is undefined and wont be applied. Evaluation object: See the JSON manager documentation under the configuration option section
cumulative	Apply persistant patches for the current page instance. That means that patches exectued will remain when further patches modification is completed by the JSON manager during the current page load. When WET is re-executed (on page load) then all the permently change are ignored. It do not change the data source, it just apply the change in the dataset. Available for: patch	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "patch", "source": "#myJSONmanager", "patches": [ Patches object supported by the JSON manager ], "cumulative": true } }'`	false (default): The patches will be ignored at the next patches update by the JSON manager. true: The patches will be cumulative for the next patches updated by the JSON manager, like from instruction received by fieldflow.
filter	Filter type Available for: mapfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "mapfilter", "source": "#id", "filter": "aoi", "value"="64 -10 34 -177" } }'` `data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "mapfilter", "source": "#id", "filter": "layout", "value"="Layout name" } }'`	`aoi`: Area Of Interest (zoom filtering) and the configuration "value" contains a 4 cardinal point or Well-Known Text (WKT) string. `layout`: Layout (overlay filtering) and the configuration "value" contains the name of that layer as displayed in the legend if any or an empty string to select all.
value	The value for the action Available for: mapfilter	`data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "mapfilter", "source": "#id", "filter": "aoi", "value"="64 -10 34 -177" } }'` `data-wb-urlmapping='{ "QueryStringToBeMapped": { "action": "mapfilter", "source": "#id", "filter": "layout", "value"="Layout name" } }'`	`<string>` (aoi): 4 cardinal point or Well-Known Text (WKT) string for filter set to the Area Of Interest (zoom filtering). `<string>` (layer): The name of that layer as displayed in the legend or an empty string to select all for filter set to Layout (overlay filtering).

Events

Event	Trigger	What it does
`patch.action.wb-urlmapping` patch	Triggered automatically on patch action execution.	Prepare the patches data to be sent to JSON manager throught the event "`patches.wb-jsonmanager`".
`ajax.action.wb-urlmapping` ajax	Triggered automatically on ajax action execution.	Execute the ajax instruction by using the data-ajax plugin.
`addClass.action.wb-urlmapping` addClass	Triggered automatically on addClass action execution.	Will add the specified class to the specified source element.
`removeClass.action.wb-urlmapping` removeClass	Triggered automatically on addClass action execution.	Will removed the specified class to the specified source element.
`tblfilter.action.wb-urlmapping` tblfilter	Triggered automatically on tblfilter action execution.	Filter the data table rows by searching on the specified column.
`wb-ready.wb-urlmapping` Plugin core	Triggered automatically after an wb-urlmapping is initialized.	Used to identify when an wb-urlmapping has initialized (target of the event) `$( document ).on( "wb-ready.wb-urlmapping", ".wb-urlmapping", function( event ) { });` `$( ".wb-urlmapping" ).on( "wb-ready.wb-urlmapping", function( event ) { });`
`wb-init.wb-urlmapping` Plugin core	Triggered manually (e.g., `$( ".wb-urlmapping" ).trigger( "wb-init.wb-urlmapping" );`).	Used to manually initialize the wb-urlmapping plugin. Note: The wb-urlmapping plugin will be initialized automatically unless the required markup is added after the page has already loaded.
`wb-ready.wb` Plugin core	Triggered automatically when WET has finished loading and executing.	Used to identify when all WET plugins and polyfills have finished loading and executing. `$( document ).on( "wb-ready.wb", function( event ) { });`

Source code

URL mapping manager plugin source code on GitHub

Page details

Date modified:: 2017-02-03

Language selection

Search

URL mapping - Documentation

Purpose

Use when

Do not use when

Working example

How to implement

Ajaxing

Table filtering

Patching

Binding actions to the page query

`match` and `default` configuration

Example 1 - Ajax

Example 2 - Ajax

Example 3 - Ajax

Example 4 - Table filtering

Default patch operation

Configuration options

Events

Source code

Page details

URL mapping - Documentation

Purpose

Use when

Do not use when

Working example

How to implement

Ajaxing

Table filtering

Patching

Binding actions to the page query

match and default configuration

Example 1 - Ajax

Example 2 - Ajax

Example 3 - Ajax

Example 4 - Table filtering

Default patch operation

Configuration options

Events

Source code

Page details

`match` and `default` configuration