Correspondance d'URL - Documentation

Needs translation

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
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
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.

Available for:

  • tblfilter
  • patch
  • addClass
  • removeClass
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.

Available for:

  • tblfilter
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.

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

Date de modification :