Merge branch 'master' of https://github.com/talpor/django-dashing

Conflicts:
	docs/widgets.rst

README.rst

@@ -51,6 +51,49 @@ Installation
 4. Start the development server and visit http://127.0.0.1:8000/dashboard/
    to view the dummy dashboard.
 
+Quick Start
+===============================================
+
+To make your own dashboard and retrieves the data from django you should:
+
+1. Create a django dashboard application with a `widgets.py` file
+
+2. Create your widget extended from **NumberWidget**, **ListWidget**, **GraphWidget** or simply **Widget** (from dashing.widgets), for example `see <https://github.com/individuo7/django-dashing-demo-app/blob/master/django_dashing_demo_app/widgets.py>`_.
+
+.. code-block:: python
+
+3. Register your widget in `urls.py` like:
+
+.. code-block:: python
+
+    from django.conf.urls import patterns, url, include
+        from dashing.utils import router
+
+        from project.dashboard.widgets import CustomWidget
+
+        router.register(CustomWidget, 'custom_widget')
+
+        urlpatterns = patterns('',
+            url(r'^dashboard/', include(router.urls)),
+        )
+
+Create a dashing-config.js file with a widget that retrive the data in your static directory like:
+
+.. code-block:: javascript
+
+    var myDashboard = new Dashboard();
+    myDashboard.addWidget('customWidget', 'Number', {
+        getData: function () {
+            var self = this;
+            $.get('/dashboard/widgets/custom_widget/', function(data) {
+                $.extend(self.data, data);
+            });
+        },
+        interval: 3000
+    });
+
+Also if you want to locate the config file in a different directory you can create a `dashing/dashboard.html` file in your **TEMPLATE_DIRS** and replace the **config_file** block to the route of your javascript config file, see the `docs <http://django-dashing.readthedocs.org/en/latest/getting-started.html#template-file>`_.
+
 Testing
 ===============================================
 
@@ -63,7 +106,7 @@ First install any development dependencies.
 
 Then download and install `PhamtonJS <http://phantomjs.org/download.html>`_
 
-django-dashing uses mocha as testing framework. Run the following command in the root directory to run the full test suite.
+django-dashing uses mocha as the testing framework. Run the following command in the root directory to run the full test suite.
 
 .. code-block:: text
 

docs/dashboards.rst

@@ -4,7 +4,7 @@ Dashboards
 Single Dashboard 
 ----------------
 
-To initialize a single dashboard you need create a Dashboard object and pass valid options as shown below:
+To initialize a single dashboard you need to create a Dashboard object and pass valid options as shown below:
 
 .. code-block:: javascript
 
@@ -65,7 +65,7 @@ listWidgets
     Returns the list of widgets created on this dashboard
 
 subscribe
-    To subscribe an event in this dashboard you can doing as follow:
+    To subscribe an event in this dashboard you can do the following:
 
     .. code-block:: javascript
 
@@ -74,7 +74,7 @@ subscribe
         });
 
 publish
-    To publish an event in this dashboard you can doing as follow:
+    To publish an event in this dashboard you can do the following:
 
     .. code-block:: javascript
 
@@ -84,7 +84,7 @@ publish
 Multiple Dashboards
 -------------------
 
-To initialize a multiple dashboards you need create a DashboardSet object and pass valid options as shown below:
+To initialize a multiple dashboard you need to create a DashboardSet object and pass valid options as shown below:
 
 .. code-block:: javascript
 
@@ -102,7 +102,7 @@ addDashboard
         myDashboardSet.addDashboard(name, options)
 
 
-    Where `name` is a string with the name of dashboard and `options` is a json object with the same format of the options of the `Dashboard` object.
+    Where `name` is a string with the name of the dashboard and `options` is a json object with the same format of the options of the `Dashboard` object.
 
 getDashboard
     To get a Dashboard from the DashboardSet object:
@@ -112,7 +112,7 @@ getDashboard
         myDashboardSet.getDashboard(name)
 
 addAction
-    To add a button on the overlay menu that running arbitrary javascript code, for example:
+    To add a button on the overlay menu that runs arbitrary javascript code, for example:
 
     .. code-block:: javascript
 
@@ -124,7 +124,7 @@ addAction
 
 *Manual*
 
-To swap between dashboards need to press the `ctrl` key to display the menu.
+To swap between dashboards you need to press the `ctrl` key to display the menu.
 
 *Automatic*
 
