Ferreteria/v0.5/dropin

A dropin is a collection of code-files which can be included in a Ferreteria project by simply being "dropped in" to the appropriate folder (as designated by the local configuration). Each dropin must have an index file which tells Ferreteria what classes, actions, files, etc. are involved.

Files/Classses

• base/dropin.php for dropin-specific loading
  • csDropinManager: the Dropin Manager
  • cDropIndex: encapsulates a single Dropin Index file
    • Feature-object registration happens in cDropIndex->RegisterMenuBits(), where the Feature'saction list is pulled from $arSect['actions'].
    • Feature-spec registration takes place... somewhere. Currently tracking that down (2022-06-04).
• loader/ClassLoader.php (see ClassLoader) for generic class registration

Process

loading

• The Dropin Manager looks through each subfolder within the dropins folder.
• For each folder found, csDropInManager::CheckFolder() checks for an index file.
• If the index file is found, it creates a crcDropIndex object and calls (crcDropIndex)->ProcessIndex()
• ->ProcessIndex()
  • loads the $arDropin data into a crcDropIndex object, which more or less encapsulates it.
  • calls ->RegisterClasses(), which processes the Dropin array's 'classes' subarray
  • calls ->RegisterMenuBits(), which processes the Dropin array's 'actions' subarray

display

• The Navbar shows only Features that the current user has permission to access.
  • cMenuFolder (tree/nav/MenuFolder.php) manages the display of each Dropin and its Features.
• The Software Feature in the Basics dropin displays a list of all available Modules and Dropins.

URL interpretation

Understanding how this works requires understanding how we end up processing the Dropin code, which requires understanding the startup process.

documentation in progress

• in cArrayLink( tree/items/ArrayLink.php):
  • GetLinkURL() calls GetLinkArray()
  • GetLinkArray() calls GetLinkArray_figured()
  • GetLinkArray_figured() calls cDropinLink→GetLinkArray_self()
• in cDropinLink tree/menu/DropinLink.php):
  • The internal events (evint) system is used for passing Render requests (using a cRender event object) down to the appropriate Feature, which returns content via the passed event object.
  • OnEventAfter() calls PageEvent(); Render() calls AddPageRendering();
  • PageEvent(), AddPageRendering(), and GetLinkArray_self() each call MakeActionObject() to get the table or record to act on.
  • InvokeFeature() parses the URL for a Feature spec, and returns the corresponding Feature object.
    • It's also supposed to pass the rest of the URI data on to the Feature object, but I don't know if this has been implemented here, or at all, as of 2022-05-25.

Classes

loading/display

These classes make heavy use of the ClassLoader system.

• csDropinManager: static class which runs the whole process; analogous (but not related) to csLoader
• cDropIndex manages the Dropin library's index file (typically index.dropin.php); descends from caLibrary
  • cDropinLink displays the Feature link, if the user has permission to access it

URL interpretation

• cDropinLink
  • cDropinAction
• value\cDropin

Index File

By convention, the index file is named index.dropin.php; this name can be changed via the global settings object. The index file's primary task is to define the $arDropin array, with the following elements:

• name: the name of the dropin
• descr: one-line description
• version: version number
• date: release date, in YYYY-MM-DD format
• URL: full URL to documentation
• db.spec: name of class for database spec (must descend from cDatabaseSpec)
  • If omitted, uses the site's default db spec.
  • if NULL, Tabloid class is constructed without a db.
• section: array which defines how the dropin will be listed in the dropins bar
  • title: what to display at the top of the section
  • popup: (optional) text to appear when mouse hovers over the dropin name
  • actions: array of items to appear within the section
    • array[<item key>]: indexed array of information for a single actionable item
      • class: name of action class to invoke
      • feature: slug for Feature class (singleton object) (replaces "class")
      • text: text to display in section listing
      • summary: one-line description of item (used for hover-over text but may appear in other places)
      • perms: permits required in order to invoke this item. If user lacks permission, item will not be displayed.
• classes: array of files and the classes they contain
  • array[<relative filespec>]: collection array of classes available in the given code-file