In blocking mode, if we start a shell command, the twisted server will loop until a process terminates. Blocking mode should not be used for functions that can be called by XML-RPC, because they will completely block the server. The server won't process other requests until the blocking code is terminated.

But when using the MMC API in command line, it's simpler to use the blocking mode.

Here is an example:

      
          # Import the shLaunch method
          from mmc.support.mmctools import shLaunch
          
          # Run "ls -l"
          # shLaunch returns once the shell command terminates
          proc = shLaunch("ls -l")
          
          # Return shell command exit code
          print proc.exitCode
          # Return shell command stdout
          print proc.out
          # Return shell command stderr
          print proc.err        
        

Non blocking-mode should be used when a method called by XML-RPC may block. Basically, the method should not return the result, but a Deferred object attached to a callback corresponding to the result. The twisted reactor will process the deferred, send the result to the callback, and the callback will finally return the wanted result.

Here is an example:

          # Import the shLaunchDeferred method
          from mmc.support.mmctools import shLaunchDeferred

          def runLs():
              def cb(shprocess):
                  # The callback just return the process outputs
                  return shprocess.exitCode, shprocess.out, shprocess.err
          
              d = shLaunchDeferred("ls -l")
              # shLaunchDeferred returns a Deferred() object
              # We add the cb function as a callback
              d.addCallback(cb)
              # We return the Deferred() object
              return d
        

For more explanation about Python Twisted and Deferred objects, please read this page.

To use the runLs function in a python script, without the XML-RPC server:

          from twisted.internet import reactor, defer
          from xxx import runLs
          
          def printResult(ret):
              print ret
              reactor.stop()

          d = runLs()
          # runLs returns a deferred object, we add a callback that is just
          # printing the result
          d.addCallback(printResult)
          reactor.run()
        

The main.php arguments are directly related to modules directory organization.

For example, when calling http://127.0.0.1/mmc/main.php&module=base&submod=users&action=add, the file /usr/share/mmc/modules/base/users/add.php is executed.

This class allows to easily creates a page with the top navigation bar and the left sidebar. Here is a commented example of a simple MMC page:

          /* localSidebar.php contains the left sidebar elements of all the pages sub-module. See next section. */
          require("localSidebar.php");
          /*
             Display the top navigation bar, and prepare the page rendering.
             The current sub-module pane is automatically selected.
          */
          require("graph/navbar.inc.php");
                  
          /*
              Create a page with a title
              The title will be displayed as a H2
          /*
          $p = new PageGenerator(_T("Simple page example"));
          /*
              $sidemenu has been defined in the localSidebar.php file
              We set it as the page left side bar
          */
          $p->setSideMenu($sidemenu);
          /*
              We ask to the PageGenerator instance to render.
              The page title and the left sidebar are displayed.
              The current page corresponding pane is automatically selected in the left side bar.
          */
          $p->display();

          /* Fill the page with content */
          ...
        

The SideMenu class allows to build the left sidebar menu of a page. Here is an example, that could have been the content of the "localSidebar.php" of the previous section.

          $sidemenu= new SideMenu();
          /*
             CSS class name to use when rendering the sidebar.
             You should use the sub-module name
          */

          $sidemenu->setClass("submodule1");
          /*
             Register new SideMenuItem objects in the menu.
             Each item is a menu pane.
          */
          $sidemenu->addSideMenuItem(new SideMenuItem(_T("Simple page"),"module1","submodule1","index", "modules/module1/graph/img/module1_active.png", "modules/module1/graph/img/module1_inactive.png"));
          $sidemenu->addSideMenuItem(new SideMenuItem(_T("Another page"),"module1","submodule1","add", "modules/module1/graph/img/module1_active.png", "modules/module1/graph/img/module1_inactive.png"));
        

The SideMenuItem constructor arguments are

With the infoPackage.inc.php file, you can also add the page of a module to another module. This is useful if you want to provide new features to an already existing module.

