LnkWcb Framework

LnkWcb  2.5.0

LnkWcb Framework > LnkWcb > LnkWcb.Bouton
Search:
 
Filters

Class LnkWcb.Bouton

Known Subclasses:
LnkWcb.BoutonBasique LnkWcb.BoutonJquery
Base Bouton.

The name is a metonymy. This class actually defines instances that handle a WCB form. Strictly speaking, a "button" is a display trigger for such a form. And this is not handled here.

This class implements all server features. It does not make any presentation choice, and this is entirely left to subclasses.

Constructor

LnkWcb.Bouton ( cfg )
Parameters:
cfg <Object> the initial configuration settings

Properties

cfg - Object

The current applicable configuration settings.

Methods

addFallbackRawError

protected static void addFallbackRawError ( fallbackRawError )
Add a fallback raw error description in the database.
Parameters:
fallbackRawError <Object> the details of some fallback error

addRawError

protected static void addRawError ( rawError )
Add a raw error description in the database. The rawError is inserted before the last position to keep the catch-all last record.
Parameters:
rawError <Object> the details of some new raw error

collectOpeners

private Array collectOpeners ( )
Collects successive window openers locations if any.

First array element is the window location. (Thus the returned array contains at least one element.) Subsequent values are successive window openers locations, if any.

Returns: Array
the location URLs of the window and its openers openers if any

createRequest

private void createRequest ( that )
Optional request creation factory method.

Internally used for better isolation in unit tests. Usually undefined.

Parameters:
that <Object> the object that might provide a createRequest method to use (usually the LnkWcb.Bouton instance)

deborder

protected void deborder ( resp , request )
Called by the server response when a falback occurs. Only valid in the serverSideManagedFallbacks=false (deprecated) compatibility mode.
Parameters:
resp <Object> the response
request <Object> the request (attributes)
Deprecated Fallbacks should be handled by web integration not controlled by server-side configuration.

estOuvert

void estOuvert ( )
Queries the back-end for the channel state.

At response time, listen to the onChannelState event to perform actions based on the channel state.

find

private Object find ( rawErrs , code , msg )
Lookup an error in a database. Matching algorithm is:
  • (1) Code (strict) equality
  • (2) Message matching the reference regexp
  • (3) Message (strict) equality
Parameters:
rawErrs <Object> a raw errors database
code <String> the cause of the error to look for
msg <String> the message of the error to look for
Returns: Object
a matching error, if found in the database, otherwise null

findFallbackRawError

protected static Object findFallbackRawError ( code , msg )
Find a fallback error details. This lookup differs from findRawError() in that it might fail and return null.
Parameters:
code <String> the error code
msg <Object> the error message
Returns: Object
the details of a matching fallback error, or null otherwise

findRawError

protected static Object findRawError ( code , msg )
Find an error details. Any error always match because the database maintains a catch-all record in last position.
Parameters:
code <String> the error code
msg <Object> the error message
Returns: Object
the details of the matching error (never null)

getDefaultSettings

protected Object getDefaultSettings ( )
Get the default LnkWcb.Bouton configuration settings.
Returns: Object
a clone of the default settings

getFallbackRawErrors

protected static Object getFallbackRawErrors ( )
Get a copy of the fallback error details database.
Returns: Object
a clone of the raw errors database

getRawErrors

protected static Object getRawErrors ( )
Get a copy of the error details database.
Returns: Object
a clone of the raw errors database

grabFormFields

private Object grabFormFields ( elemId )
Extract the data of a specific <form> element.

This method iterates over the form inputs, and build an object containing fields valued, indexed by fields names.

Multiple values are not supported. Only the first selected option of a multiple <select> element is returned. If many fields have the same name, then the value of the last one is returned.

Parameters:
elemId <String> a <form> element ID

horaires

void horaires ( )
Queries the back-end for the channel open hours.

At response time, listen to the onOpenHours event to perform actions based on the channel open hours.

In standard use cases, you need not listen to this event because any LnkWcb.Calendar (and subclasses) will do it automatically for you.

raccrocher

void raccrocher ( )
Hangs up a call.

rappeler

void rappeler ( telephone , date )
Sends a call-back request.

Validator is called. If OK, the onSendCall event is fired. The the request is sent.

