Lisa, the Simpson!

Doc Team Member writing an unofficial guide? WTF?! Heh.

First off, you will need to know HTML (or XHTML, they're both good :P). That is an absolute must. CSS will beneficial if you wanna edit style.css.
--------------------------------------------------
Lesson One - The Package Manager

Okay, you've got SMF installed, but no doubt it doesnt have a feature or two that you'd like. This is where the package manager comes into play. The package manager allows you to install new features at the click of your mouse, sadly, it cant make you hot chocolate or cookies, that's in the Development Edition. ;)

To use the package manager, go into your Admin Center and look for "Packages" in 1.1 or "Package Manager" in 1.0. This will take you to the package manager window.

To find a package, there's two ways. Under Download Packages you can connect to the SMF Mod site from your forum, and you'll be given a list of mods to install from their latest versions. IMO, it isnt exactly a good way to get packages.

So instead, head over to http://mods.simplemachines.org and look for some packages. Remember, you must read carefully which mods are compatible with your version. You cant install a package for 1.0.9 on 1.1 RC3, but you CAN install a package for 1.0.3 on 1.0.9, remember that. 1.0.x and 1.1.x are very different.

When you've found a package to install, download it to your computer, then go into the "Download Packages" option of your Package Manager and then use the browse button to look for the mod, remember, it must be in .zip, .tar.gz or .tar.bz2 format, all three will work.

Then you click Upload, you'll be taken to the option where you can apply the package, click [Apply Mod] to install.

SMF will then perform a test to see if it can install it correctly. I'll discuss failures later, but if you get perfect success's then you're free to install the package and away you go!

Click Install to finish the installation and you'll come to the final screen where you are told that the functionality has been added to your forum.

Lesson Two - Editing the layout of Board Posts in SSI.php

Please note that this is not recommended because when you upgrade your version of SMF, the code will revert back to the default, however you can create a mod to do it for you again automatically via the Package Manager.

First you need to open ip SSI.php in any text editor such as Notepad or Wordpad, or if you need colour syntaxing, then Dreamweaver can do the trick in code view.

And look for this:


Pretty small eh?

Lets go over the gibberish.

', $news['href'], ' is the link to the topic.
', $news['icon'], ' is that topic's icon.
', $news['subject'], ' is the title of the topic.
', $news['time'], ' is the time it was posted.
', $txt[525], ' is a language string for "by"
', $news['poster']['link'], ' is the link to the poster of the topic.
', $news['body'], ' is the first post.
', $news['link], $news['locked']  ? '' : ' looks to see if the topic is locked.
' . $news['comment_link'], ' is a link to the post screen to post a reply.

Other than those snippets, the rest is basically just HTML within a div tag. So you can eaisly make it look like cutenews if you wanted to. Just as long as you include all the nessesities like poster name, subject, time, href it's not a good idea to change the string for $txt[525] because the whole of SMF uses it, you wish to change it, I'd suggest that you add an entirely new string to index.english.phpin your languages folder.

Lesson Three - What to do when Mod's Fail

This will also work for getting mods to work on custom themes.

When a mod fails chances are that you have a conficting mod installed. So the only way around it is to install manually. This lesson will show you how to do just that. For this example, I'll be using JayBachatero's Global Announcement's Mod and for a custom theme, I'll be using the Babylon theme packaged with SMF 1.1.

First off, even though you get failures, complete the installation of the mod anyway. You'll be finishing the rest off the hard way.

Look in the [List Files] section of the mod to list all the files listed inside the package. The package manager can read .zip, .tar.gz and .tar.bz2 files easily.

Look for something such as install.xml, modification.xml or similar. Sometimes though this may be a .mod file instead and some have version numbers such as "RC3" or "109" to tell which file is for which version of SMF. .mod is actually easier than .xml but it's not recommended though.

To make life easier for the coder, the package manager has some special paths, they should be fairly obvious.

$boarddir = This is the forum root. eg. public_html/forum
$sourcedir = This is the sources folder.
$themedir = This is the default theme's folder.
$languagedir = This is the language folder in the default theme.
$avatardir = This is the avatar folder.
$smileysdir = This is the Smiley folder.

I'll be using those names here on out.

And look for the area for the file that failed. Lets say that MessageIndex.php failed in $sourcedir. It has this code.


