E-Democracy Pages Wiki

Search Wiki

 

Tools

 

Difference between revisions of "Page Components"

From E-Democracy.org

(Declaring)
(Input Pages)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
Zope and GroupServer provide a sophisticated set of components and classes for building web pages. This set consists of widget like content providers and viewlet, to form building/handling classes, to general web page containers.
+
Zope and GroupServer provide a sophisticated set of components and classes for building web pages. This set consists of templating tools, widget like content providers and viewlet, to form building/handling classes, to general web page containers.
  
This set, in addition to [[Zope Templates]], provides the tools a developer needs to display information and create user interfaces on E-Democracy.
+
This set provides the tools a developer needs to display information and create user interfaces on E-Democracy.
 +
 
 +
=Templating=
 +
 
 +
All pages in GroupServer use Zope's Template Attribute Language (TAL) and Template Attribute Language Expression Syntax (TALES).
 +
 
 +
* [http://docs.zope.org/zope2/zope2book/AppendixC.html TAL and TALES reference]
 +
* [http://wiki.zope.org/zope2/PageTemplates A number of references and tutorials]
 +
* [http://wiki.zope.org/ZPT/RepeatVariable Information on tal:repeat]
  
 
=Content Providers=
 
=Content Providers=
Line 39: Line 47:
 
=Viewlets and Viewlet Managers=
 
=Viewlets and Viewlet Managers=
  
Viewlets are a more flexible means of constructing indivisible displays or UI components. Viewlet Managers are a container for Viewlets. Basically, a page or template includes a Viewlet Manager, Viewlets attach themselves to Viewlet Managers, and any Viewlet attached to an included Viewlet Manager will become part of the final rendered page.  
+
Viewlets are a more flexible means of constructing indivisible displays or UI components. Viewlet Managers are a container for Viewlets. Basically, a page or Viewlet, via its template, includes a Viewlet Manager. Viewlets attach themselves to Viewlet Managers, and any Viewlet attached to an included Viewlet Manager will become part of the final rendered page.  
  
 
Viewlets and Viewlet are now the preferred way of constructing  displays and UI in GroupServer, because they are more flexible (Viewlets can be added to Viewlet Managers by any egg's configuration) and are much easier to override (any egg can override a Viewlet or Viewlet Manager).
 
Viewlets and Viewlet are now the preferred way of constructing  displays and UI in GroupServer, because they are more flexible (Viewlets can be added to Viewlet Managers by any egg's configuration) and are much easier to override (any egg can override a Viewlet or Viewlet Manager).
Line 123: Line 131:
 
* viewTopics - Indicates if the user has permission to view topics in the group.
 
* viewTopics - Indicates if the user has permission to view topics in the group.
 
* isAnnouncement - Indicates if the group is an announcement group.
 
* isAnnouncement - Indicates if the group is an announcement group.
 +
 +
=Pages=
 +
 +
GroupServer provides a number of Page objects, classes which can be extended to create a full webpage that is associated with some URL and context. They are based on Zope's Page objects, with a couple of additional convience attributes and methods (such as a SiteInfo attribute and the GSUserInfo instance of the current viewing user). Generally speaking, these Page objects are divided between Group page objects - objects meant for pages that are viewed within a group content (i.e. group home pages, topics, etc...) - and Site page objects - meant for pages viewed outside of a group context (i.e. site homepage, user profile page, etc...). These Page objects are also divided based on the primary purpose of the page, with Page objects available for pages that are meant to be viewed via a browser, pages that are meant to be email messages, and pages that are meant to take input from the user.
 +
 +
==Browser Pages==
 +
 +
* SitePage - Provided by [https://source.iopen.net/groupserver/gs.content.base/summary gs.content.base]
 +
* GroupPage - Provided by [https://source.iopen.net/groupserver/gs.group.base/summary gs.group.base]
 +
 +
===Input Pages===
 +
 +
* SiteForm - Provided by [https://source.iopen.net/groupserver/gs.content.form.base/summary gs.content.form.base]
 +
* GroupForm - Provided by [https://source.iopen.net/groupserver/gs.group.base/summary gs.group.form]
 +
* ProfileForm - Provided by [https://source.iopen.net/groupserver/gs.profile.base/summary gs.profile.base]
 +
 +
==Email Pages==
 +
 +
* SiteEmail - Provided by [https://source.iopen.net/groupserver/gs.content.email.base/summary gs.content.email.base]
 +
* GroupEmail - Provided by [https://source.iopen.net/groupserver/gs.content.email.base/summary gs.content.email.base]
 +
 +
=Style=
 +
 +
GroupServer uses two systems to style Pages, one for Browser Pages, and one for Email Pages. In both cases, a given page will rely on the CSS that is provided by one of these two systems. In both cases, the CSS is based on [http://twitter.github.com/bootstrap/ Twitter's Bootstrap].
 +
 +
==Browser Page CSS==
 +
 +
[https://source.iopen.net/groupserver/gs.content.css/summary gs.content.css] is the core of the CSS system for browser pages. If you are using the default GroupServer style, then all styling will come from this class. This class provides icons and fonts to support the default style, as well as two important CSS files: globalstyle.css - the file that establishes the Bootstrap based CSS framework - and site.css - the fill that defines the style of a given skin.
 +
 +
Note that the URLs of globalstyle.css and site.css should contain a date string. This is so browsers can cache CSS files for long periods of time (~10 years), thus reducing unneccessary file deliveries. This also requires that all skins served by the same instance of GroupServer must provide matching globalstyle.css/site.css URLs with matching date strings. In the future, this whole aspect of serving CSS [https://redmine.iopen.net/issues/614 will be streamlined].
 +
 +
In general, a GroupServer instance will implement its own skin. In these cases, the skin class will provide its own site.css file. For an example, see [https://source.iopen.net/groupserver/gs.skin.blue/summary gs.skin.blue].
 +
 +
==Email Page CSS==
 +
 +
The styling associated with an email message is provided by a different system. This is for two reasons:
 +
 +
* CSS for email messages can not be delivered in the same way as CSS for browser pages
 +
* Email messages are using an early version of a [https://redmine.iopen.net/issues/614 new GroupServer architecture for providing CSS]
 +
 +
Because email messages can not fetch resources beyond what is already contained in a message (and images of the user allows), CSS is delivered as part of the HTML message. Thus, there are no URLs associated with email CSS.
 +
 +
[https://source.iopen.net/groupserver/gs.content.email.css gs.content.email.css] is the foundation of the Email Page CSS system. Email Pages pull in viewlets provided by gs.content.email.css that provide CSS. Notably, gs.content.email.css provides viewlet managers that other eggs can associate their own CSS viewlets with, providing a way for eggs to define their own style for their unique UI elements.
 +
 +
=Layout=
 +
 +
Virtually all pages provided by a GroupServer instance will inherit one of a handful of layouts provided by two classes, making it easy to provide a consistent layout across your site and make updates quickly.
 +
 +
==Brower Page Layouts==
 +
 +
[https://source.iopen.net/groupserver/gs.content.layout/summary gs.content.layout] provides the core layouts for browser pages. Skins that wish to alter this layout can override the layouts provided by gs.content.layout.
 +
 +
==Email Page Layouts==
 +
 +
[https://source.iopen.net/groupserver/gs.content.email.layout/summary gs.content.email.layout] provides the core layout for email pages. Again, skins that wish to alter this layout can override the layout provided by gs.content.email.layout.
  
 
[[Category:Technology:GroupServer Development Reference]]
 
[[Category:Technology:GroupServer Development Reference]]

Latest revision as of 12:23, 23 July 2014

Zope and GroupServer provide a sophisticated set of components and classes for building web pages. This set consists of templating tools, widget like content providers and viewlet, to form building/handling classes, to general web page containers.

This set provides the tools a developer needs to display information and create user interfaces on E-Democracy.

Templating

All pages in GroupServer use Zope's Template Attribute Language (TAL) and Template Attribute Language Expression Syntax (TALES).

Content Providers

While quite common in GroupServer, these are mostly being phased out in favor of the more flexible Viewlets and Viewlet Managers. However, understanding Content Providers will help new developers to understand Viewlets and Viewlet Managers, which are described below.

Content providers are indivisible content displays or UI components (aka widgets) - the providers of content and structure for complete components (e.g. a post) that can be included as part of an overall page (e.g. the topic display page).

Most Content Providers are declared in an egg's configure.zcml to have:

  • a name;
  • a class;
  • a template;
  • and maybe a factory or adapter

Content Providers are included on pages by using the tal:replace or tal:content tags and the structure

Site Content Provider

gs.viewlet.contentprovider.SiteContentProvider

The base for content providers used on a site. It is simply an object with knowledge of the context, request, and view. It provides the following properties:

  • siteInfo - A groupserver.SiteInfo instance
  • loggedInUser - A groupserver.LoggedInUser instance

Group Content Provider

gs.group.base.contentprovider.GroupContentProvider

Base for content providers that are intended to be used in a group. This is a subclasses of SiteContentProvider, and provides the following properties that are relevant for groups:

  • groupInfo - A groupserver.GroupInfo instance.
  • viewTopics - Indicates if the user has permission to view topics in the group.
  • isAnnouncement - Indicates if the group is an announcement group.

Viewlets and Viewlet Managers

Viewlets are a more flexible means of constructing indivisible displays or UI components. Viewlet Managers are a container for Viewlets. Basically, a page or Viewlet, via its template, includes a Viewlet Manager. Viewlets attach themselves to Viewlet Managers, and any Viewlet attached to an included Viewlet Manager will become part of the final rendered page.

Viewlets and Viewlet are now the preferred way of constructing displays and UI in GroupServer, because they are more flexible (Viewlets can be added to Viewlet Managers by any egg's configuration) and are much easier to override (any egg can override a Viewlet or Viewlet Manager).

Understanding Viewlets by the Grok Project provides a good overview of the idea of Viewlets and Viewlet Managers, though specific implementation differs in Zope. The package documentation for zope.viewlet provides a lot of detail (too much frankly) on how Viewlets and Viewlet Managers are used.

Viewlet Managers

Viewlet Managers are usually a defined space that eggs can plug content into via Viewlets, so the interesting code is usually found in Viewlets.

Declaring

In brief, a Viewlet Manager is often declared in an egg's configure.zcml. This declaration will usually include:

  • a marker interface (usually extends zope.viewlet.interfaces.IViewletManager)
  • a class (usually gs.viewlet.manager.WeightOrderedViewletManager or a subclass of it)
  • a template
  • a name
  • a layer if overriding a default Viewlet Manager

The template typically defines the layout of the ViewManager’s area and pulls in content from the Viewlets registered with the ViewletManager. Sometimes, this is nothing more than an iteration through the registered Viewlets.

While the interface and class can in theory define interesting properties or methods, these are usually quite bare.

Properties

Instances of a Viewlet Manager will have access to the current

  • context
  • request
  • view

In addition, viewlet managers provides a global options/viewlets variable (in templates) that is an iterable of all the available viewlets in the correct order.

Types


Viewlets

Viewlets tend to be where the look of a display or UI component is defined, and where the fetching and processing of content occurs or is initiated.

Declaring

Like Viewlet Managers, Viewlets are usually declared in an egg's configure.zcml. These declarations usually include

  • the interface of the Viewlet Manager being attached to
  • a class (usually gs.viewlet.viewlet.SiteViewlet, or gs.group.base.GroupViewlet, or a subclass of it)
  • a template
  • a weight (used for ordering in WeightOrderedViewletManager)
  • a title
  • a name
  • a layer if overriding a default viewlet

Note that it is entirely possible, and not uncommon, for an egg to declare a new Viewlet using interfaces, classes, and templates defined entirely in other eggs.

Classes

Viewlet classes tend to be more sophisticated than Viewlet Manager classes. Viewlet classes usually define properties that are used by the Viewlet's templates to display information. Viewlets classes often also include methods for processing information retrieved from data sources.

GroupServer provides a couple of Viewlet classes. When creating Viewlets for GroupServer/E-Democracy, the Viewlet class will almost always extend one of these classes.

GroupServer Site Viewlet

gs.viewlet.viewlet.SiteViewlet

Very similar to the Site Content Provider above. This viewlet is used on site pages, and provides the following properties:

  • siteInfo - A groupserver.SiteInfo instance
  • loggedInUser - A groupserver.LoggedInUser instance

GroupServer Group Viewlet

gs.group.base.viewlet

Very similar to the Group Content Provider above (currently, this Viewlet is actually a simple wrapper of the Group Content Provider).

In addition to the properties provided by gs.viewlet.SiteViewlet, the following properties are provided:

  • groupInfo - A groupserver.GroupInfo instance.
  • viewTopics - Indicates if the user has permission to view topics in the group.
  • isAnnouncement - Indicates if the group is an announcement group.

Pages

GroupServer provides a number of Page objects, classes which can be extended to create a full webpage that is associated with some URL and context. They are based on Zope's Page objects, with a couple of additional convience attributes and methods (such as a SiteInfo attribute and the GSUserInfo instance of the current viewing user). Generally speaking, these Page objects are divided between Group page objects - objects meant for pages that are viewed within a group content (i.e. group home pages, topics, etc...) - and Site page objects - meant for pages viewed outside of a group context (i.e. site homepage, user profile page, etc...). These Page objects are also divided based on the primary purpose of the page, with Page objects available for pages that are meant to be viewed via a browser, pages that are meant to be email messages, and pages that are meant to take input from the user.

Browser Pages

Input Pages

Email Pages

Style

GroupServer uses two systems to style Pages, one for Browser Pages, and one for Email Pages. In both cases, a given page will rely on the CSS that is provided by one of these two systems. In both cases, the CSS is based on Twitter's Bootstrap.

Browser Page CSS

gs.content.css is the core of the CSS system for browser pages. If you are using the default GroupServer style, then all styling will come from this class. This class provides icons and fonts to support the default style, as well as two important CSS files: globalstyle.css - the file that establishes the Bootstrap based CSS framework - and site.css - the fill that defines the style of a given skin.

Note that the URLs of globalstyle.css and site.css should contain a date string. This is so browsers can cache CSS files for long periods of time (~10 years), thus reducing unneccessary file deliveries. This also requires that all skins served by the same instance of GroupServer must provide matching globalstyle.css/site.css URLs with matching date strings. In the future, this whole aspect of serving CSS will be streamlined.

In general, a GroupServer instance will implement its own skin. In these cases, the skin class will provide its own site.css file. For an example, see gs.skin.blue.

Email Page CSS

The styling associated with an email message is provided by a different system. This is for two reasons:

Because email messages can not fetch resources beyond what is already contained in a message (and images of the user allows), CSS is delivered as part of the HTML message. Thus, there are no URLs associated with email CSS.

gs.content.email.css is the foundation of the Email Page CSS system. Email Pages pull in viewlets provided by gs.content.email.css that provide CSS. Notably, gs.content.email.css provides viewlet managers that other eggs can associate their own CSS viewlets with, providing a way for eggs to define their own style for their unique UI elements.

Layout

Virtually all pages provided by a GroupServer instance will inherit one of a handful of layouts provided by two classes, making it easy to provide a consistent layout across your site and make updates quickly.

Brower Page Layouts

gs.content.layout provides the core layouts for browser pages. Skins that wish to alter this layout can override the layouts provided by gs.content.layout.

Email Page Layouts

gs.content.email.layout provides the core layout for email pages. Again, skins that wish to alter this layout can override the layout provided by gs.content.email.layout.

 

Home - Mobile - Forums - Wiki - Blog - About - Help - Contact - People - Donate - Rules - Archives