=============================
Developer Mode User Interface
=============================

The developer mode of the user interface is intended to help SchoolTool
developers and people using SchoolTool as a development platform to debug
their code and find documentation as quickly as possible. To start, open the
SchoolTool site in your browser

    >>> browser = Browser('manager', 'schooltool')

The developer mode should add an introspect button to the action menu:

    >>> def print_actions(contents):
    ...     print
    ...     for item in analyze.queryHTML('//div[@class="content-nav"]', contents):
    ...         print item
    >>> print_actions(browser.contents)
    <BLANKLINE>
    ...
    <div class="content-nav">
      <a href="http://localhost/calendar/@@introspector.html">Introspect</a>
    </div>

And some additional items to the Manage tab:

    >>> def print_navigation_links(contents):
    ...     print
    ...     for item in analyze.queryHTML('//a[@class="navigation_header"]', contents):
    ...         print item
    >>> browser.getLink('Manage').click()
    >>> print_navigation_links(browser.contents)
    <BLANKLINE>
    ...
    <a class="navigation_header" href="http://localhost/++etc++site/default/RootErrorReportingUtility">Errors</a>
    <a class="navigation_header" href="http://localhost/++apidoc++/@@index.html">API Docs</a>
    <a class="navigation_header" href="http://localhost/@@sampledata.html">Sample data</a>
    <a class="navigation_header" href="http://localhost/@@setupdata.html">Setup data</a>...

Note that we only see the developer tools here, because these tests are run
with the developer mode turned on. Commonly, the developer mode can be
controlled using ``schooltool.conf``'s ``devmode`` switch. Simply add
``devmode on`` to your ``schooltool.conf`` file to turn on the developer's
mode.


Error Reporting
---------------

Even though error reporting is always available, it is usually not easily
accessible via the Web UI. By clicking on the `Errors` menu option

    >>> browser.getLink('Errors').click()

you are brought to the root error reporting utility.

Here you can configure the utility and view errors:

    >>> print browser.contents
    <BLANKLINE>
    ...
    ...<a href="http://localhost/++etc++site/default/RootErrorReportingUtility/@@configure.html">Configure</a>...
    ...<a href="http://localhost/++etc++site/default/RootErrorReportingUtility/@@index.html">Error List</a>...
    ...

In the configuration

    >>> browser.getLink('Configure').click()

you can specify how many exceptions to keep, whether to copy the errors to the
event log and what exceptions can be ignored:

    >>> keep_entries = browser.getControl(name='keep_entries')
    >>> keep_entries.value
    '20'
    >>> keep_entries.value = '30'

    >>> copy_to_zlog = browser.getControl(name='copy_to_zlog')
    >>> copy_to_zlog.value
    False
    >>> copy_to_zlog.value = True

    >>> ignored_exceptions = browser.getControl(name='ignored_exceptions:lines')
    >>> ignored_exceptions.value
    'Unauthorized'
    >>> ignored_exceptions.value += '\nNotImplementedError'

    >>> browser.getControl('Save Changes').click()

    >>> browser.getControl(name='keep_entries').value
    '30'
    >>> browser.getControl(name='copy_to_zlog').value
    True
    >>> print browser.getControl(name='ignored_exceptions:lines').value
    Unauthorized
    NotImplementedError

Let's now make sure that we can get to the error list. First let's create a
``NotFound`` error:

    >>> browser.open('http://localhost/foo')
    Traceback (most recent call last):
    ...
    NotFound: Object: <schooltool.app.app.SchoolToolApplication object at ...>, name: u'foo'


    Now let's see the report:

    >>> browser.open('http://localhost/'
    ...              '++etc++site/default/RootErrorReportingUtility')
    >>> browser.getLink('Error List').click()
    >>> print browser.contents
    <BLANKLINE>
    ...
    <tr>
      <td valign="top" nowrap="nowrap">
        <span>...</span>
      </td>
      <td>
        <span>unauthenticated, sb.person.manager, SchoolTool Manager, </span>
      </td>
      <td valign="top">
        <a href="showEntry.html?id=...">
          <span>NotFound</span>:
          <span>Object: &lt;schooltool.app.app.SchoolToolApplication ...</span>
        </a>
      </td>
    </tr>
    ...


