CR.instrument - Revision history

Admin at 19:32, 11 May 2020

2020-05-11T19:32:03Z

Admin at 00:07, 11 May 2020

2020-05-11T00:07:35Z

Admin at 17:27, 10 May 2020

2020-05-10T17:27:27Z

Admin at 17:23, 10 May 2020

2020-05-10T17:23:23Z

Admin at 17:22, 10 May 2020

2020-05-10T17:22:36Z

Admin: Created page with "`__CR.instrument` is a function available in the ConversionRuler JavaScript Global, and is of type `function`. The method signature for this is:..."

2020-05-10T17:15:09Z

Created page with "<code>__CR.instrument</code> is a function available in the ConversionRuler JavaScript Global, and is of type <code>function</code>. The method signature for this is:..."

New page

<code>__CR.instrument</code> is a function available in the [[ConversionRuler JavaScript Global]], and is of type <code>function</code>.

The method signature for this is:

__CR.instrument(specification, timeout);

Where:

* '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|CR.data]] structure
* '''timeout''' - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.

Example usage:

<script>
__CR.instrument({
"input[type=email]": "email",
"input[autocomplete=email]": "email",
"input[name*=company]": "company",
}, -1);
</script>

The instrumentation code operates as follows:

# The selectors you specified are "searched for" on the page, if they are found they are "connected" such that changes to the values in the inputs will be reflected immediately in the same value stored in <code>__CR.data("...")</code>
# The "connecting" process is what the <code>timeout</code> values refer to - this depends on whether you are instrumenting a site where the page changes (like a web application) then you would want to have this continuously running and instrumenting inputs as the page changes.

The type of target you specify using the [https://api.jquery.com/category/selectors/ jQuery Selector] changes how the item value is saved:

- If your target is an <code>:input</code> then the value is updated whenever the control changes.
- If it is <code><input type="hidden" ...></code> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
- For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery [https://api.jquery.com/text/ text] call for that selector and stored in the <code>__CR.data("...")</code>

A few other properties of this tools:

- Values stored in the data values are stored as strings, are always trimmed of whitespace, - The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values

This function is only available as of ''May 1, 2020''.

== See also ==

* [https://api.jquery.com/category/selectors/ jQuery Selectors]
* [https://api.jquery.com/text/ jQuery text values]
* [[:Category:ConversionRuler JavaScript Functions|JavaScript Functions]]
* [[__CR.ready]]
* [[Tracking Queue]]

[[Category:ConversionRuler]]
[[Category:ConversionRuler JavaScript Functions]]

@@ Line 44: / Line 44: @@
 == Considerations ==
-- Test your code and identify which selectors match which elements on which pages first.
+* Test your code and identify which selectors match which elements on which pages first.
-- Do not specify selectors which are too broad (such as <code>*</code> or <code>div</code> for example) as this will likely kill the performance of your site.
+* Do not specify selectors which are too broad (such as <code>*</code> or <code>div</code> for example) as this will likely kill the performance of your site.
-- Do not store large amounts of data - this information ''may be'' stored as browser cookies and as such will not support data more than ~1000 characters. Generally speaking, data collection should be reserved for small data values for efficiency.
+* Do not store large amounts of data - this information ''may be'' stored as browser cookies and as such will not support data more than ~1000 characters. Generally speaking, data collection should be reserved for small data values for efficiency.
 == In operation ==

← Older revision		Revision as of 17:27, 10 May 2020
Line 41:		Line 41:

	* Values stored in the data values are stored as strings, are always trimmed of whitespace, * The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values		* Values stored in the data values are stored as strings, are always trimmed of whitespace, * The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
		+
		+	== Considerations ==
		+
		+	- Test your code and identify which selectors match which elements on which pages first.
		+	- Do not specify selectors which are too broad (such as <code>*</code> or <code>div</code> for example) as this will likely kill the performance of your site.
		+	- Do not store large amounts of data - this information ''may be'' stored as browser cookies and as such will not support data more than ~1000 characters. Generally speaking, data collection should be reserved for small data values for efficiency.

	== In operation ==		== In operation ==

@@ Line 34: / Line 34: @@
 The type of target you specify using the [https://api.jquery.com/category/selectors/ jQuery Selector] changes how the item value is saved:
-- If your target is an <code>:input</code> then the value is updated whenever the control changes.
+* If your target is an <code>:input</code> then the value is updated whenever the control changes.
-- If it is <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
+* If it is <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
-- For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery [https://api.jquery.com/text/ text] call for that selector and stored in the <code>__CR.data("...")</code>
+* For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery [https://api.jquery.com/text/ text] call for that selector and stored in the <code>__CR.data("...")</code>
 A few other properties of this tools:
-- Values stored in the data values are stored as strings, are always trimmed of whitespace, - The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
+* Values stored in the data values are stored as strings, are always trimmed of whitespace, * The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
 == In operation ==

@@ Line 9: / Line 9: @@
 Where:
-* '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|CR.data]] structure
+* '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|__CR.data]] structure
 * '''timeout''' - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.

@@ Line 1: / Line 1: @@
 <code>__CR.instrument</code> is a function available in the [[ConversionRuler JavaScript Global]], and is of type <code>function</code>.
 The method signature for this is:
@@ Line 9: / Line 11: @@
 * '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|CR.data]] structure
 * '''timeout''' - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.
 Example usage:
@@ Line 15: / Line 19: @@
   __CR.instrument({
      "input[type=email]": "email",
      "input[autocomplete=email]": "email",
      "input[name*=company]": "company",
   }, -1);
@@ Line 22: / Line 29: @@
 The instrumentation code operates as follows:
-# The selectors you specified are "searched for" on the page, if they are found they are "connected" such that changes to the values in the inputs will be reflected immediately in the same value stored in <code>__CR.data("...")</code>
+# The selectors you specified are "searched for" on the page, if they are found they are connected using event handlers such that changes to the values in the inputs will be reflected immediately in the same value stored in <code>__CR.data("...")</code>
 # The "connecting" process is what the <code>timeout</code> values refer to - this depends on whether you are instrumenting a site where the page changes (like a web application) then you would want to have this continuously running and instrumenting inputs as the page changes.
@@ Line 35: / Line 42: @@
 - Values stored in the data values are stored as strings, are always trimmed of whitespace, - The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
 This function is only available as of ''May 1, 2020''.