modules/mysite/README.txt

// $Id: README.txt,v 1.27 2007/12/30 00:16:14 agentken Exp $

-------------------------------------------------------------
README.txt for MySite version 5.x.2.y
-------------------------------------------------------------
Drupal version: 5.x

Author: Ken Rickard
Email: agentrickard [at] gmail [dot] com
Drupal: agentrickard
CVS: agentken
IRC: agentrickard

Additional documentation is online at:

  http://therickards.com/api


CONTENTS
=======
* == NEW in 5.x.3
^ == requires the MySite Icons module

1.    MYSITE OVERVIEW
1.1     Installation
1.2     Credits
1.3     MySite Terminology
1.4     Features
1.5     Access Control Permissions
1.6     Menu Items
1.7     Suggested Usage
1.8     User-Submitted Content

2.     BASIC CONFIGURATION
2.1     Activating Content
2.2     Plugins and User Options
2.3     Required Plugin Files
2.4     The 'Contrib' Folder
2.4.1     Current Contributions
2.5     CSS Files and Layout Issues

3.     DEFAULT USER SETTINGS
3.1     Default Page Settings
3.2     Default Page Content
3.3     Locking Content for Users

4.     MYSITE SETTINGS
4.1      Content Settings
4.1.1     Content Types
4.1.2     Disabled Content Types
4.1.3     Adding New Content Types
4.2      Display Settings
4.2.1     MySite Sitename
4.2.2     MySite Behavior
4.2.3     MySite Privacy
4.2.4     MySite Page Setup
4.2.5     MySite Item Deletion
4.2.6     MySite Node Links
4.3      Content Browser
4.3.1     Content Browsing ^
4.3.2     Content Layout ^
4.3.3     Items per Page
4.4      User Limits
4.4.1     Item Count
4.4.2     Element Count
4.4.3     Page Count *
4.5      Action Buttons
4.6      MySite Cache
4.7      Default MySite Page

5.      TYPE INCLUDE SETTINGS
5.1     All Content Types *
5.2     Droplets
5.2.1       Custom Droplets
5.2.2       Block Droplets
5.2.3       Views Droplets
5.2.4       Panels Droplets
5.3      Feeds
5.3.1      Aggregator Feeds
5.3.2      Allowed Feed Categories
5.3.3      Default Feed Category
5.3.4      Update Interval
5.4       Nodes
5.5       Posts
5.6       Profiles
5.7       Terms
5.8       Themes
5.9       Users

6.      MYSITE ICONS ^
6.1       Why Use Icons?
6.2       Icon Settings
6.3       Default Icons
6.4       Custom Icons
6.4.1       Adding a New Icon
6.4.2       Changing Existing Icons
6.4.3       Deleting MySite Icons
6.5       Aggregator Icons

7.      DEVELOPERS API
7.1       Changes from Earlier Releases
7.2       Type Plugins
7.3       Layout Plugins
7.4       Format Plugins
7.5       Style Plugins
7.6       Integrating With Modules and Themes

8.      CONTRIBUTING
8.1       Submitting Bug Reports
8.2       Submitting Feature Requests
8.3       Submitting New Plugins
8.4       Calls for Help

---------
1.  MYSITE OVERVIEW

MySite pages are designed to let users create a personalized summary of the
site and their favorite places on the Web.  As such, the MySite module
duplicates the functionality of tools like MyYahoo! and Google's personalized
homepage.

The module allows registered site users to create a MySite page that contains
content from throughout the site.  For sites that use the Aggregator module,
users may also add feeds from external web sites to their MySite pages.

Content collections are specific to each user, and users can choose:

  - One or more pages of content.
  - A custom layout for each page.
  - A personal stylesheet for each page.
  - The content format for each page element
  - A personal theme each page.

MySite was written using an API/Plugin model that allows the core module to be
extended to handle additional content types.  The following content concepts are
supported by MySite:

  - "Droplets" of content (HTML, PHP, or JavaScript code)
  - Blocks generated by other Drupal modules
  - Content generated by the Views and Panels modules
  - Individual RSS feeds handled by Aggregator
  - RSS feed categories handled by Aggregator
  - Blog posts by individual site users
  - Forum topics and content
  - Content assigned to taxonomy terms
  - Pages added to individual books
  - User profile data for each MySite user
  - Content posts of a specific node or CCK type
  - All posts by a specific user

The intent is for the core MySite module to handle core Drupal publishing
frameworks.

In order for MySite to function correctly, you must first enable and configure
the content types that your site will use.  For details and restrictions, see
section 5 of this manual, TYPE INCLUDE SETTINGS.

----
1.1  Installation

See the INSTALL.txt file for complete instructions on installing and upgrading.

----
1.2  Credits

MySite is sponsored by Morris DigitalWorks.  http://morrisdigitalworks.com/

Special thanks to:

    * jjeff for the jQuery Update and jQuery Interface modules
    * starbow for his work on AHAH and ajax-based tables and forms
    * merlinofchaos for tips and tricks regarding page layouts
    * Mark Baggett and Heine for security review
    * dww for the Project module
    * jonbob for the API module
    * douggreen for the Coder module
    * kbahey for getting me started in CVS
    * yelvington for encouragement
    * bobscape and MDW for time to work on the project
    * tdekhnich and mdekkers for the string settings patch
    * mikesmullin for patches and code review

    * All the Drupalers who submitted bug reports and patches

----
1.3 MySite Terminology

