Documentation for Metavus is an ongoing effort, that relies in part on your input to guide it. The information below is intended as a starting point. If there is a specific area that you would like to see more extensively documented, please let us know.
Core Concepts
Records
The core element for most operations in Metavus is the record. A record is a set of data used to describe, organize, or manage a particular item, which may be digital, physical, or conceptual (e.g. an event). Records may also contain the item itself, if it is digital.
Each record is associated with a particular schema.
Schemas
A schema is a defined set of fields, that each store a particular type of data. Schemas can be expanded and customized by adding, removing, and modifying fields, to best suit your needs.
In Metavus, schemas are used to catalog items in a digital collection, but can also be used for information about collections, users, and (via included plugins) web pages, blog entries, and events.
Field Types
Metavus supports 17 distinct types of fields:
Text – A short (usually single-line) string of characters.
Paragraph – A longer (usually multi-line) string of characters.
Email – An email address. (Like a Text field, but with special extra handling.)
URL – A web address, usually beginning with “http://” or “https://”. (Like a Text field, but with special extra handling.)
Number – An integer or floating point number.
Point – A pair of integer or floating point numbers, usually used to indicate a position in 2D space (like latitude and longitude).
Date – A date or date range, that may be approximate (for example, just the month and year).
Timestamp – An exact date and time.
Tree – One or more terms within a hierarchical controlled vocabulary, like a detailed subject classification.
Controlled Name – One or more terms within a flat (single-level) controlled vocabulary.
Option – One or more terms within a limited (small) controlled vocabulary.
File – One or more uploaded files.
Image – One or more uploaded images.
Flag – A boolean value (like True and False, or On and Off).
Reference – A reference to another record or item in the collection.
Search Parameter Set – A set of search criteria, to select a set of records or items.
User – A user on the system (like the person that created or last updated the record).
Controlled Vocabularies
Metavus supports both hierarchical and flat controlled vocabularies. Tree, Controlled Name, and Option fields use controlled vocabularies, and the Metavus distribution package includes several standard controlled vocabularies, that can be loaded into these fields.
Search Parameter Sets
Search parameters sets define a set of criteria to select a particular set of records or items. The contents of collections are determined by the set of search parameters associated with the collection, but search parameters sets are also used for things like automation rules, to select records or items to modify or alert specific users about changes to records.
Search parameters in a set may include things like looking for a text string in a particular field, but they may also include looking for specific controlled vocabulary terms, or whether a Flag field is set or cleared. Search parameters can also include whether a numerical field is greater or less than a specified value, or a date or timestamp is within a specified range. In general, anything you can specify on the Advanced Search page can be included in a search parameter set, including the operators and phrases discussed in the Advanced Search Tips section at the bottom of that page.
Search parameter sets can also include logical operators (AND and OR) and groupings, allowing very complex criteria to be constructed. This logical grouping capability, combined with the ability to include Search Parameter Set fields in a schema, makes them a very powerful tool.
Collections
In Metavus, a collection is a set of records or items, selected by a specific set of search parameters.
Collections are managed by the site or collection administrator. (The Folders plugin provides a way for individuals to organize and share their own groups of records or items.)
Privileges
Privileges control who can add, edit, or view records or items. They work through two mechanisms: privilege flags and privilege requirements.
Users are assigned privilege flags, which may be built in, like System Administrator or Controlled Name Administrator, or may be custom flags defined by the site administrator.
Schemas have privilege requirements associated with them, that determine who can add, edit, or view records or items that use that schema. Privilege requirements for a schema are set via the Metadata Field Editor, and can include requiring that the user have a specific privilege flag, or match a specific User field (e.g. be the person who created the record). Privilege requirements can also specify that fields for a record have a specified value (like Record Status is Published), and, like search parameter sets, privilege requirements can include logical operators (AND and OR) and groupings.
User Interfaces
User interfaces in Metavus are similar to “themes” in other software packages, but support more extensive customization, including adding or customizing pages or entire interface components.
Metavus sites may also have multiple user interfaces active, dynamically selecting which one to display based on the user or URL, allowing (for example) a collection site to present one interface to students and a different interface to educators, all driven by the same underlying data.
Plugins
To promote modularity and easy extensibility, Metavus uses a plugin-based architecture. Plugins are discrete combinations of PHP and HTML (and sometimes SCSS or JavaScript), that each reside in their own subdirectory, and provide a specific capability or focused set of capabilities.
Metavus comes with 25+ plugins out-of-the-box, providing additional features like a WYSIWYG page editor, a URL checker, and an OAI-PMH server. Users and other developers can create and install their own plugins, to customize or extend the software as desired.
Command Line Utility
For both developers and site administrators who may be more comfortable working at the command line, the mvus command line utility is provided, which supports the following commands:
cache clear – clear page/object/template cache
config – get/set system configuration value
database args – print MySQL command line util args
database check – check database integrity (with mysqlcheck)
database cnf – write database login info to specified MySQL config file
database dump – dump database to file
database load – load resource records from file
database reload – reload database from file
database shell – start MySQL command line client
grep – search source files for string
interface get – get current interface for user or default
interface set – set current interface for user, default, or all
list config – list available configuration settings
list fields – list fields by type or schema
list interfaces – list available user interfaces
list plugins – list available plugins
list privileges – list available privileges
list schemas – list schemas
maintenance – turn maintenance mode on or off
plugin command – run command supplied by plugin
plugin config – print current plugin configuration
plugin disable – disable plugin
plugin enable – enable plugin
privilege add – grant privilege to user
privilege list – list current privileges for user
privilege remove – revoke privilege from user
task delete – remove task from queue
task list – list queued/running/orphaned tasks
task requeue – requeue orphaned task
task run – run task
uifile – report on UI file usage in source code
upgrade – run any needed system or database upgrades
user add – add user account
Usage information for most commands is available by running mvus with the command and no other arguments.
The mvus utility can be found in the install directory, and must be run from the root directory of a Metavus installation.
Developer Support
In addition to the mvus command line utility, the Metavus distribution package includes a Developer plugin, that provides the following tools to assist in creating your own custom interfaces and plugins:
Email Whitelist – This option allows you to specify a whitelist that limits the addresses to which Metavus will send emails. (Useful in testing things like rules or other mechanisms that involve automated mailing.)
File URL Fallback – When this option is enabled, uploaded images that are not found locally can instead be loaded from a Metavus site at another URL. (Useful to load images from a production site when running a copy of the production database on a development site.)
Page Load Info – This adds a display (usually at the bottom of the page) that displays the page generation time, Metavus version, database name, database cache rate, and memory usage, for the current page load.
Variable Monitor – This adds a display (usually at the bottom of the page) that shows the variables available to the HTML file, at the start of execution.
Watermark – This adds a transparent watermark overlay (usually at the top left of the page) to help readily distinguish between development and production sites.
These features can be controlled via the plugin configuration page, but can also be set via a settings file, located in the base or local directory for the site. (See install/EXAMPLE-developer.ini for more detail on this, as well as usage examples.)
To improve maintainability and extensibility, Metavus largely conforms to the PSR-1 and PSR-12 coding standards for PHP source code.