+
+{% endblock %}
\ No newline at end of file
diff --git a/demo_proj/templates/home.html b/demo_proj/templates/home.html
new file mode 100644
index 0000000..baaa104
--- /dev/null
+++ b/demo_proj/templates/home.html
@@ -0,0 +1,59 @@
+{% extends "base.html" %}
+
+{% block content %}
+
+
+
Welcome to Django Slick Reporting
+
Powerful and Efficient reporting engine with Charting capabilities.
+ Allowing you to create professional analytics that are customizable and efficient.
Effortlessly create Simple, Grouped, Time series and Crosstab reports in a handful of code lines.
+ You can also create your Custom Calculation easily, which will be integrated with the above reports
+ types
\ No newline at end of file
diff --git a/demo_proj/templates/slick_reporting/base.html b/demo_proj/templates/slick_reporting/base.html
new file mode 100644
index 0000000..6932026
--- /dev/null
+++ b/demo_proj/templates/slick_reporting/base.html
@@ -0,0 +1,17 @@
+{% extends "base.html" %}
+
+
+{% block page_title %}
+ {{ report_title }}
+{% endblock %}
+{% block meta_page_title %}
+ {{ report_title }}
+
+{% endblock %}
+
+{% block extrajs %}
+ {{ block.super }}
+
+ {% include "slick_reporting/js_resources.html" %}
+
+{% endblock %}
\ No newline at end of file
diff --git a/demo_proj/templates/widget_template_with_pre.html b/demo_proj/templates/widget_template_with_pre.html
new file mode 100644
index 0000000..f4f19f7
--- /dev/null
+++ b/demo_proj/templates/widget_template_with_pre.html
@@ -0,0 +1,6 @@
+{% extends "slick_reporting/widget_template.html" %}
+{% block widget_content %}
+
+
+
+{% endblock %}
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 816af2a..49882cc 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -37,7 +37,7 @@ You can start by using ``ReportView`` which is a subclass of ``django.views.gene
# in views.py
from slick_reporting.views import ReportView, Chart
- from slick_reporting.fields import SlickReportField
+ from slick_reporting.fields import ComputationField
from .models import MySalesItems
from django.db.models import Sum
@@ -50,7 +50,7 @@ You can start by using ``ReportView`` which is a subclass of ``django.views.gene
columns = [
"title",
- SlickReportField.create(
+ ComputationField.create(
method=Sum, field="value", name="value__sum", verbose_name="Total sold $"
),
]
@@ -89,8 +89,8 @@ Next step :ref:`tutorial`
concept
tutorial
- howto/index
topics/index
+ howto/index
charts
ref/index
diff --git a/docs/source/ref/computation_field.rst b/docs/source/ref/computation_field.rst
index 1c5a157..2d6ce38 100644
--- a/docs/source/ref/computation_field.rst
+++ b/docs/source/ref/computation_field.rst
@@ -16,12 +16,12 @@ Let's see how it's written in `slick_reporting.fields`
.. code-block:: python
- from slick_reporting.fields import SlickReportField
+ from slick_reporting.fields import ComputationField
from slick_reporting.decorators import report_field_register
@report_field_register
- class TotalQTYReportField(SlickReportField):
+ class TotalQTYReportField(ComputationField):
# The name to use when using this field in the generator
name = '__total_quantity__'
@@ -43,7 +43,7 @@ If you want AVG to the field `price` then the ReportField would look like this
from django.db.models import Avg
@report_field_register
- class TotalQTYReportField(SlickReportField):
+ class TotalQTYReportField(ComputationField):
name = '__avg_price__'
calculation_field = 'price'
@@ -101,10 +101,10 @@ Two side calculation
# Document how a single field can be computed like a debit and credit.
-SlickReportField API
+ComputationField API
--------------------
-.. autoclass:: slick_reporting.fields.SlickReportField
+.. autoclass:: slick_reporting.fields.ComputationField
.. autoattribute:: name
.. autoattribute:: calculation_field
diff --git a/docs/source/ref/view_options.rst b/docs/source/ref/view_options.rst
index a98ce92..d96a98d 100644
--- a/docs/source/ref/view_options.rst
+++ b/docs/source/ref/view_options.rst
@@ -46,14 +46,14 @@ Below is the list of general options that is used across all types of reports.
.. code-block:: python
- class MyTotalReportField(SlickReportField):
+ class MyTotalReportField(ComputationField):
pass
class MyReport(ReportView):
columns = [
# a computation field created on the fly
- SlickReportField.create(Sum, "value", verbose_name=_("Value"), name="value"),
+ ComputationField.create(Sum, "value", verbose_name=_("Value"), name="value"),
# A computation Field class
MyTotalReportField,
@@ -95,7 +95,7 @@ Below is the list of general options that is used across all types of reports.
report_model = MySales
group_by = None
columns = [
- SlickReportField.create(Sum, "value", verbose_name=_("Value"), name="value")
+ ComputationField.create(Sum, "value", verbose_name=_("Value"), name="value")
]
Above code will return the calculated sum of all values in the report_model / queryset
diff --git a/docs/source/topics/crosstab_options.rst b/docs/source/topics/crosstab_options.rst
index 7e6e26a..14558dc 100644
--- a/docs/source/topics/crosstab_options.rst
+++ b/docs/source/topics/crosstab_options.rst
@@ -5,7 +5,10 @@ Crosstab Reports
Use crosstab reports, also known as matrix reports, to show the relationships between three or more query items.
Crosstab reports show data in rows and columns with information summarized at the intersection points.
-Here is a simple example of a crosstab report:
+
+General use case
+----------------
+Here is a general use case:
.. code-block:: python
@@ -14,129 +17,126 @@ Here is a simple example of a crosstab report:
from slick_reporting.views import ReportView
- class MyCrosstabReport(ReportView):
- group_by = "product"
- crosstab_field = "client"
- # the column you want to make a crosstab on, can be a foreign key or a choice field
-
- crosstab_columns = [
- SlickReportField.create(Sum, "value", verbose_name=_("Value")),
- ]
-
- crosstab_ids = [
- 1,
- 2,
- ] # a list of ids of the crosstab field you want to use. This will be passed on by the filter form, or , if set here, values here will be used.
- # OR in case of a choice / text field
- # crosstab_ids = ["my-choice-1", "my-choice-2", "my-choice-3"]
-
- crosstab_compute_remainder = True
- # Compute reminder will add a column with the remainder of the crosstab computed
- # Example: if you choose to do a cross tab on clientIds 1 & 2 , cross tab remainder will add a column with the calculation of all clients except those set/passed in crosstab_ids
+ class CrosstabReport(ReportView):
+ report_title = _("Cross tab Report")
+ report_model = SalesTransaction
+ group_by = "client"
+ date_field = "date"
columns = [
"name",
- "sku",
"__crosstab__",
# You can customize where the crosstab columns are displayed in relation to the other columns
- SlickReportField.create(Sum, "value", verbose_name=_("Total Value")),
- # This is the same as the Same as the calculation in the crosstab, but this one will be on the whole set. IE total value
+
+ ComputationField.create(Sum, "value", verbose_name=_("Total Value")),
+ # This is the same as the calculation in the crosstab,
+ # but this one will be on the whole set. IE total value.
]
+ crosstab_field = "product"
+ crosstab_columns = [
+ ComputationField.create(Sum, "value", verbose_name=_("Value")),
+ ]
-Customizing the crosstab ids
-----------------------------
+Crosstab on a Traversing Field
+------------------------------
+You can also crosstab on a traversing field. In the example below we extend the previous crosstab report to be on the product sizes
-For more fine tuned report, You can customize the ids of the crosstab report by suppling a list of tuples to the ``crosstab_ids_custom_filters`` attribute.
-the tuple should have 2 items, the first is a Q object(s) -if any- , and the second is a dict of kwargs filters that will be passed to the filter method of the ``report_model``.
+.. code-block:: python
-Example:
+ class CrosstabWithTraversingField(CrosstabReport):
+ crosstab_field = "product__size"
-.. code-block:: python
- from .models import MySales
+Customizing the crosstab ids
+----------------------------
+You can set the default ids that you want to crosstab on, so the initial report, ie without user setting anything, comes out with the values you want
+.. code-block:: python
- class MyCrosstabReport(ReportView):
+ class CrosstabWithIds(CrosstabReport):
+ def get_crosstab_ids(self):
+ return [Product.objects.first().pk, Product.objects.last().pk]
- date_field = "date"
- group_by = "product"
- report_model = MySales
- crosstab_columns = [
- SlickReportField.create(Sum, "value", verbose_name=_("Value")),
- ]
+Customizing the Crosstab Filter
+-------------------------------
- crosstab_ids_custom_filters = [
- (
- ~Q(special_field="something"),
- dict(flag="sales"),
- ), # special_field and flag are fields on the report_model .
- (None, dict(flag="sales-return")),
- ]
+For more fine tuned report, You can customize the crosstab report by supplying a list of tuples to the ``crosstab_ids_custom_filters`` attribute.
+The tuple should have 2 items, the first is a list of Q object(s) -if any- , and the second is a dict of kwargs filters . Both will be passed to the filter method of the ``report_model``.
- # These settings has NO EFFECT if crosstab_ids_custom_filters is set
- crosstab_field = "client"
- crosstab_ids = [1, 2]
- crosstab_compute_remainder = True
+Example:
+
+.. code-block:: python
+ class CrosstabWithIdsCustomFilter(CrosstabReport):
+ crosstab_ids_custom_filters = [
+ (~Q(product__size__in=["extra_big", "big"]), dict()),
+ (None, dict(product__size__in=["extra_big", "big"])),
+ ]
+ # Note:
+ # if crosstab_ids_custom_filters is set, these settings has NO EFFECT
+ # crosstab_field = "client"
+ # crosstab_ids = [1, 2]
+ # crosstab_compute_remainder = True
-Having Time Series Crosstab Reports
------------------------------------
-You can have a crosstab report in a time series by setting the :ref:`time_series_options` in addition to the crosstab options.
Customizing the verbose name of the crosstab columns
----------------------------------------------------
-You can customize the verbose name of the crosstab columns by Customizing the ``ReportField`` and setting the ``crosstab_field_verbose_name`` attribute to your custom class.
+Similar to what we did in customizing the verbose name of the computation field for the time series,
+Here, We also can customize the verbose name of the crosstab columns by Subclass ``ComputationField`` and setting the ``crosstab_field_verbose_name`` attribute on your custom class.
Default is that the verbose name will display the id of the crosstab field, and the remainder column will be called "The remainder".
+Let's see two examples on how we can customize the verbose name.
-.. code-block:: python
+Example 1: On a "regular" crosstab report
- class CustomCrossTabTotalField(SlickReportField):
+.. code-block:: python
+ class CustomCrossTabTotalField(ComputationField):
calculation_field = "value"
calculation_method = Sum
- verbose_name = _("Total Value")
+ verbose_name = _("Sales for")
+ name = "sum__value"
@classmethod
def get_crosstab_field_verbose_name(cls, model, id):
- from .models import Client
+ if id == "----": # 4 dashes: the remainder column
+ return _("Rest of Products")
- if id == "----": # the remainder column
- return _("Rest of clients")
- name = Client.objects.get(pk=id).name
- # OR if you crosstab on a choice field
- # name = get_choice_name(model, "client", id)
+ name = Product.objects.get(pk=id).name
return f"{cls.verbose_name} {name}"
-Example
--------
+ class CrossTabReportWithCustomVerboseName(CrosstabReport):
+ crosstab_columns = [
+ CustomCrossTabTotalField
+ ]
-.. code-block:: python
+Example 2: On the ``crosstab_ids_custom_filters`` one
- from .models import MySales
+.. code-block:: python
+ class CustomCrossTabTotalField2(CustomCrossTabTotalField):
- class MyCrosstabReport(ReportView):
+ @classmethod
+ def get_crosstab_field_verbose_name(cls, model, id):
+ if id == 0:
+ return f"{cls.verbose_name} Big and Extra Big"
+ return f"{cls.verbose_name} all other sizes"
- date_field = "date"
- group_by = "product"
- report_model = MySales
- crosstab_field = "client"
- crosstab_columns = [
- SlickReportField.create(Sum, "value", verbose_name=_("Value")),
- ]
+ class CrossTabReportWithCustomVerboseNameCustomFilter(CrosstabWithIdsCustomFilter):
+ crosstab_columns = [
+ CustomCrossTabTotalField2
+ ]
- crosstab_ids = [1, 2] # either set here via the filter form
- crosstab_compute_remainder = True
-The above code would return a result like this:
+Example
+-------
.. image:: _static/crosstab.png
:width: 800
diff --git a/docs/source/topics/group_by_report.rst b/docs/source/topics/group_by_report.rst
index 8fa53e1..81e7c63 100644
--- a/docs/source/topics/group_by_report.rst
+++ b/docs/source/topics/group_by_report.rst
@@ -22,7 +22,7 @@ Example:
columns = [
"name",
- SlickReportField.create(
+ ComputationField.create(
method=Sum, field="value", name="value__sum", verbose_name="Total sold $", is_summable=True,
),
]
@@ -89,7 +89,7 @@ Example:
columns = [
"__index__",
- SlickReportField.create(Sum, "value", verbose_name=_("Total Sold $"), name="value"),
+ ComputationField.create(Sum, "value", verbose_name=_("Total Sold $"), name="value"),
]
chart_settings = [
@@ -126,3 +126,26 @@ It just hold the index of the row in the group.
its verbose name (ie the one on the table header) can be customized via ``group_by_custom_querysets_column_verbose_name``
You can then customize the *value* of the __index__ column via ``format_row`` hook
+
+The No Group By
+---------------
+Sometimes you want to get some calculations done on the whole report_model, without a group_by.
+You can do that by having the calculation fields you need in the columns, and leave out the group by.
+
+Example:
+
+.. code-block:: python
+
+ class NoGroupByReport(ReportView):
+ report_model = SalesTransaction
+ report_title = _("No-Group-By Report [WIP]")
+ date_field = "date"
+ group_by = ""
+
+ columns = [
+ ComputationField.create(
+ method=Sum, field="value", name="value__sum", verbose_name="Total sold $", is_summable=True,
+ ),
+ ]
+
+This report will give one number, the sum of all the values in the ``value`` field of the ``SalesTransaction`` model, within a period.
diff --git a/docs/source/topics/time_series_options.rst b/docs/source/topics/time_series_options.rst
index 5adf363..734e3ec 100644
--- a/docs/source/topics/time_series_options.rst
+++ b/docs/source/topics/time_series_options.rst
@@ -6,7 +6,10 @@ Time Series Reports
A Time series report is a report that is generated for a periods of time.
The period can be daily, weekly, monthly, yearly or custom, calculations will be performed for each period in the time series.
-Here is a quick look at the Typical use case
+General use case
+----------------
+
+Here is a quick look at the general use case
.. code-block:: python
@@ -20,13 +23,13 @@ Here is a quick look at the Typical use case
group_by = "client"
time_series_pattern = "monthly"
- # options are : "daily", "weekly", "bi-weekly", "monthly", "quarterly", "semiannually", "annually" and "custom"
+ # options are: "daily", "weekly", "bi-weekly", "monthly", "quarterly", "semiannually", "annually" and "custom"
date_field = "date"
# These columns will be calculated for each period in the time series.
time_series_columns = [
- SlickReportField.create(Sum, "value", verbose_name=_("Sales For Month")),
+ ComputationField.create(Sum, "value", verbose_name=_("Sales For Month")),
]
columns = [
@@ -34,7 +37,7 @@ Here is a quick look at the Typical use case
"__time_series__",
# This is the same as the time_series_columns, but this one will be on the whole set
- SlickReportField.create(Sum, "value", verbose_name=_("Total Sales")),
+ ComputationField.create(Sum, "value", verbose_name=_("Total Sales")),
]
@@ -113,7 +116,7 @@ Let's see how you can do that, inheriting from teh same Time series we did first
Customize the Computation Field label
-------------------------------------
Maybe you want to customize how the title of the time series computation field.
-For this you want to Subclass ``SlickReportField``, where you can customize
+For this you want to Subclass ``ComputationField``, where you can customize
how the title is created and use it in the time_series_column instead of the one created on the fly.
Example:
@@ -121,9 +124,9 @@ Example:
.. code-block:: python
- class SumOfFieldValue(SlickReportField):
+ class SumOfFieldValue(ComputationField):
# A custom computation Field identical to the one created like this
- # Similar to `SlickReportField.create(Sum, "value", verbose_name=_("Total Sales"))`
+ # Similar to `ComputationField.create(Sum, "value", verbose_name=_("Total Sales"))`
calculation_method = Sum
calculation_field = "value"
@@ -142,7 +145,7 @@ Example:
report_title = _("Time Series Report With Custom Dates and custom Title")
time_series_columns = [
- SumOfFieldValue, # Use our newly created SlickReportField with the custom time series verbose name
+ SumOfFieldValue, # Use our newly created ComputationField with the custom time series verbose name
]
chart_settings = [
@@ -160,6 +163,44 @@ Example:
]
+Time Series without a group by
+------------------------------
+Maybe you want to get the time series calculated on the whole set, without grouping by anything.
+You can do that by omitting the `group_by` attribute, and having only time series (or other computation fields) columns.
+
+Example:
+
+.. code-block:: python
+
+ class TimeSeriesWithoutGroupBy(ReportView):
+ report_title = _("Time Series without a group by")
+ report_model = SalesTransaction
+ time_series_pattern = "monthly"
+ date_field = "date"
+ time_series_columns = [
+ ComputationField.create(Sum, "value", verbose_name=_("Sales For ")),
+ ]
+
+ columns = [
+ "__time_series__",
+ ComputationField.create(Sum, "value", verbose_name=_("Total Sales")),
+ ]
+
+ chart_settings = [
+ Chart("Total Sales [Bar]",
+ Chart.BAR,
+ data_source=["sum__value"],
+ title_source=["name"],
+ ),
+ Chart("Total Sales [Pie]",
+ Chart.PIE,
+ data_source=["sum__value"],
+ title_source=["name"],
+ ),
+ ]
+
+
+
.. _time_series_options:
@@ -185,10 +226,10 @@ Time Series Options
class MyReport(ReportView):
time_series_columns = [
- SlickReportField.create(
+ ComputationField.create(
Sum, "value", verbose_name=_("Value"), is_summable=True, name="sum__value"
),
- SlickReportField.create(
+ ComputationField.create(
Avg, "Price", verbose_name=_("Avg Price"), is_summable=False
),
]
diff --git a/docs/source/topics/widgets.rst b/docs/source/topics/widgets.rst
new file mode 100644
index 0000000..66f3312
--- /dev/null
+++ b/docs/source/topics/widgets.rst
@@ -0,0 +1,132 @@
+.. _widgets:
+
+Widgets
+=======
+You can use the report data on any other page, for example to create a dashboard.
+A dashboard page is a collection of report results / charts / tables.
+
+Adding a widget to a page is as easy as this code
+
+.. code-block:: html+django
+
+ {% load static slick_reporting_tags %}
+
+ {# make sure to have the js_resources added to your page #}
+ {% block extrajs %}
+ {% include "slick_reporting/js_resources.html" %}
+ {% endblock %}
+
+ {% block content %}
+ {% get_widget_from_url url_name="product-sales" %}
+ {% endblock %}
+
+Arguments
+---------
+You can pass arguments to the ``get_widget`` function to control aspects of its behavior
+
+
+* title: string, a title for the widget, default to the report title.
+* chart_id: the id of the chart that will be rendered as default.
+ chart_id is, by default, its index in the ``chart_settings`` list.
+* display_table: bool, If the widget should show the results table.
+* display_chart: bool, If the widget should show the chart.
+* display_chart_selector: bool, If the widget should show the chart selector links or just display the default,or the set chart_id, chart.
+* success_callback: string, the name of a javascript function that will be called after the report data is retrieved.
+* failure_callback: string, the name of a javascript function that will be called if the report data retrieval fails.
+* template_name: string, the template name used to render the widget. Default to `slick_reporting/widget_template.html`
+
+
+This code above will be actually rendered as this in the html page:
+
+.. code-block:: html+django
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The ``data-report-widget`` attribute is used by the javascript to find the
+widget and render the report.
+you can add [data-no-auto-load] to the widget to prevent the widget from loading automatically.
+
+The ``data-report-url`` attribute is the url that will be used to fetch the data.
+The ``data-extra-params`` attribute is used to pass extra parameters to the report.
+The ``data-success-callback`` attribute is used to pass a javascript function that will be called after
+the report data is retrieved.
+The ``data-fail-callback`` attribute is used to pass a javascript function
+that will be called if the report data retrieval fails.
+The ``report-form-selector`` attribute is used to pass a jquery selector
+that will be used to find the form that will be used to pass extra parameters
+to the report.
+The ``data-chart-id`` attribute is used to pass the id of the chart that will
+be rendered. The ``data-display-chart-selector`` attribute is used to pass
+if the report loader should display the chart selectors links.
+
+
+The ``data-report-chart`` attribute is used by the javascript to find the
+container for the chart. The ``data-report-table`` attribute is used by the
+javascript to find the container for the table.
+
+
+``get_widget`` Tag can accept a ``template_name`` parameter to render the
+report using a custom template. By default it renders the
+``erp_reporting/report_widget.html`` template.
+
+Default Arguments
+-----------------
+
+extra_params
+success_callback
+failure_callback
+display_chart
+display_table
+chart_id
+display_title
+title (default to report report title)
+
+
+
+
+
+Customization
+-------------
+
+You You can customize how the widget is loading by defining your own success call-back
+and fail call-back functions.
+
+The success call-back function will receive the report data as a parameter
+
+
+.. code-block:: html+django
+
+ {% load i18n static erp_reporting_tags %}
+
+