| Tools |
| Authorizations: |
| ›› remove |
Using JavaScript, you can program a regular link to execute in the brief moment after the Internet user clicks the link and before the browser opens the desired page.
In programming jargon, the moment when you execute a code in response to a user's action is called an event.
In the case of paid-links, there are two separate moments. The first occurs after the user clicks on the link and before the browser opens the Confirmation Window. The second moment occurs when the user leaves the Payment Window. Please also note that the user can leave the Payment Window in two ways: by either confirming or canceling the payment.
While regular links have only one event per mouse click, paid-links have no less than 4 events, and you can execute code for each of them:
Please note that only onbefore is triggered before the Payment Window opens, while all other events are triggered after this window closes. This is because when the Payment Window closes, there are two possible results: the Internet user either confirmed or canceled payment.
You should use the onafter event when you want to run the same action whenever the Payment Window closes, regardless of whether payment was made or not. However, if you want to execute something only if payment was made and something else only if the payment was canceled, then you should use onafterok or onaftercancel, respectively.
Note 1: The onclick event also exists in the paid-link. However, it is not possible to know if this event will be triggered before or after the Confirmation Window opens. For this reason, you should not use the onclick event with paid-links. Instead, use the onbefore event.
Note 2: If the JavaScript you define for some of these events contains errors, iCents.net will stop executing the event sequence and may stop executing the link itself. No error message will appear in the JavaScript error console. Therefore, if events are not being executed, look for errors in the JavaScript code for the event, even if nothing appears in the console.
Note 3: These special events of paid-links are not available for registration with modern event registration methods that use "addEventListener" or "attachEvent". Note: If you do not quite understand this note, there is no need to worry. This is an advanced event registration topic and it will not prevent you from using the paid-link events.
For further information on events in JavaScript code, we suggest reading the Introduction to Events page of the Quirksmode website.
There are several ways of registering events for a paid-link. One of the most common methods is called the "inline method", whereby events are inserted within the HTML code of the link.
To register events by the inline method, use the onbefore, onafter, onafterok or onaftercancel attributes.
You can include the JavaScript code directly in the attribute. For example:
<a href="?" price="?" onbefore="alert('click ok')">
Alternatively, you can also call up a JavaScript function:
<script>
function WarnTheUser() { alert('click ok') };
</script>
<a href="?" price="?" onbefore="WarnTheUser">
Note that if the onbefore="WarnTheUser" is used, you should not use the function-calling parentheses with WarnTheUser. It is important to not use parentheses in this definition, because the parenthesis will call a function. Here we do not want to call the function, but rather to link the function to the event.
In the following example, there are warning messages for each link event registered by the inline method:
paid-link <a href="icents:" price="R$0,01" onbefore="alert('onbefore event triggered.')" onafter="alert('onafter event triggered.')" onafterok="alert('onafterok event triggered.')" onaftercancel="alert('onaftercancel event triggered.')" >paid-link</a>
For further information on how to register events in JavaScript code using the inline method, we suggest reading the Early event handlers page of the Quirksmode website.
iCents.net also allows events to be defined by the "traditional method", namely outside HTML. This allows for a better organization of the code.
To register an event with the traditional method, you have to take a reference element and include the event as a property of this element. The best way to do this is to:
For example, to include the onbefore event:
<a id="TestEvents" href="test.html" price="USD 0.10">
<script>
obj = document.getElementById("TestEvents");
obj.onbefore = new Function("alert('click ok')");
</script>
You can also call a previously defined JavaScript function:
<a id="TestEvents" href="?" price="?">
<script>
function WarnTheUser() { alert('click ok') };
obj = document.getElementById("TestEvents");
obj.onbefore = WarnTheUser;
</script>
Note that if obj.onbefore = WarnTheUser is used, the brackets for call function next to WarnTheUser should not be used. It is important to not use parentheses in this definition, because the parenthesis will call a function. Here we do not want to call the function, but rather to link the function to the event.
For further information on how to register events in JavaScript code using the traditional method, we suggest reading the Traditional event registration model page of the Quirksmode website.
A function called by one event could identify which event is responsible for its call. Have the function receive an "e" parameter and e.type will contain the type of event.
Please note that this type of event will not have the initial "on", such that e.type will contain "before", "after", "afterok" or "aftercancel".
In the example below, the same function is called and the different types of event are identified:
paid-link
<a id="TestEvents2" href="icents:" price="R$0,01" duration="10" unlock="content9">paid-link</a> <script> function AlertaTipoEvento(e) { if (e) alert("Event triggered.\n tipo = " + e.type); } obj = document.getElementById('TestEvents2'); obj.onbefore = AlertaTipoEvento; obj.onafter = AlertaTipoEvento; obj.onafterok = AlertaTipoEvento; obj.onaftercancel = AlertaTipoEvento; </script>
It is possible to distinguish whether the link has already been paid upon clicking it. Define a function with the "e" parameter for an event. Set the e.status to true when the link is already paid on being clicked, and to false otherwise.
In the case of links with duration, such as the link of the example further above, after it has already been paid and the access has been unlocked, when it is clicked again the Payment Window does not open, but the onbefore, onafter and onafterok events are executed as if the window were open and the payment, confirmed. For the programmer, this behavior is important to guarantee that the unlocked links also execute the necessary code.
Another link that will not open the Payment Window is the paid-link without a price. The window never appears for this link, whether it has been paid or not, for which reason events will always be triggered in sequence. The only difference is that when the paid-link without a price is not authorized, the last triggered event will not be onafterok, but rather onaftercancel.
Paid-link events should be used with great care to avoid hindering the user's browsing experience. Please remember that you are legally bound to the Technical Use Rules of the iCents system.
Generally speaking, events should only carry out actions that do not delay the appearance of the Payment Window. The only exception to the rule is the following: that the onbefore event is used not just to delay but to effectively prevent the appearance of the Payment Window in the case of payments that should not be made due to incorrect actions or incorrect information given by the user.
For example, suppose that the Internet user fills in a form that will be used to generate information when he or she clicks a button to pay. If the user fills in the form incorrectly, e.g. forgets to include some required information, the server sends a warning informing that there is an error in the form. Yet the user has already paid by now. If the duration of the paid-link is of a few minutes, the Internet user can correct the problem and resend the form without having to pay again. Alternatively, the user's browser, using the onbefore event, can check if the data is completed properly, and only submit the form after everything is correct.
When an event is triggered in a paid-link, this event will be processed in sequence by all the elements contained in the paid-link. This is what is called "event bubbling".
For more information on event bubbling, we suggest reading the Events order page of the Quirksmode website.
Thus, if you define an event in an element that contains various paid-links, you will be actually defining a standard event that will function for all these links. If you define an event for the body of the document, you will be defining a default event for all the paid links of the page, since the body is the top element that contains everything.
It is possible to know exactly which paid-link created the event, as well as to identify the element that is processing the event (in this case, the body).
The paid-link events are propagated for the elements that contain them (note that there is only the "bubble" phase; the "capture" phase is not executed). This propagation allows you to define a default event to be executed whenever any paid link in the page is clicked. For example, you can define a default event in the body:
document.body.onafterok = new Function("alert('thanks for buying')");
The event above is defined for the body, but it is initiated when any paid-link contained in the body is clicked. Using the following event properties, iCents.net allows you to know both the element that originated the event and the element that is actually processing the event.
In the code below, for example, we can obtain the id of the target and currentTarget elements:
function AlertaEventoPadrao(e)
{
alert("onbefore event triggered on the no paid link" + e.target.id);
alert("however, the event was processed by the element: " + e.currentTarget.id);
return false;
}
document.body.onbefore = AlertaEventoPadrao;
Note that the definition of a default event does not prevent the additional definition of an individual event for each paid link. It is also possible to interrupt the propagation of the event by calling the e.stopPropagation() method within the event code. For example:
<a onbefore="StopEvent" href="test.html" price="USD 0.01">paid-link</a> <script> function StopEvent(e) { e.stopPropagation(); } </script>