In our example, we add a new page to the "computers" sub-module of the "base" module. Here is the corresponding infoPackage.inc.php:

          /* Get the base module instance reference */
          $base = &$MMCApp->getModule('base');
          /* Get the computers sub-module instance reference */
          $computers = &$base->getSubmod('computers');

          /* Add the page to the module */
          $page = new Page("extrapage", _T("Extra page", "module1"));
          $page->setFile("modules/module1/extra/extrapage.php");
          $computers->addPage($page);

          /* You should unset the references when you finished using them */
          unset($base);
          unset($computers);
        

With this code, the PHP script modules/module1/extra/extrapage.php will be called when using the main.php?module=base&submod=computers&action=extrapage.

The remaining problem is the sidebar management. In the called PHP script, you must include the localSidebar.php script from the other sub-module module, and add your SideMenuItem object to it.

For example:

          
          require("modules/base/computers/localSidebar.php");
          require("graph/navbar.inc.php");
          $p = new PageGenerator(_T("Extra page with new functions"));

          /* Add new sidemenu item */
          $sidemenu->addSideMenuItem(new SideMenuItem(_T("Extra page"),"base","computers","extrapage", "modules/base/graph/img/computers_active.png", "modules/base/graph/img/computers_inactive.png"));

          $p->setSideMenu($sidemenu);
          $p->display();

          ...
        

When a page is rendered, the framework includes the file modules/currentmodule/graph/currentmodule/currentsubmodule/index.css if it exists.

"currentmodule" and "currentsubmodule" are guessed from the current URL.

A HtmlContainer object owns an ordered list of elements. An element is either an instance from a HtmlContainer sub-class, either an instance from a HtmlElement sub-class.

This list of elements is either opened (new elements can be added to the list), either closed (no more elements can be added).

When adding a HtmlElement or a HtmlContainer object to a HtmlContainer, the object is added to the last added HtmlContainer which does not have a closed element list.

The HtmlContainer class main methods are:

Here is an example. The indentation helps to show which container is used:

          $o = new HtmlContainer;
              $o->add(HtmlElement());
              $o->push(HtmlContainer());
                  /* The HtmlElement are added to the latest added and open HtmlContainer */
                  $o->add(HtmlElement());
                  $o->push(HtmlContainer());
                      /* The HtmlElement are added to the latest added and open HtmlContainer */
                      $o->add(HtmlElement());
                      $o->add(HtmlElement());
                  /* closing the element list of the latest HtmlContainer */
                  $o->pop();
                  /* falling back to the previous HtmlContainer */
                  $o->add(HtmlElement());
              /* closing the element list of the latest HtmlContainer */
              $o->pop();
              $o->add(HtmlElement());
          /* Popping the root container */
          $o->pop();
          /* Display the HTML code */
          $o->display();
        

To render HTML code, a HtmContainer subclass needs only to implement these two functions:

Here is an example of a HtmlContainer subclass that wraps a HTML table:

  
          class Table extends HtmlContainer {
          
              function Table() {
                  $this->HtmlContainer();
              }
          
              function begin() {
                  return "<table>";
              }
          
              function end() {
                  return "</table>";
              }

          }
        

These objects are very simple PHP class wrapper around HTML code, and can be stored into a HtmlContainer object.

To render HTML code, a HtmElement subclass needs only to implement the display() function. This function just prints the HTML code implementing the widget. For example:

          class Title Extends HtmlElement {
          
              function Title($text) {
                  $this->$text = $text
              }

              function display() {
                  print "<H1>" . $this->text . "</H1>";
              }

          }
        

The ListInfos class allows to create a paged multi-column table with a navigation bar, and to link each row to a set of actions. For example, the MMC user list is implemented using a ListInfos widget.

