Issue #2879533 by lbaran: Improve Charts code documentation

charts.api.php

@@ -50,15 +50,15 @@ use Drupal\charts\Theme\ChartsInterface;
  * chart_data, chart_xaxis, and chart_yaxis). For a full list, see the
  * charts_element_info() function.
  *
- *
  * @see charts_element_info()
- *
- *
+ */
+
+/**
  * Alter an individual chart before it is printed.
  *
- * @param $chart
+ * @param array $chart
  *   The chart renderable. Passed in by reference.
- * @param $chart_id
+ * @param string $chart_id
  *   The chart identifier, pulled from the $chart['#chart_id'] property (if
  *   any). Not all charts have a chart identifier.
  */
@@ -76,9 +76,12 @@ function hook_chart_alter(&$chart, $chart_id) {
  * name instead of being passed in as an argument.
  *
  * @see hook_chart_alter()
- * @param $chart
+ *
+ * @param array $chart
+ *   Chart.
  */
 function hook_chart_CHART_ID_alter(&$chart) {
+  
 }
 
 /**
@@ -93,13 +96,14 @@ function hook_chart_CHART_ID_alter(&$chart) {
  * Even though this hook may be fragile, it may provide developers with access
  * to library-specific functionality.
  *
- * @param $definition
+ * @param array $definition
  *   The chart definition to be modified. The raw values are passed directly to
  *   the charting library.
- * @param $chart
+ * @param array $chart
  *   The chart renderable. This may be used for reference (or read to add
  *   support for new properties), but any changes to this variable will not
  *   have an effect on output.
+ *
  * @internal param $chart_id The chart ID, derived from the $chart['#chart_id'] property. Note that not*   The chart ID, derived from the $chart['#chart_id'] property. Note that not
  *   all charts may have a $chart_id.
  */
@@ -111,8 +115,10 @@ function hook_chart_definition_alter(&$definition, $chart) {
  *
  * Same as hook_chart_definition_alter(), only including the $chart_id in the
  * function name instead of being passed in as an argument.
- * @see hook_chart_definition_alter()
- * @param $chart
+ * @see hook_chart_definition_alter().
+ *
+ * @param array $chart
+ *   Chart.
  */
 function hook_chart_definition_CHART_ID_alter(&$chart) {
 }
@@ -143,7 +149,9 @@ function hook_charts_info() {
  *
  * If your module needs to modify the capabilities of a charting library, such
  * as to add support for a new chart type, it may do so with this hook.
- * @param $info
+ *
+ * @param array $info
+ *   Info.
  */
 function hook_charts_info_alter(&$info) {
   // Say the Google charts library supports geo charts.
@@ -167,7 +175,8 @@ function hook_charts_type_info() {
     // Many charting libraries always refer to the main axis as the "y-axis",
     // even if the chart's main axis is horizontal. An example of this is a
     // bar chart, where the values are along the horizontal axis.
-    'axis_inverted' => TRUE, // Meaning x/y axis are flipped.
+    // Meaning x/y axis are flipped.
+    'axis_inverted' => TRUE,
     // For bar/area/other charts that support stacking of series, set this value
     // to TRUE.
     'stacking' => TRUE,
@@ -180,7 +189,9 @@ function hook_charts_type_info() {
  *
  * If your module needs to modify the capabilities or labels of a paricular
  * chart type, it may alter the definitions provided by other modules.
- * @param $chart_types
+ *
+ * @param array $chart_types
+ *   Chart Types.
  */
 function hook_charts_type_info_alter(&$chart_types) {
   $chart_types['bar']['stacking'] = FALSE;

charts.module

@@ -2,14 +2,14 @@
 
 /**
  * @file
- * Charts module file that provides hook_theme.
+ * Charts - Module.
  */
 
 use Drupal\charts\Util\Util;
 use Drupal\charts\Charts\ModuleSelector;
 
 /**
- * {@inheritdoc}
+ * Implements hook_theme().
  */
 function charts_theme($existing, $type, $theme, $path) {
 
@@ -17,14 +17,14 @@ function charts_theme($existing, $type, $theme, $path) {
     'views_view_charts' => [
       'variables' => [
         'view' => NULL,
-        'row' => NULL,
+        'row'  => NULL,
       ],
     ],
   ];
 }
 
 /**
- * {@inheritdoc}
+ * Implements template_preprocess_views_view_charts().
  */
 function template_preprocess_views_view_charts(&$variables) {
 
@@ -91,6 +91,9 @@ function template_preprocess_views_view_charts(&$variables) {
     $attachmentDisplayOptions[$i]['inherit_yaxis'] = $view->displayHandlers->get($attachmentId)->options['inherit_yaxis'];
   }
   $seriesData = array_merge($seriesData, $seriesDataAttachment);
-  $moduleSelector = new ModuleSelector($library, $categories, $seriesData, $options, $attachmentDisplayOptions, $variables, $chartId);
+  $moduleSelector = new ModuleSelector($library, $categories, $seriesData, $options, $attachmentDisplayOptions, $chartId);
+  if ($moduleSelector->moduleExists()) {
+    $moduleSelector->buildVariables($variables);
+  }
 
 }

charts.permissions.yml

-# In charts.permissions.yml file.
-access all charts:
+'access all charts':
   title: 'Administer Charts'
   description: 'This permission needs to be fleshed out.'
-  restrict access: TRUE
+  'restrict access': true

charts.routing.yml

 charts.settings:
-  path: '/admin/config/content/charts'
+  path: /admin/config/content/charts
   defaults:
-    _form: 'Drupal\charts\Form\ChartsConfigForm'
+    _form: Drupal\charts\Form\ChartsConfigForm
     _title: 'Default chart configuration'
   requirements:
     _permission: 'administer site configuration'

charts.services.yml

 services:
   charts.charts_service:
     class: Drupal\charts\Services\ChartService
-
   charts.charts_attachment:
     class: Drupal\charts\Services\ChartAttachmentService
-
   charts.views_variable:
     class: Drupal\charts\Services\ViewsDataService
-
   charts.settings:
     class: Drupal\charts\Services\ChartsSettingsService
     arguments: ['@config.factory']

includes/charts.pages.inc

@@ -244,7 +244,7 @@ function charts_settings_form($form, $defaults = [], $field_options = [], $paren
 
   // Set data attributes to identify special properties of different types.
   foreach ($chart_types as $chart_type => $chart_type_info) {
-    if ($chart_type_info['axis_inverted']) {
+    if (isset($chart_type_info['axis_inverted']) && $chart_type_info['axis_inverted']) {
       $form['type'][$chart_type]['#attributes']['data-axis-inverted'] = TRUE;
     }
     if ($chart_type_info['axis'] === ChartsInterface::CHARTS_SINGLE_AXIS) {
@@ -256,7 +256,6 @@ function charts_settings_form($form, $defaults = [], $field_options = [], $paren
     $first_field = key($field_options);
 
     // $form['#theme'] = 'charts_settings_fields';
-
     $form['fields'] = [
       '#title' => t('Charts fields'),
       '#type' => 'fieldset',
@@ -602,34 +601,34 @@ function charts_default_settings_form_submit($form, $form_state) {
  * Provides default options used by charts_settings_form().
  */
 function charts_default_settings() {
-  $defaults = [];
-  $defaults['type'] = 'pie';
-  $defaults['library'] = NULL;
-  $defaults['label_field'] = NULL;
-  $defaults['data_fields'] = NULL;
-  $defaults['field_colors'] = NULL;
-  $defaults['title'] = '';
-  $defaults['title_position'] = 'out';
-  $defaults['data_labels'] = FALSE;
-  $defaults['legend'] = TRUE;
-  $defaults['legend_position'] = 'right';
-  $defaults['colors'] = charts_default_colors();
-  $defaults['background'] = '';
-  $defaults['tooltips'] = TRUE;
-  $defaults['tooltips_use_html'] = FALSE;
-  $defaults['width'] = NULL;
-  $defaults['height'] = NULL;
-  $defaults['xaxis_title'] = '';
-  $defaults['xaxis_labels_rotation'] = 0;
-  $defaults['yaxis_title'] = '';
-  $defaults['yaxis_min'] = '';
-  $defaults['yaxis_max'] = '';
-  $defaults['yaxis_prefix'] = '';
-  $defaults['yaxis_suffix'] = '';
-  $defaults['yaxis_decimal_count'] = '';
-  $defaults['yaxis_labels_rotation'] = 0;
+  $defaults = [
+    'type'                  => 'pie',
+    'library'               => NULL,
+    'label_field'           => NULL,
+    'data_fields'           => NULL,
+    'field_colors'          => NULL,
+    'title'                 => '',
+    'title_position'        => 'out',
+    'data_labels'           => FALSE,
+    'legend'                => TRUE,
+    'legend_position'       => 'right',
+    'colors'                => charts_default_colors(),
+    'background'            => '',
+    'tooltips'              => TRUE,
+    'tooltips_use_html'     => FALSE,
+    'width'                 => NULL,
+    'height'                => NULL,
+    'xaxis_title'           => '',
+    'xaxis_labels_rotation' => 0,
+    'yaxis_title'           => '',
+    'yaxis_min'             => '',
+    'yaxis_max'             => '',
+    'yaxis_prefix'          => '',
+    'yaxis_suffix'          => '',
+    'yaxis_decimal_count'   => '',
+    'yaxis_labels_rotation' => 0,
+  ];
 
   Drupal::moduleHandler()->alter('charts_default_settings', $defaults);
   return $defaults;
 }
-

modules/charts_api_example/README.txt

@@ -5,4 +5,4 @@ To see the example, navigate to:
 Settings for this chart derive from the Charts module's 
 default settings, which are configured here:
 
-/admin/config/content/charts
+/admin/config/content/charts
\ No newline at end of file

modules/charts_api_example/charts_api_example.info.yml

-name: Charts API Example
+name: 'Charts API Example'
 type: module
-description: Demonstrates how to use the Charts module without Views.
+description: 'Demonstrates how to use the Charts module without Views.'
 core: 8.x
 package: Examples
 dependencies:
-  - charts:charts
+  - 'charts:charts'

modules/charts_api_example/charts_api_example.libraries.yml

-charts_api_examples:
-  version: 1.x
-  js:
-    js/charts_api_example.js: {}
\ No newline at end of file

modules/charts_api_example/charts_api_example.module

@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Contains charts_api_example.module.
+ * Charts Api Example - Module.
  */
 
 use Drupal\Core\Routing\RouteMatchInterface;
@@ -12,41 +12,40 @@ use Drupal\charts\Charts\ModuleSelector;
  * Implements hook_help().
  */
 function charts_api_example_help($route_name, RouteMatchInterface $route_match) {
+  $output = '';
   switch ($route_name) {
     // Main module help for the charts_api_example module.
     case 'help.page.charts_api_example':
-      $output = '';
       $output .= '<h3>' . t('About') . '</h3>';
       $output .= '<p>' . t('A simple example on how to interact with the Charts API') . '</p>';
-      return $output;
-
-    default:
+      break;
   }
+  return $output;
 }
 
 /**
  * Implements hook_theme().
  */
 function charts_api_example_theme() {
-  $vars = [
-    'library' => '',
-    'categories' => '',
-    'seriesData' => '',
-    'options' => '',
-  ];
   return [
     'charts_api_example' => [
-      'template' => 'charts_api_example',
-      'variables' => $vars,
+      'template'  => 'charts_api_example',
+      'variables' => [
+        'library'    => '',
+        'categories' => [],
+        'seriesData' => [],
+        'options'    => [],
+      ],
     ],
   ];
 }
 
 /**
- * Implements template_preprocess_page
- *
- * @param $variables
+ * Implements template_preprocess_charts_api_example().
  */
 function template_preprocess_charts_api_example(&$variables) {
-  $moduleSelector = new ModuleSelector($variables['library'], $variables['categories'], $variables['seriesData'], $variables['options'], [], $variables, 'xyz');
-}
+  $moduleSelector = new ModuleSelector($variables['library'], $variables['categories'], $variables['seriesData'], $variables['options'], [], 'xyz');
+  if ($moduleSelector->moduleExists()) {
\ No newline at end of file
+    $moduleSelector->buildVariables($variables);
+  }
+}

modules/charts_api_example/charts_api_example.routing.yml

 charts_api_example.display:
-  path: '/charts/example/display'
+  path: /charts/example/display
   defaults:
     _controller: '\Drupal\charts_api_example\Controller\ChartsApiExample::display'
     _title: 'How to use the Charts API'

modules/charts_api_example/src/Controller/ChartsApiExample.php

@@ -47,20 +47,35 @@ class ChartsApiExample extends ControllerBase implements ContainerInjectionInter
     ];
 
     // Sample data format.
-    $categories = ["Category 1", "Category 2", "Category 3", "Category 4"];
+    $categories = ['Category 1', 'Category 2', 'Category 3', 'Category 4'];
     $seriesData = [
-      ["name" => "Series 1", "color" => "#0d233a", "type" => null, "data" => [250, 350, 400, 200]],
-      ["name" => "Series 2", "color" => "#8bbc21", "type" => "column", "data" => [150, 450, 500, 300]],
-      ["name" => "Series 3", "color" => "#910000", "type" => "area", "data" => [0, 0, 60, 90]]
+      [
+        'name'  => 'Series 1',
+        'color' => '#0d233a',
+        'type'  => NULL,
+        'data'  => [250, 350, 400, 200],
+      ], [
+        'name'  => 'Series 2',
+        'color' => '#8bbc21',
+        'type'  => 'column',
+        'data'  => [150, 450, 500, 300],
+      ], [
+        'name'  => 'Series 3',
+        'color' => '#910000',
+        'type'  => 'area',
+        'data'  => [0, 0, 60, 90],
+      ],
     ];
 
-    return [
+    $build = [
       '#theme'      => 'charts_api_example',
       '#library'    => (string) $library,
       '#categories' => $categories,
       '#seriesData' => $seriesData,
       '#options'    => $options,
     ];
+    
+    return $build;
   }
 
   /**
@@ -71,4 +86,5 @@ class ChartsApiExample extends ControllerBase implements ContainerInjectionInter
       $container->get('charts.settings')
     );
   }
-}
+
\ No newline at end of file
+}

modules/charts_api_example/templates/charts_api_example.html.twig

 {% set library = 'charts_' ~ chart_type ~ '/' ~ chart_type %}
 {{ attach_library("#{ library }") }}
 <p>Edit charts_api_example.html.twig to delete this message. To change the
-   library used by this file, change the <a href="/admin/config/content/charts">
-        default settings
-    </a>.</p>
+   library used by this file, change the <a href="{{ url('charts.settings',{}) }}">default settings</a>.
+</p>
 <div {{ attributes }} {{ content_attributes }} style="width:100%; height:400px;"></div>

modules/charts_c3/charts_c3.info.yml

-name: C3 Charts
+name: 'C3 Charts'
 type: module
 description: 'Charts module integration with C3 Charts.'
 package: Charts
 core: 8.x
 dependencies:
-  - charts:charts
+  - 'charts:charts'

modules/charts_c3/charts_c3.libraries.yml

 charts_c3:
   version: 1.x
   js:
-    js/charts_c3.js: {}
+    js/charts_c3.js: {  }
   dependencies:
-        - core/jquery
-        - core/jquery.once
-        - core/drupal
+    - core/jquery
+    - core/jquery.once
+    - core/drupal
 d3:
-  remote: https://d3js.org/d3.v3.min.js
+  remote: 'https://d3js.org/d3.v3.min.js'
   version: 3
   license:
-        name: BSD
-        url: https://en.wikipedia.org/wiki/BSD_licenses
-        gpl-compatible: false
+    name: BSD
+    url: 'https://en.wikipedia.org/wiki/BSD_licenses'
+    gpl-compatible: false
   js:
-    vendor/dthree/d3.v3.min.js: {}
-
+    vendor/dthree/d3.v3.min.js: {  }
 c3:
-  remote: https://cdnjs.cloudflare.com/ajax/libs/c3/0.4.11/c3.min.js
+  remote: 'https://cdnjs.cloudflare.com/ajax/libs/c3/0.4.11/c3.min.js'
   version: 0.4.11
   license:
-        name: MIT
-        url: https://opensource.org/licenses/MIT
-        gpl-compatible: true
+    name: MIT
+    url: 'https://opensource.org/licenses/MIT'
+    gpl-compatible: true
   css:
     theme:
-      vendor/cthree/css/c3.min.css: {}
+      vendor/cthree/css/c3.min.css: {  }
   js:
-    vendor/cthree/c3.min.js: {}
+    vendor/cthree/c3.min.js: {  }
   dependencies:
-        - charts_c3/charts_c3
-        - charts_c3/d3
+    - charts_c3/charts_c3
+    - charts_c3/d3
\ No newline at end of file

modules/charts_c3/src/Charts/C3ChartsRender.php

@@ -11,31 +11,33 @@ use Drupal\charts_c3\Settings\CThree\ChartData;
 use Drupal\charts_c3\Settings\CThree\ChartColor;
 use Drupal\charts_c3\Settings\CThree\ChartAxis;
 
+/**
+ * C3 Charts Render.
+ */
 class C3ChartsRender implements ChartsRenderInterface {
 
+  /**
+   * Construct.
+   */
   public function __construct() {
     Util::checkMissingLibrary('charts_c3', '/vendor/cthree/c3.min.js');
   }
 
   /**
-   * @param $options
-   * @param array $categories
-   * @param array $seriesData
-   * @param $chartId
-   * @param array $attachmentDisplayOptions
-   *
-   * @return CThree
+   * {@inheritdoc}
    */
-  public function charts_render_charts($options, $categories = [], $seriesData = [], $attachmentDisplayOptions = [], &$variables, $chartId) {
+  public function chartsRenderCharts(array $options = [], array $categories = [], array $seriesData = [], array $attachmentDisplayOptions = [],array &$variables = [], $chartId = '') {
     $noAttachmentDisplays = count($attachmentDisplayOptions) === 0;
     $types = [];
 
     // @todo - make this work for more that one attachment.
     for ($i = 1; $i <= count($attachmentDisplayOptions); $i++) {
-      if ($attachmentDisplayOptions[$i - 1]['style']['options']['type'] == 'column')
+      if ($attachmentDisplayOptions[$i - 1]['style']['options']['type'] == 'column') {
         $types[$seriesData[$i]['name']] = 'bar';
-      else
+      }
+      else {
         $types[$seriesData[$i]['name']] = $attachmentDisplayOptions[$i - 1]['style']['options']['type'];
+      }
     }
     $c3Data = [];
     for ($i = 0; $i < count($seriesData); $i++) {
@@ -61,14 +63,14 @@ class C3ChartsRender implements ChartsRenderInterface {
     // Sets the primary y axis.
     $yAxis = [];
     $yAxis[$seriesData[0]['name']] = 'y';
-    $showAxis['show'] = true;
+    $showAxis['show'] = TRUE;
     $showAxis['label'] = $options['yaxis_title'];
     $chartAxis->y = $showAxis;
 
     // Sets secondary axis from the first attachment only.
     if (!$noAttachmentDisplays && $attachmentDisplayOptions[0]['inherit_yaxis'] == 0) {
       $yAxis[$seriesData[1]['name']] = 'y2';
-      $showSecAxis['show'] = true;
+      $showSecAxis['show'] = TRUE;
       $showSecAxis['label'] = $attachmentDisplayOptions[0]['style']['options']['yaxis_title'];
       $chartAxis->y2 = $showSecAxis;
     }
@@ -117,4 +119,5 @@ class C3ChartsRender implements ChartsRenderInterface {
     $variables['attributes']['id'][0] = $chartId;
     $variables['attributes']['class'][] = 'charts-c3';
   }
+
 }

modules/charts_google/charts_google.info.yml

-name: Google Charts
+name: 'Google Charts'
 type: module
 description: 'Charts module integration with Google Charts.'
 package: Charts
 core: 8.x
 dependencies:
-  - charts:charts
+  - 'charts:charts'

modules/charts_google/charts_google.libraries.yml

 charts_google:
   version: 1.x
   js:
-    js/charts_google.js: {}
+    js/charts_google.js: {  }
   dependencies:
-        - core/jquery
-        - core/jquery.once
-        - core/drupal
-
+    - core/jquery
+    - core/jquery.once
+    - core/drupal
 google:
-  remote: https://www.gstatic.com/charts/loader.js
+  remote: 'https://www.gstatic.com/charts/loader.js'
   version: VERSION
   license:
-      name: Apache 2.0
-      url: http://www.apache.org/licenses/LICENSE-2.0
-      gpl-compatible: false
+    name: 'Apache 2.0'
+    url: 'http://www.apache.org/licenses/LICENSE-2.0'
+    gpl-compatible: false
   js:
-    vendor/google/loader.js: {}
+    vendor/google/loader.js: {  }
   dependencies:
-        - charts_google/charts_google
+    - charts_google/charts_google

modules/charts_google/charts_google.module

@@ -12,10 +12,10 @@ use Drupal\charts\Theme\ChartsInterface;
  */
 function charts_google_charts_info() {
   $info['google'] = [
-    'label' => t('Google Charts'),
+    'label'  => t('Google Charts'),
     'render' => '_charts_google_render',
-    'types' => ['area', 'bar', 'column', 'donut', 'line', 'pie', 'scatter'],
-    'file' => 'charts_google.inc',
+    'types'  => ['area', 'bar', 'column', 'donut', 'line', 'pie', 'scatter'],
+    'file'   => 'charts_google.inc',
   ];
   return $info;
 }