@@ -144,7 +144,7 @@ Then you can select the rolling time in the `ctrl` menu.  Or you can add the par
 
 **Dashboard Events**
 
-Each single dashboard publish a **shown** or **hidden** event when the dashboard are loaded or unloaded, you can use it as follows:
+Each single dashboard publishes a **shown** or **hidden** event when the dashboard are loaded or unloaded, you can use it as follows:
 
 .. code-block:: javascript
 

docs/getting-started.rst

@@ -3,7 +3,7 @@ Getting Started
 
 Installation
 -----------
-1. Install latest stable version from PyPi:
+1. Install the latest stable version from PyPi:
 
 .. code-block:: text
 
@@ -53,7 +53,7 @@ For example your project's ``settings.py`` file might include something like thi
 Accessing settings
 ~~~~~~~~~~~
 
-If you need to access the values of Django Dashing settings in your project, you should use the dashing_settings object. For example.
+If you need to access the values of Django Dashing settings in your project, you should use the dashing_settings object. For example:
 
 
 .. code-block:: python
@@ -68,7 +68,7 @@ Settings
 
 **INSTALLED_WIDGETS**
 
-A list or tuple of name of widgets to load when the dashboard is displayed, searches for resources of widgets (js, css and html) in the static directory, if not found then searches in the remote repository
+A list or tuple of name of widgets to load when the dashboard is displayed, searches for resources of widgets (js, css and html) in the static directory, if not found then search in the remote repository
 
 Default:
 
@@ -78,7 +78,7 @@ Default:
 
 **PERMISSION_CLASSES**
 
-A list or tuple of permission classes, that determines the default set of permissions checked when display the dashboard.
+A list or tuple of permission classes, that determine the default set of permissions checked when displaying the dashboard.
 
 The default permissions classes provided are: *AllowAny*, *IsAuthenticated*, and *IsAdminUser*
 
@@ -186,7 +186,7 @@ Your ``dashing/dashing.html`` might looks like this:
 Python Widget Classes
 ----------------------
 
-Django Dashing provide an useful set of classes to return the expected data for the default widgets, you can create a `widgets.py` file and inherit of these classes or create your own widgets inherit from ``dashing.widgets.Widget``.
+Django Dashing provides a useful set of classes to return the expected data for the default widgets, you can create a `widgets.py` file and inherit of these classes or create your own widgets inherit from ``dashing.widgets.Widget``.
 
 A custom widget can look like this:
 

docs/widgets.rst

@@ -1,7 +1,7 @@
 Widgets
 ===============================================
 
-To place widgets in your dashboard you need create a javascript file, where you call each widget that you need to place with the correct options, each widget provide an events that you can call in any javascript file to update the data.
+To place widgets in your dashboard you need to create a javascript file, where you call each widget that you need to place with the correct options, each widget provides an event that you can call in any javascript file to update the data.
 
 For example if you create a number widget
 
@@ -23,14 +23,14 @@ For example if you create a number widget
         }
     });
 
-Then you can publish in any moment the event ``dashboard.publish('example_widget/getData')`` to get new data and update the widget.
+Then you can publish at any moment the event ``dashboard.publish('example_widget/getData')`` to get new data and update the widget.
 
-Note that in this example the `getData` method will be executed each 1000 milliseconds because is the default value of `interval` option in a `Number` widget.
+Note that in this example the `getData` method will be executed each 1000 milliseconds because it is the default value of `interval` option in a `Number` widget.
 
 Clock Widget
 ------------
 
-This widget can display an specific day an hour.
+This widget can display a specific day or an hour.
 
 Options
 ~~~~~~~~~~~~
@@ -65,7 +65,7 @@ interval
 Graph Widget
 ------------
 
-This widget can display a value with an associate graph as background.
+This widget can display a value with an associated graph as a background.
 
 Options
 ~~~~~~~~~~~~
@@ -103,17 +103,17 @@ getData
     *(default: empty function)*
 
 getWidget
-    Return the DOM element that represent the widget.
+    Return the DOM element that represents the widget.
 
 interval
     Actualization interval of widget scope on milliseconds. *(default: 1000)*
 
 Graph options
 ~~~~~~~~~~~~
 
