Gyroscope / Building a List View

The list view is usually invoked by clicking on a menu icon. For example, clicking on the "landlords" icon in the sample app displays a list of landlords on the left.

A fully functional list view performs the following actions:

sets the title of the left panel;
allows auto-complete search;
allows pagination;
loads related JavaScript functions (client handlers);
displays the record list

The number of list views in a Gyroscope application is predefined. In settings.php, the $viewcount variable sets the view count.

Each list view has an ID. For example, "lv0", "lv1", etc.

When adding more views, make sure there're enough list view containers in index.php.

The last view container is reserved for displaying lookups, so the view count is usually the number of entities + 1. When in doubt, allocate more views than needed.

Starting v4.4, the list view containers are automatically generated by the viewcount in settings.php.

Set up a template app. We'll gradually transform a blank application into the sample application.

Locate the section, in index.php, where the menu icons are defined:

The acronym tag gives a tool tip when the mouse hovers over the icon. The hintstatus function displays the same help text at the bottom of the view port.

New in v4.4, the toolbar icons are configured in a shared object in settings.php.

$toolbaritems=array(
array('title'=>'List 1','viewindex'=>0,'icon'=>'img-big1'),
array('title'=>'List 2','viewindex'=>1,'icon'=>'img-big2'),

array('type'=>'break'), // divider

//hide in mobile view
array('title'=>'A','viewindex'=>1,'icon'=>'img-big1',
'noiphone'=>1),

//custom action
array('title'=>'B','viewindex'=>1,'icon'=>'img-big1',
'action'=>"alert('custom action');"),

//custom action without list view
array('title'=>'C','viewindex'=>null,'icon'=>'img-big1',
'action'=>"alert('custom action');"),

//custom entry
array('type'=>'X',
'desktop'=>'D','iphone'=>'<div class="menuitem">M</div>'),
);

To display a list view, call the showview function with its ID. This function subsequently calls the slvX service handler.

For example, showview(2) sends the slv2 message to myservices.php.

In myservices.php, add the list view handler:

switch($cmd){
// ...
case 'slv0':
include 'icl/listlandlords.inc.php';
listlandlords();
break;
// ...
}

Important: in iPhone mode, showview must be called with the force parameter in the toolbar. Otherwise the list view will not take over the screen in portrait mode:

showview(1,null,true);

Create icl/listlandlords.inc.php with the following content:

<?php function listlandlords(){ echo 'Landlord List'; }

Now load the app in a browser and click on the menu icon. Tada!
Next we'll display "Landlords" on the list view title:

<?php
function listlandlords(){
?>
<div class="section">
Landlord List
</div>
<script>
gid('tooltitle').innerHTML='<a>Landlords</a>';
</script>
<?
}

The "section" class is predefined in gyscope.css. It gives the content some margin.

Next we'll pull some records from the database. Import the sample database. You may use the sample app as an editing interface to add new records.

<?php
function listlandlords(){
global $db;
$query="select * from landlords.*, persons.* ";
$query.=" from landlords, persons where ";
$query.=" landlords.personid=persons.personid ";
$query.=" order by persons.fname ";
?>
<div class="section">
<?
$rs=sql_query($query,$db);
while ($myrow=sql_fetch_array($rs)){
$llid=$myrow['llid'];
$llname=$myrow['fname'].' '.$myrow['lname'];
?>
<div class="listitem">
<?echo $llname;?>
</div>
<?
}//while
?>
</div>
<script>
gid('tooltitle').innerHTML='<a>Landlords</a>';
</script>
<?
}//func

Next we'll add the hooks for displaying landlord details.

In the script section, detect whether a JavaScript function showlandlord has been loaded. If not, load the JavaScript file that defines all the landlord related handlers:

ajxjs(self.showlandlord, 'landlords.js');

In landlords.js, add the following lines:

showlandlord=function(llid,llname){
addtab('landlord_'+llid, llname,'showlandlord&llid='+llid);
}

In myservices.js, add a server-side handler:

switch ($cmd){
// ...
case 'showlandlord':
include 'icl/showlandlord.inc.php';
showlandlord();
break;
// ...
}

Create icl/showlandlord.inc.php with the following content for now:

<?php
function showlandlord(){
echo "Landlord details";
}

Now back in listlandlords.inc.php, we link the showlandlord event with each record:

In practice, we should guard against apostrophes in names:

//...
$dbllname=str_replace("'","\'",$llname);
?>
<div class="listitem">
<a onclick="showlandlord(<?echo $llid;?>, '<?echo $dbllname;?>');">
<?echo $llname;?>
</a>
</div>
<?
}//while