The following terms are used throughout this documentation and in elements of
the MySite administrative and user interfaces.

  User -- the person looking at a MySite collection.
  Owner -- the person to whom a MySite collection belongs.  (In cases where the
    user is the owner, the term User is generally applied.)
  Admin -- the person(s) who may administer MySite settings and collections.
  Personal Page -- the default MySite page for a user.  Also called page.
  Settings -- the display options available to a MySite user.
  Content -- the content options available to a MySite user.
  Collection -- a MySite user's current content selections.  A collection may contain
    multiple pages.
  Page -- a specific page view in a user's collection.
  Item -- a group of content displayed on a MySite page.
  Element -- the number of headlines or stories within a content item on a
    MySite page.
  Plugin -- a code file used to define and extend MySite options and features.
  Content Types -- a MySite plugin that defines and controls how content items
    are generated.
  Icon -- a graphical element used by MySite.
  Action Buttons -- display elements that trigger changes in a user's MySite
    page.

If you need help with common Drupal terminology, see:

  http://drupal.org/node/21951.

If you find deviation from these terms, you may consider it an interface bug
and open a new issue at http://drupal.org/project/issues/mysite.

----
1.4  Features

MySite allows each registered site user to create a page that shows a custom
view of the site's content.

Users with the permission to create a MySite page have the following features:

  - The user page exists at http://example.com/mysite/UID/view, where UID is
    the user's Drupal id.
  - User pages can be named and may be made public or private at the user's
    discretion.
  - An overview page, http://example.com/mysite/all, shows all public MySite
    pages, so that users can see how other people organize site content.
  - Users may add and remove content from their MySite.
  - Users may sort the order of their MySite content.
  - Users may rename the title of their MySite content items.
  - Users may choose a display format for each MySite content item.
  - Users may select the following options based on the plugins available:
      - Theme, which selects the Drupal theme used to display the MySite page.
      - Layout, which controls the page structure of the MySite content.
      - Style, which controls the CSS file used to present the MySite content.
      - Format, which controls what information to display for each MySite item

Administrators have the following settings options available:

  - How to handle the URL http://example.com/mysite.
      The two options are to go to the list at http://example.com/mysite/all
      or to automatically redirect the user to his or her MySite page.
  - Which of the available content plugins are available for users.
      As noted above, MySite ships with twelve (15) content types (including a
      "Most Popular Content" type); admins do not have to enable all the
      content types for their site.
  - How many items a user can assign to the MySite page.
      Since retrieving the data for a MySite page can be intensive, there is
      a default cap of 10 content items per MySite page.  This number can
      be altered under the module settings.
  - How many elements are displayed for each content item in a MySite page view.
      As above, if we pulled back all content related to a taxonomy term,
      pagination and response time may become an issue.  Since MySite is
      designed to be a gateway to content, the default caps the element count
      at the 5 most recent articles.
  - Whether or not to use the included action button icons in MySite.
  - Whether and how long to cache MySite content views (see section 4.6
      for more detail).
  - How to handle user-submitted Aggregator content (RSS feeds).
      Since we allow users to submit their own RSS feeds, the administrator
      should set default values for the updating and categorization of these
      feeds (see section 3.1.1 for more detail).
  - Which taxonomy vocabularies to allow users to access with MySite.
  - A default user MySite page for use as a site homepage or navigation element.
  - Whether to show default theme blocks on MySite pages, or to give MySite the
     entire page width.
  - What default content and formats to use for new and anonymous users.

----
1.5  Access Control Permissions

MySite has the following access control permissions by default:

  - 'administer mysite'
    Allows a user to control the MySite settings at:
        http://example.com/administer/settings/mysite.
    Users with this permission also have the ability to edit other user's
    MySite content and settings.  This is allow you to provide customer
    support for users having trouble with MySite.

  - 'edit mysite'
     Grants a user the ability to create and update a MySite page.

  - 'view mysite'
    Grants a user the ability to see public MySite pages created by other
    users.

If the Aggregator module is present and enabled, then an additional permission
exists:

  - 'add mysite feeds'
    Grants MySite users the ability to add RSS feeds to the site based on the
    settings established under the MySite settings page.
    (See sections 1.8 and 5.3 for more detail).

----
1.6  Menu Items

For most users, the menu paths enabled by MySite are the following:

  - http://example.com/mysite-all
    A list of all public MySite pages, visible to those with 'view all mysites'
    permissions.

  - http://example.com/mysite-default
    The default user's MySite page.  This is used if the site admin wants to
    keep a public page, especially as a front page.  This value is set in the
    module settings and is optional.

  - http://example.com/mysite/UID/view
    The MySite page for a given user id (UID).

  - http://example.com/mysite/UID/edit
    The MySite configuration page for a given user.

  - http://example.com/mysite/UID/content
    The content adding page for a given user's MySite

  - http://example.com/mysite/UID/reset
    Reverts a user's collection to the default settings and content set by the
    site administrator.  See http://drupal.org/node/153560

  - http://example.com/mysite/UID/delete
    Allows a user or the administrator to delete an entire MySite collection.

  - http://example.com/mysite/UID/settings/MID
    The settings configuration page for an item in a user's MySite collection.

All other menu items are callback functions or administrative settings.

In the main site navigation menu, two links are registered by default:

  - 'My SITENAME'
    A link to http://example.com/mysite/UID/view, where SITENAME is taken
    from admin/settings.

  - 'View all custom sites'
    A link to http://example.com/mysite-all

----
1.7  Suggested Usage

MySite gives your users a personal homepage for your web site.  The recommended
usage is to configure the third-level domain http://my.example.com to send
visitors directly to http://example.com/mysite.

Under this configuration, set the MySite settings for 'Display Settings' to
'Go to User MySite.'  This is the default setting and will automatically
direct users from http://example.com/mysite to http://example.com/mysite/UID/view.

If MySite is configured in this manner, you can market and promote the URL
http://my.example.com as you see fit.

Giving instructions for configuring sub-domains on your server is beyond the
scope of this file.  For more information, start with
http://en.wikipedia.org/wiki/Subdomains.

