Social Engine Package Manifest File Explained
Introduction
When creating a social engine package via the SDK, one of the files created is the manifest file which contains a number of meta data and not much else. It is up to the developer to figure out which element goes which. This post is an attempt to help others figure out what the parts of the manifest file, how they work and when they should be used.
Initial Content
The package manifest file initially contains an array definition. This is an associative array containing a single element and this element has “package” as key. The keys “type”, “name”, “version”, “path”, “title”, “description”, and “author” are self-descriptive and most of them are the values you entered when creating the package via the SDK.
Note that version is used to determine if the package upgrades or downgrades a package when it is installed in case the package is already installed before hand. In case of upgrades SE also calculates whether it needs to run upgrade sql scripts. Let’s consider a module named Foo version 4.0.0. During installation the queries in the files my.sql and my-install.sql will be executed. If the version of the package is incremented to 4.0.1, you may add the file my-upgrade-4.0.0–4.0.1.sql. When the package is rebuilt and installed so that it upgrades a previous 4.0.0 install the sql statements in the upgrade sql script will be executed.
For modules, the name of the package is the name space for the module. That is if the name of the package is “Foo” then the module will reside in applications/Foo and every resources therein will be prefixed with “Foo_”. Naming a module with hypens like foo-bar will result in a name space such as “FooBar” and a prefix of “FooBar_”.
The “directories” key are the paths/directories defined by the package. Initially it contains only the package’s path. Additional paths can be added and defined here (I have not tested all possibilities and limitations of this function).
The “files” key are the files contained in the package that is outside the packages path. A good example is the language file that is initially created for modules. You may add additional files outside the package path and add a key on this this files array and that file will be included in the package.
Additional Package Meta
There are additional keys in the package array that are not defined initially. They are “revision”, “changeLog”, “callback”, “dependencies” and “tests”.
The key “callback” defines, no surprise here, the callback class. This call back is used to run custom queries to build pages or altering tables as needed. The class is expected to be in settings/install.php. This class must extend Engine_Package_Installer_Module for modules and Engine_Package_Installer_Themes for themes.
During installation the statements defined in the methods onPreinstall and onInstall of the callback class will be run during the appropriate step of the install. Note that these method are only called during installation and not during upgrades. This methods are useful for queries that you need to run but are otherwise impossible to do so without the use of stored procedures. Like building the pages for your module.
Composers
Composers are the scripts that allows end users to attach items on posts. For example, the core module defines a link composer. That is where the “Add Link” link on the activity feed widget is defined. The subject merits a whole other blog post.
Hooks
The hooks array contains two element arrays that defines engine hooks. The “event” key is the event you want to hook on to and the “resource” key is the class that contains the handler. Here are a list of events that can be hooked on to out of the box and here is an example of a hook. You may create additional events via the Engine_Hooks_Dispatcher.
Items
The items array contains the array contains the items defined in the module. Items are at the core of socialengine both literally and theoretically. It is something than can be viewed, owned, posted on, commented on, attached, deleted moderated etc. It is yet another subject of a blog post. For now it’s enough for us to know that defining an item in the manifest also requires us to define a model and a db table for the item to be of use.
Items extends Core_Model_Item_Abstract. By default an item’s name is the concatenation of the containing module’s name an underscore and the name of the item itself. You may change this by changing the value of the $_name property of the model.
Routes
Routes should be familiar to experienced Zend Framework users or users of other MVC frameworks. It’s a subject of another blog post. For now let me refer you to how routing works in ZF which is the framework SE is build upon.
Originally published in https://social-engine-tutorials.blogsplot.com.
