List Viewers have options at the top you can customize. Here's an example with all the available options. Note that the code generator will only the options you need, so your viewer code might be much shorter.

Note that for the most part you can just cut and paste the generated code and don't need to know what these options are. For advanced users, though, they're documented here.

<?php
  /* STEP 1: LOAD RECORDS - Copy this PHP code block to the TOP of your page BEFORE anything else. */
  require_once "/www/htdocs/cmsb/lib/viewer_functions.php";

  list($newsRecords, $newsMetaData) = getRecords(array(
    'tableName'          => 'news',     // REQUIRED, error if not specified, tableName is prefixed with $TABLE_PREFIX
    'limit'              => '3',        // optional, defaults to blank (specifies max number of records to show)
    'offset'             => '1',        // optional, defaults to blank (if set but no limit then limit is set to high number as per mysql docs)
    'perPage'            => '1',        // optional, number of records to show per page - loads page number from url as viewer.php?page=1
    'allowSearch'        => true,       // optional, defaults to true, adds search info from query string
    'requireSearchMatch' => false,      // optional, don't show any results unless search keyword submitted and matched
    'loadUploads'        => true,       // optional, defaults to true, loads upload array into upload field
    'loadCreatedBy'      => true,       // optional, defaults to true, adds createdBy. fields for created user
    'loadListDetails'    => true,       // optional, defaults to true, adds $details with prev/next page, etc info
    'useSeoUrls'         => false,      // optional, use SEO urls, defaults to no
    'where'              => '',         // optional, defaults to blank
    'orWhere'            => '',         // optional, adding " OR ... " to end of where clause
    'orderBy'            => '',         // optional, defaults to table sort order if undefined
    'joinTable'          => 'tablename',// optional, add results from another table that are created by the same users
    'debugSql'           => false,      // optional, display SQL query, defaults to no
  ));
?>

All of these settings are automatically generated and generally don't need to be modified. Here's what each of them do.

require_once ".../lib/viewer_functions.php";

This tells the viewer where the program is located. The Viewer Generator automatically figures out the right path. If you move files around on your server you'll need to update this page.

tableName

This is the MySql database tablename that the viewer will load records from. If you change the Table Name (in Admin > Section Editors), you'll need to update it here as well.

limit

The "limit" option lets specify the maximum number of records to show. Setting 'limit' => '3', would only show the first 3 records. By default all records will be shown.

offset

The "offset" option lets you skip a number of records. If you wanted to show the 2nd and 3rd result you'd use an offset of 1 and a limit of 2.

perPage

This specifies how many records to show per page when you displaying pages of results with previous and next links. When using this option the current page number is loaded from the 'page' value in the url query string. Example: viewer.php?page=3

allowSearch

By default automatic searching is enabled. If you have multiple viewers on one page you may want some viewers to always show all results and ignore search keywords. To do that set this value to false.

requireSearchMatch

By default viewers will show all matching records even if there is no search keywords. This means searching for blank "" or accessing a viewer directly will show all records. You can set this option to true to prevent this. When set to true the viewer won't show any results unless they match a search keyword and a non-blank search keyword was entered.

loadUploads

By default uploads are loaded so they can be displayed (see Displaying uploads). If you have an upload field, but you're not displaying it in your viewer, you can set this to false to prevent uploads from being loaded and reduce the number of database queries required.

loadCreatedBy

By default the account information from the user who created a record are added to the results as createdBy.* (such as createdBy.email, createdBy.fullname, etc). This makes it easy to display author information. If this isn't needed you can disable this feature by setting this value to false. This will reduce the number of database queries required to display the page.

loadListDetails

The second variable returned by getRecords() ($newsMetaData in the example) contains inforation about the total number of results, page links, etc. If you don't need this information you can set this to false to avoid loading it.

useSeoUrls

When set to true this enables search engine friendly urls for page links. All the links created by the program are search engine friendly, but the useSeoUrls use a / instead of a ?. They look like this:

articlePage.php/Hello_World-1/
articleList.php/page-1/
articleList.php/color-blue/page-1/

instead of this:

articlePage.php?Hello_World-1/
articleList.php?page=1
articleList.php?color=blue&page-1

This is not supported on all web servers.

where

If you are comfortable with MySQL this field lets you specify your own custom MySQL WHERE clause. Please note that this WHERE clause is in addition to any automatic search parameters that are being used (see Search Engines for more details).

orWhere

If you are comfortable with MySQL this field lets you specify your own custom MySQL WHERE clause that gets added AFTER the search and 'where' conditions as an " OR ... " condition. You'd use this advanced feature if you wanted to show results that matched a search query OR something else.

orderBy

By default viewers use the sorting order specified in "Admin > Section Editors > Sorting". But you can override that and specify a different sorting order if needed. The orderBy field is a comma seperated list of fields used to sort the list of records (example: author, title). Here are some common special sorting commands:

fieldname DESC - The suffix "DESC" will sort the field in descending order (i.e. backwards). Added to a date fieldname, this will sort the newest records first.
fieldname+0 - sorts the field as a numeric value. Use this suffix if you are sorting numbers, but the sorting is coming out in a strange order (1, 2, 20, 21, 3, 4, 45, etc.).
RAND() - Sorts the results in a random order. The results will be randomized every time the viewer is loaded.

Tip: orderBy is actually just a standard MySQL ORDER BY clause. If you are comfortable with MySql you can whatever conditions you might need here.

joinTable (advanced)

This option loads records from another section that have the same creator. If you had a section for 'listings' and a section for 'homepage' and your 'listings' viewer had joinTable => 'homepage' then for every listing displayed it would load the first homepage that was created by the same user and make those fields available as homepage.*

debugSql (advanced)

This is an advanced feature for troubleshooting. If set to true the viewer will output all the SQL queries being used as text before running them.


Copyright © 1999-2024 interactivetools.com, inc.