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 parser 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 webpages 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 set with the set_article_pages_url() method, or empty string by default. 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 added with the add_extra_url() method. 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->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.

$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.

$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.

$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 if it has one, or from the dc:title property of one of its ancestors failing that.

This ensures that the article has been fully loaded, so that if the article parser plugin sets a title for it, that will get used.

$file->short_title

Same as the title() method above, except that if the file or any of its ancestors have a daizu:short-title property then that is used in preference to daizu:title.

$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 if it has one.

This ensures that the article has been fully loaded, so that if the article parser plugin sets a description for it, that will get used.

$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->ensure_article_loaded

Updates $file to include full article information, including the DOM of the content of the article. Does nothing if the file isn't an article. Fails if it is but there are no plugins able to load it.

This is where article parser plugins set with the Daizu method add_article_parser() are invoked.

Doesn't return anything.

$file->init_article_doc

This can be used by plugins which know how to read the content of a file and turn it into an article document. It creates an empty document (an XML::LibXML::Document object) with a body root element in the XHTML namespace, and stores it so that the article_doc() and article_body() methods can return it. The document object is also returned from this method. Dies if the file is not an article.

$file->article_doc([$doc])

Returns an XML::LibXML::Document object representing the content of the article, loading the article's content first if necessary. Dies if the file is not an article.

If the argument $doc is provided, sets the file's article content to that value. This can only be done once.

$file->article_body

Returns an XML::LibXML::Element object representing the root body element of the content of the article, loading the article's content first if necessary. Dies if the file is not an article.

$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->set_article_pages_url($url)

Set the URL for the actual article's HTML page. This will usually be a relative URL, for example just a filename or the empty string. It will be resolved relative to the 'base URL' provided by the file's generator.

If the article has multiple pages, this URL will be used for the first page and the subsequent ones will be generated automatically based on it. See the article_urls() method for details of how this affects the URLs generated by an article file.

$file->add_extra_url($url, $mime_type, $generator_class, $method, $argument)

Add an extra URL for a resource associated with the article. This could be used for example by a plugin which generates a printer-friendly PDF version of an article to add the URL for the PDF file.

$argument is optional, and defaults to the empty string.

Any URL information added here by plugins will be returned by the article_urls() method.

$file->add_article_extras_template($filename)

TODO

TODO - this should apply to the file as a whole, but to individual URLs

$file->article_extras_templates

TODO

$file->tags

Return a list of tags which have been applied to this article. The list comes 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.

A list is returned, each item of which 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.

$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

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.

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.

COPYRIGHT

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

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