Library management

The purpose of the library feature of the website allows us to embed the contents of a folder directly in a page, making the files in that folder available to view or download. Any file present or added to the folder (with some exceptions) is automatically and immediately displayed in the corresponding library "instance" on the website.

With the addition of the ability to display custom metadata for files within the library, this basic premise is surprisingly powerful and can be extended to cover a variety of usage scenarios.

The following example showcases a basic library displaying the files in a folder specified relative to the root library path. These files can also be viewed more directly via the server-generated directory listing at /en/files/business-names/.

[gn:library] path: business-names title: Forms [/gn:library]
Forms

Adding and removing files

To add an entry to a library instance, all you have to do is place the file or folder in the corresponding directory using your computer's file browser. The file or folder is immediately visible in the library the next time you load the page (you can reload the current page using the F5 key). Remember that all changes you make are immediately publicly visible!

You can set up attributes for files and folders before adding them to a library. Attributes are applied to files matching a mask, and not to a specific file (in the general sense); so it's okay to have masks which match no files. Remember that in most cases, providing attributes for files is optional; by default a file will appear in the library more or less as it does in your computer's file browser.

Similarly, library entries cease to display as soon as the corresponding file or folder is moved or deleted. You do not have to remove metadata associated with these files, but it is a good idea to keep your metadata files tidy.

If attributes do not seem to be applying to a file, check that the filename is entered correctly, and that the file is in the correct folder. If a filename contains accented characters, it is generally advisable to copy and paste the filename into the attributes file directly to avoid transcription errors. You can copy a filename by clicking on the file or pressing F2 with the file selected to initiate the renaming process, and then pressing Ctrl+C to copy.

Metadata

Libraries are able to associate metadata - data about data - with the files and folders in a library. Rather than over-complicating the situation with the addition of a database to house this information we use a simpler, proven technology: text files. Housing metadata alongside the associated files and folders not only makes it easier to cross-reference, but also makes the process of maintaining this information relatively transparent and discoverable.

These text files define named attributes associated with the files and folders stored in the same directory structure. By default the system looks for attribute files named @.ind, however this may occasionally vary for some library instances. Any file with this filename in the directory tree of the library is automatically loaded as metadata source, and will not display as an entry in the library.

Metadata for your files is specified in inident format text files, which should be very intuitive for basic usage scenarios. In more complex situations, you may want to consult the inident documentation. These files must be edited in a plain text editor such as Notepad. A word processor such as Word, Wordpad, or Wordperfect will not work as expected.

Each entry in an attributes file defines attribute values assigned to files or folders matching a file mask:

1
file_mask.ext:
2
attribute_name: attribute value
3
4
file.pdf:
5
title: The Title
6
description: This is the description.

The most basic and common mask is a filename, however it is possible to define masks matching multiple files or folders using wildcards. The section on masks provides a detailed look at the types of masks you can create.

An attribute definition in a metadata file must be indented by at least two spaces from a mask in order to be associated with the mask. Tabs count as up to four spaces, as determined by the usual tab stop rules. In the following example, the description is not associated with file_1.pdf because it is only indented by one space from the mask:

file_1.pdf: title: The Title description: This is the description.
{ "file_1.pdf": { "title": "The Title" }, "description": "This is the description." }

An attributes file should never have more than three levels of indentation. The base level is where masks are specified, and the second level is used to associate attribute values with the preceding mask. The third level should only be used for declaring multi-line attribute values using inident folded/unfolded string syntax.

1
# Level 1
2
file_mask.pdf:
3
# Level 2
4
title: The Title
5
description: >
6
# Level 3
7
This is a longer description of the file which
8
you might want to write over several lines.

Blank lines in an attributes file are ignored, and have no effect on the interpretation of the file. As such you can space your entries as you like in order to improve clarity.

Attribute files can also contain comments beginning with # on their own line. A comment line has no impact on the interpretation of the file - it is as though the line does not exist. Comments are useful for leaving information for other people who may edit the file, or for temporarily "disabling" entries.

The use of accented or special characters is supported in attribute files, however for best results it is suggested that you save the files as UTF-8 encoded text. In notepad, the Save As dialog box features a drop down menu from which you can select the encoding.

Attributes

Built-in attributes

The following attributes are built in, and can be overridden within an attributes file:

Attribute Format Default value
title text File/folder name.
description markdown text (none)
date text File/folder modification date in ISO 8601 format (YYYY-MM-DD).

The title attribute is the only attribute which is always used, and is displayed as a link to the associated file or folder regardless of how the library instance is configured. By default, the title attribute displays the file or folder name.

Some additional attributes exist whose values are provided automatically, and cannot be overridden:

Attribute Format Provided value
filename text The file name.
filesize text Human-readable filesize.
is_file text For sorting purposes.
is_folder text For sorting purposes.
mimetype text The MIME type of the file as determined by the server (e.g. text/plain).
url text The URL of the file.

Custom attributes

In addition to the built in attributes, each library instance may define custom attributes to display additional information associated with library entries.

There is no real distinction between custom and built-in attributes, however a custom attribute must be configured for use with the library instance before it will have any effect.

Attribute formats

Attributes can be configured for different formats which affect how the provided attribute value is displayed. The supported attribute formats are:

Plain Text
The provided attribute value is displayed verbatim as a single word or sentence. This is the default attribute format.
Markdown
The provided attribute value is processed as Markdown without support for embedded HTML.
Markdown Text
The provided attribute value is processed as a single Markdown paragraph with support for links, bold, and italics.
HTML
The provided attribute value is inserted directly into the output as raw HTML. Use of the HTML attribute format is discouraged, as you must be careful to correctly escape the attribute value as proper HTML.

By default all attributes are treated as plain text except for the description attribute, which is treated as markdown. With the exception of the title attribute which is always displayed as plain text, the format of each attribute is configurable on a per-library basis. Note that a linked attribute is always treated as plain text.

For formats other than plain text it is often convenient or even necessary to use inident's folded/unfolded string syntax for multi-line strings. Such strings consist of an > or | marker followed by lines of content indented an additional level from the associated attribute label.

If an attribute is configured to be displayed as a link, an attribute called {attribute}_url may be used to specify an alternative URL to be used instead of linking to the file or folder itself:

1
jus.*.pdf:
2
department: Justice
3
department_url: https://www.justice.gov.nt.ca

Note that URLs are resolved relative to the file or folder, and not the page on which the library is displayed. Alternatively you can specify a URL starting with ~/ which will be resolved relative to the home page.

Masks

Attribute values defined in an attributes file are assigned to files using masks which select the affected files or folders. The simplest and most common form of mask is a filename, which will match files with the specified name:

1
form_a.pdf:
2
title: Form A

We use the term mask because it is possible to apply attributes to many files at once by using a mask containing wildcards. A single asterix (*) is a wildcard matching zero or more characters not including directory separators. As such the mask form*.pdf would match both form.pdf and form_a.pdf.

Two consecutive asterixes (**) match zero or more characters including directory separators. As a special case, the pattern /**/ will match zero or more directories - the mask a/**/c.pdf will match both a/c.pdf and a/b/c.pdf.

A mask must include or match file extensions. In Windows, file extensions for common file types are hidden by default, which can be problematic when trying to come up with a mask. You can change your settings so that file extensions are displayed by searching for "Folder Options" in the Start Menu, and then disabling the "Hide extensions for known file types" option under the "View" tab.

To match a folder, a mask must end with a directory separator. This requirement makes the intended target of a mask clear.

Masks are case-insensitive - it is not possible to differentiate between upper and lowercase versions of the same filename. Forward and back slashes can also be used interchangably as directory separators.

There are no restrictions on which characters can be contained in a mask save that it must exist on a single line, and cannot contain a colon (:) followed by a space or tab character - this signals the end of the mask. For (ridiculously) complex filenames, it may be necessary to specify the mask using inident quoted string syntax.

An attributes file is scoped to its containing folder and descendants. Consider the following directory structure:

1
root/
2
+- a/
3
| +- a.pdf
4
| +- @.ind
5
+- b.pdf

Here root/a/@.ind can define attributes applying to root/a/ and root/a/a.pdf, but not root/b.pdf.

A mask beginning with a directory separator is anchored, and matches for the mask must begin at the folder containing the attributes file. For example, the mask form_a.pdf will actually match any file with this name in any subfolder of the folder containing the attributes file. The mask /form_a.pdf will only match a file with this name in the same folder as the attributes file.

A mask can be inverted by prepeding it with !, causing it to match files not matching the mask pattern. For example, the mask !*.pdf can be used to match entries which are not PDF files.

Additional Notes

Filenames

In most cases, the filenames of your files will be displayed directly on the website and are used by visitors to identify the file they are looking for. It is a good idea to adopt a simple, consistent naming scheme for your files so that they sort nicely and are easily identified.

It is also a good idea to avoid using characters which must be percent-encoded in a URL path segment - specifically /, ?, #, [, and ]. This will help to ensure that your files have "nice" URLs (addresses).

It is possible to create files with filenames which cannot be displayed in a library. This occurs when the absolute path to the file on the server exceeds 259 characters in length or contains characters which are not representable in the Windows-1252 codepage.

The former can be resolved by shortening the name of the file or parent folders. The latter most often occurs in the case of filenames that were automatically generated by - or copied and pasted from - a word processor, and can generally be resolved by manually re-typing the filename. Generally you should stick to characters you can type and French accented characters.

Sorting

The default sort applied to library entries is:

  • numeric sort by order, ascending; then
  • folders before files; then
  • natural sort by title, ascending.

Note that this behavior can be overridden on a per-library basis.

The order attribute is intended to allow you to override the usual ordering of entries by manually specifying the order in which entries should appear as a sequence of numbers. Entries for which the order attribute is undefined come last.

A number of sort types are are configurable on a per-library basis, which may impact the ordering of entries in subtle ways:

  • natural sort, ordering entries as a human would
  • alphabetical sort, ordering entries as a computer would
  • numeric sort, ordering entries by numeric value
  • boolean sort, ordering entries by true/false/yes/no value
  • existence sort, prioritizing entries where a specific attribute is defined

Related Pages

Legislation of the Northwest Territories
A complete alphabetical listing of the consolidated territorial Acts and associated regulations.
Contact Us
Contact the Department of Justice