Notes for Using Specific Packages
---------------------------------
The following notes detail the available packages and their usage. Package names that have (default) appended
to their name are Package Type's that are installed by default. Package Types not installed by default can be
used after being installed from their bundle (refer to "Installing Package Types" in "getting_started.txt").
-------------------------------------------------------------------------------------------------------------
Auto_Code (default)
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides an Auto_Code class which is used to automatically generate unique sequential codes that
can be used by instances of any other Class.
After installation to get a Class to use an "auto code" field first create a field (e.g. Code of type str010)
then add a "for_auto_code_user" Specification to the Class. In this Specification link the Field to the newly
created field (i.e. Code) and set the Value to a unique identifier for this "auto code" (e.g. user_code) then
"Save Details". Next click "Add Source Info" and select the Auto_Code Class and its "Increment" Procedure.
In order for the "auto code" to function at run-time an Auto_Code record with its key matching the identifier
that was entered as the Value in the "for_auto_code_user" Specification must exist. As records that are using
"auto codes" could have Initial_Record values (e.g. the User class) the Auto_Code records needed by the users
of them need to be created as Initial_Record instances.
Thus from the Classes child list of the Model select Auto_Code then select the Initial_Records child list and
click "New Record". The Key for the Initial Record must be the same as the Value for the "for_auto_code_user"
used (e.g. "user_code").
After creating the Initial_Record the Initial_Record_Values for Name and Mask must be provided. For the above
example the Initial_Record_Value's Value for Name could be set to "User_Code" with the Mask's Value being set
to a useful "auto increment mask" (e.g. "U#####"). It should be noted that the Name must be unique (but isn't
otherwise important). The System Information value must be set to "system" in order to satisfy that mandatory
relationship value.
An "auto incement mask" must contain one or more "#" or "?" characters that are replaced when determining the
"next" auto increment value with digits and letters respectively. The following table of auto code masks with
sample values illustrates how this works (note that generated letters are only upper case).
AC#### ==> AC0000,AC0001,AC0002,...,AC9999
??#### ==> AA0000,AA0001,AA0002,...,ZZ9999
XYZ#?? ==> XYZ0AA,XYZ0AB,XYZ0AC,...,XYZ9ZZ
-------------------------------------------------------------------------------------------------------------
Blog
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides a Blog implementation that supports multiple blogs that each contain blog entries which
are ordered by date. A blog entry remains private until it is published. After publication any blog entry can
be removed or republished.
Package Options:
@use_demo_data - Use this option to create demo blogs and blog entries.
@use_home_list - Use this option to display the last published blog entry as a "home" list.
group_for_home - If using the "group" package then this will determine the group to use for the "home" list.
group_package - Optional "group" package to divide blogs between groups.
max_blog_tags_per_user - Use this option to set the upper limit of blog tags a user can create. *
max_blogs_per_user - Use this option to set the upper limit for the number of blogs a user can create. *
max_entries_per_blog - Use this option to set the upper limit of blog entries that a blog can contain. *
max_entry_parts_per_entry - Use this option to set the upper limit of entry parts a blog entry can contain. *
max_tags_per_blog_entry - Use this option to set the upper limit of blog tags a blog entry can contain. *
use_comments - Use this option to allow other users to leave comments.
use_comments_publishing - Use this option to only display comments the author chooses to publish.
use_permissions - Use this option to require user permissions for blog maintenance.
use_tags - Use this option to add "tags" to blog entries useful for searching.
use_user_access_level - Use this to apply the user access level to blogs and blog entries. **
use_user_ignore_users - Use this option to filter blog and blog entries from users in the ignore set. **
* These options only pertain to the blockchain version of this package.
** It should be noted that these options will have no effect if the relevant options were not set in the User
package before it was installed.
-------------------------------------------------------------------------------------------------------------
Cube
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides a Rubik's Cube simulator in which each record is a virtual cube of either 2x2x2, 3x3x3,
4x4x4 or 5x5x5 cubies per side (a cube having always six sides). After a Cube record has been created one can
use the Scramble action in order to perform a random scramble of the cube. The Reset action restores the cube
to its solved state and the Execute Algorithm executes the "steps" provided through the Enter Algorithm field
field (with multiple steps being space or comma separated).
The notation used for algorithms includes the following face rotations: U L F R B D U' L' F' B' D' along with
the following slice turns: M M' E E' S S' and second layer turns: u l f r b d u' l' f' r' b' d'. It will also
accept the following whole cube rotations: X X' Y Y' Z Z' and for non-inverted operations the number 2 can be
appended to perform the operation twice (such as U2, M2, u2 or X2). Extended double layer turns are supported
via: Uu Ll Ff Rr Bb Dd Uu' Ll' Ff' Rr' Bb' Dd' and turns which include all but one of the cubie layers are as
follows: Uw Lw Fw Rw Bw Dw.
Package Options:
@use_demo_data - Use this option to create demo 2x2x2, 3x3x3, 4x4x4 and 5x5x5 cubes.
-------------------------------------------------------------------------------------------------------------
Event
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides an Event implementation in which each record has a date and time (as well as optionally
a duration) and a status. Such records can be treated like a list of public events, but also could be handled
more like private appointments, reminders or tasks and as such can be generated from a Schedule.
Package Options:
@use_demo_data - Use this option to create demo events.
group_package - Optional "group" package to restrict users and optionally divide events between groups.
message_package - Optional "message" package to provide support for notifications (needs "user" to work).
use_duration - Use this option to give an event a duration (and to allow overlap detection).
use_group - This option needs to be set true in order to to tie events to specific groups.
use_tz_name - Use this option to be able to tie a timezone name to an event.
use_user - This option needs to be set true in order to to tie events to specific users.
user_package - Optional "user" package for permissions and allowing messages or tying events to users.
-------------------------------------------------------------------------------------------------------------
Folder (generic)
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides a Folder implementation for a given "item class". This is perhaps easiest understood in
the way that an OS will typically have "files" within "folders". The folders form an acyclical graph from the
parent folder relationship.
Package Options:
@use_demo_data - Use this option to create demo folders.
folder_item_class.Class - Use this option to identify the "item" to which folders are being added.
folder_item_class.View - Use this option to identify the item "view".
folder_item_class.List - Use this option to optionally identify a "list" to add folder restrict selection.
folder_item_class.Field - Identifies the field to display in the child item list for the folder "view".
folder_item_class.Other_Field - An optional second column for displaying in the child item list.
folder_item_class.Other_Field_2 - An optional "active" check restriction for the child item list.
folder_item_class.Source_Field - Identifies the "owner" field for the item (if is applicable). *
folder_item_class.Other_Source_Field - Identifies the "group" field for the item (if is applicable). **
group_package - Optional "group" package to tie folders to groups.
is_mandatory - Use this option to determine with each item "must be in a folder" (default is "yes").
no_top_level_maint - Use this option to prevent normal maintenance of the "top level folder(s)".
use_folder_status - Use this option to add "folder status" class support (so folders can be set "inactive").
use_transient_paths - Use this option for a "transient" path implementation (faster writes but slower reads).
user_package - If is provided and folder_item_class.Source_Field has not been then will result in permissions
being added for folder assignment and maintenance to the User. If folder_item_class.Source_Field is not empty
and the "group package" has also been provided then the permissions will also be added.
* It should be noted that if this field is provided then the "user_package" must also be provided.
** It should be noted that if this field is provided then the "group_package" must also be provided.
-------------------------------------------------------------------------------------------------------------
Forum
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides a Forum implementation that includes "boards" (with multiple levels of nested children)
that contain "topics" which in turn contain "posts". The topics are ordered according to the most recent post
with "pinned" topics always appearing first. If a topic is "locked" then posting (or post editing) below this
topic is not permitted (except by "moderators" or the "admin" user).
Package Options:
@use_demo_data - Use this option to create demo boards, topics and posts.
@use_home_list - Use this option to display the forum boards as a "home" list.
check_for_interim_posts - Use this option to display interim posts when attempting to save a reply post.
hot_topic_posts - This option if the number of posts a topic needs to contain to be considered as "hot".
min_posts_to_lock_own - A user can lock their own threads after they have posted this many times.
min_posts_to_rate - If using the user rating implementation then a user must post this many times before they
can rate another user.
months_before_topic_is_old - Newer topics appear with different icons to older ones.
rating_multiplier - If using the user reputation implementation then this is used to calculate the number for
reducing/increasing the rated users rating.
use_post_publishing - Use this option to force all posts to be reviewed by a moderator before publication (if
this option is used then the check_for_interim_posts option will be ignored).
use_special_boards - Use this option to allow certain boards to be restricted to users that have been granted
permission to access them.
use_tags - Use this option to allow users to create tags which they can apply to specific posts (for mods and
admin these can be used in order to split or merge threads).
use_user_access_level - Use this option to apply the user access level to boards, threads and posts. *
use_user_ignore_users - Use this option to filter posts and threads out from users in the ignore set. *
use_user_reputation - Use this option to allow adding/subtracting reputation ratings from users for posts. *
very_hot_topic_posts - As per the hot_topic_posts option.
* It should be noted that these options will have no effect if the relevant options were not set for the User
package before it was installed.
-------------------------------------------------------------------------------------------------------------
Group (default)
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides a "Group" class and implements the Relationship between a User and its Group. Although
the Relationship is optional typically only the "admin" user would not belong to a Group.
The Group (or renamed as Department if preferred) is used as a simple means of slicing the DB records between
different users. Various other Packages will accept the Group Package as an option where it can make sense to
be dividing records between different Groups.
Package Options:
@use_demo_data - Use this option to create demo Groups (and demo Users belonging to them).
-------------------------------------------------------------------------------------------------------------
Holding
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides a simple implementation for recording a collection of Holding Items (where each item is
a company share or other similar unit holding) which includes the ability to record all item acquisitions and
disposals as well as other potentially relevant events such as bonuses, splits and consolidations. Each group
of holding items has a start and finish date which are intended to be the start and end of the financial year
so that the PDF reports of current holdings and capital gains can be generated for accounting purposes.
Package Options:
@use_demo_data - Use this option to create demo set of Holding Items for a sample financial year.
-------------------------------------------------------------------------------------------------------------
Itinerary
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard Event
This package provides a simple Itinerary implementation that supports generating "day by day" itineraries for
events within a specified date range.
Package Options:
@use_demo_data - Use this option to create a demo Itinerary.
event_package - Mandatory "event" package that itineraries are generated for.
user_package - Optional "user" package for either ownerership or permission.
use_active - Use this option to allow itinerary records to have an "active" status (default is "yes").
use_user - Set this option in order to tie itineraries to "users". *
* If the "user" package isn't provided then this option is ignored.
-------------------------------------------------------------------------------------------------------------
Ledger
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides a basic General Ledger system. Each ledger is intended for a single financial year with
every account being classified as either Assets, Equity, Expenses, Income or Liabilities (these can be nested
to a maximum of three or four levels). Balance Sheet and Income Statement reports are easily generated in PDF
format.
Package Options:
@use_demo_data - Use this option to create a demo Ledger.
-------------------------------------------------------------------------------------------------------------
Photo
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides a Photo Album implementation that can be used to easily create and publish photos from
a CIYAM application.
In order to be able to view "published" Photo Album web pages the open source application Galleria must first
be installed. A script to install Galleria (and a copy of Galleria itself) is included in the repository - so
to install it simply run the following:
./setup_galleria
If the User package is not tied to the Photo package (via the "use_user" option below) then Photo Albums will
be accessible to all users and will be published to the "webroot" directory. If the User package is linked in
then Photo Albums and Photos are only visible to the user that "owns" them. Photo Albums with "public" access
visibility (and Photos likewise) are able to be "published" and the published Photo Albums will be visible to
anyone having access to the server.
Package Options:
@use_demo_data - Use this option to create one or more demo Photo Albums (depends upon User demo data).
use_user - This option needs to be set true in order to use the other "user" options.
use_user_id_path - Use this option to publish Photo Albums below a directory that is the same as the User Id.
use_user_permissions - Use this option to add permissions for being able to access/modify Photo Albums.
use_user_tags - Use this option in order to be able to add/remove "tags" to/from individual Photos.
user_image_directory - This is the name of the directory in which published Photos will be stored.
-------------------------------------------------------------------------------------------------------------
Project
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides a project management system which breaks individual projects into individual tasks that
are groups by areas (which can be nested). Task management "workflow" is added via the option "use_task_dibs"
(this controls task allocation and completion in a strict step by step manner).
Package Options:
@use_demo_data - Use this option to create a demo project.
cash_demonimation - Use this option to specify the currency code for amounts in cash. *
funds_demonimation - Use this option to specify the currency code for non-cash funds. **
group_package - Optional "group" package to divide projects between groups.
message_package - Optional "message" package used for providing task notifications.
transaction_package - Optional "transaction" package used to help create raw Bitcoin (or clone) transactions.
use_external_funds - Use this option to use an external API for checking fund balances.
use_external_funds_escrow - Use this option to use an external API for checking escrow fund balances.
use_external_funds_type - Use this option to enable the use of different external funds types. **
use_open_projects_list - Use this option to be able to see a list of open projects (default is "yes").
use_pdf_print_support - Use this option to be able to generate PDF printed versions of tasks.
use_task_dibs - Use this option to add task management workflow.
use_task_dibs_with_skills - Use this option to add "project skills" to the task management workflow.
use_user_access_level - Use this for "user access level" in projects, areas and tasks (default is "yes").
* If left empty then the funds in cash amount is not used.
** If the "use_external_funds_type" option is used then "funds_denomination" is ignored.
-------------------------------------------------------------------------------------------------------------
Schedule
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard Event
This package allows for the scheduling of events in advance for a cycle (weekly, monthly or annually). Within
the schedule one creates separate schedule items which will be used to create the specific events. The design
is intended for scheduling cyclical tasks such as meetings or other recurring activity reminders.
Package Options:
@use_demo_data - Use this option to create a demo schedule.
event_package - This needs to be linked to an installed "event" package.
user_package - Optional "user" package for either ownerership or permission.
timezone_package - Optional "timezone" package to be able to tie a timezone to a schedule.
use_user - Use this option to be able to tie schedules to specific users. *
* If the "user" package isn't provided then this option is ignored.
-------------------------------------------------------------------------------------------------------------
Tag (generic)
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides a Tag implementation for a given "item class". Such tags can either be "system wide" or
"group wide" to be more useful for a "librarian" type situation or can instead be tied to individual users as
a means for creating "personal tags". Tags are most useful when "searching" for items.
Package Options:
group_package - Optional "group" package to tie tags to groups. *
tag_item_class.Class - Use this option to identify the "item" to which tags will be added.
tag_item_class.View - This is the View for the item.
tag_item_class.List - The search list to which tag searching will be added.
tag_item_class.Field - If creating a child list of items below a tag then this is the first column.
tag_item_class.Other_Field - An optional second column for this child list.
tag_item_class.Source_Field - An optional "actions" field for the item (if not provided then will be added).
use_item_list_for_tags - Use this option to be able to see an item list below each tag.
use_tag_status - Use this option to add "tag status" class support (so tags can be set "inactive").
use_user_specific_tags - Use this option to have "user specific" tags rather than ones that are either system
wide or "group" specific. **
use_user_tags_child_list - Use this option to use a "user view child list" for the user specific tags (rather
than a My Item Tags list - default is "yes"). ***
user_package - Optional "user" package. If not using "user specific" tags then instead permisssions for usage
and maintenance of tags will be added to the user class.
* If the "user" package is provided and "use_user_specific_tags" is set true then this is ignored.
** If the "user" package isn't provided then this option is ignored.
*** If the "user" package isn't provided and "use_user_specific_tags" is not set then this option is ignored.
-------------------------------------------------------------------------------------------------------------
Timezone
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides the ability to manage records for different timezones that can include daylight savings
adjustments and historical changes for such. The "timezones.sio" file used by the application server can also
be generated from the timezone records.
-------------------------------------------------------------------------------------------------------------
Transaction
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard User
This package provides the ability to help users to construct "raw transactions" for Bitcoin or its clones. It
can also be used in conjunction with the Project package to help in creating transactions for moving external
funds between a Project and its Project Areas and Project Tasks.
Package Options:
user_package - Optional "user" package to tie transactions to users.
-------------------------------------------------------------------------------------------------------------
User (default)
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard
This package provides the User class which is required for an application to support "logging in". To be able
to create the User instances an "admin" user is automatically created when an application is generated. To be
sure a system is secured the password for "admin" must be changed (the default password is "admin"). There is
also a "guest" user created with the password "guest" so this user should be either set to "inactive" or have
its password changed as well for production systems. Non-traditional (i.e. blockchain) systems do not support
the changing of passwords nor setting a user to inactive, however, as the "admin" and "guest" users cannot be
used to create blocks or sign transactions they are of no security concern.
Package Options:
@use_demo_data - Use this option to create one or more demo User records.
timezone_package - Optional "timezone" package to be able to tie a timezone to a user.
*** the following three options are only avaiable for traditional 3-tier sytems ***
use_access_level - Use this option to be able to assign users a specific "access" level.
use_access_level_ten_deep - If using "access level" then this option will extend the number of levels to ten.
use_authenticator - Use this option to let users optionally use 2FA at login via an RFC 6238 TOTP.
use_gpg - Use this option to enable the support of GPG for email messages.
use_ignore_users - Use this option to support the maintenance of a set of users to be ignored. Other packages
(such as the Forum package) will utilise this list for the purposes of "hiding" records.
use_personalisation - Use this option to add additional personal information (such as avatar and website).
use_quick_link - Use this option to allow the user to maintain quick link records. *
*** the following option is only avaiable for traditional 3-tier sytems ***
use_quick_link_active - Use this option to allow quick link records to have an "active" status.
*** the following option is only avaiable for non-traditional sytems ***
use_signature - Use this option to add a HTML signature field.
use_reputation - Use this option to allow other packages to award or subtract reputation ratings.
use_templates - Use this option to support the creation of users from a user template (this is most useful if
the application has a need for different user "types" that have different permissions).
* A "quick link" is a method for extending the standard menu so applications can include menu items which are
either links to a specific record or to a specific record search (these are also known as "user links").
-------------------------------------------------------------------------------------------------------------
Wallet
-------------------------------------------------------------------------------------------------------------
Other Package Dependencies: Standard Transaction
This package provides a Bitcoin (and clone) Wallet implementation that supports multiple wallets which can be
each either external and optionally watch-only or internal and optionally deterministic.
Package Options:
@use_demo_data - Use this option to create a demo watch-only wallet.
key_name (and key_plural) - Change these options from the default Key/Keys if desired.
user_package - Optional "user" package to tie wallets to users.
