=======
Inspect
=======

Grok's own object inspector.

The Grok object browser is basically simply a view on objects.

.. contents::


How to use it
-------------

You can use the object inspector through-the-web (TTW) or using
Python. It was primarily designed for TTW-use. This is explained
here.


Simple usage: Inspecting easy reachable objects
-----------------------------------------------

The inspector is called by appending ``/@@inspect.html`` to an URL
describing an object in the ZODB. For example, to watch the object
description of your Zopes root folder, you can use something like:

	    http://localhost:8080/@@inspect.html

Note, that not all URLs you type into your browser denote
objects. They often describe only certain views of certain
objects. Currently the browsing of views with the object inspector is
not supported.

If you want to examine another object, which is reachable 'via URL',
just get the path you would normally enter into the browser and append
``@@inspect.html``.

Assuming you once created an object, which is reachable by::

	 http://localhost:8080/my_object

then you can examine it via the object browser, using the following
URL::

         http://localhost:8080/my_object/@@inspect.html

Easy, isn't it?

In most cases you can also skip the 'eyes', the strange ``@@`` symbol
in front of the view name (``inspect.html``). The 'eyes' are only
neccessary, when you examine an object, which has got an own attribute
called ``inspect.html``.


Extended usage: Inspecting 'hidden' objects
-------------------------------------------

All objects we exmined so far, are 'easy reachable'. This means, they
are reachable by entering a simple URL. However, some (to tell the
truth: many) objects cannot be reached this way. Such objects might be
'subobjects' of others, they might be handled by a special traverser,
simply have no view or whatever. We call those objects here 'hidden
objects'. What, if we want to know more about
those hidden objects?

For example, we might have the attribute of an object (which is an
object as well), which is not directly callable::

  http://localhost:8080/my_object/hidden_attribute

might so generate an error. It does not help to append simply
``@@inspect.html`` to the URL. Instead we have to call a special
traverser, which is able to look up the object for us and helps
out. 

This traverser is called by inserting ``docgrok-obj/`` as root of
the path in the URL. The above mentioned hidden_attribute can
therefore be reached using::

  http://localhost:8080/docgrok_obj/my_object/hidden_attribute/@@inspect.html

Such, you can reach even deeply nested subobjects of subobjects. 

Just think of ``docgrok-obj`` as a special URL-namespace like
``++annotations++``, ``++view++`` or similar (in fact it is not a
URL-namespace), which can examine the complete object tree stored in
the ZODB. In fact this 'namespace' can be used with every object, also
with 'visible' ones. The above call to see ``my_object`` could
therefore be reached (in a more complicated way) as::

  http://localhost:8080/docgrok_obj/my_object/@@inspect.html

This is the most general form to call the object browser:

  http://<hostname>[:<port>]/docgrok_obj/<object-path>/@@inspect.html

where 'docgrok-obj/' and '@@inspect.html' are the object browser
specific parts.