If you cannot configure your 3rd-level domain, you may also choose to set your
default site homepage to be 'mysite' and then direct MySite to "Go to user
MySite page."  To set your default homepage, go to Administer >> Site
Configuration >> Site Information and change the "Default front page:" to
'mysite' (the default value is 'node').


----
1.8  User-Submitted Content

A note here on how MySite interacts with Aggregator.  The key feature of sites
like MyYahoo! and Google's personal homepage is that they allow users to import
content from across the web to a single page.

Normally, the ability to add an Aggregator feed to a Drupal site is restricted
to trusted users (the site administrator, and perhaps a specific role).  In a
few cases 'authenticated users' are allowed to add their own RSS feeds using
Aggregator.

That is because misuse of Aggregator can have some adverse effects,
particularly if feeds are updated too often, or if too many feeds are updated
at the same time.

Further, Aggregator's method for selecting Categories for RSS feeds is rarely
opened to authenticated users.

MySite handles these issues in two ways.

  1) It is possible to simply turn off the ability for users to add their own
  RSS feeds to their MySite page.  Deselect the 'add mysite feeds' permission
  in your site's access control settings.

  2) The site administrator can configure the default settings for handling
  user-submitted RSS feeds.  Those controls are at
  http://example.com/administer/settings/mysite, under the
  'Feeds' tab.

If you grant users the ability to add RSS feeds to their MySite, they only
have limited permissions, described below.

  - Users can only enter the Name and URL of the feed source.  Other settings
    (update frequency, categories) are set by the administrator.

  - When a user enters a new feed, both the title and the URL are checked
    against existing feeds.  If a match is found, that existing feed is used
    and the new feed is ignored.

  - Users can only assign a feed to a category if the administrator enables
    more than one feed category under the module settings.  In practice, we
    recommend that you establish a User Feeds category in Aggregator and force
    all user submitted feeds into this category.  Doing so has the effect of
    separating user-submitted feeds from those entered by site administrators.
    Some, but not all, sites will desire this type of separation to indicate
    which feeds are 'endorsed' by the site and which are the responsibility
    of site users.

  - If only one category is available for users to add feeds, that category
    will be used for all user-submitted feeds.  If more than one is available,
    users may choose, though the administrator can set a default category.

Further separation of user feeds from 'site administrator' feeds is not
possible without changes to the Aggregator module.  Such changes are also, in
most cases, not necessary and are considered out of scope for MySite.


--------
2.     BASIC CONFIGURATION

The MySite module has a large number of configuration options.  Individual
Content Types can also define their own settings.  This section covers only
the most basic options.  For further detail, see sections 4 and 5.

----
2.1  Activating Content

For MySite to function, three conditions must be met:

  1) Your site must contain some content or the ability to create content.
  2) The directory mysite/plugins/types must exist and contain the type.inc
     file you wish to activate.
  3) At least one MySite Content Type must be activated.

On the MySite settings page (http://example.com/admin/settings/mysite), you
have the option of enabling all content types that are available.  However,
you are not required to offer all content to users.  Use these settings to
determine which content types can be added to a MySite page.

The MySite module is largely dependent on other modules.  In MySite 5.x.2,
however, you can configure MySite to work if you activate "Droplets," since
these are independent of other modules, or "Posts" or "User Posts," both of
which use required core modules.

To get the full benefit of the MySite module, at least one of the following
core modules should be active on your site:

a) Aggregator
If you wish to allow users to add new RSS feeds, set the appropriate Aggregator
settings for MySite at http://example.com/admin/settings/mysite (the Feeds tab).

Note that there are two types of feed handling in MySite.  'Web Feeds' refer to
individual RSS feeds.  'Web Headlines' refer to Aggregator categories
containing multiple RSS feeds.

b) Blog
If the Blog module is active, MySite will allow users to add any active blogger
to their MySite page.

c) Book
If the Book module is active, MySite will allow users to track recent changes
to individual books.

For this feature to work, at least one book must exist.

d) Comment
If the Comment module is active, MySite will allow users to track comments
on specific posts.

e) Forum
If the Forum module is active, MySite will allow users to add Forum topics to
their MySite page.

For this feature to work, at least one forum container and one forum topic
must be present.

f) Path
If the Path module is active and you turn on Path Aliasing, each MySite will
be aliased to the path 'mysite/USERNAME' when the MySite is created or updated.

g) Taxonomy
If the taxonomy module is active, MySite will allow users to add tagged content
to their MySite page.

For this feature to work, you must have at least one Vocabulary and one Term
created at http://example.com/admin/content/taxonomy.

Note that Forum categories are not included in MySite's taxonomy-based lists.

h) Theme
MySite supports user-based theme settings. When enabled, MySite users may
choose from any active site theme. Anyone viewing a MySite page will view the
page in the user-selected theme.

Special Cases

i) Droplets, Blocks and Views
"Droplets" are the Drupal equivalent of Google Gadgets: they enable the site
administrators to create small widgets that add new features to the site.
Droplets can be created from HTML, JavaScript, or PHP code.  They can also be
generated from Blocks or from Views.

MySite does not expose Blocks or Views directly to end users; the administrator
must select which elements to expose via the Droplet creation system.

j) Node and CCK (Content)
The node module is a required core module.  MySite can handle requests for all
posts of a specific node type.  If you use the CCK (Content) module, CCK node
types are also supported.

k) User
The user module is a required core module.  MySite can track posts based on
individual users.

See sections 4.2.1 and 5 for additional details.

----
2.2  Plugins and User Options

Part of the design of MySite is to reduce code overhead through the use of
includes (called Plugins).  For MySite to function, certain plugins are
required, but others are optional and can be removed.

