python-schooltool 1:2.1.0-0ubuntu1 / usr / share / pyshared / schooltool / devmode / apidoc.txt

===============
Developer Tools
===============

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>
    ...

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.

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 Browser' url='.../++apidoc++/Code/@@menu.html'>
    >>> browser.getLink('Book')
    <Link text='Book' url='.../++apidoc++/Book/@@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 = 'ICalendar'
    >>> browser.getControl('Find').click()

When the screen returns we should see our interface:

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

Clicking on one of those results will give you the typical interface
details screen:

    >>> browser.getLink('schooltool.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 "calendar" gives us multiple results:

    >>> browser.getControl(name='path').value = 'calendar'
    >>> browser.getControl('Find').click()
    >>> print browser.contents.strip()
    <!DOC...
    ...
    <div>
      ...
      <a href=".../++apidoc++/Code/schooltool/calendar/recurrent/DailyRecurrenceRule/"
         target="main">schooltool.calendar.recurrent.DailyRecurrenceRule</a>
      <a href=".../++apidoc++/Code/schooltool/calendar/recurrent/MonthlyRecurrenceRule/"
         target="main">schooltool.calendar.recurrent.MonthlyRecurrenceRule</a>
      <a href=".../++apidoc++/Code/schooltool/calendar/recurrent/RecurrenceRule/"
         target="main">schooltool.calendar.recurrent.RecurrenceRule</a>
      ...
    </div>
    ...