3.0.4/doc/src/DevelopersGuide/inspector.xml

<!-- $Id$ -->
<!--
   Copyright 2004 The Apache Software Foundation
  
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

  <chapter id="inspector">
    <title>The Tapestry Inspector</title>
    <para>
Tapestry includes a powerful tool: the Inspector, which reveals the construction 
of a running Tapestry application. 
</para>
    <para>
The &InspectorButton; component is used to include a link that 
launches the Inspector.  This is typically included in the navigational border of an 
application, so that it is available to the developer from any page.  The 
Inspector itself is a page that is provided by the framework and available to 
any Tapestry application.
</para>
    <section id="inspector.spec">
      <title>Specification View</title>
      <figure>
        <title>Inspector - Specification View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Inspector-Spec.jpg" format="JPG"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>
The Inspector allows the developer to see how the page is constructed.  
It reveals the page's specification, a list of embedded components within the page, 
the page's HTML template and more.
</para>
      <para>
It is possible to dig down and see the same information for 
any component within the page.
</para>
    </section>
    <section id="inspector.template">
      <title>Template View</title>
      <figure>
        <title>Inspector - Template View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Inspector-Template.jpg" format="JPG"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>
The template view shows the HTML template for the component.  Within the template,
component references are links that "dig down" into their template (if they have one).
</para>
    </section>
    <section id="inspector.properties">
      <title>Properties View</title>
      <figure>
        <title>Inspector - Properties View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Inspector-Properties.jpg" format="JPG"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>
The properties view shows the persistent properties for the page and any components on the page.
</para>
    </section>
    <section id="inspector.engine">
      <title>Engine View</title>
      <figure>
        <title>Inspector - Engine View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Inspector-Engine.jpg" format="JPG"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>
The engine view shows information about the running engine instance, including its name and class.
</para>
      <para>
Not shown in the figure is the serialized state of the application engine (in a hex dump format) and a
long display of all the request cycle information (the same information produced when an 
uncaught exception is thrown).
</para>
    </section>
    <section id="inspector.logging">
      <title>Logging View</title>
      <figure>
        <title>Inspector - Logging View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Inspector-Logging.jpg" format="JPG"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>
The final tab allows control of the logging behavior of the application.  It allows the logging level
for any category to be set, and allows new categories to be created.
</para>
    </section>
  </chapter>