In the case of Format, Layout, and Style plugins, the "default" file is always
required.  If this file is the only plugin present, users will not be allowed
to change their content settings.

For Type plugins, only the plugins you wish to use need to be present.  Since
the administrator can deactivate Content Types, there is no reason to remove
these files.

For additional detail, including how to change the default files, see the
README.txt files in each plugin directory.

----
2.3  Required Plugin Files

If you remove any of these files from your modules directory, MySite will not
work correctly.

    mysite/plugins/formats/default.theme
    mysite/plugins/layouts/default.php
    mysite/plugins/styles/default.css

----
2.4  The 'Contrib' Folder

When you download MySite and untar the file, you may see a 'contrib' folder
within the MySite directory.  Files within this directory require Contributed
rather than Core Drupal modules.

MySite development has been targeted at Drupal's Core modules.  The items
within the "contrib" folder are designed to extend MySite for use with
additional modules.

Any file within the "contrib" folder can be used with MySite by placing the
file inside the appropriate "plugins" folder.

For instructions, open the file and look for this section at the top:

  /**
   * INSTALLATION
   *
   * Requires: name_of.module
   * Directory: mysite/plugins/path_to_folder
   * Settings: Yes / No
   *
   */

These items indicate:

    1) Requires: the name of the module required to use this Plugin.
    2) Directory: the location of the MySite plugins folder to put the file.
    3) Settings: whether the plugin requires any administrative settings
       before it can be activated.

----
2.4.1  Current Contributions

MySite 5.x.2 ships with four contributed plugins.

  - biblio.inc -- for the Biblio module, plugin by csc4
  - refine.inc -- for the Refine by Taxonomy module, plugin by agentrickard
  - storylink.inc -- for the Vote Up Down module, plugin by patchak
  - weblinks.inc -- for the Links / Weblinks module, plugin by suchold-it

For more information on contributing to MySite, see sections 7 and 8.

----
2.5 CSS Files and Layout Issues

A note here about mysite.css and the included layout files.

On fixed-width layouts, content that extends beyond the default width of columns
on the mysite pages will be forced to scroll in order to not break the page
layout. As three column layouts create more narrow columns, you are more likely
to see scrolling on mysite pages with 3 columns.

The css that governs this behavior is the div.mysite-group (lines 59-64 of
mysite.css).  If you prefer, you may set the 'overflow' value to 'hidden'.
Doing so will hide parts of elements that extend beyond the content group.

Remember that you can also remove layouts that you do not wish to use.

--------
3.  DEFAULT USER SETTINGS *

As of MySite 5.x.2, the administrator can now set up the user default settings
for MySite.  It is highly recommended that you configure MySite's default
options for your users.

----
3.1  Default Page Settings *

Clicking on the "Default page settings" tab will take you to the MySite
configuration page for user 0 (zero).

The settings and content that are established for user zero (0) will be used
for all anonymous users who visit http://example.com/mysite and for all users
who have not yet created a MySite page.

Further, when a user creates a MySite page, the user's settings will initially
match the Default Settings.

----
3.2  Default Page Content *

As of MySite 5.x.2, the administrator can now select a default set of content
to show to all anonymous users and to authenticated users who have not yet
created a MySite page.

When a user creates a new MySite page, the default content set will
automatically be saved in their collection.  Once saved, the user can change
his or her individual content settings to remove the default content.

To define the default content set, click on the "Default page content" tab
of MySite's administration page.

----
3.3  Locking Content for Users *

For MySite 5.x.2.5 and higher, the site administrator now has the option to
"lock" default page content.  Locking content forces the content element
to load for each MySite user; locked content loads in the position set by
the site administrator.

To lock a content item, click on 'Default Page Content' and click the
configure action button.  You should see a checkbox that asks if you
would like to lock the content.  Check the box and submit the form to lock
the content item.

Note: This feature may have some odd behavior when the user changes
his or her content layout.  Since the user no longer has control over the
position of locked content, there may be some user confusion.

See http://drupal.org/node/152917 for the feature request.

--------
4.     MYSITE SETTINGS

This section covers the core settings for MySite.  The options are divided
into sections on the MySite settings page.

----
4.1  Content Settings

The Content Settings option highlights the Content Types panel, which lets you
configure which content options will be available to your users.

These settings control the options that MySite users will be presented.

----
4.1.1  Content Types

In the MySite Settings main page, find the section labeled MySite Content Types.
The default options are:

 MySite Content Types:
    Aggregation options:
    []  Web Feeds: News items for a specific Aggregator feed.
    []  Web Headlines: News items for an Aggregator category.
    Comment options:
    []  Post Comments: Comments on a specific post.
    Content options:
    []  Blog Posts: Blog posts from a specific user.
    []  Books: Pages from a book collection.
    []  Categories: Content assigned to a specific taxonomy term.
    []  Forum Topics: Forum posts within a specific topic.
    []  Posts: Add a specific post.
    []  Post Types: Content posts of a specific type.
    []  User Posts: Content posted by a specific user.
    []  User Profiles: Selected information about the user
    MySite options:
    []  Droplets: Content defined by the site administrator.
    []  Most Popular: The mysite content most requested by users.
    Usability options:
    []  Path Aliases: Creates mysite/USERNAME path aliases for MySite users.
    []  Theme Switching: Enables users to choose a theme for MySite.

Of these options, only the Droplets content type is native to MySite.  The
other options require that specific modules be present.  For example, if you
have not activated the Aggregator module, then neither the Web Feeds nor Web
Headlines options will be available.

Note: Some type files have configuration settings -- these are visible as menu
tabs.  Be sure to configure each active content type as needed.

See sections 2.1 and 5 for more information.

----
4.1.2  Disabled Content Types

