Ion 2.x or Ion 3.0
This article is designed to introduce Ion administrators to the concept of using Ion profiles to customize, override or insert JavaScript in web pages using the custom scripts feature in Ion profiles. Administrators are assumed to be familiar with JavaScript language syntax and usage prior to using this feature. Several examples are provided at the end of this KB article.
Ion allows administrators to insert custom or new JavaScript into web pages when loaded by an Ion Profile. For Ion, these scripts can be entered via the “Script Injection Manager” available under each profile in the Ion Configuration Manager.
The Scripts tab is a powerful addition to an administrator’s toolkit that gives them the ability to do “JavaScript injection”, that is — to override (overload) existing JavaScript code or add new JavaScript code to any web page at page load time. This JavaScript injection gives administrators more ways to debug website issues, the potential to apply page load time patches and even perform optimizations to the old JavaScript code of legacy web applications such that those web applications can continue to function and interact with users who use more modern browsers. Scripts modified in this way get applied to every page for which the profile is loaded (so if you need to modify scripting for just one page, you should create a separate profile just for that page).
One way websites could be debugged using the Scripts tab is by creating a Script that uses alert messages (popup messages) that divulge the value of certain variables/conditions during a browsing session.
One way websites could be patched using the Scripts tab is by overloading (overwriting) an existing function in the page source of a legacy web page such that the new function will contain revised references and code that is generally more compatible with the new browsers.
Finally, one way websites could be optimized using the Scripts feature is by overriding an old function that uses inefficient code with a new function that uses more effectively methodology.
A collection of examples of common scenarios that could benefit from the Scripts tab is provided later in this KB article.
The Scripts feature is quite simple to use. To create a new script in Ion, select ‘Add Script Injection Item’ from the action pane under the ‘Script Injection Manager’ for the given profile. This will present the window which allows you to enter your custom Javascript.
In this window, administrators can give their new Script an arbitrary name (used only for reference inside the Configuration Manager, the name does not affect code or functionality) as well as write the actual content of their Script. The actual content of the Script is the literal code that the administrator desires to be injected into the page source. Please note that syntax validation is not performed on content entered in the Script editor window, so any malformed JavaScript code may cause script errors or other unexpected behavior.
The JavaScript defined by this feature is injected in the <head> tag of the document after the page loads and before the OnLoad event of the <body> tag is triggered. No individual script object can be larger than 2MB in size, but there is no limit on the number of scripts you can add this way (beyond practical limits like available memory). Once injected, the browser will run the script as if it was a native part of the web page being rendered, and is therefore subject to all limitations and quirks of the browser engine being used (be it an Internet Explorer 7, 8 or 9 engine).
If a function contained in a script in the Scripts tab has the same signature (name and parameters) as an existing function in a website governed by a given Profile, the existing function will be overwritten by the function introduced in the Scripts override feature. Otherwise, in the case that a function is new and does not have the same signature as an existing function, this new function will simply be injected into the page source at page load time.
To remove or edit an existing Script, simply highlight the Script from the Script list and Click the appropriate button on the right-hand side of the window (“Edit” or “Remove”).
Example 1 – Overloading / Overriding JavaScript already present in a page
This first example of the Scripts override feature provides an illustration of how to use this feature to fix website issues by overriding old script code. In this example, the given webpage uses a function that gets the current year using a call to the obsolete getYear() function. The getYear() function is well known to be deprecated, and its use is heavily discouraged, however old web pages occasionally still use the function. Additionally, in modern browsers, the function is implemented inconsistently, therefore it is even more critical to remove its use in order to provide users with the most robust and consistent browsing experience possible.
<html>
<body>
<script type=”text/javascript”>
function GetYr()
{
var dt = new Date();
var theYr = dt.getYear();
return theYr;
}
function BuildPage()
{
var currentYr = GetYr();
/* Code omitted here for simplicity that uses the value returned by GetYr() */
}
BuildPage();
</script>
</body>
</html>
In this case the fix is straightforward. Simply replace the GetYr() function with a new function that depends on a more dependable function called getFullYear(). To do this, click the Create button to open the Script editor window. Then, provide a name for your script – again, this name is for your reference purposes only; it is not part of the function or script itself. Next, enter the entire JavaScript shown below into the Script window and click Ok. This example shows a single function, but the Script can contain any number of functions or statements (up to an object size limit of 2MB).
function getYr()
{
var dt = new Date();
var theYr = dt.getFullYear();
return theYr;
}
After you have clicked Ok and saved the Profile, the script will be injected into any page loaded by the associated Profile and will help ensure this website continues to function with modern browsers.
Please note that in an actual implementation, the resolution to this issue is likely to be more complicated because getFullYear() returns the date in a different format than the original getYear() function (“2011” vs “111”), and additional changes to the page’s script may be required to utilize the new return value correctly.
Example 2 – Debugging web page issues
This next example of the Scripts override feature provides an illustration of how to use the feature to debug web site issues by using popup messages to divulge the value of a certain variable. The variable, “importantVariable”, is useful for an administrator to know when debugging the issue because, as seen in the code, its value is crucial to the JavaScript function that actually outputs HTML code to build the page. Our proposed solution is to use an alert() function call to show the value of “importantVariable” immediately before it is used.
<html>
<body>
<script type=”text/javascript”>
function Calculate(input) // This is the function used to generate the value of “importantVariable.” Its result is difficult to predict.
{
var output; // This is what is eventually returned by this function
/* Code omitted for simplicity; imagine some code that evaluates some data and returns the data in the variable ‘output’
return output;
}
function BuildPage()
{
var importantVariable;
importantVariable = Calculate(importantVariable);
/* Code omitted here for simplicity that uses the value returned by the function */
}
BuildPage();
</script>
</body>
</html>
To override the BuildPage() function each time this page is loaded by a given Profile such that the popup message divulges the value of “importantVariable” before writing HTML to the page, simply click the Create button to open the Script editor window. Then, provide a name for your script – again, this name is for your reference purposes only; it is not part of the function or script itself. Next, enter the entire JavaScript shown below in the Script window and click Ok. This example shows a single function, but the Script can contain any number of functions or statements (up to an object size limit of 2MB).
function BuildPage()
{
var importantVariable;
importantVariable = Calculate(importantVariable);
alert(importantVariable); // This line will cause the browser to open a pop-up showing the value of ‘importantVariable’ which may be useful for debugging
/* Additional code omitted for simplicity */
}
This script will now be injected into every page loaded by the associated Profile and will assist the administrator with debugging the webpage.
Example 3 – Improving existing Javascript performance
This final example of the Scripts override feature provides an illustration of how to use the feature to improve web site performance by replacing existing code with new and optimized code. Below is the HTML code for with a page that provides monthly financial reports for a company. In the JavaScript code contained in the source, one should take note of the way the “message” string is built. This method of multiple concatenation is known to be inefficient, and accordingly, it should be replaced by the more efficient alternative using the join() function
<html>
<body>
<script type=”text/javascript”>
function OutputReport()
{
var companyName = ‘YOUR_COMPANY_NAME_HERE’;
var numSales = ‘YOUR_NUM_SALES_HERE’;
var monthlyRev = ‘YOUR_MONTHLY_REVENUE_HERE’;
var message = ‘This is a report for the ‘ + companyName + ‘ performance for the month. ‘ + companyName + ‘ made ‘ + numSales + ‘ this week, totalling $’ + monthlyRev;
document.write(“<p>” + message + “</p>”);
}
OutputReport();
</script>
</body>
</html>
To override the OutputReport() function each time this page is loaded by a given Profile such that optimized code is used instead, simply click the Create button to open the Script editor window. Then, provide a name for your script – again, this name is for your reference purposes only; it is not part of the function or script itself. Next, in the Script window, enter the entire JavaScript shown below and click Ok. This example shows a single function, but the Script can contain any number of functions or statements (up to an object size limit of 2MB).
function OutputReport()
{
var companyName = ‘YOUR_COMPANY_NAME_HERE’;
var numSales = ‘YOUR_NUM_SALES_HERE’;
var monthlyRev = ‘YOUR_MONTHLY_REVENUE_HERE’;
var message = [‘This is a report for the ‘, companyName, ‘ performance for the month. ‘, companyName, ‘ made ‘, numSales, ‘this week, totaing $’, monthlyRev].join();
document.write(“<p>” + message + “</p>”);
}
This script will now be injected into every page loaded by the associated Profile and will provide a slight performance increase on most browsers. Please note that while this new script will only run on a page when it calls the OutputReport() function, the script itself will be injected to all pages that are loaded by this profile.
Posted in: Ion Knowledge Base,
