How does one modify modules/assets called by default.master.tpl?

Accent

Hi all,

First of all: as you might know from previous posts of mine, or will see through this one, I'm pretty new to vanilla, so please forgive my relative incompetence! sorry!

I'm currently trying to tweak the layout of my forums, but I'm having some trouble understanding where I should look for files to modify. I've read the various pages in the documentation and I understand that default.master.tpl is the file that basically calls the various parts of the forum from the php files present in the views directories, and assembles everything together to generate your forum page...

The thing is, for instance I'd like to modify what is displayed in the forums' panel – the corresponding line in default.master.tpl is {asset name="Panel"}, and I did move that line to where I wanted the panel to be displayed, but I can't actually modify the contents. How should I proceed to do that?
Same goes for the modules: there's {module name="MeModule"} but then I found several folders called 'modules', containing several files that could refer to the 'MeModule'. How do I know which one I am to modify?

And, actually, for now I'm only having issues with the assets and modules but I'll probably run into the same problem later on with the views as well – for instance if I want to modify how the discussions list looks, where should I go? There are 2 folders called 'discussion(s)' in applications/vanilla/views, each containing several files, and then there's applications/conversations which could refer to discussions as well, and I'm probably missing some...

So, yeah, I'm a bit confused, haha :stuck_out_tongue_closed_eyes: Any help would be appreciated.

peregrine

First off - you may be on a road to self-destruction, if you modify core files. Some users in the past thought it a great idea to modify the core files, and then because they had so many changes, they lost track and have not been able to upgrade (despite updates in security).

you can create your own modules and then call your own modules.

Best to lean about theme modification and plugins.

Lots of tutorials.

a bunch of links here:
http://vanillaforums.org/discussion/comment/210155/#Comment_210155

http://vanillaforums.org/discussion/20231/how-to-become-somewhat-adept-at-modifying-vanilla-to-meet-your-needs-for-free

also see the tutorials for themes - and see the wiki.

do you have linux or some unix system? if so.

to find a module

du -a | grep memodule

would give you this

/applications/dashboard/modules/class.memodule.php

I'm not a fan of copying views and modifying them either, because if the view changes in the core on the next upgrade, you might be missing out on view changes, and you might not be aware of it. But if you are changing views you could look at a few plugins that change views - e.g. firslastname

The best thing to do is look at fireevents and write your plugins to trigger off events to manipulate things. Obviously you could hide things with css as well.

peregrine

changing wording..

http://vanillaforums.org/discussion/26597/tutorial-how-to-change-wording-how-to-change-text-how-to-change-language-how-to-change-locale

if you want to sort panels via a confiig statement in config.php

http://vanillaforums.org/discussion/comment/163830/#Comment_163830

there is no generic answer to your questions really, if you have a specific module with something post a screenshot and show what you want to change and to what.

you can add links to some modules or tabs, and remove them via events.

R_J

The default.master.tpl can be subdivided in 4 parts:

1. an asset called "Content" - that is basically a placeholder for discussions and such (if you add #Content {background-color: yellow;} to your css, you will see what is in that asset ("asset" being a nicer word for "container").
2. an asset called "Panel" where most of the modules will be shown, though you can show a module in any asset you like by altering its source code. You have already found out how you can show modules outside of the panel when you've found the MeModule
3. a HTML skeleton that fram-es around those two assets giving it its structure.
4. default.master.tpl is a Smarty file and a strength of Smarty is that you can sum up longer pieces of code into handy snippets. There are several snippets in /library/vendors/SmartyPlugins which you can insert into default.master.tpl to spice up its functionality.

---

Modules are part of applications or plugins. So you will find them in /applications/someapp/modules or in /plugins/someplugin/
Not every plugin has a module and it can be in a subfolder of a plugin, but it will most probably be called class.pluginnamemodule.php, so you might like to search in your plugins directory. Creating only a module isn't useful, because you need some code to show it somewhere. That must be done in a plugin and that's why a module is always accompanied by a plugin. Therefore you'll have to enable the according plugin to show a module.

You can change the order of the modules. Take a look at the Modules section in /conf/config-defaults.php. There are arrays for several parts where modules appear. Most probably you are interested in $Configuration['Modules']['Vanilla']['Panel']. Copy that line over to /conf/config.php (don't change the config-defaults.php). Change the order of the elements in that array and the order of the loaded modules will change, too. But that is not the place to define which modules should be shown at all. It only handles the order...

---

You've said you do not know where to look for files that you want to change. Don't make changes to the core! You'll regret doing something like that because every update might destroy all your work. If you are trying to alter the look of your forum, you'll need to create a custom theme. As soon as you have that, you can start copying the files that you would like to change to your custom theme folder and make the changes there.
Vanilla will use the files from your folder, so you don't have to destroy anything.

Here are some words to the structure, but I guess you'll have to use a full text search tool (eg grep or notepad+) in the beginning to find what you are looking for.

Generally spoken, Vanilla is just an application that has been built with a framework called Garden. You'll find most of the framework in /library. There you can find global functionalities. Take a look at the file names in /library/core to get an impression what is handled by Garden.

If you do that, you'll see that there is nothing like a forum in that directory.

Now let's have a look at the applications. They are basically structured in the following way:

/applications/appname
/controllers - read something about MVC to get a basic understanding what's in here
/js - javascript files. Libraries as well as custum files
/locale - translations
/models - you really should read something about MVC
/modules - we've spoken about them and here they are!
/settings - everything that has to be done when the application is started such as db changes for example
/views - MVC again... But if you are interested where the HTML you are looking at comes from, you'll have to take a look at this directory

Vanilla comes with 4 applications: dashboard, vanilla and conversations. Let's forget about skeleton by now.

Have you read about MVC already? If yes you'll know what you can expect when you look at /applications/someapp/controllers. If you open up any page of your forum and take a look at the url. The first part will tell you the name of the controller. You can now scan through all "controllers" folders, but it easy to guess where you have to look at. Conversations is most easy. Every message or a conversation which consists of multiple messages is shown with one of the conversations controllers (getting the data with the model, displaying it with the view all in the according subfolders of /applications/conversations

Whenever you look at categories, discussions or comments, you'll have something forum specific and /applications/vanilla is the forum application. So if you are interested in them, look at the vanilla aplications subfolders. If you look at the controllers folder, you'll see some more things that vanilla takes care for, but they are no surprise, either.

Basically spoken, all other work is done in the dashboard application. It provides other apps with a settings framework, user management and quite a lot more.

So when you are searching for a view, go through that scheme:
1. is it a conversation or a message? => /applications/conversations
2. is it a discussion or comment? Or more of the or something that is directly related to them? => /applications/vanilla
3. has it something to do with users or the admin section? Login, logout, authenticate, notifying, settings, etc? => /applications/dashboard

---

Okay, now you now in which "views" folder you have to look when you try to understand how a HTML page is build up. I guess you know now why there is a /views/discussions and a /views/discussion subfolder. example.com/discussions shows the discussion index while /example.com/discussion/123/abc shows 1 discussion and its comments - two really different things and therefore two different folders!

But from there you have to work through the files: example.com/discussions will fetch the view /applications/vanilla/discussions/views/index.php
If you look at that file, you'll see that index.php calls the file discussions.php and discussions.php use a function WriteDiscussion which is in the file helper_functions.php
As I 've said before: you'll have to make your way through that files once you are there. You'll soon be able to recognize patterns in the file structure but in the beginning some full text search tool is a invaluable help!

And now, if you've found the file that you are not happy with, don't alter it copy it in your custom theme folder and change it there.

Good luck!

Accent

wow great answers. I'm gonna read everything and report back and if I manage to get a custom theme up and running I might even publish it here!

now wondering whether I should mark your posts as insightful or awesome...

Accent

Just letting you know that I've been making a lot of progress in way less time than I expected, and now the layout is almost complete for the main views... I still have to handle special pages like individual profiles, etc. and make sure I don't forget anything (since I removed a lot of extra fluff I didn't want from some modules).

As soon as it's all done and functional, I'll upload it with just the minimum amount of CSS to make it look right while keeping the default theme's colours and feel.

Thanks again for your help!

Accent

Ran into an issue I can't quite manage to solve...
I'm trying to move 4 elements: the side menu in a profile edit screen (where it says Edit Profile, Change My Password, Notification Preferences, etc.) and, in a conversation with someone, the Delete Conversation button, the list of people in the conversation, and the Add people form.

Now I think I found which modules control those. Respectively, there's SideMenuModule from the dashboard application, and ClearHistoryModule, InThisConversationModule and AddPeopleModule from the conversations application.

The thing is, when I add those modules to other parts of the site in default.master.tpl, they aren't actually displayed – apart from the 'add people' form which actually works as it should, but I thought I'd mention it to be clear. I've tried copying the views corresponding to those modules in my theme folder, in case there was a conflict between applications or something, but it didn't work.

I really can't think of what I might be doing wrong, those are the only modules that are reluctant in this way...

hgtonight

How are you attempting to move them?

Modules are sorted at the application level, so there are separate config items for each application.

Accent

I just copied {module name="SideMenuModule"} and the others where I want them to be in default.master.tpl. This is how I've done it for the others (CategoriesModule, NewDiscussionModule, DiscussionFilterModule, MeModule etc.) and it's always worked so far

Accent

I also tried adding echo Gdn_Theme::Module('ClearHistoryModule'); to the correct views I wanted the modules to be displayed in, and again only the AddPeople module works.

R_J

Modules are very, very variable in how they could be built. The clearhistorymodule expects a ConversationID. That ConversationID is not read somewhere in the module itself, but it must be given on the time the module is created.

I guess you would have to create a custom smarty function, but I would not know how...

hgtonight

Modules are usually added via a controller method in the application or via a plugin that hooks into the controller. If you are adding a module via a view, you will need to pass it the information it needs via the {module} Smarty plugin.

For example, for the ClearHistoryModule you would use the following smarty markup:

{module name="ClearHistoryModule" ConversationID="123"}

Where 123 is the conversation id.

R_J

@hgtonight said:
{module name="ClearHistoryModule" ConversationID="123"}

Where 123 is the conversation id.

I bet he needs it dynamically. So I think it would be necessary to create a custom Smarty function where you have to get the ConversationID from the controller.

Accent

I can't just use Smarty plugins in php files though, can I? That's why I have to use echo Gdn_Theme::Module

R_J

If you are in a php file, you could use the power of the framework! Great you reminded me of that...

First you have to find out how you can get the ConversationID. Put a decho($this); somewhere in the target view and be prepared to see a lot of information. You should find the ConversationID somewhere and then you might be able to do the following in your new view (ugly, but maybe someone else has a better idea)

    $ConversationID = $this->...whatever you've found out->ConversationID;
    $ClearHistoryModule = new ClearHistoryModule($this);
    $ClearHistoryModule->ConversationID($ConversationID);
    $this->AddModule($ClearHistoryModule);

edited based on hgtonights knowledge ;-)

hgtonight

Views are executed in the scope of the controller, so you should inspect $this rather than sender.

EDIT - I am getting confused, is this in a plugin hook? Then inpect $Sender :S

Accent

okay so I think I found something. I did see the ConversationID in the debug info... for instance there's this:

[AddPeopleModule] => AddPeopleModule Object
                        (
                            [Conversation] => stdClass Object
                                (
                                    [ConversationID] => 2
                                    ...

which I assume confirms that the ConversationID was properly passed on to the AddPeople module.

But then I found this:

[ClearHistoryModule] => ClearHistoryModule Object
                        (
                            [ConversationID:protected] => 2
                            ...

and doesn't that mean the ClearHistoryModule also managed to retrieve the correct ID? (It still doesn't show up, though...)

And I also found:

[InThisConversationModule] => InThisConversationModule Object
                        (
                            [AssetName] => 
                            [_ApplicationFolder:protected] => conversations
                            [Data] => Gdn_DataSet Object
                                (
                                    ...
                                    [_Result:protected] => Array
                                        (
                                            [0] => stdClass Object
                                                (
                                                    [UserID] => 1
                                                    [Name] => Accent
                                                    ...

and below that, more information about me as well as the other participants of that conversation. So it really looks like the modules can get access to whatever information they need, and yet they're still not displayed...

R_J

@Accent: it would be much easier if you you would show us some more code
I've added that lines to the /applications/conversations/views/messages/messages.php view:

$ConversationID = $this->Conversation->ConversationID;
$ClearHistoryModule = new ClearHistoryModule($this);
$ClearHistoryModule->ConversationID($ConversationID);
$this->AddModule($ClearHistoryModule, 'Content');

and I see the [Delete Conversation] button now (also) under a conversation.

Assets like Panel and Content are containers and you can stack modules. But if you want to have the modules output somewhere in the html flow, you couldn't always rely on the AddModule but you would have to trigger it's output directly. You can put that (nearly) anywhere you like inside of your views:

$ConversationID = $this->Conversation->ConversationID;
$ClearHistoryModule = new ClearHistoryModule($this);
$ClearHistoryModule->ConversationID($ConversationID);
echo $ClearHistoryModule->ToString(); // or simply echo $ClearHistoryModule;

"nearly anywhere" because $this has to be a conversation controller, but I guess that button makes no sense outside of a conversation...

---

@hgtonight: as far as I know, it should be inside of a custom view

Accent

Hm, it works with ClearHistoryModule but completely breaks with InThisConversationModule. I'll investigate. Those are the last things I need before I can publish the theme!!!

Accent

This is the error apparently:

         trigger_error(ErrorMessage('The "' . $this->ClassName . '" object does not have a "' . $ActualMethodName . '" method.', $this->ClassName, $ActualMethodName), E_USER_ERROR);

R_J

Investigate how that Module is called inside Vanilla (by using a full text search):

      $InThisConversationModule = new InThisConversationModule($this);
      $InThisConversationModule->SetData($this->RecipientData);
      $this->AddModule($InThisConversationModule);

It needs "RecipientData". Don't know what that is but I guess if you copy those three lines into your view, you'll see the module (maybe you have to replace the last line with echo $InThisConversationModule;)