You may also see a section like this on the settings page:

    Disabled Content Types:
    * Categories: Content assigned to a specific taxonomy term.
       The MySite Category options must be configured.

The MySite module checks to see if various options and permissions have been
defined before allowing you to activate a content type.  The module will
present you with a link to correct the configuration error.  After you make
the suggested change, the content type should be available for activation.

For further detail about configuring specific Content Types, see section 5.

----
4.1.3  Adding New Content Types

When a new Type plugin is added to your module, a new option should appear in
the Content Types of the Disabled Content Types lists.


----
4.2 Display Settings

Options that affect user interaction with MySite.

----
4.2.1  MySite Sitename

This option allows you to change the default 'My Sitename' string used
to display menu links and page titles for the MySite module.

Note: If you do not change this value, it will update if you change
the name of your site in your System Information settings.

----
4.2.2  MySite Behavior

Options: *default
 * Show list of all user mysites
    Go to User MySite

This option tells MySite how to behave when a visitor goes to
http://example.com/mysite.

Most installation will use the default setting 'Go to User MySite page' which
directs the user to http://example.com/mysite/UID/view.

The additional option 'Show list of all user mysites' mirrors the menu callback
for http://example.com/mysite/all and is mainly used for debugging.

----
4.2.3  MySite Privacy

Options: *default
 * Default setting is "public"
    Default setting is "private"

This option sets the default visibility of the owner's MySIte page with regard
to other users.  By default, all users with the "view all mysites" privilege
can see all other user personal pages.  Individual users can turn this setting to "private."

----
4.2.4  MySite Page Setup

Options: *default
 * Show MySite within normal theme
    Show MySite pages full screen

The administrator now has the option to turn off the left and right rail regions for
MySite pages.  This allows the user to have complete control over the content
presented by MySite.

If this feature is turned on, the "footer" region of your site will still be
printed on all MySite pages.

Note: The full screen display may have unexpected consequences for your theme,
since it eliminates the default sidebars and most page regions.  Test before
you deploy.

----
4.2.5  MySite Item Deletion

The administrator may configure MySite to require users to confirm the deletion
of content from their MySite collection.  Users have the option to disable this
feature for their own collection.

----
4.2.6  MySite Node Links

By enabling this feature, MySite will place a link at the bottom of all content.
The link, when moused over, will display a box of options related to the content.
Typical options include adding the item to your collection or deleting an item
from your collection.

----
4.3  Content Browser

The Content Browser settings affect how users will be presented the content
options for adding elements to their MySite page.

----
4.3.1  Content Browsing ^

This option will only be available if you have activated the MySite Icons
module.

Options: *default
 * Display a text-only table
    Display rows of icons

Versions prior to 5.x.2 presented users with a simple table of choices.  In
newer versions, MySite presents options for displaying content choices to users.

The default setting is to show a plain-text table of items, with "Add" links.

The optional behavior is to show a table of icons, with each icon representing
a content option.

----
4.3.2  Content Layout ^

This options will only be available if you have activated the MySite Icons
module.

Options: *default
    * 4
    Numbers 1 through 10

If you select the 'Display row of icons' option for content browsing, this
option is used to set the number of items to show per row.  You should test
this settings to optimize the presentation for your site theme(s).

----
4.3.3  Items per Page

Options: *default
    * 10
    10, 25, or 50

This option sets the pagination limit for the content browser.  In either
table or panel mode, this setting will control the number of items to show per
page.

----
4.4  User Limits

These options determine how much content a user can add to their MySite page.

----
4.4.1  Item Count

Options: *default
  * 10
     5, 10, or 20

Since MySite collects content from a variety of Drupal content, it can make a
high number of database requests.  This setting puts a cap on the number of
content items a user can add to a MySite page.  The default is 10.

----
4.4.2  Element Count

Options: *default
  * 5
     3, 5, 10, 15 or 20

MySite is meant to give a quick overview, not to substitute for reading the
original content in context.  This setting limits the number of items (links)
presented under each content group.  The default is 5.

----
4.4.3  Page Count *

Options: *default
  * 5
     1, 3, 5, 8, 10, 15 or 20

In 5.x.3, users may have multiple pages in their MySite collection.

This setting places a limit on the number of pages a user may create.

----
4.5  Action Buttons

Options: *default
    Text
  * Icons
    Icons and Text

MySite ships with a small set of GPL icons, created by agentrickard expressly
for MySite, which can be used to present the action buttons to users.  Select
the option that you prefer.  Default is 'Icons.'  The icons are previewed on
the settings page.

----
4.6  MySite Cache

Options: *default
   * Cache Off
      5 minutes
      15 minutes
      30 minutes
      1 hour

For high-traffic sites,  MySite might cause a high volume of database requests
(especially if the Item and Element Count settings are very high).  If you
have performance issues, you can cache the results of a MySite page view for
a set amount of time.

----
4.7  Default MySite Page

Options: *default
   * <empty>
    The numeric User ID of any MySite user

In response to http://drupal.org/node/93012, the administrator can now set a
default user id for MySite.  Visitors who browse to
http://example.com/mysite/default will be taken to that user page.

Default value is <empty>; if default user is not configured, then the page will
return users to the standard behaviors defined in 4.1.1.

Note: No navigation menu item will be generated for this link; you must add one
to your site manually.

--------
5.  TYPE INCLUDE SETTINGS

Each content type for MySite can be configured.  Some configuration options
are more advanced than others, see below for details.

----
5.1  All Content Types

As of MySite 5.x.3 (currently HEAD), there are default settings for all type
includes. These were developed by mdekkers and tdekhnich.  See
http://drupal.org/node/174673 for the history.

Each content type now has default settings, which include:

 -- Prefix value preppended to content titles.
 -- Suffix value appended to content titles.
 -- Menu label that appears to users in the content interface.
 -- Link target used when a user clicks on a headline link.

