Documentation URL Mapping - v0.1.0

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:

• URL manager - Ajaxing
• URL manager - Table filtering
• URL manager - Patching

French:

• URL manager - Ajaxing
• URL manager - Table filtering
• URL manager - Patching

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.

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.

Events

$( document ).on( "wb-ready.wb-urlmapping", ".wb-urlmapping", function( event ) {
});

$( ".wb-urlmapping" ).on( "wb-ready.wb-urlmapping", function( event ) {
});

$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

wb-urlmapping.js