Here is an example. We create a table with two columns: the first is a fruit, the second is a quantity.

          require ("includes/PageGenerator.php");
          $fruits = array("apple", "banana", "lemon", "papaya", "fig", "olive", "clementine", "orange", "mandarin", "grapes", "kumquat");
          $stock = array("5", "8", "40", "12", "40", "51", "12", "7", "9", "15", "21");
          
          /*
              Create the widget.
              The first column will be labeled "Fruit name", and each cell will contain an item of the $fruits array.
          */
          $l = new ListInfos($fruits, _T("Fruit name"));
          /* Add the second column */
          $l->addExtraInfo($stock, _T("Quantity"));
          /*
              Set the item counter label.
              The counter is displayed just above the table:
              Fruits 1 to 10 - Total 11 (page 1/2)
          */
          $l->setName(_T("Fruits"));
          /* Display the widget */
          $l->display();       
        

The item counter label is displayed just above the table. In our example, it shows: Fruits 1 to 10 - Total 11 (page 1/2). It means:

Now we are going to add some action items to each rows:

          require ("includes/PageGenerator.php");
          $l = new ListInfos($fruits, _T("Fruit name"));
          $l->addExtraInfo($stock, _T("Quantity"));
          $l->setName(_T("Fruits"));
          /* Add actions */
          $l->addActionItem(new ActionItem(_T("View fruit"), "view", "display", "fruit"));
          $l->addActionItem(new ActionPopupItem(_T("Delete fruit"), "view", "delete", "fruit"));
          $l->display();       
        

Thanks to addActionItem, we add to each row two actions: view the fruit, and delete the fruit.

ActionItem constructor arguments are:

In our example, the URL link for the first row will be: "main.php?module=module1&submod=submodule1&action=view&fruit=apple". For the second row, "...&fruit=banana", etc.

Sometimes an action link needs to send the user to another module or submodule, instead of the current one. To do this, you add these parameters to the ActionItem constructor:

ActionPopupItem displays a little popup page when clicked. This is useful for actions that just need an extra validation to be performed.

When there are actions, the first column cells are automatically linked to the first action. But this can be disabled with:

          $l->disableFirstColumnActionLink();
        

The default size of the JavaScript popup window is 300 pixel. This can be changed like this:

          $p = new ActionPopupItem(_T("Delete fruit"), "view", "delete", "fruit");
          $p->setWidth(500); /* Size is now 500 px */
          $l->addActionItem($p);
        

With the addActionItem method, you add an action to every row of a ListInfos widget. In some cases, an action can't be performed for a specific row, so you don't want the action link to be available.

The addActionItemArray method allows to pass to the ListInfos widget an array of actions to display:

          require ("includes/PageGenerator.php");
          $fruits = array("apple", "banana", "lemon", "papaya", "fig", "olive", "clementine", "orange", "mandarin", "grapes", "kumquat");
          $stock = array("5", "8", "40", "12", "40", "51", "12", "7", "9", "15", "21");

          $viewAction = new ActionItem(_T("View fruit"), "view", "afficher", "fruit");
          $deleteAction = new ActionPopupItem(_T("Delete fruit"), "view", "supprimer", "fruit");
          /* an EmptyActionItem will be displayed as a blank space */
          $emptyAction = new EmptyActionItem();

          $actionsView = array();
          $actionsDel = array();
          foreach($stock as $value) {
              if ($value < 10) {
                  /* Only put the deleteAction link if value is lower than 10 */
                  $actionsDel[] = $deleteAction;
                  $actionsView[] = $emptyAction;
              } else {
                  /* else only put the viewAction link */
                  $actionsView[] = $viewAction;
                  $actionsDel[] = $emptyAction;
              }
          }
          
          $l = new ListInfos($fruits, _T("Fruit name"));
          $l->addExtraInfo($stock, _T("Quantity"));
          $l->setName(_T("Fruits"));
          $l->addActionItemArray($actionsView);
          $l->addActionItemArray($actionsDel);
          $l->display();
        

