Commits

Hynek Cernoch  committed 41daf73

Improved readability of some docs and example project

  • Participants
  • Parent commits 5760841

Comments (0)

Files changed (3)

File docs/usage.rst

 Usage
 =====
 
-A very simple example project is in the directory :file:`livesettings/test_app`. It is almost identical to the following description and is a useful example for integrating livesettings into your app.
+An example project is in the directory :file:`test-project`.
+It's beginning isidentical to the following description and is a useful example for integrating livesettings into your app.
 
 Creating Config.py
 ------------------
 
-In order to use livesettings, you will need to create a :file:`config.py` in your django application. For this example, we will create a :file:`config.py` file in the 'myapp' directory.
+In order to use livesettings, you will need to create a :file:`config.py` in your django application.
+For this example, we will create a :file:`config.py` file in the 'test-project/localsite' directory.
 
-For this specific app, we want to allow an admin user to control how many images are displayed on the front page of our site. We will create the following :file:`config.py`::
+Example: "For this specific app, we want to allow an admin user to control how many images are displayed on the front page of our site."
+We will create the following :file:`config.py`::
 
     from livesettings import config_register, ConfigurationGroup, PositiveIntegerValue, MultipleStringValue
     from django.utils.translation import ugettext_lazy as _
 
     python manage.py runserver
 
-Dislayed values can be limited to only one group. For example, using the following url: `group settings <http://127.0.0.1:8000/settings/MyApp>`_ ::
-where `MyApp` is the key name of the displayed group, will limit the group to only `MyApp`.
-    
+Dislayed values can be limited to a configuration group by the url. For example
+we want to do experiments with configuration group `MyApp` only:
+`group settings <http://127.0.0.1:8000/settings/MyApp>`_ ::
+where `MyApp` is the key name of the displayed group.
+
 More examples for all implemented types of ..Values can be found in
-:file:`livesettings/test_app/localsite/config.py`::
+:file:`test-project/localsite/config.py`::
 including configuration groups which are enabled or disabled based on modules selected in the form.
 You can review examples by:
 
-    cd livesettings/test_app
+    cd test-project
     python manage.py runserver
     
 and browse `<http://127.0.0.1:8000/settings/>`.
 Security and Restricting Access to Livesettings
 -----------------------------------------------
 
-In order to give non-superusers access to the settings, make sure to use the django user permission admin screen to give the desired user the *livesettings|setting|Can change settting*.
+In order to give non-superusers access to the /settings/ views, open Django Admin Auth screen
+and give the user or to its group the permission *livesettings|setting|Can change settting*.
+The same permission is needed to view the form and submit.
+Permissions for insert or delete and any permissions for "long setting" are ignored.
 
 .. Note::
-    Superusers will have access to this setting without enabling any specific permissions
+    Superusers will have access to this setting without enabling any specific permissions.
 
-Permissions for insert, delete or permission for longsetting are ignored and only the above-mentioned permission is used.
-The same permission is needed to read values.
 
 .. Note::
     Because of the security significance of livesettings, all views in livesettings support CSRF regardless of whether or not the 
     CsrfViewMiddleware is enabled or disabled.
 
-If you want store sensitive information to livesettings on production site, e.g. a login password for a payment gateway to verify payments,
-we recommend removing permissions to livesettings at least from users which are logging in everyday. The most secure method is to export the settings and disable livesettings as described below.
+If you want to save a sensitive information to livesettings on production site (e.g. a password for logging into other web service)
+it is recommended not to grant permissions to livesettings to users which are logging in everyday.
+The most secure method is to export the settings and disable web access to livesettings as described below.
 Exporting settings itself is allowed only by the superuser.
 
-For password values it is recommended to define them by PasswordValue(... render_value=False)
-so that the actual password is not re-echoed to the browser.
-Though passwords are hidden by asterisks to human reader, they should still be considered accessible by attacker's javascripts. In other words,
-if a user can view the password fields, they could determine the
+Password values should be declared by `PasswordValue(... render_value=False)`
+that replaces password characters by asterisks in the browser. (Though hidden
+to a human observer, password is still accessible by attacker's javascripts or
+by connection eavesdropping.)
 
 Exporting Settings
 ------------------

File test-project/localsite/config.py

-"Examples for livesettings" 
+"""Examples for livesettings"""
+
 from livesettings.values import *
 from livesettings import config_register, config_register_list
 from django.utils.translation import ugettext_lazy as _
         'NUM_IMAGES',
         description = _('Number of images to display'),
         help_text = _("How many images to display on front page."),
-        # if no help_hext is given, Default falue is displayed
+        # if no help_text is given, Default falue is displayed
         default = 5
     ))
 
 )
 
 
-# Example of enabling modules which have own settings groups in different files
+# Example of conditional items (fiels or modules) that can by enabled/disabled
+# by selecting in some choises list.
+# These contitional items and their corresponding choice for enable/disable can
+# be independently installed/uninstalled by adding a new config.py file (like
+# plugins - without modifying another file)
+# (Here is the second part under the line below.)
 
-GR_MOD_FLYING = ConfigurationGroup('FLYING', 
-        _('Examples for modules - enabling subsettings of modules for... e.g. Flying :-)'), ordering=3)
+GR_MY_CONDITIONAL = ConfigurationGroup('MY_CONDITIONAL', 
+        _('Enable and configure conditional modules'), ordering=3)
 
 # Every module can have its own set of specific live settings, which are enabled/disabled together with a module.
 
-FLYING_MODULES = MultipleStringValue( GR_MOD_FLYING, 'MODULES',
-        description=_('Modules for Flying'),
-        choices=(('calendar', 'calendar'),),
+MY_CONDITIONAL_SWITCHES = MultipleStringValue(GR_MY_CONDITIONAL, 'MODULES',
+        description=_('Conditional modules'),
+        choices=(('calendar', 'Calendar module'),),
         default=['calendar',],
-        help_hext='Try to enable/disable these modules and save to see a more os less dependent settings',
+        help_text='Enable/Disable some of these modules and press Update to see more/less settings fields or groups',
     )
 
+# A contitionally displayed field
 config_register_list(
-    FLYING_MODULES,
+    MY_CONDITIONAL_SWITCHES,
 
-    StringValue(GR_MOD_FLYING, 'first_day', description='Calendar - First day of week', default='Monday',
+    StringValue(GR_MY_CONDITIONAL, 'first_day', description='Calendar - First day of week', default='Monday',
         ordering=1,
         choices=zip(* 2 * (('Sunday', 'Monday'),)),
-        requires=FLYING_MODULES,
+        requires=MY_CONDITIONAL_SWITCHES,
         requiresvalue='calendar',
+        help_text = 'Visibility of this field depends on selecting the item "Calendar" above.'
     )
 
 )
 
-# ==== This part is usually located in a separate file control.py in optional's module directory
+# ==========================================================================================
+# This part is usually located in a separate file control.py in optional's module directory
+# and can be completely removed. That only removes some one conditional group and its
+# choice in MY_CONDITIONAL_SWITCHES.
 
 from decimal import Decimal
 from django.utils.translation import ugettext_lazy as _
 from livesettings import *
 
-FLYING_MODULES = config_get('FLYING', 'MODULES')
-FLYING_MODULES.add_choice(('django.contrib.webdesign.lorem_ipsum', 'Lorem Ipsum'))
+# add a new choice to main choises where this module can be enabled
+MY_CONDITIONAL_SWITCHES = config_get('MY_CONDITIONAL', 'MODULES')
+MY_CONDITIONAL_SWITCHES.add_choice(('django.contrib.webdesign.lorem_ipsum', 'Random text module'))
 
-LOREM_GROUP = ConfigurationGroup('django.contrib.webdesign.lorem_ipsum',
-    _('Lorem Ipsum Settings'),
-    requires = FLYING_MODULES,
+# create a conditional configuration group and some item.
+MY_FIRST_OPTIONAL_GROUP = ConfigurationGroup('django.contrib.webdesign.lorem_ipsum',
+    _('Random Text Module Settings'),
+    requires = MY_CONDITIONAL_SWITCHES,
     requiresvalue='django.contrib.webdesign.lorem_ipsum',
     ordering = 101)
 
 config_register_list(
-    ModuleValue(LOREM_GROUP, 'MODULE', default='django.contrib.webdesign.lorem_ipsum', hidden=True),
+    ModuleValue(MY_FIRST_OPTIONAL_GROUP, 'MODULE', default='django.contrib.webdesign.lorem_ipsum', hidden=True),
 
-    MultipleStringValue(LOREM_GROUP, 'lorem_words', description='Lorem ipsum words',
-        choices= zip(* 2 * ('lorem ipsum dolor sit amet'.split(),))
+    MultipleStringValue(MY_FIRST_OPTIONAL_GROUP, 'lorem_words', description='Random words',
+        choices= zip(* 2 * ('lorem ipsum dolor sit amet'.split(),)),
+        help_text = 'Visibility of this group depends on selecting the item "Random text module" above.',
     )
 )
 

File test-project/localsite/templates/myapp/index.html

 <html><body>
-<pre>
-<p>Measurement system: {{ measurement_system }}</p>
-<p>Image count: {{ image_count }}</p>
-<p><a href="{% url satchmo_site_settings %}">Values can be modified</a> if the user has sufficient permissions (livesettings_setting:change).</p>
+<table border="1">
+    <tr><td>Measurement system:</td><td>{{ measurement_system }}</td></tr>
+    <tr><td>Image count:       </td><td>{{ image_count }}</td></tr>
+</table>
+<p>Values <a href="{% url satchmo_site_settings %}">can be modified here</a> if the user has sufficient permissions (livesettings_setting:change).</p>
 </body></html>