Quite a bit huh? Dont worry, what the actual code is isnt important. This is just a copy and paste job.

First, lets look at the XML tags around the code.


This tells us what file to look at. In our case, we're looking to download MessageIndex.php from $sourcedir onto our local computer and open it in any text editor.


This tells us that the code we are about to add must go before the code we are looking for.

Okay, listen up, this important, ignore the "<![CDATA[" "]]>" code, we're not going to be using it. Thats just there so that you can use <, >,&, " etc without it turning into HTML entities. (&amp;, &quot; etc...).

Now that we know that we have to be looking to add the code before what we're searching for, we can add the second batch of code which is stated after <add>.

There are some other search possitions they are

<search position="after">

This one places the second batch of code after what we're after.

<search position="replace">

This replaces the first batch of code with the second.

<search position="end" />

This adds the code to the end of the file before the closing "?>" ideal for stuff going in $languagedir files.

Once you've manually inputted all the code the mod requires, you can just upload it over your current one.

To install on custom themes, such as our Babylon theme, you need to look out for the $themedir filenames. Such as ManagePermissions.template.php, and basically do the same thing. But if your theme does not have the file it's looking for then it'll be in the default theme, because if your theme does not have its own, then SMF automatically falls back on the default theme's, and chances are that the mod will be installed on that file anyway. (unless it failed. :P)

I hope I never have to understand this... *clutches A-Level Physics textbooks*


Thanks for the guide though, will certainly help some peoples here :)

Heh, you should have posted that two hours earlier. I just managed to install the SMF Gallery mod at my local astronomy club's forum (http://www.sternwarte-kreuznach.de/forum/index.php), and I also had to edit my template to get the gallery button into the navigation (and I had to translate it to German, obviously, including editing the language strings in the PHP files, since the translation someone else did wasn't that great). PHP (and programming in general) isn't really my forte, but finally, I managed to get it working as desired. :)

First two lessons are really useful; thank you for writing and posting them. :)
The third one... I've spent half the day reading the official guide to the mods development, and another half the day trying things and searching for workarounds here and there. Either I'm dumb, or it's almost impossible to learn how to create mods from such a short article. :homer:

What would be really useful for mod creators, is the tools that packages the mod automatically. It's quite possible thing to make; the idea is that you have two copies of the forum installed on different local hosts - the original one and the one you edited manually (added all needed features, uploaded new files, etc), and that tool simply compares them and packages the differences.

Or, and another side-note: the mod (http://mods.simplemachines.org/index.php?mod=520) I've published so long ago, still isn't approved and marked as unsafe. :(

Dag, I'll mention about your mod to the team and have them take a look. It's been long enough.

Andreas, translating language strings is pretty simple, just look in /default/languages and then in your case, Modifications.english.php and then copy and paste the strings into Modifications.german.php and then paste it before the closing ?> and then translate in between 'gdhvdd'; :P

Dag, We have a package SDK, which bascially explains it all for you. You can use the .mod format which is MUCH easier than the XML method, The SDK also has a thing where you can test the mod too.

Yes, I know, and that was the easy part. It got a bit more complicated to modify the template, so the gallery button showed up. Luckily, I found the code that was needed in the support forum, but then again, I had to find the correct placement. You know, that PHP code is like Chinese symbols to me...  :p

Heh. Even adding new tabs is simple. :P

http://docs.simplemachines.org/index.php?topic=564.0

If you ever have a question about SMF, just ask me... I'm there to help.

Ok, I'll take that literally. ;) As I said, I just installed that Gallery mod, and it's a very nice addition indeed. But I'm missing one feature in the thumbnail list: The title of the image! I'm presenting astronomical images, so in many cases, you see only black with some white or colored dots in the thumbnail list - showing the title below the pic would be nice, whereas other information, such as number of clicks, name of the uploader etc. could be reserved for the detail view. I haven't checked the support forum yet if someone posted a code snippet for this, but I assume you're at least familar with that mod and could provide me with some links. Thanks in advance! :)

EDIT: Nevermind, I just found the information I was looking for in the support forum. :)

Mind the swearing in this one. :P

Lesson Four - Backporting the Package Manager

Did you know that even though a mod is technically incompatable, since you get the notice with your version of SMF that you can still install it?

