################################################################################
## Stagsi Cookbook
################################################################################
This comprehensive document is a hacker’s guide to Stagsi – an *Interface to
Soletude’s Tagging System*.
With Stagsi you and your team can organize data with a hierarchy of tags. While
this is not new (see #ALTERNATIVES), the openness and flexibility of the data
model, #QUERYLANGUAGE, applicability to any file format, and durability (fault
tolerance and number of managed objects) are distinguishing Stagsi even from
the industry leaders (*Adobe Bridge* and *Apple iTunes*).
Stagsi is a commertial product but its *Free* edition can be used in
non-commercial environments with a few light limitations, and a *Professional*
license costs pennies compared to others and is irrevocable and non-expiring by
design.
* Stagsi homepage: https://go.soletude.ca/stagsi .
* Community forum: https://go.soletude.ca/stagsi/forum .
* Contribute your scripts: https://go.soletude.ca/stagsi/recipe .
* Up-to-date online documentation: https://go.soletude.ca/stagsi/cookbook .
* Offline documentation in various formats:
https://go.soletude.ca/stagsi/archive/cookbook
========================================================
Data File Structure #DATA#
========================================================
Stagsi is using simple, easily accessible data storage mechanisms. At its core
lies Stagsi.sqlite – a standard #SQLITE version 3 database which is described
in detail in its own section.
Other files and folders that may appear:
* Temp directory – holds temporary data during import, search and other
activities.
* Icons directory – holds icons assigned to tags, displayed on top of the
objects tagged with them. First, TagRowId.png is searched; if not found
and the tag is *system* then System.png is also searched (e.g. _mp3.png
).
* Attachments directory – holds extra files and folders connected with
specific objects.
* Sorting directory – holds persistent data used by #SORTINGPLUGINS.
* Tools directory – these files are directly accessible from the main menu.
Normally you put useful scripts here, e.g. to back up the database or clean
Temp . See #TOOLS.
* Numbered directories – hold imported object thumbnails and data, e.g.
images, documents, etc. or links to them (for objects imported in linked
mode).
* JSON files – hold program settings and state (window positions, list of
tabs, etc.).
* Welcome.html – a web page displayed when opening the database in
interactive mode (not with maintenance operations like /rehash ). See
#WELCOME.
Subfolders in this, Temp , Attachments and other subdirectories are used to
work around certain file systems (especially FAT) limitations on big number of
files that become increasingly slow when a directory contains more than a few
thousand of entries. Stagsi is designed to work with hundreds of thousands of
objects (each object having multiple files).
If you wish to store custom data within a Stagsi database directory, prefix
your (root) files and folder with an underscore: _Docs\License.txt or just
_License.txt if it’s directly under the data path. Such names are guaranteed
to never conflict with Stagsi’s own data.
Welcome Page #WELCOME#
----------------------------------------
If the database folder contains Welcome.html file, it’s presented to the user
whenever it’s opened in Stagsi. Because it’s a local file, you can use the
file:// scheme and reference resources ( and others) relatively to the
database folder. However, interaction with remote resources and