NAME

Daizu::File - class representing files in working copies

DESCRIPTION

Each object of this class represents a particular file in a Daizu CMS working copy (a record in the wc_file table).

METHODS

Note that all the functions which return the value of a Subversion property will strip leading and trailing whitespace, and treat a value which is empty or entirely whitespace as if it wasn't set at all.

Daizu::File->new($cms, $file_id)

Return a new Daizu::File object for the file with the specified ID number.

$file->data

Return a reference to a string containing the file data (content).

$file->wc

Return a Daizu::Wc object representing the working copy in which this file lives.

$file->guid_uri

Return the GUID URI for this file.

$file->directory_path

Returns the path of a directory, either the same as the file if it's a directory itself, or the path of its parent directory, or '' if it's at the top level.

$file->permalink

Returns the first URL generated by the file, which will be the URL you want to link to most of the time. For articles this will always be the normal HTML version of the article, even if there are also other URLs available for it, and it will always be the first page of multipage articles. For non-article files there is no guarantee about what this will return, but most will only generate a single URL anyway, and for those that don't generators are likely to return the most 'linkable' URL first.

The URL returned is an absolute URL provided as a URI object.

Returns nothing if the file doesn't generate any URLs.

There are some cases where this might not be what you want. For example, the root directory of a website using Daizu::Gen will either not generate a URL at all, or will generate one for a Google sitemap XML file, neither of which is likely to be useful for linking. To get the URL of the website you would probably need to find a file called something like '_index.html'. On the other hand, the Daizu::Gen::Blog generator will give you a sensible URL for the blog homepage if you call this on its root directory.

$file->urls_in_db($method, $argument)

Return a list of the URLs (plain strings, each an absolute URI) of the file which have the specified method and argument values, drawing from the url table in the database.

$file->article_urls

Return information about the URLs which the file should have, if it is an article. Fails if it isn't.

The URLs are returned in the same format as the Daizu::Gen method custom_urls_info, and should be used within implementations of that method to ensure that articles get the proper URLs even if an article loader plugin or DOM filtering plugin has changed the usual forms.

There are two sets of URLs returned, as a single list:

• URLs for the pages of the actual article, as normal web pages published through the templating system. There will always be at least one of these, which will be the first URL returned. It will have a method of 'article', an empty argument string, and a content type of 'text/html'. The generator class is likely to be Daizu::Gen, although it doesn't have to be. The URL for this first article page will be the one supplied by the article loader plugin as pages_url, and stored in the database in the article_pages_url column. If none is supplied it defaults to the empty string. If the article has multiple pages, this URL info will be followed by others, one for each subsequent page, which will be identical except for the actual URL and the argument, which will contain the page number (starting from '2' for the second page).

  The first 'article' page URL is the one which should be used when linking to an article, unless you have some special reason to link to a particular page or an alternative URL for the same file. For example, this is the URL which will be included in blog feeds and navigation menus. To get at it conveniently, see the permalink() method.

• There may be additional URLs for supplementary resources generated by plugins, although by default a simple article written in XHTML won't have any 'extra' URLs. These URLs are the ones supplied by the article loader plugin as extra_urls, and stored in the database in the wc_article_extra_url table. One example of an 'extra' URL is a POD file (Perl documentation, like this document itself) published with the Daizu::Plugin::PodArticle plugin. If the filename of the POD file ends in '.pm', then this plugin will add an extra URL for the original source code, since that might be of interest to programmers reading API documentation.

$file->parent

Return a new Daizu::File object representing this file's parent directory. Returns nothing if this file is at the 'top level' of its branch and so has no parent.

$file->file_at_path($path)

Returns a Daizu::File object for the file found at $path in the same working copy as $file. $path can be an absolute path (if it starts with '/'), or it can be relative to the path of $file.

Dies if there is no such file.

$file->issued_at

Return a DateTime object for the publication date and time of the file. All files have an 'issued' date, either specified explicitly in a dcterms:issued property, or determined from the time at which the file was first committed into the Subversion repository (which is assumed to be about the time it was first published).

$file->modified_at

Return a DateTime object for the last-updated date and time of the file. This is always defined. The value is either specified explicitly in a dcterms:modified property, or determined from the time of the last commit which modified or renamed the file.

$file->property($name)

Return the value of the Subversion property $name on this file, or undef if there is no such property.

The value is assumed to be text, so leading and trailing whitespace is trimmed off, and the value is decoded as UTF-8. If the value exists but contains only whitespace then undef is returned.

$file->most_specific_property($name)

Return the value of the Subversion property $name on this file, or on its closest ancestor if it has no such property. Therefore properties on subdirectories will override those of their parent directories. Returns undef if there is no property of this name on the file or any of its ancestors. Properties whose values are empty or contain only whitespace are ignored.

The value is assumed to be text, so leading and trailing whitespace is trimmed off, and the value is decoded as UTF-8.

$file->least_specific_property($name)

Return the value of the Subversion property $name on this file, or on its most distant ancestor if it has no such property. Therefore the return value is the 'top level' value for this property. For example, if you ask for the dc:title property then you might get the title of the website of which $file is a part. Returns undef if there is no property of this name on the file or any of its ancestors. Properties whose values are empty or contain only whitespace are ignored.

The value is assumed to be text, so leading and trailing whitespace is trimmed off, and the value is decoded as UTF-8.

$file->homepage_file

Return the file which most probably represents the 'homepage' of the website on which $file will be published. This will be the file closest to the top level of the filesystem hierarchy which has a daizu:url property set.