----
5.2  Droplets

Droplets are content elements similar to Drupal blocks, Google Gadgets and
Yahoo! Widgets.  The Droplet system allows the site administrator to define
custom content objects that users may place on a MySite page.

The Droplet system enables the creation of Droplets from code that you supply,
from existing Drupal Blocks, or from existing Views (if the Views module is
installed and active).

No Droplets are installed by default.  The following Droplet creation options
exist:

----
5.2.1  Custom Droplets

Custom droplets allow you to place whatever code you wish into a Droplet item.
In this sense, Droplets are very similar to Blocks.  We do not use the Drupal
Block system because it doesn't make sense to require administrators to create
new Blocks every time they wish to add a new Droplet.

Custom Droplets can contain any code that you desire, but are subject to
Drupal's normal input filter system.  If, for example, you wish to add the
JavaScript to use a Google Gadget, you must input that Droplet as "Full HTML."

----
5.2.2  Block Droplets

MySite will show a selection form that will allow you to convert any existing
Block into a MySite Droplet.  Simply select the Block to convert and submit
the form.  You will then have the option to preview and configure the Droplet.

Note: Not all Blocks make good Droplets.  Also note that Block access rules
do not apply to Droplets.  Any user can access any Droplet.

----
5.2.3  Views Droplets

If you have installed and activated the Views module, you can create Droplets
based on existing Views.  (You cannot, however, create Droplets based on
default Views until you have activated them locally.)

To create a Droplet based on a View, simply select the View from the select
list and submit the form.  You will then have the option to preview and
configure the Droplet.

Note: Not all Views make good Droplets.  In particular, Views that require
arguments cannot be handled by the current Droplet system.  The only argument
that a View on a MySite page can accept is the UID of the MySite page owner.

To enable this argument, use this code in your View:

  if (arg(0) == 'mysite' && is_numeric(arg(1))) {
    return array(arg(1));
  }

Also note that Views access rules do not apply to Droplets.  Any user can
access any Droplet.

----
5.2.4  Panels Droplets

The Panels module creates Blocks for each Panel.  These blocks  can be added
to MySite in the same manner described in 5.2.2.

----
5.3  Feeds

Please see section 1.8 "User-Submitted Content" before configuring Feeds.

If the Aggregator module is enabled and you have given users the permission
to 'add mysite feeds,' you will need to configure the default settings for
handling new Aggregator feeds.  These settings help prevent users from
overloading the Aggregator be setting throttles on update frequency.

----
5.3.1  Aggregator Feeds

  Options: *default
       Allow users to add new feeds
    * Do not allow users to add new feeds

Only if you 'Allow users to add new feeds' will the access control settings
appear.  Then you can give specific roles the ability to add new feeds.
Recommended use is to allow all registered users to add new feeds.

----
5.3.2  Allowed Feed Categories

  Options: varies
    default is <empty>

When a user adds a new feed through MySite, they will only be given the
category options that you allow.  If only one option is selected, there is no
choice allowed and all user feeds will be filed under the default category.

In MySite 5.x.2 Feed Categories are no longer required.

----
5.3.3  Default Feed Category

  Options: varies
    default is <empty>

Establishes the default feed category for user-submitted feeds.  This is
helpful because it separate user-submitted feeds from those set up by the site
administrator.

----
5.3.4  Update Interval

  Options: *default
      15 minutes
      30 minutes
      1 hour
      2 hours
      3 hours
   * 6 hours
      9 hours
      18 hours
      1 day
      2 days
      3 days
      1 week
      2 weeks
      4 weeks

Sets the feed update interval for all user-submitted feeds.  This prevents your
site from getting flooded when trying to process all user-submitted feeds.

----
5.4  Nodes *

The Node module is a core Drupal module.  This MySite feature also works with
CCK (Content) module to allow users to select content based on content type.

On the Nodes settings page, you should see a list of checkboxes for all
content types used by your site.  Simply select which elements you want users
to be able to access through MySite.

If you do not select content types, then all content types will be available to
users.

The MySite module will display the X most recent posts by type, where X is set
by the default Element Count setting.

Note: MySite does not use PHPTemplate for node formatting.  Custom node theming
do at the template layer will not appear to MySite users.  See the API
documentation for information about changing node templates in MySite.

----
5.5  Posts *

The Posts handler allows users to add single posts (Drupal nodes) to their
MySite collection.

The administrator may restrict users to specific node types.

If you do not select content types, then all content types will be available to
users.

----
5.6  Profiles *

The Profiles handler is new in MySite 5.x.2 and is a little tricky.  This
plugin works with the User module -- through hook_user() -- and the Profile
module to define the available profile elements that MySite users may display
on their personal page.

The problem is that Profile elements may be different for users of different
roles or permissions, or for users who have done certain actions (like
blogging).

The settings on this page establish the default elements for each user's
MySite profile item.  Users may change these settings after they activate
their profile item.

Note: MySite users can only add their profile to their personal page.  By
design, only publicly-viewable profile fields are allowed.  The link to a
user's MySite page provided by mysite_user() will not be shown, since it
is redundant.

----
5.7  Terms

If the Taxonomy module is enabled, you may configure which taxonomy categories
(Drupal vocabularies) that users may add to MySite pages.  At least one
vocabulary must be selected, and that vocabulary must have active terms.

If you select no categories, then all categories will be available to users.

----
5.8  Themes

On Mysite's Theme settings page, you will find a list of all active themes
for your web site. Check the themes that users are allowed to apply to their
MySite page and save. When users edit their MySite page, the available theme
list will be presented if more than one theme is made available.

----
5.9  Users *

