Gdn_Module - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/8215VSV4S4U6/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/8215VSV4S4U6/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>If controller methods represent the main content/purpose of a page, modules represent secondary information or functions. Modules are small groupings of functionality or information on a page. Some modules that are bundled with Garden include:</p><ul><li><strong>HeadModule</strong> - Allows addition of javascript, css & meta information to be rendered in the page.</li><li><strong>MenuModule</strong> - Handles management and rendering of items in the main menu.</li><li><strong>PagerModule</strong> - Takes information about a dataset and renders a pagelist.</li><li><strong>GuestModule</strong> - Displays information for unauthenticated users in the sidebar on how to sign in or register.</li></ul><p>Modules are application-specific, and are located in the application’s “modules” folder. To see all of the modules packaged with Garden, browse to <code class="code codeInline" spellcheck="false" tabindex="0">/applications/garden/modules</code>. If a module has an associated view, it can be found in the application’s views/modules folder with the same name as the module file minus “class” and “module”. For example, the view associated with the <code class="code codeInline" spellcheck="false" tabindex="0">/applications/garden/modules/class.guestmodule.php</code> is <code class="code codeInline" spellcheck="false" tabindex="0">/applications/garden/views/modules/guest.php</code>. Modules are extended from the Module class, which is like a very simple version of the controller class. They are typically used to display information in the Panel asset, but they can actually be used anywhere in the page. A module’s default asset is defined with the AssetTarget method, which simply returns the name of the asset to add the module to by default.</p><h2 data-id="examples">Examples</h2><p>The simplest modules will have just two methods: AssetTarget and ToString. Let’s make a “Hello World” module. Create a file called class.helloworldmodule.php and place it in your test application’s modules folder (if you don’t have a test application, put it in Vanilla’s modules folder). Open the file and enter the following:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">class HelloWorldModule extends Gdn_Module { public function assetTarget() { return 'Panel'; } public function toString() { return 'Hello World!'; } } </pre><p>Now let’s go add it to a controller. Open up a controller in your test application and add the following (if you don’t have a test application, use vanilla’s <code class="code codeInline" spellcheck="false" tabindex="0">controllers/discussions.php</code> file and add it to the bottom of the index method) right above the call to <code class="code codeInline" spellcheck="false" tabindex="0">$this->render():</code></p><pre class="code codeBlock" spellcheck="false" tabindex="0">$this->addModule('HelloWorldModule'); </pre><p>If you browse to this page, the text “Hello World!” will not appear in the panel. You can change where the “Hello World!” text appears either by changing the value returned by the AssetTarget method, or on the fly when the module is added by the controller. Let’s change the AddModule call to send the module to the Content asset instead of the Panel:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$this->addModule('HelloWorldModule', 'Content'); </pre><p>Go back and refresh the page to see that the text has moved over to the Content asset. The AddModule method will take a string as the first parameter, or an instantiated module object. So, we could have also added the module in the following manner:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$helloWorldModule = new HelloWorldModule(); $this->addModule($helloWorldModule); </pre><h2 data-id="organizing-module-sort-order">Organizing Module Sort Order</h2><p>You can organize the order that modules appear in assets by manipulating the Modules collection of the Configuration array. Take a look at conf/config-defaults.php to see the default sort order of core-packaged modules:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Modules $Configuration['Modules']['Vanilla']['Panel'] = array('NewDiscussionModule', 'GuestModule', 'Ads'); $Configuration['Modules']['Vanilla']['Content'] = array('Gdn_MessageModule', 'Notices', 'Content', 'Ads'); $Configuration['Modules']['Garden']['Content'] = array('Gdn_MessageModule', 'Notices', 'Content', 'Ads'); $Configuration['Modules']['Conversations']['Content'] = array('Gdn_MessageModule', 'Notices', 'Content', 'Ads'); </pre><p>The collection names the application, followed by the asset to organize. The value is an array in order that modules should be organized. If a module is not added, it will simply be ignored. If a module is added that does not appear in the array, it will be added after the defined modules, and in the order that it was added to the code.</p><h2 data-id="doing-more">Doing More</h2><p>While it’s nice to be able to add messages to pages, it doesn’t illustrate the true power of modules. Modules can be used to retrieve and display data, contain forms for submitting data, and much more. To see all that can be done with modules, take a look at the modules in Garden & Vanilla. Listed below are a couple examples of modules that do more than just spit out text:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">/applications/garden/modules/recentactivitymodule.php</code> - Grabs recent activities for display in the panel.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">/applications/conversations/modules/class.addpeoplemodule.php</code> - Adds a form to the panel that allows users to add people to a conversation.</li></ul><p><br></p> </article> </main>