gs.group.messages.base

Core messages support for GroupServer

Author:Michael JasonSmith
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2015-10-30
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.Net.

Contents:

gs.group.messages.base API

There are two parts to the API supplied by the gs.group.messages.base product: there is a viewlet and some utilities.

Viewlet

The gs.group.messages.base product supplies a viewlet — for the group page (gs.group.home) — called gs-group-messages-base. In turn it contains a viewlet manager that creates a slot for the various views of the list of messages. (In the user-documentation this is generally referred to as the archive.)

The viewlet manager provides the interface interfaces.IGroupHomepageMessages.

class gs.group.messages.base.interfaces.IGroupHomepageMessages[source]

A viewlet manager for the messages on the group homepage

The viewlets that provide lists for the Group page register against this interface.

<browser:viewlet
  name="gs-group-messages-topics-tab"
  manager="gs.group.messages.base.interfaces.IGroupHomepageMessages"
  template="browser/templates/topics.pt"
  class=".topicstab.TopicsTab"
  permission="zope2.Public"
  weight="10"
  title="Topics" />

The viewlets and viewlet manager combine to create tabs, using the Bootstrap tabs system. The title of each viewlet becomes the tab-title, with the content of the viewlet becoming the tab-panel. All the tabs are marked-up with WAI:ARIA roles. The viewlet itself has the HTML id attribute value gs-group-messages-base-tabs

Utilities

There are utilities for file icons and for formatting file sizes. These happen to be used in many different contexts, so the functions are placed here.

File icons

In GroupServer the file icons are actually characters. The icon font supplied by gs.content.css turns the character into a glyph.

gs.group.messages.base.get_icon(mimeType)[source]

Get the icon (character) for a particular MIME-type

Parameters:mimeType (str) – The mime-type to look up
Returns:The character for the icon representing the MIME type
Return type:unichr
Example

Call the function:

f['icon'] = get_icon(f['mime_type'])

Use the icon in the page template:

<a class="icon-alone" href="#" tal:attributes="href f/url; title f/name">
  <span aria-hidden="true" data-icon="&#x1f3a8;"
        tal:attributes="data-icon f/icon"></span>
  <span class="screen-reader-text">File type:
    <span tal:content="f/mime_type">application/octet-stream</span>
  </span>
</a>
File sizes

File sizes are displayed in the list of attached posts in both email and on the web, and on the Image page, hence the presence of the file_size_format() function here. It formats the size so it has the appropriate unit (b, kb, mb, gb, tb…) after it, or it displays empty.

gs.group.messages.base.file_size_format(bytes)[source]

A humanized string for a given amount of bytes

Parameters:bytes (int) – The number of bytes
Returns:The file size with the units
Return type:str

See also

The original version of this function <http://python.todaysummary.com/q_python_11123.html>

[1]The main section of the Group page is provided by gs.group.home.interfaces.IGroupHomepageMain. See gs.group.home <https://github.com/groupserver/gs.group.home>

Hierarchical and temporal navigation

Authors:Michael JasonSmith; Dan Randow
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2015-10-16
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.Net.

Hierarchy

There is a hierarchy of pages in GroupServer. The primary hierarchy is (from most general to most specific) Site, Group, Topic, Post, Image. This hierarchy is shown in the breadcrumbs going from left to right. Conceptually the site is at the top and any up link goes up to the page that is higher in the hierarchy, so there is a slightly awkward mapping of Left in the breadcrumbs onto Up in the navigation links.

It is possible that in future versions of GroupServer that this mapping may be removed, so the Left navigation button (or swiping to the right) will go the containing (more general) page.

Temporal navigation

The temporal navigation of messages in a group may seem inconsistent. However, it follows the principal of supporting the user’s task: follow closely, or keep in the loop. We switch mode because the user is switching mode; this is in tension with consistency.

Follow closely

If the user is following something closely then the posts are shown in a strict temporal order with the oldest post first. This is similar to a book, or a diary. There is one page that follows this order: the Topic page. This makes reading the conversation much easier.

Two other pages take their queue from the Topic page for organising the navigation links.

  • The Post page has four links: First, Older, Up, Newer, Last.
  • The Image page has three links: Older, Up, Newer. The Up link goes to the post.

Because Up has been taken for the page hierarchy, Left has been mapped to Up in the sense of moving higher on the Topic page.

Keep in the loop

Keeping in the loop is the other task supported by GroupServer. For interfaces that support this task the posts (or topics) are displayed from newest to oldest. These pages include:

  • The Site page, which lists topics
  • The Group page that lists topics, post, and files
  • The rarely visited Topics page
  • The even more rarely visited Posts page

In all these pages the Left navigation button has been mapped to Up in the sense of moving higher on in the list. So as all these interfaces show posts from newest to oldest Left is the same as Newer.

Changelog

3.2.0 (2015-10-30)

  • Adding the file_size_format utility
  • Adding unit tests
  • Adding Sphinx documentation

3.1.2 (2015-02-04)

  • Naming the reStructuredText files as such
  • Pointing to GitHub as the primary repository

3.1.1 (2014-03-26)

  • Switched to Unicode literals
  • Minor code cleanup

3.1.0 (2013-04-21)

  • Added the get_icon utility function
  • Updated the metadata

3.0.0 (2013-02-20)

  • Added accessibility with WAI-ARIA roles
  • Switching to Twitter Bootstrap tabs for the new GroupServer UI
  • Taking over responsibility of the Messages tabs from the Group page

2.0.1 (2012-12-17)

  • Following the updated search JavaScript

2.0.0 (2012-06-06)

1.1.0 (2011-04-21)

  • Updated help

1.0.0 (2011-02-18)

Initial version

This is the core code for displaying messages in a GroupServer group. This module supplies:

Hierarchical and temporal navigation is also discussed here, because it mostly comes up with the design of the pages associated with messages.

Indices and tables