-
Notifications
You must be signed in to change notification settings - Fork 26
Board Rules Directory Structure and Content Guide
This WIKI page is a guide to the directory structure and content of the Board Rules extension.
The acp directory contains two files which are responsible for our Admin Control Panel interface.
boardrules_info.php - This file provides information to phpBB's Module Management system about Board Rules. It defines the name of our ACP module, and the available modes contained within our ACP module, which are "settings" and "manage". It also contains version and permission information for our ACP module.
boardrules_module.php - This is the file loaded when our ACP module is accessed. While this file would usually contain all the functionality needed for an ACP module, we have moved almost all logical code out of this file and into the admin_controller.php in the controller directory.
The adm directory contains the template files needed for our boardrules_module.php in the ACP. All new template files that an extension will use for the ACP must be contained in the adm/style/ directory, just as phpBB does.
Note that any template events for the ACP should be be located in the adm/style/event/ directory.
The composer.json contains basic information about this extension including its name, version, dependencies, requirements, and authors. It is required by phpBB's extension system and may play a role in the future if extensions can be distributed to phpBB installations through Composer.
The config directory contains YAML files used by our controller, entity and operator classes.
services.yml - This file defines the services required by some of the classes in our extension.
routing.yml - This file contains the routing definitions used by our main_controller.php.
tables.yml - This file contains table definitions used by some of the services in services.yml
The controller directory contains front-facing controller files for our ACP page (admin_controller.php) and the actual Rules page (main_controller.php). Each controller implements an interface (the interfaces are used mainly for documenting and organizing our contollers methods).
The entity directory contains a rule class that contains all of the methods for working with a single rule. It too implements an interface.
The event directory contains a listener class that is responsible for hooking our extension into phpBB's core code. This allows us to load our language files, add a link to our front-facing controller in phpBB's navigation bar, and inject other components of our extension into phpBB.
The exception directory contains several custom exception classes that handle the exceptions thrown by our entity and operator classes.
The ext.php class is required by all extensions, and is responsible for making phpBB aware of our extension. Normally this file's main class is left empty, but our use of phpBB notifications presented a rare need to extend the default enable/disable/purge methods of the extension system with some additional code handling notifications during those processes.
The language directory contains all of the language files used by our extension. Language files can be named and organized however you like, however, it should be noted that the ACP automatically loads files prefixed with "info_acp_". If you do not use this, then the language file must be loaded manually in the ACP controller files. Likewise, the permissions system will automatically load files prefixed with "permissions_" for use in the ACP permissions pages.
The license.txt file is a copy of the same GPL-2.0 license that comes with phpBB, and must be included with any publicly distributed phpBB extension.
The migrations directory contains the files that make changes to the database. They have been divided up into several files that were created as this extension was undergoing various stages of development. Although there are no requirements on how they are named, we used prefixes to make it easier to understand the sequence in which they will be run by the migrator.
The notification directory contains our notification class which extends phpBB's notification system with methods of our own that allow Board Rules to send out its own notifications to users.
The operators directory contains a rule class that contains all of the methods for working with a set of rules. It too implements an interface.
The styles directory contains all of the template/style/ files needed by our extension.
all/ - This directory contains style files that can be used by any/all styles.
prosilver/ - This directory contains style files specifically for prosilver (and any styles that inherit from prosilver).
subsilver2/ - This directory contains style files specifically for subsilver2 (and any styles that inherit from subsilver2).
*/event/ - This directory contains our template events. These are snippets of template code that are injected into phpBB's at template event locations. Template event files must be named the same as the event they are injecting for.
The tests directory contains unit test files. The unit tests allow continuous integration testing through Github and Travis in order to fully test our extension's code, integration with phpBB, and prevent possible regressions. Unit-testing is optional but highly recommended for extensions hosted in a Github repository.
.gitattributes This file is used to block some files from being downloaded in Github. These are files that are not needed in the Board Rules distribution package.
.travis.yml This file is used by Travis-CI to set up the testing environment.
.gitignore This file is used to prevent Git from tracking certain files.