At response time, listen to

  • the onErrorDigest event to handle errors.
  • the onEnded event if you placed a delayed call (immediately fired in this specific case)
  • the onStatus event to follow an immediate call status
  • the onEnded event to handle OK and KO endings
  • the onFallback event to handle fallback cases (might be an initial error or a KO ending)
Only one of the events onErrorDigest, onEnded and onFallback is fired. This point is very important to help you handle all situations.
Parameters:
telephone <String> the callee telephone number
date <Date> an optional date at which the delayed call should occur

reponseEstOuvert

protected void reponseEstOuvert ( reponse )
Call-back method called after estOuvert().

Fires the the onChannelState event.

Parameters:
reponse <Object> the server response

reponseHoraires

protected void reponseHoraires ( )
Receives the requested open hours and fires the onOpenHours event.

reponseRappeler

protected void reponseRappeler ( resp , request )
Call-back method called after rappeler().

Receives the response of call and delay services.

Parameters:
resp <Object> the response
request <Object> the request (attributes)

reponseSuivreAppel

protected void reponseSuivreAppel ( resp , attrs )
Call-back method called after suivreAppel().

Receives the response of lastEvent service and fires the onStatus or the onEnded event (never both).

The onStatus event is fired only when a new websurfer status or a new company agent status is received. Any duplicate status won't fire the onStatus event. With the exception of digit pressed statuses (on both sides) which always do fire the onStatus event.

Parameters:
resp <Object> the response
attrs <Object> the request attributes

serializeArrayReverse

private String serializeArrayReverse ( a )
Transforms an array of strings into a JSON string. The array is reversed while being serialized. This method does not support double quotes in input strings.
Parameters:
a <Array<String>> an array of strings
Returns: String
the reversed array serialized as JSON

suivreAppel

protected void suivreAppel ( )
Start following the current call status. It's unique ID must be in this.callId. This method is automatically called by reponseRappeler() when an immediate call-back request is accepted. Thus it should not be called directly. It is provided in the prototype in order to allow instance customization.

traiterErreur

protected void traiterErreur ( msg , exc , status , params )
Handle a call-back reject. Receives the response of call or delay services. This method is automatically called by reponseRappeler() when an call-back request is rejected. Thus it should not be called directly. It is provided in the prototype in order to allow instances customization.
Parameters:
msg <String> a message describing the error
exc <Object> the exception, containing a cause being a kind of error code
status <Object> the response
params <Object> the request attributes

useHttps

protected void useHttps ( https )
Force the use of HTTP or HTTPS queries.

This method has to be used instead of modifying the https config directly.

In standard use cases, you should not need calling this method. Because the https config is auto-configured, based on the current window URL.

Parameters:
https <Boolean> whether to force the use of HTTPS (if true) or HTTP (if false)

Events

onChannelState

onChannelState ( response , etatOuverture )
Fires when the channel state is received.

The server response is an object that contains these members:

  • codeCanal <String>: the queried channel code. It is the same as the canal config property.
  • estActif <Boolean>: whether the channel is active or not.
  • peutRecevoirAppel <Boolean>: whether the channel can receive calls (is under quota) or not (over quota).
  • estOuvert <Boolean>: whether the channel is open (in open hours at request time) or not.
  • estSature <Boolean>: whether the channel is overwhelmed (too many concurrent calls) or not.
  • etatOuverture <String>: the open status, which one of these 3 values
    • OUVERT: when in open hours (OPEN)
    • FERME: when out of open hours (CLOSED)
    • FERIE: when in open hours BUT an exceptionally closed day (HOLIDAY)
The digested channel status, is one of these values:
  • INACTIF: not active.
  • HORS_LIMITES: over quota.
  • SATURE: overwhelmed.
  • FERME: closed (i.e. out of open hours).
  • FERIE: holiday (in open hours).
  • OUVERT: open.
Parameters:
response <Object> the server response
etatOuverture <String> a digest channel status (recommended)

onCreate

protected static onCreate ( bouton )
Class event. Fires when an LnkWcb.Bouton instance is just created.
Parameters:
bouton <Object> the new instance

onDigit

onDigit ( status , params )
Fires when a received call status contains a pressed digit. The digit might have been pressed by the websurfer or the company agent.

