code_hacking.txt

A brief introduction to Fang of Mongo internals.

Warning:
I am backend  programmer, this is my first attempt to design both mongo tool and
complicated javascript ui.The whole concept of this application is experimental
and there is probably a lot to improve in it.


1. General overview

   Fang of Mongo is a web based GUI for mongodb.
   Being web applications it is made of:
   
    - server part, written in python using django and mongodb drivers.
      this part is responsible for providing mongo interface for clients,
   
    - client part, written in javascript (+few html templates)

2. Django parts

    On server side, see fangofmongo/fom/views.py and urls.py.
    Fom defines few views which either show its user interface
    (mainly start page and page with fom user interface)
    or access mongodb (all ^rest.* urls). The first ones will return rendered html templates,
    the latter json with returned data. There is really nothing complicate there.

3. User interface

   The goal was to build UI from independent components (like database list, collection list)
   which communicate with each other by sending signals via message bus.
   
   When user will perform any action on one of components, it will send singal to bus informing others
   and allowing them to respond to action.
   
   For example if you click on database in database list, it will send signal "database_selected".
   When Collection list will receive it, it will send ajax request to get list of collecions
   for selected df. Returning set of collections will also be send as a signal ("collection_list_reveived")
   and any interested component may use it (like collection list will use it to present it to the user).

   So we have:
 
     - a message bus. If you write component it will likely be interested in receiving some messages,
       so it has to call listen method of message bus object.

     - a set of components, like database list, collection list, collection info and others.
       Most of then is available as plugins.

     - mongo_ajax object for accessing mongo via ajax calls.
     
     - understanding those ideas, you will be able to modify existing code
       or even create your own components. You can create them either
       by sub-classing existing ones (if you want enhance or replace them) or creating 
       entirely new functionality.

    There are also some ui elements that simplify creation of commonly used ideas (like dialog with a list of items)
     
4. Few words about plug-ins

    A plug-in is just xml file (with .fomxml extension), and may contain:
        - some meta-information like author, name or version
        - js code
        - html and css code
        
   Basically all those resources are just inserted into ui page. fangofmongo/plugins/sample_plugin.fomxml_template
   contains example. See fangofmongo/fom/handle_plugins.py for more information about how plug-ins are processed.

   Because even core fom functionality like listing databases and collection has been separated into plug-ins,
   you are free to enhance them or replace with better ones.