The Users plugin is new in MySite 5.x.2 and allows MySite users to track posts
by individual site users.

The settings for this plugin are based on the user Roles active for your site.
Only selected roles can be tracked in MySite.  This feature lets the site
administrator have some selectivity over which users can be tracked.

By default, all "authenticated users" are available to all MySite users.  If
"authenticated users" are allowed, then _all_ roles will be allowed by MySite
except for "anonymous user".

Note: The "anonymous user" role is included in the list in cases where
anonymous users are allowed to post site content.


--------
6.  MYSITE ICONS *^

The MySite Icons module is included in the MySite 5.x.2 release.  The icons
module allows the site administrator to assign a small graphic to represent
a content item.

MySite Icons should work correctly for sites using both the Public and Private
file download methods.

The MySite Icons module allows the upload of GIF, JPG, and PNG files only and
stores them inside a folder your File uploads directory.

----
6.1  Why Use Icons?

An icon-based content listing page can be more attractive to users.  Using
icons makes MySite more similar to the experience of Google or Yahoo!

Icon usage with MySite is purely optional; enabling or disabling the MySite
Icons module will not affect the core MySite module.

----
6.2  Icon Settings

When you install  MySite Icons, two new Administrative menu items appear.
Both the path Administer > Settings > MySite Icons and the MySite settings
tab "Content icons" will take you to the MySite Icons settings page.

There are four options for MySite Icons.  All are required.

  1) MySite Icons Directory   * default: "mysite"
  This is the folder inside your File uploads directory where MySite will
  store icons.  A directory name is required.  The default value for this
  directory is "mysite" and should not need to be changed.  The directory
  name must not conflict with other modules.

  2) Icon maximum dimensions  * default "120x60"
  This sets the Width x Height (in pixels) of the largest size image that
  can be uploaded.  If your site uses GD or another supported image processor,
  MySite will automatically resize the image on upload.

  3) Icon maximum file size  * default "32"
  The maximum size of an icon uploaded through MySite, in kB. If your site
  uses GD or another supported image processor, MySite will automatically
  resize the image on upload.

  4) Download icons * default 'Attempt to download icons'
  To make icon loading faster and more secure, RSS feeds that contain image
  identifiers will have those images downloaded to a local directory.  If you
  wish to disable this behavior, set this option to 'Do not download icons.'

----
6.3  Default Icons

MySite comes with default icons that are used in cases where custom icons
have not been loaded.  These icons are all 120x60 pixels.  Changing the Icon
maximum dimensions setting may alter the appearance of these icons.

The following icons are provided inside mysite/plugins/icons:

  - icon-aggregator.png
  - icon-blog.png
  - icon-book.png
  - icon-droplet.png
  - icon-extra.png
  - icon-extra2.png
  - icon-extra3.png
  - icon-feed.png
  - icon-forum.png
  - icon-node.png
  - icon-term.png
  - icon-user.png
  - icon.png

These icons a used by the Type plugins for MySite.  If no type-specific icon
is found, the default icon.png is used.   The icon-extra.png files are included
if you wish to extend or change the default icons.

When a custom icon is not found, MySIte prints the default icon as a CSS
background image and displays the title of the item over the image.

Note: If a user has uploaded a User picture, it will be used by the Blog,
Profile, and User content types unless a Custom Icon is loaded.

----
6.4  Custom Icons

Custom Icons are uploaded by the administrator through a simple file interface.
They are checked, resized, and saved as {type}-{type_id}.ext inside the MySite
Icons Directory.  A record of the upload is also stored in the {mysite_icon}
table of the database.

----
6.4.1  Adding a New Icon

To add a new icon, click the "Add content icon" link under MySite Icon settings.
You will be shown a list of selection menus, one for each available Content
Type used by MySite.

Select the name of the item you wish to add an icon for and hit "Select Item
and Continue."  You will then be taken to an icon upload form.

Select an image file from your computer and submit the form.  On success, you
will be given the "Icon saved" message.  On failure, an error message will
appear.

Note: As the site administrator, you can also add icons from the MySite
Content Browser list at http://example.com/mysite/UID/content/type.  Click
the * next to the item title to add or change the icon for that item.

----
6.4.2  Changing Existing Icons

To change an existing icon, click the Current icons tab in MySite Icons
settings.  Doing so will take you to a table showing all current icons.

----
6.4.3  Deleting MySite Icons

From the Current icons screen, you may also delete an icon be clicking the
"delete" link and then verifying the deletion.

Note: Deleting files from the server may cause errors, since the icon record
is also stored in the {mysite_icon} table.  If you wish to delete all MySite
Icons, the preferred method is to Uninstall the MySite Icons module.  Doing so
will delete icons from the file server and the database.

----
6.5  Aggregator Icons

MySite is trying a new technique with site icons provided by RSS and ATOM
feeds.  Normally, the Aggregator module stores complete IMG tags in the
database, with absolute URLs to the files on remote servers.

This method introduces network latency when fetching images from remote
servers.  When MySite loads data for Aggregator feeds, it will attempt to grab
the feed icon and store a local version on your web server.

This behavior is recorded in your site logs whenever MySite tries (or fails)
to retrieve a feed image.

Images fetched from remote servers are processed and verified (as GIF, JPG, or
PNG files) the same way as uploaded files are.

For discussion on this feature, see http://groups.drupal.org/node/3716.


----
7. DEVELOPERS API

MySite is designed to be extended to handle additional types of content or
content groupings.  The API is documented throughout the code, in the API.php
file and online at:

    http://therickards.com/api

The API documentation can show you how to create new plugins to extend MySite.
This section defines the types of plugins and their roles within MySite,

----
7.1 Changes from Earlier Releases

For users who have written custom plugins, you may need to revise your code
to match changes in the API.

