How Do I Setup the Image Onload Technique (IOL)?

NOTE THIS POST IS BEING UPDATED - I AM TRYING TO INLINE THE IOL SETUP INSTRUCTIONS AND IT IS MAINLY AN ISSUE OF LEARNING HOW TO FORMAT IN THE NEW FORUM.


Image Onload Technique Setup

This document describes a step by step procedure for setting up the image onload technique. The whole purpose of the image onload technique is to allow user supplied JavaScript code to be loaded into various types of pages {new, view, edit, report, grid edit} and be immediately executed so as to provide some type of enhanced behavior to the page. In effect the image onload technique places user supplied JavaScript into a page as if that script was originally served by QuickBase itself.

This technique is affectionately called the image onload technique because it employs writing a special formula that inserts an invisible image into the page and uses the onload attribute of that image to load the code page module.js. Despite the technical details, the procedure I describe below will allow anyone to setup the image onload technique. What follows is the "second" version of the image onload technique which improves on the first version but is functionally equivalent. Also note that this is a workaround to allow you to enhance forms and pages with additional features and capabilities while we lobby for QuickBase to come up with a supported method of allowing an administrator (not a mere user) to specify that a user supplied JavaScript file should be attached to a form/page for unrestricted purposes. 

Step 1

Insert two user defined variables into your application named iol and /iol with the following definitions:

iol=

<img qbu='module' src='/i/clear2x2.gif' onload="javascript:if(typeof QBU=='undefined'){QBU={};$.getScript(gReqAppDBID+'?a=dbpage&pagename=

/iol=

&rand='+new Date().getTime())};">

Note that the strings "iol=" and "\iol=" are not part of the user defined variable definitions.

Also note that each of these two definitions are in fact one line of text. The forum and screenshot of the QuickBase interface is wrapping the text to make it appear on multiple lines.

These two variables are named so that when they are used in formulas they are reminiscent of HTML markup (see Step 3) and easy to remember. As explained below, we will be writing formula using these two user defined variables similar to the following:

[iol] & "module.js" & [/iol]

Step 2

Create a code page named module.js

and initially place the following single statement in the code page module.js:

alert("module.js is now loaded - I now own your page");

Again, note that this is one line of code.

We will replace this page's contents with some (1) boiler plate code and (2) custom code to implement various additional features.

Step 3

In any table where you want to use an image onload field (typically named [-]) create a text formula field with some HTML allowed using this formula:

[iol] & "module.js" & [/iol]

The name of the image onload field does not include the brackets "[" or "]". The reason the field is typically named [-] is so that when included on a report it takes up the least amount of space and will appear as a very skinny column.

This formula uses the two user defined variables [iol] and [/iol] to simplify the formula and allow you to easily remember the formula if you choose to use it in other tables. Once the user defined variables [iol] and [/iol] are set up you can create additional image onload fields in other tables and forms with similar definitions:

[iol] & "moduleTableName.js" & [/iol]

You will of course have to create a new code page named moduleTableName.js for this additional instance. Generally, I name the code page module.js if there is only one instance or moduleTableName.js if there are going to be several instances. I would encourage you to follow the same naming convention.

Step 4

In the field properties page for the image onload field [-] configure the following properties:

Check:

• Allow some HTML tags to be inserted in the field (Already set in Step 3)

Uncheck:

• Include this field when searching/filtering this table
• Reportable Add this field to all new reports
• The field may be used in reports

Step 5

Place the image onload field [-] on the form you want to enhance. It does not matter where you put the field because we will take all efforts to insure the the field's inclusion on the form is not visible. Set the field to have Alternate Label text but leave the Alternate Label text empty (so it will not be visible). What we are doing here is merely including an invisible image on the form for the sole purpose on forcing our code page to load as if it was originally part of the QuickBase page.

You can additionally control which pages the image onload field is included on by setting the field property Display when this form is used for to one of the following selectable values:

• edit
• view
• add
• edit or add
• edit or view
• add or view
• edit, add or view

This setup controls including the image onload field on a {add, view, edit} form is a secondary mechanism to control when the image onload field is called into action to enhance the page's behavior. You can also include logic in the code page module.js to control when the page's behavior will be modified. As it stands now the code page merely includes an alert() statement to get you familiar with how the image onload technique works.

Step 6

Now visit a form that has been configured to include the image onload field. What you should observe that the form loads in its normal fashion but automatically an alert displays. You now have control of your page and can customize and enhance it.

Step 7