-To render the graph this widget use Rickshaw_ library, for now the config options are quite limited, if you need be more specific you can overwrite the rivetsjs binder (rv-dashing-graph) or write a custom widget use this as guide.
+To render the graph this widget use Rickshaw_ library, for now the config options are quite limited, if you need to be more specific you can overwrite the rivetsjs binder (rv-dashing-graph) or write a custom widget using this as a guide.
 
-To configure the X and Y axis you must define custom methods *xFormat* and *yFormat* in the scope, also you can use the methods *beforeRender* and *afterRender* to execute arbitrary javascript before or after of render, for example:
+To configure the X and Y axis you must define custom methods *xFormat* and *yFormat* in the scope, also you can use the methods *beforeRender* and *afterRender* to execute arbitrary javascript before or after rendering, for example:
 
 
 .. code-block:: javascript
@@ -129,7 +129,7 @@ To configure the X and Y axis you must define custom methods *xFormat* and *yFor
         $.extend(self.scope, scope);
     });
 
-Also you can specify any properties that the graph constructor accepts in the `scope` object, for example a valid `scope` may be:
+Also, you can specify any properties that the graph constructor accepts in the `scope` object, for example a valid `scope` may be:
 
 .. code-block:: javascript
 
@@ -157,13 +157,13 @@ Also you can specify any properties that the graph constructor accepts in the `s
 Python Class
 ~~~~~~~~~~~~
 
-This class helps to return valid scope to be use by the widget, you can see the definition in GitHub__
+This class helps return valid scope to be used by the widget, you can see the definition in GitHub__
 
 .. _GraphWidgetDefinition: https://github.com/talpor/django-dashing/blob/59def5a53d5b76db232196f2fffacd49270b27e1/dashing/widgets.py#L94-118
 
 __ GraphWidgetDefinition_
 
-Here's an example of a graph widget where in `value` is displayed the total of Errands and in `data` is returned an array with the last two hour of activity
+Here is an example of a graph widget where `value` is displayed the total number of Errands and in `data` returns an array with the last two hour of activity
 
 .. code-block:: python
     
@@ -198,7 +198,7 @@ Here's an example of a graph widget where in `value` is displayed the total of E
 List Widget
 ------------
 
-This widget can display a list of elements with an associate value.
+This widget can display a list of elements with an associated value.
 
 Options
 ~~~~~~~~~~~~
@@ -279,7 +279,7 @@ Here's an example of a graph widget where in the `scope` returns an array with t
 Number Widget
 -------------
 
-This widget can display a value with another interesting information.
+This widget can display a value with other interesting information.
 
 Options
 ~~~~~~~~~~~~
@@ -317,13 +317,13 @@ interval
 Python Class
 ~~~~~~~~~~~~
 
-This class helps to return valid data to be use by the widget, you can see the definition in GitHub__
+This class helps to return valid data to be used by the widget, you can see the definition in GitHub__
 
 .. _NumberWidgetDefinition: https://github.com/talpor/django-dashing/blob/59def5a53d5b76db232196f2fffacd49270b27e1/dashing/widgets.py#L35-64
 
 __ NumberWidgetDefinition_
 
-Here's an example of a graph widget where in `value` is displayed the total of payments and in the detail and moreInfo shows other information of interest
+Here is an example of a graph widget where in `value` is displayed the total of payments and in the detail and moreInfo shows other information of interest
 
 .. code-block:: python
     
@@ -348,9 +348,9 @@ Here's an example of a graph widget where in `value` is displayed the total of p
 Custom Widgets
 ===============================================
 
-To make a custom widget you must create three static files to define configuration parameters and appearance, in addition, you can create a python class to communicate with the Django project.
+To make a custom widget you must create three static files to define configuration parameters and appearance. In addition, you can create a python class to communicate with the Django project.
 
-To name your widgets should follow a naming convention, where the name must by unique for findable through the settings.
+To name your widgets should follow a naming convention were the name must be unique and searchable through the settings.
 
 Static Files
 -------------
@@ -392,7 +392,7 @@ Script File
 
 Your location should be ``<static_directory>/widgets/<widget_name>.js`` in this file will be defined the configuration options and default values for the new widget, the idea is to create an object using the ``new`` keyword, then we define properties and methods using ``this`` keyword.
 
-We must provide an ``__init__`` method where binding the scope with the template and add to the dashboard, this function is quite similar in all widgets, then it is provided by ``Dashing.utils.widgetInit`` to facilitate implementation and improve reading of widgets, also must provide a ``scope`` element which will be binded to the template, and a ``getData`` function will surely be the to be overwritten to obtain relevant data as required,
+We must provide an ``__init__`` method were we bind the scope with the template and add to the dashboard, this function is quite similar in all widgets, then it is provided by ``Dashing.utils.widgetInit`` to facilitate implementation and improve the lecture of widgets, also must provide a ``scope`` element which will be binded to the template, and a ``getData`` function will surely be the to be overwritten to obtain relevant data as required,
 
 For example ``{% static %}widgets/list/list.js`` looks like this:
 
@@ -414,7 +414,7 @@ For example ``{% static %}widgets/list/list.js`` looks like this:
         this.interval = 10000;
     };
 
-if we want to initialize widget with an scope we can write:
+If we want to initialize widget with the scope we can write:
 
 
 .. code-block:: javascript
@@ -432,7 +432,7 @@ if we want to initialize widget with an scope we can write:
 Python Class
 -------------
 
-Surely in many cases may be necessary give the option to get some Dajngo project data into the widget, for this dashing has a Widget class that can be inherited to deliver properly serialized data, also subsequently can be serve the data using the dashing router.
+Surely in many cases it may be necessary to give the option to get some Dajngo project data into the widget, for this dashing has a Widget class that can be inherited to deliver properly serialized data, subsequently serving data using the dashing router.
 
 For example ListWidget in ``dashing/widgets.py`` looks like this:
 
@@ -464,17 +464,17 @@ For example ListWidget in ``dashing/widgets.py`` looks like this:
                 'data': self.get_data(),
             }
 
-If you develop your widget with python classes necessarily going to have to distribute it via PyPI
+If you develop your widget with python classes it is necessary that you distribute it via PyPI
 
 Distribution
 ------------
 
-To distribute a widget you have two options, the fastest way is throught  Django Dashing Channel but is a bit limited, and through PyPI a bit trickier to pack but you have more options when developing the widget.
+To distribute a widget you have two options. The fastest way is through  Django Dashing Channel but it is a bit limited, and through PyPI, a bit trickier to pack but you have more options when developing the widget.
 
 Via Django Dashing Channel
 ~~~~~~~~~~~~
 
-Using this distribution method the users will only have to add the widget name on ``INSTALLED_WIDGETS`` then to loading the dashboard, this locates the static files from a remote location (specified in the preconfigured repository), if the user creates a copy of the files on your local static directory then these will open locally.
+Using this distribution method the users will only have to add the widget name on ``INSTALLED_WIDGETS`` then load the dashboard, this locates the static files from a remote location (specified in the preconfigured repository), if the user creates a copy of the files on your local static directory then these will open locally.
 
 You will have to host your files into a CDN, I recommend creating a github project and use RawGit_ to serve through MaxCDN_, you can take `dj-dashing-weather-widget`__ project as a guide.
 
@@ -485,19 +485,19 @@ __ WeatherWidget_
 
 Finally to publish your widget in Django Dashing Channel you need to make a fork of `django-dashing-channel`__, add your repository to repositories.json and send a pull request. In the repository root will be sought the widget static files (.js .css and .html)
 
-You should create a README file for installations instructions.
+You should create a README file for installation instructions.
 
 .. _DashingChannel: https://github.com/talpor/django-dashing-channel
 __ DashingChannel_
 
 PyPI Package
 ~~~~~~~~~~~~
 
-If your widget requires python code or just want to provide an easy way to get the widget locally then a PyPI package is the way to go.
+If your widget requires python code or you just want to provide an easy way to get the widget locally then a PyPI package is the way to go.
 
-As a requirement is necessary follow the widgets naming convention (`see static files`__). To create a PyPI package `see the documentation <https://docs.python.org/2/distutils/packageindex.html>`_, and should create a README file for installations instructions.
+As a requirement it is necessary follow the widgets naming convention (`see static files`__). To create a PyPI package `see the documentation <https://docs.python.org/2/distutils/packageindex.html>`_, and should create a README file for installations instructions.
 
-This not excluding the previous way, you could create a minimalist version of your widget and upload to django-dashing-channel and in the project instructions leave on how to install the PyPI version
+This is not excluding the previous way, you could create a minimalist version of your widget and upload it to django-dashing-channel and in the project instructions show how to install the PyPI version
 
 .. _WidgetsNamingConvention: #static-files
 __ WidgetsNamingConvention_