There have been substantial changes to the Format, Layout, and Style plugins.

Type plugins have changed in subtle ways and may not work in MySite 5.x.2
as they did in MySite 5.x.1.

Some specific items to watch for:

  FORMATS:
    Be sure you check the $element array for the 'content' item.
    If $element['content'] is set, then it should be printed for
    the end user instead of other data elements.

    Changes have been made to mysite_theme_hook().  See the API.

  LAYOUTS:
    Added mysite_layout_hook(), required API element.

    Added mysite_prepare_columns(), required element.

    The CSS ids and classes have changed radically to support
      the Interface drag-and-drop library.

  STYLES
    Styles have been rewritten totally.  Start over.  Use the
    provided examples as guides.

  TYPES
    Deprecated the THRESHOLD settings element.

    Changes the mysite_type_hook() array elements.

    Adds mysite_type_hook_active($type) for administrators.
    This function reports configuration errors.

    Make sure all items in mysite_type_hook_options use
    mysite_type_hook_title() to retrieve their names.

    Makes sure that mysite_type_hook_title() invokes the
    mysite_type_hook() with the parameter set to FALSE.
    (Failing to do so can cause infinite callback loops!)

    Note the use of the 'icon' element in the mysite_type_hook_options()
    array.

    In mysite_type_hook_data(), use mysite_teaser($node) to generate teaser
    elements for all nodes.  (Only call this function for nodes, though.)

    The function mysite_type_hook_block_node() is new to some.  It is
    used on node view pages (e.g. http://example.com/node/123).

For details on the API, see http://therickards.com/api.

----
7.2 Type Plugins

'Types' are content definitions.  They control the content selection options
available to the user and generate the data that is presented on a MySite page view.

They are named {type}.inc and stored in the /mysite/plugins/types/ folder.

----
7.3  Layout Plugins

These plugins handle the page architecture of the MySite page.  They are named
{layout}.php and stored in the /mysite/plugins/layouts folder.

Layouts have two parts: a {layout}.php file that defines the layout theme and
a {layout}.png image that is used in the layout selection form.

To create a new {layout}.png, use the provided default.png as a blank.  There
is a 5px space between sections in each provided image.

NOTE: You must at least keep default.php in this folder.  If you wish, you may
remove any other files.  If only one layout file is present, users will not be
given an option during MySite customization.

----
7.4  Format Plugins

Handles the presentation theming for individual content elements on a MySite
page.  They are named {format}.theme and stored in the /mysite/plugins/formats/
folder.

NOTE: You must at least keep default.theme in this folder.  If you wish, you
may remove any other files.  If only one layout file is present, users will
not be given an option during MySite customization.

----
7.5  Style Plugins

Handles stylesheets for user MySite pages.  Users may select the style that
they prefer.  They are named {style}.css and stored in the
/mysite/plugins/styles/ folder.

Current styles are very simple.  The default style is designed to respect
inherited styles, and is deliberately minimal.

All stylesheets should include the core styles defined in default.css,
rewritten as needed.  Only the selected stylesheet is loaded on MySite page
views.

NOTE: You must at least keep default.css in this folder.  If you wish, you may
remove any other files.  If only one layout file is present, users will not be
given an option during MySite customization.

----
7.6  Integrating With Modules and Themes *

As of MySite 5.x.2.5, you can now reference individual MySite content elements
from external function calls.  Two functions are available.

  mysite_render($type, $type_id, $uid = 0)
  Returns the raw data array for a specific content element.  Formatted
  according to mysite_type_data().

  mysite_display($type, $type_id, $uid = 0, $format = 'default')
  Returns a themed HTML snippet ready for insertion into a theme or to be
  used by a module or block.

In both cases, the functions are looking for the following information:

 $type ==  A string indicating the content type
 $type_id == The content id (such as term id) to retrieve
 $uid == The user account to retrieve MySite page settings for. Optional.

The $format parameter in mysite_display() is an optional name of the MySite
format plugin to use for output theming.

For more details, see http://therickards.com/api.

----
8.  CONTRIBUTING

The MySite project page is at http://drupal.org/project/mysite.  You are
invited to submit bug reports and feature requests there.

----
8.1  Submitting Bug Reports

Before submitting a bug report, please check the issue queue for duplicate
entries at:

  http://drupal.org/project/issues/mysite

When submitting a bug report, please include the following:

  - Drupal version (e.g. Drupal 5.3)
  - PHP version (e.g. PHP 5.1.6)
  - Database type and version (e.g. MySQL 4.1.13)
  - MySite release number (e.g. MySite 5.x.3.0)

If you don't include this information, I'll just have to ask you for it.

When you submit a bug report, it is very likely that I will need to ask you
follow-up questions, so please track your request.

----
8.2  Submitting Feature Requests

Feature requests are welcome, and should be submitted to:

  http://drupal.org/project/issues/mysite

Please check the "closed", "by design" and "postponed" feature requests before
submitting.  Your request may have been addressed previously.

Please limit each new issue to a single feature request.  If you have six
ideas, you may overview them in a single issue and then divide the requests
into separate tasks.  Doing so make development more efficient and tracking
collaboration easier.

----
8.3  Submitting New Plugins

To submit a new plugin for MySite, go to the project page and submit a new
feature request.  File the feature request under the specific type of Plugin
that you are submitting.

----
8.4     Calls for Help

The MySite module could use work on the following additions:

  - A comment.inc that tracks comments by user
  - A search.inc that tracks search terms
    (see http://drupal.org/node/102219)
  - Work on privacy settings for user content
    (see http://drupal.org/node/135378)
  - Work on "Pages" for MySite (see http://drupal.org/node/145423)


--------

/**
 * @file
 * Module information and configuration notes for the MySite and MySite Icons modules.
 */  