Now that you have the image onload technique setup in your application you can modify the code in module.js to detect what type of page you are on and supply additional custom logic. The following is a generic template for module.js which can be used to detect which type of page is being displayed:

Pastie Database
https://haversineconsulting.quickbase.com/db/bgcwm2m4g?a=dr&rid=293

(function(){
  //$("img[qbu=module]").remove();
  //$("img[qbu=module]").hide();
  var querystring=document.location.search;
  if (/dlta=mog/i.test(querystring)) {
    //GRID EDIT PAGE ========================================
    alert("You are on the Grid Edit Page");
  } else if(/a=er/i.test(querystring)) {
    //EDIT RECORD PAGE ========================================
    alert("You are on the Edit Record Page");
  } else if (/a=API_GenAddRecordForm/i.test(querystring)) {
    //API_GenAddRecordForm PAGE ========================================
    alert("You are on the GenAddRecordForm Page!");
  } else if (/a=GenNewRecord/i.test(querystring)) {
    //ADD RECORD PAGE ========================================
    alert("You are on the Add Record Page");
  } else if (/a=nwr/i.test(querystring)) {
    //ADD RECORD PAGE ========================================
    alert("You are on the Add Record Page");
  } else if(/a=dr/i.test(querystring)) {
    //DISPLAY RECORD PAGE
    alert("You are on the Display Record Page");
    $("img[qbu=module]").closest("td").css("background-color","#FFFFFF");
  } else if(/a=q/i.test(querystring)) {
    //REPORT PAGE ========================================
    alert("You are on the Report Listing Page");
  } else if(/a=td/i.test(querystring)) {
    //TABLE DASHBOARD PAGE ========================================
    alert("You are on the Table Dashboard Page");
  } else if (/a=FinishEditRecord/i.test(querystring)) {
    //FINISH EDIT RECORD PAGE ========================================
    alert("You are on the Finish Edit Record Page");
  } else if (/a=API_GenAddRecordForm/i.test(querystring) {
    //API_GenAddRecordForm ========================================
    alert("You are on the API_GenAddRecordForm Page"); 
  } else {
    //OTHER PAGE ========================================
    alert("You are on the Some Other Page");
  }
})();

Note that the logic in this generic template is only evaluated if you have configured the image onload field to be included on the form in in Step 5.

Step 8

When I answer questions in the forum where I make reference to using the image onload technique all of the steps above are assumed to be undertaken and I typically only post the essential code that would be needed within any one branch of the generic template. This approach allows me to quickly develop "state of the art" customization techniques as questions come up without getting bogged down in endlessly repeating predicate information. Also you may well have to do some additional work or hire a developer if you want a production solution that meets your exact needs.

Step 9

The setup of the image onload technique can be automated. For details see this entry:

Is there a new "image onload technique" in town?

https://haversineconsulting.quickbase.com/db/bgcwm2m4g?a=dr&rid=242

Notes

The use of user defined variables in formulas eliminates some tricky escaping you would otherwise have to do in writing formulas.

The customary names used for the code page module.js and the image onload field [-] are not significant.

The attribute qbu='module' added to the image onload field is actually not needed and is more of a historical artifact used during development. I retain it mostly to avoid coming up with new versions of the technique.

The testing for the existence of the QBU variable is only needed to prevent repeated loading of code page module.js when the [-] field is included in reports and grid edits.

The inclusion of the &rand parameter is currently not needed and was included as a cache busting technique. QuickBase never explicitly states their caching policy so I thought it wise to include it. I retain it mostly to avoid coming up with new versions of the technique.

I really appreciate this guide and the process is notably logical. However, it's still not executing the alert() call. I am currently getting used to the database. Semantically, I may not be interpreting the statement correctly: "Now visit a form that has been configured to include the image onload field..."

Are you referring to the [-] field that you create when you say, "visit a form"? 

Either I didn't follow your guide correctly, which I have read several times now. Or I am misinterpreting what you mean by that statement.

Thanks for the help

Great tutorial Dan! Quick question, is there a way to have the IOL variables to fire off an html code page instead of a javascript one?

Hiya, is there a limit to how many of these buttons you can have on one form?  And is there a specific naming convention?  Having used "-" would "--" be okay? 

I don't know if anybody noticed but in the Pastie Database code above, the line:

else if (/a=API_GenAddRecordForm/i.test(querystring)

Is missing an extra ')' at the end

Thanks I have got this working now, I've added field variables via the button and sorted out a few other issues.  Thank you for your guidance, without your pastebin scripts I'd be lost.