1. Directory naming, creating a meta.txt file, and ModuleInfo objects

As stated in the introduction, two parts of a Portal module that absolutely must be present are a parent directory and a file named meta.txt. The directory name must be a proper slug, consisting only of lowercase letters, the digits 0-9, and hyphens. In addition to general information such as the name, description, and author of the module, meta.txt contains functionally relevant values such as the module version and dependencies, as well as activation and deactivation instructions.

The format of meta.txt is very simple, yet strictly enforced. Let’s take a look at an example:

# Copyright 2018 Ringfree Communications Inc.

moduleName:: Demonstration Module
moduleDesc:: Provides "proof of concept" functionality for development and testing purposes.
moduleIcon:: bookmark
authorName:: Kendall Weaver
authorEmail:: kendall@ringfree.com

version:: 1.0.0
license:: WTFPL
section:: none
depends:: papaladmin>=0.0.1,homepage>=0.0.1,CORE>=0.0.1

onActivate:: \Papal\DemoModule::activate
onDeactivate:: \Papal\DemoModule::deactivate

Note the very first line beginning with a # character. This is a comment. Any line beginning with a # will be ignored when the file is evaluated. To keep things simple, inline and multiline commenting are not supported.

The remaining lines adhere to a very simple syntax: the name of the field immediately followed by two instances of the : character, immediately followed by a single space. Failure to strictly ahere to the name:: value paradigm will result in the line not being correctly parsed when the file is evaluated.

When the file is evaluated, what happens “under the hood” is that a \Papal\ModuleInfo object is created and each field is stored as a class-level public variable. Additionally three other class-level public variables are stored: slug being a string containing the name of the directory housing the module code, path being a string containing the file path to the module directory, and active being a boolean representing whether or not the module has been activated. More on this later.

The Fields

  • moduleNameRequired Field – A user-readable name for the module. Feel free to use capitalization, punctuation, numbers, and special characters if they’re necessary to properly name the module.
  • moduleDesc – A user-readable description for the module. Like the name, feel free to take liberties regarding the characters used.
  • moduleIcon – A reference to which icon should be displayed beside the module information on the module administration page. By default the Portal makes use of Font Awesome and supported values for this field are any icon in the solid section of the free set.
  • authorName – The name of the module author. Convention is to use a full, real name.
  • authorEmail – The email address of the module author. Please use a valid email address.
  • versionRequired Field – The module version number. This is used for dependency checking and, as such, it is advisable (though not required) to keep the versioning scheme in line with other modules. Semantic versioning is strongly suggested.
  • license – Presumably all modules written for the Portal will be owned by Ringfree with all rights reserved, however the core itself is fairly application agnostic and could potentially be licensed to other companies and/or open-sourced in the future.
  • section – Simply a means of organizing modules within the module administration interface.
  • depends – A comma separated list of other modules required to be active before this module can be activated. Note that the list also includes comparators and version numbers. Each listed dependency must have a comparator and version number. If a specific version is not required, use >=0 as this should encapsulate all possible versions. Standard comparators are supported: >, <, >=, >=, ==, and !=. Also note that specific version requirements for the Portal itself can be specified by using CORE as the dependency name.
  • onActivate – This allows you to specify a function (with no arguments) to be evaluated when the module is activated. The function can be (and in most cases should be) within the module itself. Note that the namespace and class must be included if applicable. Please do not include parenthesis at the end.
  • onDeactivate – Similar to above, this allows you to specify a function to be evaluated when the module is deactivated. Again no arguments will be passed to the function, the namespace and class must be included, and parenthesis must be omitted.

Note that there are only two required fields: moduleName and version. Also additional arbitrary fields may be specified and they’ll likewise be evaluated into class-level public variables. A potential use case would be making additional metadata available to other modules.

Creating ModuleInfo Objects

The ModuleInfo class exists within the Papal namespace and has a constructor that accepts a single argument: the module slug (the name of the directory where the meta.txt file and the module code is stored). Presuming our above example file exists within a directory named demomodule, the ModuleInfo object would be created as follows:

$x = new \Papal\ModuleInfo('demomodule');

ModuleInfo objects are primarily used to construct the module administration interface, itself part of the papaladmin module. When instantiated, the constructor function explicitly sets the active, path, and slug variables before calling the private parseMeta function which evaluates the data in meta.txt. A missing meta.txt file or the absense of required fields will result in an Exception. Additionally attempting to call the constructor with a reserved value such as CORE will result in an exception. At present CORE is the only reserved value. This page will be updated with any additional reserved values added in the future.

Now that you have a basic understanding of how to put together the meta.txt file, let’s take a look at how the portal handles data:

References, metadata, and the database.