Planet Module API

Source repository: https://code.edge.launchpad.net/~m-baert .You may download it directly from command line:

bzr branch lp:~m-baert/drupal-planet/6.x

Attention:

This is unofficial an draft dcoumentation in continuous change. Please refer to http://drupal.org/project/planet for official releases.

Purpose

Planet is an RSS feed aggregator dedicated to your site users own blogs.

Your site thus promotes community spirit by offering your members a place to share their ubuntu-related articles and contributions, in the spirit of http://planet.ubuntu.com/ .

The challenge for this module may be to provide site administrators agile and efficient means to keep this tool serving this spirit, as the number of users grow, while being as friendly as possible.

Readers who understand French may find these pages interesting:

• http://doc.ubuntu-fr.org/evenements/planet
• http://forum.ubuntu-fr.org/viewtopic.php?pid=63810

Entry Points

• Module help text
• Configuration

Configuration

Main administration page for Planet is accessed from path admin/settings/planet and presented via _planet_settings().

However, each authorized user manages his self-provided feeds from a new tab in his account settings page, user/%25user/planet / planet_page_last().

Feed definition

To add a new feed, give it a title, select an author, provide the feed url, and you're off.

Feeds management

This section lists current feeds, when they were last updated, how many items they have, and it allows you to edit, refresh, or freeze them. Freezing is a quick way to temporarily suspend updates from the given feed.

Feed refresh

You'll have to manually refresh it or wait for a cron run for items to be imported.

Automatic refresh can be disabled by freezing the feed.

Feed items presentation

The filter format drop down will allow you to select the filter format that will be used to show planet entry nodes.

Content Types

• Planet Entry : Node to contain posts aggregated from various blogs. configured at admin/content/types/planet.

pages

Main user page for Planet allows visitor to read all users feeds. It is accessed from path planet and presented via _planet_page_last().

Module help text

Module Definition

Here's how planet is defined in planet.info :

• name Planet
• description Aggregates RSS feeds and faciliates their association with site users who belong to a given role.
• package Community - optional
• version 6.x
• core 6.x

History notes

dropped features

Converting feed items to blog nodes

avatars

This provides the benefit of showing avatars with content, providing per-user aggregation of planet content in addition to blog content, etc.

Focus on user role

The role to select bloggers from lets you narrow the user list for when you're adding a feed and associating it with a user. A common setting will be to create a staff role and use this for planet.

Menus and Pages

Menu items and page callbacks are defined in the hook_menu() implementation, planet_menu.

This diagram shows how requests are handled.

Menus and Page Requests

Each arrow is labeled with the permission required to access link.

The menu item colors reflect the item type:

• MENU_NORMAL_ITEM (default) Normal menu items show up in the menu tree and can be moved/hidden by the administrator.
• MENU_LOCAL_TASK Local tasks are rendered as tabs by default. For menu items that describe actions to be performed on their parent item.
• MENU_CALLBACK Callbacks simply register a path so that the correct function is fired when the URL is accessed. They are not shown in the menu.

Global calls graph

Here is a map of internal function calls.

It is quite large for now, and may not be easy to read as displayed here, but you may download the svg version here.

Dashed lines show indirect invocations ( hooks, callbacks, forms, other handlers ).

Database access is also shown with access type indicators:

• C : Create table rows
• R : Read table rows
• U : Update table rows
• D : Delete table rows

Internal Function Calls

Function Groups

Each planet function may belong to one or more categories:

• Basic Definitions for Planet Module
• System Interaction
• Page callbacks (Menu System)
• Forms
• Planet Node Type support
• All Implemented Hooks
• Managing Planet feeds
• Managing Planet feed items
• RSS Feed Handling

Persistence

Planet data is stored in the following database tables:

planet module tables

planet_feeds

planet_items

Table planet_feeds

The base table for planet.

Name	type	size	description
#fid	serial		Primary Key: Unique identifier for a planet RSS feed.
ouid	int		Foreign key to users.uid . Identifies user who choose the feed.
title	varchar	50	Title of the feed.
link	varchar	80	URL to the feed
oimage	varchar	120	An image representing the feed
ochecked	int		Last time feed was checked for new items, as Unix timestamp
frozen	int		When TRUE, prevents the feed from being automatically updated
ohash	varchar	32	A hash of the feed's headers.
error	int	1	Whether the feed is throwing errors or not.

Other Indexes

• name: error; columns: (error)

Table planet_items

Connects a planet feed to its owned planet nodes

Name	type	size	description
#id	serial		Primary key: Unique identifier for a planet feed item
ofid	int		Foreign key to the planet_feed.fid which owns this item.
onid	int		Foreign key to the node.nid of the planet node where this item is stored.
iid	varchar	32	md5 of the feed item's title and body.
oguid	varchar	120	TODO: describe me
olink	varchar	180	TODO: describe me
ocreated	int		TODO: describe me

Classes and OOP (experimental)

Recent versions of Doxygen allow to define, directly in doc blocks, classes and members, as well as other OOP concepts, even when not explicity defined in source code.

At the moment, I'm only testing the feature, so don't pay attention so the related output or suggested software architecture.

Examples:

• class OOplanet_node
• class OOplanet_feed