Drop Shadow

Focusing

Only show some fields

By default, when a visitor focuses on an item from a list, the plug-in will display all data from the table. If you don’t want that, you can specify which fields get shown during a focus, or detail, page:

<? $db->focusSelect($displayFields); ?>

It works just like $db->select($displayFields); except that it only modifies the fields displayed during an auto-focus.

Focus on categories of data

The plug-in can also allow focusing in on other columns besides the ID field. You need to tell the plug-in which fields are allowed to be linked to a search on themselves. You’ll usually want to limit this to fields which contain data that repeats throughout multiple rows.

<? $db->focusFields($displayFields); ?>

Each of the fields in the list will be linked to a search on the data in that field. If, for example, you have a column for “city”, this will allow your viewers to click on a city and see every row pertaining to that city.

If you are joining to other tables, and they contain a column you want to focus on but which has the same name as a column in the main table; or if you are renaming a column in a callback; you can provide a list of equivalents.

<? $db->focusFields('category', array('category'=>'categories.title')); ?>

This will cause the system to focus the 'category' column on the column “title” in the table “categories”.

Do not automatically focus

The system will automatically recognize if a search results in only one record, and it will focus on that record. If you want to force the system to not automatically focus when there is only one record displayed, use “noAutoFocus()”.

<? $db->noAutoFocus(); ?>

Do not show a focus link

If you don’t want to focus on the entire record, use “noFocusLink()”.

<? $db->noFocusLink(); ?>

Focus to a different page

The default behavior is for the plug-in to provide the focus automatically for you. But if you wish to send focuses to a different page, use

<? $db->focusDestination('url'); ?>

The plug-in will automatically add “?_focus=ID” to the end of the URL (or “&focus=ID” if the url already contains a question mark).

If you need to use a different field name instead of _focus, specify that as the second item to the method:

<? $db->focusDestination('url', 'id field name'); ?>

You may also need to send other data from the record to the focus page. You can use customFocusKey() to list the fields that need to be sent. They will be sent with their field name.

<? $db->focusDestination('http://www.example.com/showPerson'); $db->customFocusKey('Last_Name'); ?>

Or, if you need to send more than one field over:

<? $db->focusDestination('http://www.example.com/showPerson/'); $db->customFocusKey(array('Last_Name', 'First_Name', 'Birthday')); ?>

This might generate a URL like:

http://www.example.com/showPerson/?_focus=66&Last_Name=Flintstone&First_Name=Fred&Birthday=19950231

Require a focus link

By default, the system does not show a focus link if the row display shows all columns. If you plan on doing something else during a focus, however, you may want to display the focus link even though all columns are already visible. The “forceFocusLink()” method will force the focus link to show even if it isn’t obviously necessary.

<? $db->forceFocusLink(); ?>

Are we focused?

If you want to know if the system has focussed on a single item, you can use “focussed()” to get either false or the ID of the row it has focussed on.

If you want to force the system to unfocus, use “unFocus()”. You might use this to display information from a second table after the focussed table. When you use unFocus(), it will automatically reset _page to empty so that the second table does not think it needs to show a page of data that most likely doesn’t even exist.

For example, this provides a sub-display of other sites attached to an account:

<? IF ($view->focussed()): IF ($account = $view->latest('account')): echo "<h2>Other sites on this account</h2>\n"; $view->unfocus(); $view->noAutoFocus(); $view->unjoin('Accounts'); $view->addRestriction(array('account'=>array('operator'=>'is', 'value'=>$account))); $view->displayList(array('URL')); ENDIF; ENDIF; ?>