Overview
Cypht has a modular design. Instead of an application with a plugin API, Cypht is an application comprised
entirely of plugins, or as we call them, "module sets". There is only one required set, the "core" modules. The
components of any module set can be added to, or even replaced, by site specific modules. All the functionality
of Cypht is broken out into module sets, and each set is built from small pieces that are also easy to override.
The module system is powerful, but also a bit complex. First let's take a look at the module sets that come with
Cypht:
- 2faissues
TOTP
based 2 factor authentication using the Google Authenticator mobile app
- accountissues
UI
features for admins to create accounts, and for users to update passwords (when using the built-in DB
authentication). Functional, but could use more admin features
-
advanced_searchissues
Support
for advanced search
- api_loginissues
Login
using an API to provide single sign on ability
- calendarissues
Basic
calendar.
- contactsissues
Contact
management. Requires at least one contact backend module set to be enabled
-
carddav_contactsissues
Support
for contacts stored in CardDav
- local_contactsissues
Simple
locally stored contact support
- ldap_contactsissues
Support
for contacts stored in LDAP
- gmail_contactsissues
Read-only
support for Gmail contacts with an Oauth2 enabled Gmail account
- coreissues
Handles page layout, login/logout, and the default settings pages
- desktop_notificationsissues
Desktop
notifications for new messages
- developerissues
For development, provides resources and installation details. Only available in "debug mode"
- dynamic_loginissues
Allows
user to authenticate against a list of popular mail services, or to auto-discover the services for the
specified E-mail address
- feedsissues
RSS/ATOM feed support
- githubissues
Github repository tracking
- hello_worldissues
Example module set with lots of comments
- highlightsissues
Color highlighting for message lists
- historyissues
Simple list of messages read since login
- idle_timerissues
Controls idle time and automatic logout
- imapissues
IMAP E-mail account support
- imap_foldersissues
IMAP E-mail folder management support
- inline_messageissues
View messages inline in a reading pane instead of on a new page
- jmapissues
JMAP (JSON Meta Application Protocol) It uses a JSON-based structure to streamline communication and optimize performance. By reducing the number of network round-trips compared to traditional protocols like IMAP and SMTP, JMAP enhances responsiveness and reduces resource usage. With its real-time updates and simplified structure. It is designed to improve the user experience by providing faster, more reliable access to data, making it ideal for modern applications.
-
keyboard_shortcutsissues
Adds
support for site navigation and actions using the keyboard
- nasaissues
Access
the NASA APOD API content
- nuxissues
Friendly new user experience. Quickly add common E-mail services, and view development updates. Needs help
text added
- PGPissues
Encryption using Pretty Good Privacy
- profilesissues
Profiles to set reply-to, name, and signature to associated E-mail accounts
- recaptchaissues
Enable Recaptcha on the login form
-
recover_settingsissues
Ability to recover user settings after an external password change
- saved_searchesissues
Save and re-run searches easily
- sievefiltersissues
Message filtering
- siteissues
Site specific overrides. Used to control other module sets without hacking the code
- smtpissues
Send outbound E-mail using SMTP servers
- tagsissues
Allows users to organize content effectively by utilizing tags or labels. It is designed to enhance content management by enabling users to assign relevant tags, facilitating easy categorization, filtering, and retrieval of content. The tagging feature is fully implemented, allowing for seamless interaction where users can add, edit, or remove tags as needed.
- themesissues
Change the UI using CSS
- wordpressissues
WordPress.com notifications and freshly pressed lists
Module sets are setup in the hm3.ini file. With the exception of the core module, they can all be enabled or
disabled independently (though module sets can rely on each other, like the nux module). When the site build
process is run, module assignments are calculated and saved in the configuration file (so they don't need to be
re-calculated at run-time). There is also a debug mode in which modules are activated dynamically (for the most
part) to make development easier.
File Structure
Module set names in the ini file match the directory the module code is in under modules/. Files in a module
have pre-defined names. Any other required code should be included from one of these files.
- setup.php
This is where a module set defines it's own modules and assigns them to request
identifiers. This file must return an array of valid input and associated types in order for the module code
to have access to it.
- modules.php
This is where the actual module code lives. If you have external libraries to include
this is a good place to do so.
- site.js
Optional file to include JavaScript for the module set.
- site.css
Optional file to include CSS for the module set.
A module set can also include an assets sub-directory. Anything in that directory will be made availble in the
browser. An example of this is the HTML WSIWYG editor for the smtp module set. In debug mode the module site.css
and site.js files are included directly if they exist. In production mode combined and optionally minified
versions are used consisting of a single js file and a single CSS file generated by the build process. Minifying
programs can be specified in the hm3.ini file.
Input and Output
There are two kinds of modules: Input processing modules called "handler modules", and output formatting modules
called "output modules". Modules can pass data to each other, and output modules have access to all the data
input modules create. By default, module output is immutable and can't be stepped on by other modules. Data can
be marked writable and an "appendable" data type is also supported. The typical job of a handler module is to
analyze user input and do some work based on it, which it then sends to the output modules. The typical job of
an output module is to take the results of an input module and format it for the browser.
Hello World
For more information, check out the "hello world" module set. It illustrates how modules work and has loads of
comments that explain what is going on:
https://github.com/cypht-org/cypht/tree/master/modules/hello_world