The Introspector
----------------

The introspector allows you to look at the current object, without any
security constraints. The actual functionality of the introspector is part of
the Zope 3 core and is simply "repackaged" for SchoolTool.

The first step is to get to the object we would like to
introspect. For example, let's see what the SchoolTool Manager looks
like. We can open the introspector using the Developer Tools menu in
the top-right corner:

    >>> browser.open('http://localhost/persons/manager/@@introspector.html')

Let me explain some of the features now. The headline gives you the class of
the object, followed by the name:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <h1>
      Object Introspector:
      <a href="...person/Person/index.html">schooltool.person.person.Person</a>
      ( manager )
    </h1>
    ...

Below the title is a link to the parent:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <em>
      Parent:
      <a href=" http://localhost/persons/@@introspector.html">
        persons
      </a>
    </em>
    ...

The probably most important information that the introspector can give a
developer, are the directly provided interfaces; usually there are none, as in
this case:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <h2>Directly Provided Interfaces</h2>
    <div class="indent">
      <div>
        No interfaces are directly provided.
     </div>
    </div>
    ...

The following sections "Provided Interfaces", "Bases", "Attribute/Properties",
and "Methods" are simply taken from the class documentation of the apidoc,
with the exception of the attribute and property values, which are the actual
values on the object.

The introspector also allows you to see the mapping or sequence items of the
object, if it is a mapping or sequence, respectively. Since the `Person`
object is neither, those sections are not available in our example.

The final section of the introspector shows you a list of annotations, if they
are inspectable. Since the attribute annotations are inspectable, we can see a
range of annotation keys and their values:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <h2>Annotations</h2>
    <div class="indent">
      <ul class="attr-list">
        <li>
          <b>
            <code>'schooltool.app.PersonPreferences'</code>
          </b>
          <br />
          <a href="++annotations++schooltool.app.PersonPreferences/@@introspector.html">
            <code>&lt;schooltool.person.preference.PersonPreferences object at ...&gt;</code>
          </a>
            (<span>type:</span>
            <a href="http://localhost/++apidoc++/Code/schooltool/person/preference/PersonPreferences/index.html">
              <code>PersonPreferences</code></a>)
        </li>
    ...

The best part about it is that you can usually click on the annotation value
to inspect it even further:

    >>> browser.getLink('schooltool.person.preference.PersonPreferences').click()

And now it starts all over again:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <h1>
      Object Introspector:
      <a href=".../index.html">schooltool.person.preference.PersonPreferences</a>
      ( preferences )
    </h1>
    <em>
      Parent:
      <a href=" http://localhost/persons/manager/@@introspector.html">
        manager
      </a>
    </em>
    ...

That's it. Since the code should allow you to inspect annotations, as well as
mapping and sequence items as deep as you wish, you can gain a lot of insight
of the functionality of SchoolTool by simply "browsing" the objects.


API Documentation
-----------------

The SchoolTool API Documentation is a customized version of the regular Zope 3
API documentation. Some features are removed, others added. But let's have a
look.

    >>> browser.getLink('Manage').click()
    >>> browser.getLink('API Docs').click()

We can now look at the module list:

    >>> browser.getLink(url='modulelist.html').click()

The modules available in the SchoolTool API documentation are:

    >>> browser.getLink('Interfaces')
    <Link text='Interfaces' url='.../++apidoc++/Interface/@@menu.html'>
    >>> browser.getLink('Code')
    <Link text='Code' url='.../++apidoc++/Code/@@menu.html'>
    >>> browser.getLink('Book')
    <Link text='Book' url='.../++apidoc++/Book/schooltool/@@menu.html'>

You can also access the user preferences that are specific to the API
documentation:

    >>> browser.getLink('User Preferences').click()
    >>> browser.getLink('Interface Details').click()

On the main contents frame of the apidoc now appears a long list of options
that specify the detail level you will see by default in the interface details
screen.

