Revize 70a3df53

+ Re #8086
+ php refactoring and comments

website/public/js/zcu-heatmap.js

@@ -17 +17 @@
 var isAnimationRunning = false
 var data = []
 
+var info = []
+var currenInfo = 0
+
 // holds all instances of markers for bind/unbind popup purpose
 // contains: {key:[L.circle,L.pupup]}
 // key: x and y, x + '' + y string
@@ -51 +54 @@
   ${genPopUpControls([previousButton, posInfo, nextButton])}
   `
 }
+/**
+ * Initialize leaflet map on start position which can be default or set based on user action
+ */
 // eslint-disable-next-line no-unused-vars
 function initMap () {
   startX = localStorage.getItem('lat') || startX
@@ -67 +73 @@
   mymap.on('click', showInfo)
 }
 
-var info = []
-var currenInfo = 0
 
 function showInfo (e) {
   info = []
@@ -137 +141 @@
   mymap.setView([latitude, longitude], zoom)
 }
 
+/**
+ * Change animation start from playing to stopped or the other way round
+ */
 // eslint-disable-next-line no-unused-vars
 function changeAnimationState () {
   isAnimationRunning = !isAnimationRunning
@@ -173 +180 @@
   changeUrl()
 }
 
+/**
+ * Change browser url based on animation step
+ */
 function changeUrl () {
   window.history.pushState(
     '',
@@ -190 +200 @@
   $('#timeline').attr('class', 'time hour-' + currentTime)
 }
 
+/**
+ * Load and display heatmap layer for current data
+ * @param {string} opendataRoute route to dataset source
+ * @param {string} positionsRoute  route to dataset postitions source
+ */
 // eslint-disable-next-line no-unused-vars
 function loadCurrentTimeHeatmap (opendataRoute, positionsRoute) {
   dataSourceRoute = opendataRoute
@@ -292 +307 @@
   // $(.leaflet-heatmap-layer).css('opacity', 'value');
 }
 
+/**
+ * Checks dataset availibility
+ * @param {string} route authority for datasets availibility checks 
+ */
 // eslint-disable-next-line no-unused-vars
 function checkDataSetsAvailability (route) {
   $.ajax({

website/src/Controller/HeatmapController.php

@@ -11 +11 @@
 
 class HeatmapController extends AbstractController {
     /**
+     * Map page controller.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     *
      * @Route("/heatmap", name="heatmap")
      */
     public function index(Request $request, IOpenDataManager $manager) {
@@ -22 +26 @@
         $isSubmitted = $form->isSubmitted();
         if ($isSubmitted) {
             $dataSet = $form->getData();
+            // Chceck whether the data is valid i.e. such a collection exists
             if (false == $manager->isCollectionAvailable($dataSet->getType(), $dataSet->getDate())) {
+                // Not? Populate form with empty data
                 $dataSet = new DataSet();
             }
             $form = $this->createForm(DataSetType::class, $dataSet);
@@ -39 +45 @@
     }
 
     /**
+     * Provides specific dataset information i.e. position, number and other informations depending on data type.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $name    dataset name
+     * @param string           $date    dataset date in format YYYY-mm-dd
+     * @param string           $time    dataset time, number between 0 - 23
+     *
+     * @return json with dataset information
+     *
      * @Route("heatmap/opendata/{name}/{date}/{time}", name="opendata")
      */
     public function opendata(IOpenDataManager $manager, $name = 'NONE', $date = '2020-01-01', $time = '1') {
@@ -49 +64 @@
     }
 
     /**
+     * Provides available datasets in given date.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $date    dataset date in format YYYY-mm-dd
+     *
+     * @return json with available datasets names
+     *
      * @Route("heatmap/available/{date}", name="available")
      */
     public function availableDatasets(IOpenDataManager $manager, $date = '2020-01-01') {
@@ -56 +78 @@
     }
 
     /**
+     * Provides dates with at least one available dataset.
+     *
+     * @param IOpenDataManager $manager connection to database
+     *
+     * @return json with dates with at least one available dataset in format YYYY-mm-dd
+     *
      * @Route("heatmap/dates", name="dates")
      */
     public function datesWithAvailableDatasets(IOpenDataManager $manager) {
@@ -63 +91 @@
     }
 
     /**
+     * Provides for dataset with given name all locations.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $name    dataset name
+     *
+     * @return json with all locations for dataset with given name as [x => lat, y => lng]
+     *
      * @Route("heatmap/positions/{name}", name="positions")
      */
     public function dataSourcePoistions(IOpenDataManager $manager, $name = 'NONE') {
@@ -70 +105 @@
     }
 
     /**
+     * Provides last available date for each available dataset type.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     *
+     * @return json with last available date for each available dataset type as [collection-type-name => YYYY-mm-dd]
+     *
      * @Route("heatmap/last", name="last")
      */
     public function lastAvailableCollections(IOpenDataManager $manager) {

website/src/Controller/HomeController.php

@@ -7 +7 @@
 
 class HomeController extends AbstractController {
     /**
+     * Home page controller.
+     *
      * @Route("/", name="home")
      */
     public function index() {

website/src/Entity/DataSet.php

@@ -2 +2 @@
 
 namespace App\Entity;
 
-//Todo some checks
+/**
+ * Class wich represent From on heatmap page and is bind to that form.
+ *
+ * @see https://symfony.com/doc/current/forms.html
+ */
 class DataSet {
     protected $time;
     protected $date;

website/src/Form/DataSetType.php

@@ -5 +5 @@
 use App\Utils\Utils;
 use App\Entity\DataSet;
 use App\Repository\IOpenDataManager;
-use Symfony\Component\Form\FormView;
 use Symfony\Component\Form\AbstractType;
-use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\Form\Extension\Core\Type\TextType;
@@ -15 +13 @@
 use Symfony\Component\Form\Extension\Core\Type\SubmitType;
 
 class DataSetType extends AbstractType {
+    /**
+     * @var IOpenDataManager autowired connection to database
+     */
     private $manager;
 
+    /**
+     * @param IOpenDataManager autowired connection to database
+     */
     public function __construct(IOpenDataManager $manager) {
         $this->manager = $manager;
     }
 
+    /**
+     * @see https://symfony.com/doc/current/forms.html
+     */
     public function buildForm(FormBuilderInterface $builder, array $options) {
         $builder
             ->add('date', TextType::class)
+            // Populate time select with data
             ->add('time', ChoiceType::class, [
                 'choices' => [
                     '0:00-1:00' => 0,
@@ -52 +60 @@
                     '23:00-0:00' => 23,
                 ],
             ])
+            // Populet type select with data
             ->add('type', ChoiceType::class, [
                 'choices' => Utils::prepareDatasetsNames($this->manager->getAvailableCollections()),
             ])
             ->add('submit', SubmitType::class);
     }
 
+    /**
+     * @see https://symfony.com/doc/current/forms.html
+     */
     public function configureOptions(OptionsResolver $resolver) {
         $resolver->setDefaults([
             'data_class' => DataSet::class,
             'method' => 'GET',
         ]);
     }
-
-    // public function buildView(FormView $view, Forminterface $form, array $options) {
-
-    // }
 }

website/src/Repository/IOpenDataManager.php

@@ -2 +2 @@
 
 namespace App\Repository;
 
+/**
+ * interface for database connection management
+ * autowired @see website/config/services.yaml and https://symfony.com/doc/current/service_container/autowiring.html.
+ */
 interface IOpenDataManager {
+    /**
+     * Provides specific dataset information i.e. position, number and other informations depending on data type.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     * @param string $hour dataset hour, number between 0 - 23
+     *
+     * @return array with dataset information
+     */
     public function getCollectionDataByName($name, $date, $hour);
 
+    /**
+     * Provides all available data sets types.
+     *
+     * @return array with avalable datasets names
+     */
     public function getAvailableCollections();
 
+    /**
+     * Provides available datasets in given date.
+     *
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return array with available datasets names
+     */
     public function getAvailableCollectionsByDay($date);
 
+    /**
+     * Check if dataset with given name is available for given date.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return bool true if dataset with given name is available in given date otherwise false
+     */
     public function isCollectionAvailable($name, $date);
 
+    /**
+     * Provides dates with at least one available dataset.
+     *
+     * @return array with dates with at least one available dataset in format YYYY-mm-dd
+     */
     public function getDatesWithAvailableCollection();
 
+    /**
+     * Provides max value of all locations (data dources) in dataset with given date on given date.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return number max value of all locations (data dources) in dataset with given date on given date
+     */
     public function getMaxCollectionNumberAtDay($name, $date);
 
+    /**
+     * Provides for dataset with given name all locations.
+     *
+     * @param string $name dataset name
+     *
+     * @return array with all locations for dataset with given name as [x => lat, y => lng]
+     */
     public function getDataSourcePositions($name);
 
+    /**
+     * Provides last available date for each available dataset type.
+     *
+     * @return array with last available date for each available dataset type as [collection-type-name => YYYY-mm-dd]
+     */
     public function getLastAvailableCollections();
 }

website/src/Repository/OpenDataManager.php

@@ -5 +5 @@
 use MongoDB\Driver\Query;
 use MongoDB\Driver\Manager;
 
+/**
+ * Implementation of IOpenDataManager
+ * autowired @see website/config/services.yaml and https://symfony.com/doc/current/service_container/autowiring.html.
+ *
+ * @see IOpenDataManager for methods comments
+ */
 class OpenDataManager implements IOpenDataManager {
+    /**
+     * @var IOpenDataManager autowired connection to database
+     */
     private $manager;
 
+    /**
+     * @param IOpenDataManager autowired connection to database
+     */
     public function __construct($connectionString) {
         $this->manager = new Manager(
             $connectionString
-            // $_ENV['DATABASE_CONNECTION_STRING']
         );
     }
 
@@ -20 +31 @@
             return [];
         }
 
+        // Number has to be two digit
         $valh = $hour < 10 ? '0'.$hour : $hour;
         $openData = $this->manager->executeQuery('open-data-db.'.$name.$date, new Query(['date' => $date.'-'.$valh], []));
 
+        // Converts result to php array
         $openData->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -35 +48 @@
     public function getAvailableCollections() {
         $openData = $this->manager->executeQuery('open-data-db.DATASETS', new Query([], ['projection' => ['key-name' => 1, 'display-name' => 1, '_id' => 0]]));
 
+        // Converts result to php array
         $openData->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -104 +118 @@
 
         $max = $this->manager->executeQuery('open-data-db.'.$name.$date, new Query([], ['sort' => ['number' => -1], 'limit' => 1]));
 
+        // Converts result to php array
         $max->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -122 +137 @@
 
         $positions = $this->manager->executeQuery('open-data-db.'.$name.'DEVICES', new Query([], []));
 
+        // Converts result to php array
         $positions->setTypeMap([
             'array' => 'array',
             'document' => 'array',

website/src/Utils/Utils.php

@@ -2 +2 @@
 
 namespace App\Utils;
 
+/**
+ * Class for static helper functions.
+ */
 class Utils {
+    /**
+     * Transforms array of arrays in form [['display-name' => whatever, 'key-name' => whatever, ...], ...]
+     * to simple array in form [dataset-display-name => dataset-key-name, ...].
+     *
+     * @param array of arrays for tranformation
+     *
+     * @return array in form [dataset-display-name => dataset-key-name, ...]
+     */
     public static function prepareDatasetsNames($datasets) {
         $names = [];