It is possible for this to return $file itself if there is nothing above it with a URL. Returns undef if not even $file has a URL set, in which case it can't have a homepage because it won't be published itself.

$file->title

Return the title of $file, as a decoded Perl text string, or undef if the file doesn't have a title. The title is taken from the file's dc:title property.

$file->short_title

Return the 'short-title' of $file, as a decoded Perl text string, or undef if the file doesn't have a title. The title is taken from the file's dc:title property.

$file->description

Return the description/summary of $file, as a decoded Perl text string, or undef if the file doesn't have a description. The value is taken from the file's dc:description property.

$file->generator

Create and return a generator object for the file $file. Figures out which generator class to use, by looking at the daizu:generator property for the file, and if necessary its ancestors. The class is loaded automatically. It also knows to use Daizu::Gen if no generator specification is found.

Returns the new object, which should support the API of class Daizu::Gen.

$file->update_loaded_article_in_db

Updates the cached article content for $file in the database. This includes the finished XML version of the content, the article pages URL, the extra URLs, and the extra templates. Does nothing if the file isn't an article. Fails if it is but there are no plugins able to load it.

This normally happens automatically when a file's content is updated, and can also be triggered manually from the daizu program with the

This is where article loader plugins set with the Daizu method add_article_loader() are invoked.

Doesn't return anything.

$file->article_doc

Returns an XML::LibXML::Document object representing the content of the article, as stored in the article_content column of the wc_file table. The first time this is used on $file it will parse the content from the database, doing XInclude processing.

Dies if the file is not an article.

$file->article_body

Returns the root element of the article content. Equivalent to this:

$file->article_doc->documentElement

$file->article_content_html4([$page_num])

Returns the content of an article file as HTML 4. If $page_num is provided, only returns the content for that page, otherwise for the whole article. Fails if the file is not an article, or if $page_num is greater than the number of pages ($page_num would be 0 for the first page, not zero).

$page_num can be undef to select the whole article, and making it the empty string has the same effect (to make this easier to use from within templates).

$file->article_extract

Returns a short extract (up to a certain number of words) from the beginning of the article's content, with all markup removed. What's left is plain text, except that the text from different top-level elements in the document is separated by two newlines. The text returned is not XML escaped.

$file->article_extra_urls

Return a list of URL info hashes describing additional URLs which should be generated by this file, pulled from the wc_article_extra_url table. Returns nothing for files which aren't articles.

$file->article_extra_templates

Returns a list of the extra templates which should be included in the article's 'extras' column. Returns nothing for files which aren't articles.

$file->tags

Return a reference to an array of tags which have been applied to this article. These come ultimately from the daizu:tags property, although it is loaded into the database tables tag and wc_file_tag when the working copy is updated. The tags are returned sorted by canonical tag name.

Each item of the returned array is a hashref containing the following values:

tag

The canonical tag name, as used as the primary key in the tag table.

original_spelling

The spelling used for to name the tag in the daizu:tags property of this file.

Both of these values are provided as text strings, decoded from UTF-8.

$file->article_snippet

Return an XML::LibXML::Document object representing the part of an article which comes before the fold, or before the first page break (whichever comes first). If there are no fold markers or page breaks in the article, returns the complete article content.

$file->article_snippet_html4

Returns a chunk of HTML 4 markup for the article's content, just as the article_content_html4() method does, except that this only returns the content up to the fold or first page break, if the article has any of those.

This also sets an internal flag called snippet_is_not_whole_article to true if the content returned represents a truncated version of the article's content (that is, there was a fold mark or page break found).

$file->authors

Returns information about the author or authors credited with creating the file. The return value is a reference to an array of zero or more references to hashes. Each one contains the following keys:

id

The ID number of the entry in the database's person table.

username

The username, as specified in the daizu:author property, decoded into a Perl text string. Always defined.

name

Full name of the author, as a Perl text string. Always defined.

email

Email address as a binary string, or undef.

uri

A URL associated with the author, probably their own website, or undef.

The authors are returned in the same order that they are specified in the daizu:author property.

Note that because of the way the standard property loader works, directories are not considered to have authors. If a directory has a daizu:author property, that will just affect all the files within it.

$file->update_urls_in_db([$dup_urls])

Updates the url table to match the current URLs generated by $file, as returned by the generator method urls_info(). This includes changing active URLs to redirects or marking them 'gone' if they are no longer generated by the file.

If this update isn't being done in isolation, but for example is being run by the update_all_file_urls() function, then $dup_urls should be a reference to a hash which can be used to keep track of new URLs which cannot be added to the database yet because they would conflict with an existing active URL. This method will remove them from the hash later if the original active URL becomes inactive, and will replace it in the database with the new one. Some cleanup code is needed in the caller though to finish processing any URLs left in the hash, or to signal errors if they are a genuine conflict which cannot be resolved. An error should cause the transaction to update, because items in the hash represent unfinished updates to the database.

Returns a list of two values, which can each be either true or false. They indicate whether the set of URLs which are redirects or marked as 'gone' have changed. The first indicates that at least one redirect has been added, removed, or had its destination changed. The second value indicates that a previously active or redirected URL is now marked 'gone', or that a previously dead URL has been reactivated or turned into a redirect. These two values can be used to determine whether redirect maps need to be regenerated by the caller.

The work is done in a transaction, so that if it fails there will be no changes to the database.

TODO - update docs about return value

COPYRIGHT

This software is copyright 2006 Geoff Richards <geoff@laxan.com>. For licensing information see this page:

http://www.daizucms.org/license/