=====================================================================
ice.control - System Administration and Site Management for BlueBream
=====================================================================

.. contents::
   :local:


Package overview
================

ice.control is package for:

- BlueBream application developers: `developer kit` and `starter kit`.
- system administrators: `site management`.

Also, it can be used by site manager (`manage site`) but only if
application developer likes this and he defines management forms as
`controls` view or `details` ajax-views.

This package provides:

- treeview ZODB browser
- tables for rename and remove objects
- object introspector
- ajax based python shell (REPL) to debug and interact the
  application in selected context
- configuration view to manage ZODB objects, edit metadata, other
  `details` ajax based views and ability to add new views
- optional simple skin (as part of `starter kit`)
- optional module with all needed zcml registrations

Each facility is optional. Include needed modules using zcml, or
include root configuration file to use entire functionality of the
package.

IMPORTANT NOTE: use Mozilla Firefox.


Getting started
===============

Add `ice.control` dependency into main package of your BlueBream
application. If you like to install the package from Git repository,
see HACKME, section ``Install from Git repository``.


Include zcml files 
++++++++++++++++++

There are number of options to use ice.control. You have define this
including certain modules in zcml. If you like to use entire
functionality of the package, add these directives into your configure.zcml
file, before of `include file="securitypolicy.zcml"`::

  `include package="ice.control.zcml"`
  `include package="ice.control"`
  `include package="ice.control.repl"`
  `browser:defaultSkin name="control"`

Now run tests and run the server::

  $ bin/test
  $ bin/paster serve debug.ini


Admin UI for BlueBream - overview
=================================

There are virtual context, `++etc++control` for the `controls`.
It is not real persistent object. Controls can be used within any
z3c.pagelet-based views on this context.

- In "Tree" `control` are contents' tree which show database
  structure. Open / close tree branches by clicking on triangles.
  Click links (names or icons) to open "Details" ajax pseudo-window.
  See menu at bottom of this pseudo-window.

- This "Details" ajax psudo-window might be closed or minimized
  into "dock". It contains number of sub-views, depend on context
  and depend on your custom registrations:

- "Contents" - for containers: rename and remove contained items.
  There are pagination ("batching") if length of the list is >10.

- "Metadata" - form for edit Dublin core Metadata.

- "Introspector" - inspect persistent objects, looking apidoc.

- "REPL" - interactive Python shell to inspect and edit persistent
  objects, interact with this instance.

- "Configurator" - general way to manage ZODB.

- Custom views for Error Reporting Local Utility.
  
- You might like to add your custom views to "Details". See below.

- There are another `controls`, not only contents tree. See and
  learn UI. You might like to add your custom `controls` also, see
  below.


REPL overview
=============

Ajax based python shell and server for Emacs. Session is defined
for user and context. So, each context has its own session. In other
words, you can open, close, minimize number of 'Details' pseudo-windows,
and each will contain its own REPL session.

Ajax based REPL
+++++++++++++++

Predefined variables and methods:

- `context` is current context in ZODB tree
- `getObject` from zope.security.proxy
- `transaction` import

Key bindings:

- `up` - up to history
- `down` - down to history
- `Tab` - tab indent

REPL server for Emacs
+++++++++++++++++++++

not implemented yet
