From 83e5eeb1a393701236ced7c8f35822743c40cc95 Mon Sep 17 00:00:00 2001 From: Ramez Ashraf Date: Sun, 24 Sep 2023 10:41:05 +0300 Subject: [PATCH] Docs for settings + enhancements --- README.rst | 7 -- docs/source/charts.rst | 114 --------------------- docs/source/howto/override_filter_form.rst | 0 docs/source/index.rst | 2 - docs/source/ref/settings.rst | 29 ++++-- 5 files changed, 22 insertions(+), 130 deletions(-) delete mode 100644 docs/source/charts.rst delete mode 100644 docs/source/howto/override_filter_form.rst diff --git a/README.rst b/README.rst index 792ec3c..cb97be3 100644 --- a/README.rst +++ b/README.rst @@ -239,13 +239,6 @@ You can also use locally the ``create_entries`` command will generate data for the demo app -A Preview: - -.. image:: https://i.ibb.co/SvxTM23/Selection-294.png - :target: https://i.ibb.co/SvxTM23/Selection-294.png - :alt: Shipped in View Page - - Documentation ------------- diff --git a/docs/source/charts.rst b/docs/source/charts.rst deleted file mode 100644 index 3dafcef..0000000 --- a/docs/source/charts.rst +++ /dev/null @@ -1,114 +0,0 @@ -Charting and Front End Customization -===================================== - -Charts Configuration ---------------------- - -Charts settings is a list of objects which each object represent a chart configurations. - -* type: what kind of chart it is: Possible options are bar, pie, line and others subject of the underlying charting engine. - Hats off to : `Charts.js `_. -* engine_name: String, default to ``SLICK_REPORTING_DEFAULT_CHARTS_ENGINE``. Passed to front end in order to use the appropriate chart engine. - By default supports `highcharts` & `chartsjs`. -* data_source: Field name containing the numbers we want to plot. -* title_source: Field name containing labels of the data_source -* title: the Chart title. Defaults to the `report_title`. -* plot_total if True the chart will plot the total of the columns. Useful with time series and crosstab reports. - -On front end, for each chart needed we pass the whole response to the relevant chart helper function and it handles the rest. - - - - -The ajax response structure ---------------------------- - -Understanding how the response is structured is imperative in order to customize how the report is displayed on the front end - -Let's have a look - -.. code-block:: python - - - # Ajax response or `report_results` template context variable. - response = { - # the report slug, defaults to the class name all lower - "report_slug": "", - # a list of objects representing the actual results of the report - "data": [ - { - "name": "Product 1", - "quantity__sum": "1774", - "value__sum": "8758", - "field_x": "value_x", - }, - { - "name": "Product 2", - "quantity__sum": "1878", - "value__sum": "3000", - "field_x": "value_x", - }, - # etc ..... - ], - # A list explaining the columns/keys in the data results. - # ie: len(response.columns) == len(response.data[i].keys()) - # It contains needed information about verbose name , if summable and hints about the data type. - "columns": [ - { - "name": "name", - "computation_field": "", - "verbose_name": "Name", - "visible": True, - "type": "CharField", - "is_summable": False, - }, - { - "name": "quantity__sum", - "computation_field": "", - "verbose_name": "Quantities Sold", - "visible": True, - "type": "number", - "is_summable": True, - }, - { - "name": "value__sum", - "computation_field": "", - "verbose_name": "Value $", - "visible": True, - "type": "number", - "is_summable": True, - }, - ], - # Contains information about the report as whole if it's time series or a a crosstab - # And what's the actual and verbose names of the time series or crosstab specific columns. - "metadata": { - "time_series_pattern": "", - "time_series_column_names": [], - "time_series_column_verbose_names": [], - "crosstab_model": "", - "crosstab_column_names": [], - "crosstab_column_verbose_names": [], - }, - # A mirror of the set charts_settings on the ReportView - # ``ReportView`` populates the id and the `engine_name' if not set - "chart_settings": [ - { - "type": "pie", - "engine_name": "highcharts", - "data_source": ["quantity__sum"], - "title_source": ["name"], - "title": "Pie Chart (Quantities)", - "id": "pie-0", - }, - { - "type": "bar", - "engine_name": "chartsjs", - "data_source": ["value__sum"], - "title_source": ["name"], - "title": "Column Chart (Values)", - "id": "bar-1", - }, - ], - } - - diff --git a/docs/source/howto/override_filter_form.rst b/docs/source/howto/override_filter_form.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/index.rst b/docs/source/index.rst index 49882cc..37a577f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -90,8 +90,6 @@ Next step :ref:`tutorial` concept tutorial topics/index - howto/index - charts ref/index diff --git a/docs/source/ref/settings.rst b/docs/source/ref/settings.rst index a34f726..d303de4 100644 --- a/docs/source/ref/settings.rst +++ b/docs/source/ref/settings.rst @@ -12,12 +12,12 @@ Below are the default settings for django-slick-reporting. You can override them .. code-block:: python - SLICK_REPORTING_SETTINGS_DEFAULT = { + SLICK_REPORTING_SETTINGS = { "JQUERY_URL": "https://code.jquery.com/jquery-3.7.0.min.js", "DEFAULT_START_DATE_TIME": datetime( datetime.now().year, 1, 1, 0, 0, 0, tzinfo=timezone.utc - ), # 1st Jan of current year - "DEFAULT_END_DATE_TIME": datetime.datetime.today(), # today + ), # Default: 1st Jan of current year + "DEFAULT_END_DATE_TIME": datetime.datetime.today(), # Default to today "FONT_AWESOME": { "CSS_URL": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/all.min.css", "ICONS": { @@ -37,18 +37,33 @@ Below are the default settings for django-slick-reporting. You can override them }, } +* JQUERY_URL: + + Link to the jquery file, You can use set it to False and manage the jQuery addition to your liking + +* DEFAULT_START_DATE_TIME + + Default date time that would appear on the filter form in the start date + +* DEFAULT_END_DATE_TIME + + Default date time that would appear on the filter form in the end date + +* FONT_AWESOME: -*. FONT_AWESOME Font awesome is used to display the icon next to the chart title. You can override the following settings: + 1. ``CSS_URL``: URL to the font-awesome css file 2. ``ICONS``: Icons used for different chart types. -*. CHARTS: +* CHARTS: + The entry points for displaying charts on the front end. - YOu can add your own chart engine by adding an entry to this dictionary. + You can add your own chart engine by adding an entry to this dictionary. * MESSAGES: - The strings used in the front end. You can override them here, it also gives a chance to set and translate them per your requirements. + + The strings used in the front end. You can override them here, it also gives a chance to set and translate them per your requirements. Old versions settings: