Commits

Benoît Bryon committed 15b9cda

Updated overview in docs, which introduces some changes that are about to be performed on the code.

  • Participants
  • Parent commits 14664a3

Comments (0)

Files changed (1)

docs/overview.txt

 
 Blocks are typically a concept used in content management systems (CMS).
 
-In a website (or a web application), the following three roles are encountered:
+In a website (or a web application), the following three roles are met:
 
 * the developer. He provides the application. He provides the mecanisms that
-  handle data.
+  handle requests and data.
 * the template designer. He provides the graphic theme (layout and style). He
-  puts data into templates.
+  writes templates.
 * the site administrator. He provides data and configures the website.
 
 The main idea behind blocks is to split any page in a website into subparts, 
   for the content of blocks to be displayed. As an example, he puts the
   "header" block group at the beginning of the page, in a <div class="header">.
 * the site administrator wants to configure plugins and to put information in
-  the template areas. 
+  the template areas. As an example, he puts the "login form" block in the
+  "header" slot, creates a "static HTML" block with a WYSIWYG editor and puts
+  it in the "header" too.
 
 **********
 References
 
 Drupal is a well-known CMS which makes use of blocks.
 See http://drupal.org/handbook/modules/block.
+Drupal base block module embed several functionalities: blocks are grouped in
+regions, regions are inserted in templates, blocks have publication parameters
+such as visibility, visibility against user role (group)...
+Third-party modules can define additional blocks. The site administrator 
+controls the relationships between blocks and regions.
+
+Django-Blocks
+http://code.google.com/p/django-blocks/
+A block system. Core includes functionalities like menus or sitemap.
 
 *************************
 Why Django-TemplateBlocks
 Django-TemplateBlocks is not intended to be a plug-and-play CMS solution. It is
 intended to be a basis on which developers can easily add CMS functionalities 
 to a Django project.
+
+******************************
+Django-TemplateBlocks concepts
+******************************
+
+What choices have been made to provide the functionality?
+
+Definitions
+===========
+
+Block
+-----
+
+A block is an instance of a block-plugin.
+For the developer, it is a Python object, a Django model instance. It 
+implements the "block API" so that it can be handled by core tools and 
+extensions (at least to "render" the block).
+For the template designer, it is a template variable, an object available in
+some particular contexts.
+For the site administrator, it is a piece of information that can be displayed
+on the website. This involves data and theme (layout and style). It can be 
+dynamic or static. Optionally it is customizable.
+
+Block plugin
+------------
+
+A block plugin is a Python class or Django model which instances are blocks.
+It provides the block functionality by implementing an API.
+
+Plugins are made available for the site administrator. The site administrator
+uses plugins to create block instances.
+
+Goals
+=====
+
+* provide the basis. The core does simple things.
+* allow extensions.
+* a block can be used in general page layout (header, footer, ...)
+* a block can be used in specific page content (as a model field, inserted in
+  a WYSIWYG editor...)
+* initiate a library of useful plugins for most common needs
+* quick creation of specific functionality is better than dirty hack of generic
+  functionality (which is not so generic since it requires a hack to fit
+  specific needs)
+
+Core
+====
+
+Block and plugin base classes are Django-TemplateBlocks core.
+
+The following elements should be part of the core:
+
+* block and plugin base classes
+* a template tag to fetch and render a list of block instances in templates
+* block admin base. Some base forms and admin views
+* plugin management base (installation, configuration, admin...)
+
+Extensions
+==========
+
+The following elements should be handled by extensions:
+
+* regions. Site administrator groups blocks in regions. This is also called
+  "slots" or "areas" in some CMS. In a region, blocks are ordered. Regions are 
+  used in templates to render a filtered-list of blocks.
+* publication parameters, such as visibility (enabled/disabled), visibility 
+  depending on user group (enabled if authenticated), visibility depending on
+  dates (publication start date)... All of these elements are specific to the
+  project (the needs may vary from one project to another). Like regions, these
+  are filters that can be applied when requesting a list of blocks in templates.
+* plugins.
+
+Functionalities
+===============
+
+Here are some suggestions about functionalities and how they could be 
+implemented.
+
+{% render_blocks %} template tag
+--------------------------------
+
+The main tool to render blocks in templates.
+
+By default, it renders all the available block instances.
+
+Extensions can add filters. It consist in filtering the default queryset which
+is used to fetch the blocks. 
+
+Filters can be specified as template tag arguments. As an example, if the 
+"regions" extension is enabled, then {% render_blocks region="header" %} will 
+render only blocks in the "header" region.
+
+Filters can be applied automatically. As an example, if the "visibility" 
+extension is enabled, then the blocks that are disabled are automatically 
+hidden. There is no need to use parameters like {% render_blocks enabled=1 %}.
+
+The list of filters available as template tag arguments should be a setting.
+
+The list of filters applied automatically should be a setting.
+
+AJAX loading
+------------
+
+
+Blocks in content, as fields
+----------------------------
+
+
+Blocks in WYSIWYG content
+-------------------------
+