A ListInfos widget content can be dynamically filtered.

First, we write the page that render the ListInfos widget. This page gets the filter to apply to the ListInfos widget as a GET parameter. Here is the code of /usr/share/mmc/modules/module1/submodule1/ajaxFruits.php:

          /* Get MMC includes */
          require("../../../includes/config.inc.php");
          require("../../../includes/i18n.inc.php");
          require("../../../includes/acl.inc.php");
          require("../../../includes/session.inc.php");
          require("../../../includes/PageGenerator.php");

          $filter = $_GET["filter"];
          $fruits = array("apple", "banana", "lemon", "papaya", "fig", "olive", "clementine", "orange", "mandarin", "grapes", "kumquat");
          
          /* Make a fruit list using the filter */
          $filtered = array();
          foreach($fruits as $fruit) {
              if ($filter == "" or !(strpos($fruit, $filter) === False))
                  $filtered[] = $fruit;
          }

          $l = new ListInfos($filtered, _T("Fruit name"));
          /*
              Instead of using the standard widget navigation bar, use the AJAX version.
              This version allows to keeps the filter when clicking on previous / next.
          */
          $l->setNavBar(new AjaxNavBar(count($filtered), $filter));
          $l->setName(_T("Fruits"));
          $l->display();
        

This PHP code just displays a ListInfos widget where the elements are filtered.

Now we create a page where the ListInfos widget is automatically updated using a filter. Here is the code of /usr/share/mmc/modules/module1/submodule1/index.php:

          require("localSidebar.php");
          require("graph/navbar.inc.php");

          /*
              Create the filtering form with a input field, and bind this input field to an AJAX updater that will use the specified URL to dynamically fill in a DIV (see below) container.
          */
              
          $ajax = new AjaxFilter("modules/module1/submodule1/ajaxFruits.php");
          /* You can ask the AJAX updater to be called every 10s */
          /* $ajax->setRefresh(10000); */
          $ajax->display();

          /* Set page title and left side bar */
          $p = new PageGenerator(sprintf(_T("Fruits"), "module1"));
          $p->setSideMenu($sidemenu);
          $p->display();
          
          /* Display the DIV container that will be updated */
          $ajax->displayDivToUpdate();
        

In infoPackage.inc.php, these two PHP script should be registered like this:

          $mod = new Module("module1");
          ...
          $submod = new SubModule("submodule1");
          ...
          /* Register the first page */
          $page = new Page("index", _T("Fruit list", "module1"));
          $submod->addPage($page);     
          /* Register the page called using the AJAX DIV updater */
          $page = new Page("ajaxFruit");
          $page->setFile("modules/module1/submodule1/ajaxFruits.php",
                         array("AJAX" => True, "visible" => False)
          );
          $submod->addPage($page);
          ...
        

This widget (a subclass of HtmlContainer) is a HTML form with input fields validation. The form can't be validated (POSTed) if some required fields are not filled in, or if their values don't match a given regex.

