• VestaWeb
• PluginAPI

This page documents the API for the Vestaweb Plugin System. All plugins are file based Mason Components. They are called in alphabetical order among their type. To add a plugin, just drop the file in the directory given as the Location.

Directory Reading

There are two plugins involved in reading directories. The first is called for each directory entry, the second is called for the entire directory after all of the entry plugins have finished.

Directory Entry

• Location: plugins/dir_entry/

• Arguments:

  • $vs - the Vesta::VestaSource for this entry.

  • $name - name of this entry.

• Returns:

  • a false value to supress (hide) this entry. Hiding a version from the /package view will also hide all branches and scribbles based on that version. A plugin can use $r->request_comp to determine if it is being used by /dir or /package.

  • a reference to a hash in the following format (use {} ). A plugin wishing to make no changes should just return {} :

    • optionally {disp_name}  - a name to display instead of the actual file name

    • optionally {style}  - a CSS style string to effect how the name is displayed. This string should end in ; as the strings returned by multiple plugins will be concatinated together. This final string will be the value of the style attribute in a <span> tag.

• Examples:

  • Turn all items with 'vesta' in their name green.

  • Hide all items with an 'obsolete' attribute that has a true value.

Directory Contents

• Location: plugins/read_dir/

• Arguments:

  • @contents - an array of directory entry objects with the following fields (in order of usefulness):

    • {name} - the real name of the entry.

    • {disp_name} - if defined, the "display name" set by the directory entry plugins.

    • {style} - if defined, the style string set by directory entry plugins.

    • {type} - one of the types defined in Vesta::VestaSource::typeTag

    • {typeString} - the full name of the type

    • {master} - the mastership status

    • {fileSid} - the shortID of the file, if it is a file.

  • $vs - the Vesta::VestaSource of the directory itself.

• Returns: an array in the same format as the @contents argument. The items will be displayed on the /dir page in the order of @contents after all the plugins run.

• Examples:

  • Sort the contents of a directory into alphabetical order. Note: This one explicitly doesn't bother sorting the contents of a package because the /package page will re-sort into version order anyway. Though, it should check $r->request_comp instead since a user could view a package as a directory.

Directory View

These plugins can be used to add additional information to the end of each line in the directory view.

• Location: plugins/dir_view

• Arguments:

  • $name - name of the item

  • $vs - the Vesta::VestaSource of the item

• Returns: nothing. Any return value will be ignored. These plugins make their impact by outputting directly to the page.
• Examples:

  • Print an attrib button on the end of each line

  • Blame by line could be implemented with this mechanism.