Gyroscope / Tab Functions

Gyroscope uses keys to uniquely identify each tab, so that the same record view is opened only once.

Tab keys are usually mapped to record IDs in the database. For example, "tenant_17" is the tab key for the tenant record whose record ID is 17. The tab for creating a new tenant is simply "tenant_new". This ensures that only one new tenant tab is open at any time.

Four tab operations are defined in tabs.js.

addtab (key, title, params, loadfunc)
reloadtab (key, title, params, loadfunc)
showtab (key)
closetab (key)

To display the record details of Tenant #23 in a tab, use the addtab function:

addtab ('tenant_23', 'John Smith', 'showtenant&tenantid=23');

In the above example, tenant_23 is the key, and the display title for the tab is "John Smith". A server-side handler message "showtenant" is sent with the parameter tenantid=23.

In practice, the ID value and title are dynamically generated:

addtab ('tenant_<?echo $tenantid;?>',
'<?echo $tenantname;?>',
'showtenant&tenanted=<?echo $tenantid;?>');

The loadfunc parameter is optional; it points to a JavaScript function that is called when the tab content is successfully loaded.

addtab('tenant_new', 'tenant_new', 'newtenant',
function(){
gid('tenant_fname_new').focus();
}
);

If a tab is already displayed, addtab will exit without sending a server request; if a tab is not yet loaded, reloadtab won't load the tab. We can combine these properties to force reload a tab, present or not:

reloadtab ('tenant_23', 'John', 'showtenant&tenantid=23');
addtab ('tenant_23', 'John', 'showtenant&tenantid=23');

It's important to call reloadtab before addtab as their omission conditions cancel each other out, and their active functions complement each other.

Starting Version 3.2, the add and reload tab functions support extended features:

addtab (key, title, params, loadfunc, data, opts)
reloadtab (key, title, params, loadfunc, data, opts)

All XHR requests are sent via POST, and the data parameter carries the POST data if supplied.

The opts argument is an optional array.

As of 3.2, the tab system supports two special flags:

noclose: remove the close icon from the tab
newkey: assign a new tab key during tab reload

An example:

reloadtab('welcome','Welcome','wk',null,null,
{noclose:true, newkey:'welcome_1234'};

In previous versions of Gyroscope (<3.2), creating a new record involved closing a tab and opening a new one, using a blocking XHR call. The rekey function enables record creation with the reloadtab function, which supports POST and asynchronous loading.

Starting 5.9.1, the rekey parameter is dropped in favor of server response header. Record adders should contain the following lines:

header('newrecid:'.$newid);
header('newkey:client_'.$newid);

Server header response can also override the tab title:

header('newtitle: Test');

In addition, reloadtab detects the apperror header. If the error is present, the tab reload will abort without losing its current content.