view: intro
dependencies: css/intro.css
missing dependencies: none
downloads: intro.zip ccViewsSkel.zip ccViewsAll.zip
show: descriptionsourceappearance

				
<?php
/*
 * Copyright 2008-2009, Peter Rowntree. All Rights Reserved.
 * http://www.hdyn.com/mail/contact.php?addr=pr
 */
?>
<!-- depends: css/intro.css -->
<div class='introHead'>&#x2638; Introduction to CCViews &#x2638;</div>
<div class='introItems'>
  <p>CCViews is a parameterizable nested view loader with an optional global-scope function API.</p>
  <p class='subHead'>How to use CCViews</p>
  <p>Put ccViews.php and (optionally) ccViewsGSFAPI.php somewhere accessible to your PHP-enabled webserver, 
    create a folder called 'views' in the same directory, and &mdash;if you want to use
    the global-scope function API&mdash; include the following 
    2 lines in the PHP file that will act as a holder (see below for more about holders):</p>
  <code>require_once 'path/to/ccViewsGSFAPI.php'; //fs path; abs or rel to holder<br/>createViewsObject();</code>
  <p>To create a CCViews object directly, and not use ccViewsGSFAPI.php, you can use the static factory method CCViews::create():
  <code>require_once 'path/to/ccViews.php'; //fs path; abs or rel to holder
  <br/>$viewsOb=CCViews::create();</code></p>
  <p>Replace 'path/to/' with the actual filesystem path. That's it! createViewsObject() 
    creates a single global CCViews object (to use with the global-scope API),
    and both it and CCViews::create() can take 3 optional parameters (in order):</p>
  <ul>
    <li>a default associative array of GET parameters to use when there are no 'get' or 'post' data;</li>
    <li>an integer specifying the maximum view depth;</li>
    <li>a view-file extension to use instead of the default (should probably start with '.').</li>
  </ul>
  <p class='subHead'>Some characteristics of views (for everyone)</p>
  <ul>
    <li>must be in a folder called 'views', a sibling of the ccViews.php file;</li>
    <li>must have the view-file extension (currently '<?php echo $this->viewFileExtension; ?>');</li>
    <li>must be valid PHP, which, since PHP is a superset of HTML, can mean pure HTML;</li>
    <li>should expect all relative web and filesystem paths, including those of PHP includes, 
      to be relative to the 'holder'.</li>
    <li>should contain an HTML comment or a PHP block comment listing its dependencies, if any. The comment should have the following form.
      <code>/* depends: css/someCSSFile.css, js/someJSFile.js, etc. */</code></li>
  </ul>
  <p class='subHead'>Some characteristics of views (for programmers)</p>
  <ul>
    <li>can load sub-views by calling the API functions viewByIndex() or viewByName();</li>
    <li>are loaded by a CCViews method, so--
      <ul>
        <li>in the top-level scope of a view, '$this' is the CCViews object;</li>
        <li>globals need to be set using the helper functions setGlobal(), setGlobals(), or 
          after using the 'global' keyword, not just by assignment in the 
          top-level scope of a view (PHP function definitions in a view, however, 
          <i>will</i> have global scope).</li>
      </ul>
    </li>
  </ul>
  <p class='subHead'>The URL syntax</p>
  <p>Since the views can be nested, and can be specified in the URL's query string,
    understanding the URL syntax is important if you want to use viewByIndex().</p>
  <p>The URL syntax is as follows.</p>
  <p>holder.php?d0=group[0];group[1];...group[n]&amp;d1=...&amp;dn=...&amp;trace</p>
  <p>where:</p>
  <p>holder.php is the file that holds the views (the 'holder', e.g. this page);</p>
  <p>all parameters are optional;</p>
  <p>dx, means 'depth' x (the depth of the groups, starting at depth 0);</p>
  <p>each group has the form:</p>
  <p>viewName[0],viewName[1],...viewName[n], where viewName[i] is 
    the name of a view file in the 'views' folder, without its extension;</p>
  <p>each group represents a view&mdash;that has children (subviews)&mdash;in the depth 
    <i>above</i> that depth;</p>
  <p>trace means show the trace tree (tracing can also be forced by setting $g_alwaysDoTrace in ccViews.php).</p>
  <p class='subHead'>Each trace item has the form:</p>
  <p>|groupIndex[viewIndex]:viewName</p>
  <p>or, if the view is loaded using viewByName():</p>
  <p>|name: viewName</p>
  <p>where '|' indicates the depth.</p>
  <p class='subHead'>The CCViews Server</p>
  <p><a href='ccViewsViewer.php'>The CCViews Viewer</a> (ccViewsViewer.php) works with the CCViews Server (ccViewsServer.php) to let you share your
  views with others. It requires that the 'zip' utility (available at <a href='http://www.info-zip.org/'>info-zip.org</a>)
  be callable from PHP via exec().</p>
  <p></p>