Parameters are the same as those of the onStatus event.

This event does not shortcut the onStatus event which fires as it would normally. The difference is that this event fires on all received statuses with digit pressed. Even if duplicates, usually one per second. On the contrary, the onStatus event fires only when new statuses are received. is received.

Parameters:
status <Object> the response object
params <Object<Array<String>>> the request parameters

onEnded

onEnded ( status , params )
Fires when a immediate call ends, or when a delayed call is accepted. The final status (in status.status) might be "OK", or "OK" with a cause for the failure (in status.cause).

KO causes are:

  • Websurfer causes
    • MACHINE: websurfer phone is an answering machine
    • INABOUTI_INTERNAUTE: websurfer phone is wrong number or does not answer
    • INVERSE_INABOUTI_INTERNAUTE: same as above, but in reversed mode
    • RACCROCHE_INTERNAUTE_AVANT_AGENT: websurfer has hanged up before being bridged with a company agent
  • Technical causes
    • CAUSE_INCONNUE: unknown cause
Parameters:
status <Object> the response object
params <Object<Array<String>>> the request parameters

onError

private onError ( msg , exc , status , params )
Fires when a call-back request is rejected by the server.

You should not use this event. Prefer using onErrorDigest instead.

Parameters:
msg <String> a textual description of the error
exc <Object> the exception, containing a cause being a kind of error code
status <Object> the response object
params <Object<Array<String>>> the request parameters

onErrorDigest

onErrorDigest ( msgCode , errCode , status , params )
Fires when a call-back request is rejected by the server.

Provides value-added information about the error, such as a message code and an error code. Please refer to the documentation for details about those codes.

Message codes are:

  • userErrorTelephone: invalid phone number
  • userErrorDate: invalid date for delayed call
  • userErrorDuplicateCall: duplicate request
  • techError: technical error
When the forceFallbacks config is set to false (not recommended, and deprecated), then other message code might occur for fallbacks: debErrorBlocked, debErrorClosedHour, debErrorClosedDay, and debErrorOverwhelmed. You should never need these. They are listed here only for comprehensiveness.
Parameters:
msgCode <String> a message code for the error
errCode <String> an error code for the error
status <Object> the response object
params <Object<Array<String>>> the request parameters

onFallback

onFallback ( status , params )
Fires on a fallback condition.

This might be an error (when a call is rejected) or a KO ending (when a call ends with a "KO" final status), but you won't have to know because onEnded won't be fired, nor onErrorDigest, nor onError.

Parameters:
status <Object> the response object
params <Object<Array<String>>> the request parameters

onOpenHours

protected onOpenHours ( response )
Fires when the channel open hours are known.

The server response is an object that contains these members:

  • codeCanal <String>: the queried channel code. It is the same as the canal config property.
  • horairesOuverture <Array>: a list of open hours schedules, which are objects containing these members
    • debut: start of open schedule (websurfer time zone)
    • fin: end of open schedule (websurfer time zone)
    • debutHeureCanal: start of open schedule (channel time zone)
    • finHeureCanal: end of open schedule (channel time zone)

    An empty array means that the channel is never open.

    All hours are ISO compliant partial dates encoded as Strings. They contain the week day, the hours of day, and minutes of hour. For example, "-W-1T14:55" means Monday on 14:55 (2:55 PM). Hours are 24-hours based.

  • joursFeries <Array>: a list of holidays, which are objects containing this member
    • date: a partial date, which might be yearly repeatable

    An empty array means the channel has no exception to its weekly schedule.

    Dates are ISO compliant partial dates encoded as Strings. They contain the month of year, the day of month, and optionally a 4 digits year. For instance, {date: "2010-07-14"} means the 14th of July, 2010. And {date: "--08-15"} is the 15th of August, applicable every year.

Parameters:
response <Object> the server response

onPollStatus

protected onPollStatus ( attrs )
Fires just before a call status is polled from the server. Allows for tweaking the request attributes.
Parameters:
attrs <Object> the attributes of the server request to be sent

onSendCall

onSendCall ( arguments , attrs )
Fires just before a call-back request is sent to the server. Allows for tweaking the request attributes.

Very useful to start a spinner while the call is being processed.