A lot of MMC pages display a HTML form, containing a HTML table with multiple rows of a single labeled input field. Here is an example

          /* Build a new validating form */
          $f = new ValidatingForm();

          /* Push a table into the form, and go to the table level */
          $f->push(new Table());
          /* Add two TR to the table */
          /* Ask for a given name */
          $f->add(
              new TrFormElement(_T("Given name"), new InputTpl("givenName"),
              array("value" => "", "required" => True)
          );
          /* Ask for a family name */
          $f->add(
          new TrFormElement(_T("Family name"), new InputTpl("name"),
              array("value" => "", "required" => True)
          );
          /* Go back to the validating form level
          $f->pop();

          /* Add a button to the form */
          $f->addButton("bvalid", _T("Validate"));

          /* Close the form */
          $f->pop();

          /* Render all the form and the objects it contains */
          $f->display();
        

The TrFormElement class creates objects that will render a HTML row (a TR) with two columns (two TDs). The first column contains a describing label, and the second column an input field. In the example:

          /* Ask for a given name */
          $f->add(
              new TrFormElement(_T("Given name"), new InputTpl("givenName"),
              array("value" => "", "required" => True)
          );
        

TrFormElement takes three argument:

See next section about all the InputTpl widget options.

The InputTpl class allows to render a standard HTML input field. The constructor takes two arguments:

When rendering the widget, additional options can be given to the "display" method thanks to an array:

A lots of class that inherits from InputTpl have been written. For example: MACInputTpl is an HTML input field that only accepts MAC address, NumericInputTpl only accepts numeric value. Theses kind of classes are very easy to write:

          class NumericInputTpl extends InputTpl {
          
              function NumericInputTpl($name) {
                  $this->name = $name;
                  $this->regexp = '/^[0-9]*$/';
              }

          }

          class MACInputTpl extends InputTpl {
              
              function MACInputTpl($name) {
                  $this->name = $name;
                  $this->regexp = '/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/i';
              }
              
          }
        

This widget allows to build a MMC popup form triggered by a ActionPopupItem very quickly. For example:

          if (isset(_POST["bdel"])) {
              /* action to remove the fruit */
              ...
          } else {
              $fruit = urldecode($_GET["fruit"]);
              /* Create the form and set its title */
              $f = new PopupForm(_T("Delete a fruit"));
              /* Add a little description text */
              $f->addText(_T("This action will delete all the fruit"));
              /*
                  Put a hidden input field into the form.
                  The HiddenTpl is explained later in this document
              */
              $hidden = new HiddenTpl("fruit");
              /* Add this field to the form */
              $f->add($hidden, array("value" => $fruit, "hide" => True));
              /* Add validation and cancel buttons */
              $f->addValidateButton("bdel");
              $f->addCancelButton("bback");
              $f->display();
          }
        

These two widgets displays a javascrip popup with a message, with a OK button.

          /* Error message popup */
          new NotifyWidgetFailure(_T("Error ! /o\"));
          /* Success */
          new NotifyWidgetSuccess(_T("Reboot was successful ! \o/"));
        

This widget allows to include a tab selector that displays a page when clicking on a tab.

For example:

          require("localSidebar.php");
          require("graph/navbar.inc.php");

          /* We use the TabbedPageGenerator class */
          $p = new TabbedPageGenerator();
          /* Set the sidemenu, as the PageGenerator class */
          $p->setSideMenu($sidemenu);

          /*
            Not required: you can add some content above the tab selector
            The content is a title, and a PHP file to include.
          */  
          $p->addTop("Page title", "modules/module1/submodule1/top.php");

          /*
            Now we add new tab to the tab selector.
            Each tab is associated to an id, a tab title, a page title, and a PHP file to include.
            
          */
          $p->addTab("tab1", "Tab 1 title", "Page 1 title", "modules/module1/submodule1/tab1.php");
          $p->addTab("tab2", "Tab 2 title", "Page 2 title", "modules/module1/submodule1/tab2.php"); 
          $p->addTab("tab3", "Tab 3 title", "Page 3 title", "modules/module1/submodule1/tab3.php");

          /*
            You can add a fifth argument, which is an array of URL parameters
            that will be used when building the URL link of the tab.
          */
          $p->addTab("tab4", "Tab 4 title", "Page 4 title", "modules/module1/submodule1/tab4.php", array("uid" => "foo"));
          $p->display();
        

If no tab is selected, the first tab is automatically activated.

To build a tab URL link, the current module, submodule and action are used, with the given tab id and the given array of URL parameters. For example:

          $p->addTab("tab4", "Tab 4 title", "Page 4 title", "modules/module1/submodule1/tab4.php", array("uid" => "foo"));
        

will build this link: module=currentmod&submod=currentsubmod&action=currentaction&tab=tab4&uid=foo