We can, for example, turn on the "Extended Browser Views" option, which is
turned off by default:

    >>> browser.getControl('Extended Browser Views').selected
    False
    >>> browser.getControl('Extended Browser Views').click()
    >>> browser.getControl('Change').click()

So now that we know how to change the preferences, let's have a detailed look
at the various documentation modules:


Interfaces
~~~~~~~~~~

The interfaces documentation module let's you search through all registered
SchoolTool interfaces. Zope 3 interfaces are purposefully excluded:

    >>> browser.open('http://localhost/')
    >>> browser.getLink('Manage').click()
    >>> browser.getLink('API Docs').click()
    >>> browser.getLink(url='modulelist.html').click()
    >>> browser.getLink('Interfaces').click()

You are now presented with a menu, where you can search for various
interfaces. Let's search for the devmode interfaces:

    >>> browser.getControl(name='search_str').value = 'schooltool'
    >>> browser.getControl('Find').click()

When the screen returns we should see our devmode layer and skin interface:

    >>> print browser.contents.strip()
    <!DOC...
    ...
    <div>
      ...
      <div>
        <a href="./schooltool.calendar.interfaces.ICalendar/index.html"
           target="main">st.calendar.interfaces.ICalendar</a>
      </div>
      ...
    </div>
    ...

You can also see how "schooltool" is abbreviated as "st" to make the name
shorter. Clicking on one of those results will give you the typical interface
details screen:

    >>> browser.getLink('st.calendar.interfaces.ICalendar').click()
    >>> browser.contents
    '...schooltool.calendar.interfaces.ICalendar...'


Code
~~~~

Similar to the interfaces, you can search the SchoolTool source code for
classes of a particular name.

    >>> browser.open('http://localhost/')
    >>> browser.getLink('Manage').click()
    >>> browser.getLink('API Docs').click()
    >>> browser.getLink(url='modulelist.html').click()
    >>> browser.getLink('Code').click()

Again, searching by the term "devmode" gives us multiple results:

    >>> browser.getControl(name='path').value = 'devmode'
    >>> browser.getControl('Find').click()
    >>> print browser.contents.strip()
    <!DOC...
    ...
    <div>
      ...
      <a href=".../++apidoc++/Code/schooltool/devmode/apidoc/BookMenu/"
         target="main">st.devmode.apidoc.BookMenu</a>
      <a href=".../++apidoc++/Code/schooltool/devmode/apidoc/CodeMenu/"
         target="main">st.devmode.apidoc.CodeMenu</a>
      <a href=".../++apidoc++/Code/schooltool/devmode/apidoc/InterfaceMenu/"
         target="main">st.devmode.apidoc.InterfaceMenu</a>
      ...
    </div>
    ...

Again, "schooltool" is collapsed to "st" and the documentation comes right up
when clicking a link:

    >>> browser.getLink('st.devmode.apidoc.InterfaceMenu').click()
    >>> browser.contents
    '...schooltool.devmode.apidoc.InterfaceMenu...'

Book
~~~~

The book is a collection of many text documentation files of the SchoolTool
project.

    >>> browser.open('http://localhost/')
    >>> browser.getLink('Manage').click()
    >>> browser.getLink('API Docs').click()
    >>> browser.getLink(url='modulelist.html').click()
    >>> browser.getLink('Book').click()

It is really the section of the entire apidoc book. The menu provides you with
a tree-based outline. One of the chapters is "Calendar", so let's have a look:

    >>> browser.getLink('Calendar', url="calendar/show.html").click()
    >>> browser.contents
    '...SchoolTool calendaring library...'


Sample Data
-----------

SchoolTool also features a data generator, which will fill your SchoolTool
instance with a lot of random data, which is perfect for performing and
advanced functional testing. So let's have a look:

    >>> browser.open('http://localhost/')
    >>> browser.getLink('Manage').click()
    >>> browser.getLink('Sample data').click()

You are now presented with a screen in which you can choose a random seed key
for the data and a "Generate" button. The purpose of the seed is that you can
reproduce a particular set of generated data. Since the generation process
takes a very long time, I am refraining from a demonstration.
