Web/Dashboard: Keep all error messages consistent & add some class docblocks

Author: yhabteab

library/Icinga/Web/Dashboard/Common/DashboardEntries.php

@@ -109,7 +109,7 @@ public function rewindEntries()
     public function unsetEntry(BaseDashboard $dashboard)
     {
         if (! $this->hasEntry($dashboard->getName())) {
-            throw new ProgrammingError('Trying to unset an invalid Dashboard entry: "%s"', $dashboard->getName());
+            throw new ProgrammingError('Trying to unset an invalid Dashboard entry: "%s"', $dashboard->getTitle());
         }
 
         unset($this->dashboards[strtolower($dashboard->getName())]);

library/Icinga/Web/Dashboard/Common/DashboardManager.php

@@ -100,7 +100,10 @@ public function loadDashboardEntries(string $name = null)
     public function activateHome(DashboardHome $home): self
     {
         if (! $this->hasEntry($home->getName())) {
-            throw new ProgrammingError('Trying to activate Dashboard Home "%s" that does not exist.', $home->getName());
+            throw new ProgrammingError(
+                'Trying to activate Dashboard Home "%s" that does not exist.',
+                $home->getTitle()
+            );
         }
 
         $activeHome = $this->getActiveHome();

library/Icinga/Web/Dashboard/Common/DashboardUserManager.php

@@ -10,7 +10,6 @@
 use Icinga\Util\DBUtils;
 use ipl\Stdlib\Filter;
 
-// TODO: Remove this completely as soon as we have introduced a daemon in Icinga Web 2.
 trait DashboardUserManager
 {
     /** @var User */

library/Icinga/Web/Dashboard/Dashboard.php

@@ -173,9 +173,7 @@ protected function assemble()
                 . ' You will always be able to edit them afterwards.'
             );
             $this->addHtml(HtmlElement::create('p', null, $message));
-        } elseif (! $activeHome->hasEntries()) {
-            $this->addHtml(HtmlElement::create('h1', null, t('No dashboard added to this dashboard home.')));
-        } else {
+        } elseif ($activeHome->hasEntries()) {
             $activePane = $activeHome->getActivePane();
 
             if (! $activePane->hasEntries()) {
@@ -185,6 +183,8 @@ protected function assemble()
                     $this->addHtml($dashlet->getHtml());
                 }
             }
+        } else {
+            $this->addHtml(HtmlElement::create('h1', null, t('No dashboard added to this dashboard home.')));
         }
     }
 }

library/Icinga/Web/Dashboard/DashboardHome.php

@@ -14,10 +14,16 @@
 use Icinga\Web\Dashboard\Common\Sortable;
 use Icinga\Util\DBUtils;
 use Icinga\Web\Dashboard\Common\WidgetState;
+use Icinga\Web\Navigation\NavigationItem;
 use ipl\Stdlib\Filter;
 
 use function ipl\Stdlib\get_php_type;
 