Well, its true. You can fool the package manager into thinking that you have a different version.

Lets use my Gmail Field mod because I know it is not compatable with any version beyond 1.1 RC1. (I'm a lazy shit :P, it needs database converting anyway).

When you've downloaded the mod to your local machine and uploaded it via your package manager, go back to the package manager (click the link in the side bar on the left) and then add


This will make the package manager think that you're using SMF 1.1 RC1 rather than SMF 1.1.1.

But due to the Core theme being very different than the Babylon, I dont remcommend installing anything that isnt compatable with 1.1 RC2 or newer, unless you're happy to manually install anything that fails and check for bugs.

Remember that if you emulate to any version that has had a security patch released (1.1 RC2, 1.1 RC2-1, 1.1 RC3, 1.1) then you may get the notifications for them. But you can ignore those since if you're using 1.1.1 then they will already have them applied.

PS. 1.1 RC2-1 is the first patch for RC2, 1.1 RC2-2 would be the second, the reason a second patch was released for RC2, was because of TinyPortal not being RC3 compatabale on release, a one-off patch for RC2 was made for those who could not upgrade there and then, and it only closed one security hole. RC3 was still the prefered version at the time.

-----
But Dag, there were more replies to this thread, why delete them? I'm not really liking the idea that you delete my posts and dont let me know... :(

AwwLilMaggie
Gary, I didn't touch anything, please read this topic (http://www.lisa-simpson.net/topic/102.0) for details.

Ah right. Sorry 'bout that then. I guess that explains it.

Gary (or anyone else who knows a bit about SMF),

I'm trying to set up a little news box on my astronomy club website, using the SMF for writing the news, and displaying them with the SSI.php function "ssi_recentTopics". I managed to filter the output to a specific board, but when trying to format the output, I hit a roadblock. Unfortunately, my programming knowledge is next to nonexistant, so I simply don't understand how to apply the code properly.

First of all, here's the code for generating the output on my my "news page":


This works fine, and results in this: http://www.sternwarte-kreuznach.de/news.php

Now my problem is that I don't like the formatting of the list; I'd rather prefer only the topic title with the link, and maybe the date. I've been reading through the reference for the function (http://support.simplemachines.org/function_db/index.php?action=view_function;function=590), and it appears that you can control the output via the parameter "$output_method". But I simply don't know how to apply this to my code snipplet above. Could you point me into the right direction?

In the second post, you mentioned something about editing the SSI.php, but that it would be "not recommended", so I figure there is a better way by using this "output_method"?!

Yeah, setting output_method to array and then displaying the way you would like it to look below with echo statements should do the trick.

Something like


However, I havent tested it so I might need to mess with it.

Hmm, I tried this and that in order to avoid the constant error messages, but it still doesn't work.  :( At the moment, my code looks like this ( replaced the "array = ..." with "array(..." at the beginning, because that appeared to be the wrong syntax):


Well, my news page is displayed again, but there's still an error with the "foreach" line, it looks like this (http://www.sternwarte-kreuznach.de/news.php) at the moment...

Yeah, that's probably because $array is undefined now. Try

Andreas
Suusje
Yay PHP madness :D
Dunno why Gary included that "array = ..." in the beginning of his example, it invalidates the whole block. The same about assignments in the function's arguments list, they shouldn't be there. Here is a more believable fragment:

$topics = ssi_recentTopics(5, array(1, 2, 3, 4, 5, 6, 7, 9, 10), 'array');
foreach ($topics as $topic) echo '...';
Although I haven't tested it as well.

^ that should work.

but do lay it out better than that for your own personal reference to make it easier on yourself. ;)

Thanks for the help, guys! It seems to work now, I only had to format the output a bit. :)

http://www.sternwarte-kreuznach.de/news.php

Andreas
English instructions ruined! Must use German! "Registrieren"? What the hell is that?!
...sorry :D Congratulations with the first experience in PHP :)

Well, it's not my first PHP experience, because I had to mess with the integration of some mods already (such as adding a gallery link to the German navigation template), but all I can do is copying code and modifying the contents. As for writing functions etc., I'm completely lost (and I won't learn that ever :rolleyes: ).

Dagdamor
:D

Andreas
You'll learn it eventually. If you're interested in it, that is. ;)