Parameters:
arguments <Array> the arguments (converted to a real array) passed to rappeler()
attrs <Object> the attributes of the server request to be sent

onStatus

onStatus ( status , params )
Fires when some new call status is received (on any side).
  • The string tag in status.uStatus describes the websurfer status.
  • The string tag in status.aStatus describes the company agent status.
At least one of these statuses is new to the boutton—among all that have already been received while following the current call. And possibly both are new.

Status tags are one of the following:

  • INCONNU: before dialing
  • APPEL_EN_COURS: while dialing and ringing
  • MESSAGE_BIENVENUE (websurfer only): while the websurfer listen to the welcome message
  • MUSIQUE_ATTENTE: when music on hold is on
  • COMMUNICATION_EN_COURS: when line is up
  • COMMUNICATION_ETABLIE: when both lines are bridged together
  • TOUCHE_APPUYEE: when a key was pressed, with its value in status.uDigit or status.aDigit
Parameters:
status <Object> the response object
params <Object<Array<String>>> the request parameters

Configuration Attributes

backUrl - protected String

The current "WCB Extranet" backend base URL. The one currently in use.
Default Value: http://wcb.linkeo.com/extranet/bouton/

backUrlHttp - protected String

Standard URL of the "WCB Extranet" Back-Office server – HTTP.
Default Value: http://wcb.linkeo.com/extranet/bouton/

backUrlHttps - protected String

Secure URL of the "WCB Extranet" Back-Office server – HTTPS.
Default Value: https://wcb.linkeo.com/extranet/bouton/

canal - String

The channel code.

Refers to a channel configuration in the "WCB Extranet" back-office.

Default Value: null

forceFallbacks - private Boolean

Activate fallbacks (on errors or KO endings) even if none is set up in the channel setup (of the "WCB Extranet" Back-Office).

true by default here, which is the recommended value. Indeed fallbacks should be handled by web integration not controlled by server-side configuration.

Do not set it to false unless you really know what you are doing. This will revert to compatibility mode which is now deprecated.

Default Value: true

frontUrl - protected String

The current "WCB Frontal" backend base URL. The one currently in use.
Default Value: http://wcb.linkeo.com/wcbFrontal/services.do

frontUrlHttp - protected String

Standard URL of the "WCB Frontal" server – HTTP.
Default Value: http://wcb.linkeo.com/wcbFrontal/services.do

frontUrlHttps - protected String

Secure URL of the "WCB Frontal" server – HTTPS.
Default Value: https://wcb.linkeo.com/wcbFrontal/services.do

grabbedFormId - String

The HTML ID of some form to "grab".

null by default. If set to some "truthy" value, it enable the "form-grabbing" feature.

If enabled, the "grab" feature will collect the values of all fields in the form and send them along with any call-back request (as supplementary parameters). Multiple values in the form are not supported.

The "grab" feature will also collect window location and any window openers locations. These will be reversed and stored as JSON in the userUrls request attribute.

Default Value: null

https - protected Boolean

Whether to use HTTPS (if true) or HTTP (if false).

Only use this at creation time. To change this setting in live, call the useHttps() instead.

In standard use cases, you should not need modifying this setting, because it is auto-configured based on the current window URL.

Default Value: true if document.location.protocol is 'https:' at instanciation time, false otherwise

serverSideManagedFallbacks - private Boolean

Activate the (deprecated) compatibility mode in handling fallbacks.

false by default. Do not change it unless you know what you are doing.

Deprecated Fallbacks should be handled by web integration not controlled by server-side configuration.
Default Value: false

statusPollingTimeout - protected Number

The polling frequency when following call statuses. Expressed in milliseconds.
Default Value: 1000 (one second)

timeZone - protected String

The current websurfer timezone.

By default, this is set to the current websurfer time offset with LnkWcb.util.buildTimeZone(). This gives something like "GMT+02:00". If you get a better information (or ask it directly to the websurfer), then you can put any ID from this list of available time zones.

Default Value: the websurfer time offset, such as "GMT+02:00" for instance

validator - Function

A validation function for rappeler() method.

Arguments are those of the rappeler() method. Must return a boolean, true indicating the input is correct, false otherwise.

Default Value: an empty function that always returns true

Modules

Properties

Copyright © 2010 Linkeo.com All rights reserved.