+/**
+ * A Dashboard Home groups various Dashboard Panes and provides the ability
+ * to load Panes from different entry point of view. Dashboard Homes are
+ * rendered as child of {@see NavigationItem}s of the main dashboard menu.
+ */
 class DashboardHome extends BaseDashboard implements DashboardEntry, Sortable
 {
     use DashboardEntries;
@@ -108,15 +114,18 @@ public function getType(): string
     public function activatePane(Pane $pane): self
     {
         if (! $this->hasEntry($pane->getName())) {
-            throw new ProgrammingError('Trying to activate Dashboard Pane "%s" that does not exist.', $pane->getName());
+            throw new ProgrammingError(
+                'Trying to activate Dashboard Pane "%s" that does not exist.',
+                $pane->getTitle()
+            );
         }
 
         $active = $this->getActivePane();
         if ($active && $active->getName() !== $pane->getName()) {
             $active->setActive(false);
         }
 
-        $pane->setActive(true);
+        $pane->setActive();
 
         return $this;
     }
@@ -250,6 +259,8 @@ public function manageEntry($entryOrEntries, BaseDashboard $origin = null, bool
                         'id = ?'      => $origin->getEntry($pane->getName())->getUuid(),
                         'home_id = ?' => $origin->getUuid()
                     ];
+
+                    $this->addEntry($pane);
                 }
 
                 $conn->update(Pane::TABLE, [
@@ -262,9 +273,10 @@ public function manageEntry($entryOrEntries, BaseDashboard $origin = null, bool
                 // Failed to move the pane! Should have already been handled by the caller,
                 // though I think it's better that we raise an exception here!!
                 throw new AlreadyExistsException(
-                    'Dashboard Pane "%s" could not be managed. Dashboard Home "%s" has Pane with the same name!',
-                    $pane->getTitle(),
-                    $this->getTitle()
+                    'Failed to successfully manage the Dashboard Pane. Dashboard Home "%s" has already' .
+                    ' a Pane called "%s"!',
+                    $this->getTitle(),
+                    $pane->getTitle()
                 );
             }
 

library/Icinga/Web/Dashboard/Dashlet.php

@@ -13,9 +13,8 @@
 use ipl\Web\Widget\Link;
 
 /**
- * A dashboard pane dashlet
- *
- * This is the new element being used for the Dashlets view
+ * A Dashlet/View is basically an Url which is being visualized
+ * into a single View by Icinga Web 2
  */
 class Dashlet extends BaseDashboard
 {
@@ -91,7 +90,7 @@ public function getUrl(): ?Url
     }
 
     /**
-     * Set the dashlets URL
+     * Set the URL of this dashlet
      *
      * @param string|Url $url The url to use, either as an Url object or as a path
      *
@@ -191,7 +190,7 @@ public function isModuleDashlet(): bool
     }
 
     /**
-     * Set whether this dashlet widget is provided by a module
+     * Set whether this dashlet is provided by a module
      *
      * @param bool $moduleDashlet
      *

library/Icinga/Web/Dashboard/Pane.php

@@ -20,7 +20,8 @@
 use function ipl\Stdlib\get_php_type;
 
 /**
- * A pane, displaying different Dashboard dashlets
+ * A Pane or Dashboard Pane organizes various Dashlets/Views into a single panel
+ * and can be accessed via the tabs rendered on the upper navigation bar of Icinga Web 2.
  */
 class Pane extends BaseDashboard implements DashboardEntry, Sortable
 {
@@ -100,6 +101,7 @@ public function loadDashboardEntries(string $name = null)
         $dashlets = Model\Dashlet::on(DBUtils::getConn())
             ->utilize(self::TABLE)
             ->with('icingaweb_module_dashlet');
+
         $dashlets->filter(Filter::equal('dashboard_id', $this->getUuid()));
 
         // TODO(yh): Qualify those columns properly??
@@ -166,7 +168,8 @@ public function manageEntry($entryOrEntries, BaseDashboard $origin = null, bool
 
         if (! $this->getHome()) {
             throw new \LogicException(
-                'Dashlets cannot be managed. Please make sure to set the current dashboard home beforehand.'
+                'Dashlet(s) cannot be managed without a valid Dashboard Home. Please make sure to set' .
+                ' the current dashboard home beforehand.'
             );
         }
 
@@ -231,6 +234,8 @@ public function manageEntry($entryOrEntries, BaseDashboard $origin = null, bool
                         'id = ?'           => $origin->getEntry($dashlet->getName())->getUuid(),
                         'dashboard_id = ?' => $origin->getUuid()
                     ];
+
+                    $this->addEntry($dashlet);
                 }
 
                 $conn->update(Dashlet::TABLE, [
@@ -246,9 +251,9 @@ public function manageEntry($entryOrEntries, BaseDashboard $origin = null, bool
                 // Failed to move the pane! Should have already been handled by the caller,
                 // though I think it's better that we raise an exception here!!
                 throw new AlreadyExistsException(
-                    'Dashlet "%s" could not be managed. Dashboard Pane "%s" has a Dashlet with the same name!',
-                    $dashlet->getTitle(),
-                    $this->getTitle()
+                    'Failed to successfully manage the Dashlet. Dashboard Pane "%s" has already a Dashlet called "%s"!',
+                    $this->getTitle(),
+                    $dashlet->getTitle()
                 );
             }