</div>
☸ Introduction to CCViews ☸

CCViews is a parameterizable nested view loader with an optional global-scope function API.

How to use CCViews

Put ccViews.php and (optionally) ccViewsGSFAPI.php somewhere accessible to your PHP-enabled webserver, create a folder called 'views' in the same directory, and —if you want to use the global-scope function API— include the following 2 lines in the PHP file that will act as a holder (see below for more about holders):

require_once 'path/to/ccViewsGSFAPI.php'; //fs path; abs or rel to holder
createViewsObject();

To create a CCViews object directly, and not use ccViewsGSFAPI.php, you can use the static factory method CCViews::create(): require_once 'path/to/ccViews.php'; //fs path; abs or rel to holder
$viewsOb=CCViews::create();

Replace 'path/to/' with the actual filesystem path. That's it! createViewsObject() creates a single global CCViews object (to use with the global-scope API), and both it and CCViews::create() can take 3 optional parameters (in order):

  • a default associative array of GET parameters to use when there are no 'get' or 'post' data;
  • an integer specifying the maximum view depth;
  • a view-file extension to use instead of the default (should probably start with '.').

Some characteristics of views (for everyone)

  • must be in a folder called 'views', a sibling of the ccViews.php file;
  • must have the view-file extension (currently '.thtml');
  • must be valid PHP, which, since PHP is a superset of HTML, can mean pure HTML;
  • should expect all relative web and filesystem paths, including those of PHP includes, to be relative to the 'holder'.
  • should contain an HTML comment or a PHP block comment listing its dependencies, if any. The comment should have the following form. /* depends: css/someCSSFile.css, js/someJSFile.js, etc. */

Some characteristics of views (for programmers)

  • can load sub-views by calling the API functions viewByIndex() or viewByName();
  • are loaded by a CCViews method, so--
    • in the top-level scope of a view, '$this' is the CCViews object;
    • globals need to be set using the helper functions setGlobal(), setGlobals(), or after using the 'global' keyword, not just by assignment in the top-level scope of a view (PHP function definitions in a view, however, will have global scope).

The URL syntax

Since the views can be nested, and can be specified in the URL's query string, understanding the URL syntax is important if you want to use viewByIndex().

The URL syntax is as follows.

holder.php?d0=group[0];group[1];...group[n]&d1=...&dn=...&trace

where:

holder.php is the file that holds the views (the 'holder', e.g. this page);

all parameters are optional;

dx, means 'depth' x (the depth of the groups, starting at depth 0);

each group has the form:

viewName[0],viewName[1],...viewName[n], where viewName[i] is the name of a view file in the 'views' folder, without its extension;

each group represents a view—that has children (subviews)—in the depth above that depth;

trace means show the trace tree (tracing can also be forced by setting $g_alwaysDoTrace in ccViews.php).

Each trace item has the form:

|groupIndex[viewIndex]:viewName

or, if the view is loaded using viewByName():

|name: viewName

where '|' indicates the depth.

The CCViews Server

The CCViews Viewer (ccViewsViewer.php) works with the CCViews Server (ccViewsServer.php) to let you share your views with others. It requires that the 'zip' utility (available at info-zip.org) be callable from PHP via exec().