ice.control 0.1.3

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

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

- `context` is current context in ZODB tree

Prefefined imports - see module `ice.control.repl.bootstrap`

Key bindings:

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


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

not implemented yet


ice.control development
=======================

.. contents::
:local:


Modes&Praxises
++++++++++++++

Fork author's branch on GitHub repository. Install it (see below) but
use your own repository's private URL.


Install from Git repository
---------------------------

Download sources from GitHub repository using `mr.developer` buildout
extension. You have much more control on the source code using this way.

It requires number of steps first time, but simple to maintain in
futher. First, add follow lines into buildout.cfg, section [buildout]::

[buildout]
...

extensions = mr.developer
sources-dir = dev
sources = sources

then run buildout to create `develop` script::

$ bin/buildout

then add section [sources] into buildout.cfg::

[sources]
ice.control = git git://github.com/astoon/ice.control.git

and run the script to download the branch::

$ bin/develop checkout ice.*

You'll see now the package branch in /dev directory. Allow to run tests
from ice.control package. For this, edit buildout.cfg again::

[test]
...
eggs = sample
ice.control

and add dependency for your project in setup.py::

install_requires=[...
'ice.control'
],

Finally, run buildout::

$ bin/buildout


Issues, Blueprints
------------------

* https://bugs.launchpad.net/ice.control
* https://blueprints.launchpad.net/ice.control
* https://answers.launchpad.net/ice.control
* http://github.com/astoon/ice.control/issues

* For free discussions - Goole Wave ID: googlewave.com!w+r7PkMjhxA
(https://wave.google.com/wave/?#restored:wave:googlewave.com!w%252Br7PkMjhxA)


Versions, release tags, branches
--------------------------------

**


Bug reports: https://bugs.launchpad.net/ice.control.

Or use GitHub social coding system, fork and make proposal to merge.


List of known bugs in current release (0.1.0)
=============================================

** JavaScript not handles click-event on details view until
details menu clicked. So, when load details pseudo-window, first
view (`Base Info`) should not contain any links or forms.
Need fix JS.

** Need better Google Chrome web browser support. Right now UI
is not ideal in this browser. Use only Mozilla Firefox.

** Auto scrolling for REPL not works.


Releases
========

0.1.3 (2010-04-14)
------------------

Fixed a bug that appeared in 0.1.2: `details` view not send
ajax form data.


0.1.2 (2010-04-12)
------------------

100% tests or something like.
Added zcml condition for details: metadata.
Apidoc window features: fixed.
Fixed bug: anchor's behavior in introspector.
Increased supported version of bluebream: 1.0a5


0.1.1 (2010-04-07)
------------------

Fixed MANIFEST.in to include docs into distribution.


0.1.0 (2010-04-07)
------------------

First release tag.