Difference between revisions of "SMF1.1:Package manager"

From Online Manual

Jump to: navigation, search
m (Add format for URL)
Line 54: Line 54:
*URL - The exact URL of the desired modification package.
*URL - The exact URL of the desired modification package.
*Name of the file - Required if the download URL does not include the file name of the package. If left blank, the base name of the file from the URL will be used. For example, the default name of the file for a package mod_name.zip would be mod_name.
*Name of the file - Required if the download URL does not include the file name of the package. If left blank, the base name of the file from the URL will be used. For example, the default name of the file for a package mod_name.zip would be mod_name.
''For example the URL format will be: http://custom.simplemachines.org/mods/index.php?action=download;mod=1519;id=179488''

Revision as of 08:31, 19 June 2012

The package manager is a default feature of SMF that allows you to install packages for your forum. Packages consist of customizations and updates to your forum. Customizations can be a number of things: a new feature, a theme, avatar set, smiley set, a feature enhancement, or anything you can think of and program for SMF to do. Before we go any further, it cannot be emphasised enough, here, that you REALLY, REALLY should backup your forum, before installing any packages (mods). It is VERY important that you back up both your forum AND the database. Detailed information on backing-up can be found here: Backup

Browse Packages

In the Browse Packages section of the package manager, you will see all of the packages that are currently downloaded on to your forum. You can install/uninstall them, view details of a package, and delete packages. Applying the package to your forum is as easy as clicking 'Proceed' next to the package you want to install, most of the time. However, you may be asked to fill in FTP information whenever the files needed are not writable.

Latest Packages / Package of the Moment

Located at the top of the 'Browse Packages' section is a box that includes the 'Latest Packages' that have been added to the SMF Customizations Site. Clicking on the name of any of the packages will expand information about the package taken from the mod's download/description page from the mod site.

You can select 'Install Now!' underneath the name of the mod after it is expanded and then the package will be downloaded to your forum and the install screen will appear showing what files could be edited successfully, and which ones (if any) couldn't be. To go back to the list of the latest packages, you can select (go back), located at the bottom of the information about the mod.

These packages are grabbed from a javascript file on the SMF server which is automatically updated with the latest mods that have been added to the mod site.

At the bottom of the 'Latest Packages' box is the 'Package of the Moment', which is taken by selecting a random mod package from the SMF mod site. The package listed here works the same way as the latest packages above it do and will expand and allow you to install it.

Browse Packages

Underneath the Latest Packages box you will see the listing of all the mod packages you have downloaded on your forum. There are three options listed next each mod that you can use for each mod:

  • Apply Mod or Uninstall
  • List Files
  • Delete

When installing a package, you must select Apply Mod next to the package you want to install. If you see failure instead of success on the pre-install, this means that there is an issue with the editing a file the package is suppose to edit or the package does not work with your version of SMF. You might want to contact the developer of the package for more information. If there are test failures, it generally not advised to proceed with the installation until you are prepared to manually install the mod.

When uninstalling a package, you must click Uninstall next to the package you want to uninstall. If you get any failure notices for any files, that means the mod can not be uninstalled completely. If there are test failures, it is generally advised to proceed only when you are prepared to manually uninstall the mod.


At the bottom of the Browse packages section is a link located on the right side of the page. Clicking this will add an additional box to the page which allows you to emulate your version of SMF to another version temporarily. Just type exactly the version you want to emulate in the input box next to Emulate Version. This is useful if a mod is set to only install for specific versions of SMF, however the mod may still work on your version. To revert the text entered in the input to your version of SMF, click the Revert link.

For more information on using this feature, please see How can install a mod that doesn't work in my SMF version

Download Packages

The download packages section of the package manager provides tools for loading and installing a package and for using the package server browser. To download a package is to obtain it from some place it is stored. In some cases, the package may be downloaded directly to your forum. In other cases, it must be first downloaded to your desktop, then uploaded from your desktop to your forum. Download packages is accessed by selecting the download packages tab from the package manager. Required FTP settings are found in the installation options section.

Package servers

An SMF package server is a repository stocked with modification packages for SMF forums.

The package servers browse feature can be used:

  • to obtain packages from a local SMF package server, if one is located on the forum host
  • or to obtain packages from a remote SMF package server (such as the Simple Machines Third-party Mod Site), if the forum host permits downloading SMF packages directly from a remote SMF package server

Selecting the browse button next to a server in the package servers list allows viewing of the packages available on that package server. If this feature does not work, upload a package may be used instead to upload a package that has already been manually downloaded to the desktop. The delete button is used to remove a package server listing.

Add server

To add a package server to the list to the list, the administrator may type in a server name (e.g. Simple Machines Third-party Mod Site) and a URL (e.g. http://custom.simplemachines.org/mods/), then select the add server button

Download a package by URL

Download a package by URL is a quick way to download a package from the web to a forum.

  • URL - The exact URL of the desired modification package.
  • Name of the file - Required if the download URL does not include the file name of the package. If left blank, the base name of the file from the URL will be used. For example, the default name of the file for a package mod_name.zip would be mod_name.

For example the URL format will be: http://custom.simplemachines.org/mods/index.php?action=download;mod=1519;id=179488

Upload a Package

Upload a Package is used to upload a package from the desktop to the forum. The browse button is used to locate the package file, and the upload button is used to upload it to the forum. After an upload, the administrator is given the option to immediately apply the package, or to use browse packages to install it at a later time.

If you prefer, you may upload the package, or a directory full of package files, to your "Packages" directory, using FTP. For more information about Uploading packages using FTP, see Packages - How to upload packages using FTP.

Installing a Package

Once you have uploaded a package, you can install it -- either immediately, or later, from the Browse Packages list.

Under the heading Install Mod, you'll see the warning Please remember to always make regular backups of your sources and database before installing mods, especially beta versions. Heeding this advice can save you from trouble later.

Below this, the Installation Readme will display any readme text supplied by the mod's author.

Under the heading of Installations actions, you will see a list of all the actions the package manager will take to install this mod. You will see actions of the following types.

  • Execute Modification Changes made to existing files. Select the selected icon to reveal a list of exactly what is being done to this file, complete with a Package ops icon to show the search and/or replace strings used in this operation.
  • Extract file A file will be copied from the package, to the given path and file name.
  • Extract Tree An entire directory full of files will be copied from the package, to the given path
  • Adapt Database The named script from the package will be executed. Generally, this script will get the database ready for the mod to run.

Modification packages often make changes to the default theme. These will be listed under Installation actions. Often, it is possible for the package to make changes to all of your themes. These changes are optional, and won't be done unless you check the box next to the modification's name.

As the Package Manager prepares this list, it has made a backup of php files for the forum (please see the FAQ on using package backups for more on this file). At the same time, it tests each action it is preparing to take on your forum, and reports the results in the list. The Package manager will report whether the installation test was successful or failed. If the test failed, it is recommended that you resolve the problem before proceeding with the installation. Checking-out the parser, on the mod's download page, will tell you what edits are made, to which files. If you can match-up the file edited, there, with the edit that's failing, you can often make the failed edit, yourself, manually. If you do that, we have to stress, again, the importance of backing-up, before you do this. You can read more about installing mods by hand.

Installation will begin when you select the Install Now button at the bottom of the page. After a successful installation, the Package Manager may redirect you to the new mod's configuration page, or return you to the Package Manager.

Installed Packages

This page allows you to view your installed mods, the files included in each mod, and gives you the ability to uninstall any mods that you no longer want at the moment. It is similar to the Browse Packages section.

Note that the list of mods shown on this section are taken directly from the Packages/installed.list file of your forum. When mods are added or removed, the file is updated and thus the list on this page will also be updated.

You can select the Delete Mod List button at the bottom of the page to clear the list of mods you have installed, but this is generally not recommended.

File Permissions

You can use this section to review the writable status of critical files and folders within your forum directory. Note this only considers key forum folders and files - use an FTP client for additional options.

Please Note:

  1. Be careful when changing file permissions from this section - incorrect permissions can adversely affect the operation of your forum!
  2. On some server configurations selecting the wrong permissions may stop SMF from operating.
  3. Certain directories such as attachments need to be writable to use that functionality.
  4. This functionality is mainly applicable on non-Windows based servers - it will not work as expected on Windows in regards to permission flags.
  5. Before proceeding make sure you have an FTP client installed in case you do make an error and need to FTP into the server to remedy it.
  6. If you make changes to your file permissions and they don't seem to be having the effect that you expected, you'll need to contact your host, asking them if you have FULL OWNERSHIP of all of the files on your site. Don't worry, if you don't know what that means, exactly, because your host certainly will.

Change File Permissions

Apply individual file permissions settings selected above:

If "Custom" has been selected use chmod value of: You can manually set the permissions you wish to set the selected files to. To do this enter the chmod value as a numeric (octet) value. Note - these flags will have no effect on Microsoft Windows operating systems.

Use predefined permission profile: this only applies the predefined profile to key SMF folders and files.


The installation Options section of the package manager, accessed via package manager's options tab, is for information that is sometimes required during installation. Some package installations may require FTP login information or changes to file permissions.

  • Installation Options
  • Cleanup Permissions
  • FTP Information Required

Installation Options

Settings for FTP Server, Username and Port are used by SMF to make an FTP connection in order to complete certain package installations. The Create Backup versions of replaced files with a tilda[sic] (~) on the end of their names checkbox instructs SMF to save a backup version of any file that is changed or replaced during installation.

Cleanup Permissions

Because it is generally more secure to keep as few files writeable as possible, and because some package installations involve more files than others, this section provides a quick way to change file permissions in the smf directories. In order of increasing permission and decreasing security, the options under this heading are: The minimum files are writable[sic]; All files are writable[sic]; and Only the standard files are writable[sic]. Choosing one of these options and then selecting the Change file permissions button below makes the change.

FTP Information Required

After the change file permissions button is selected, SMF will display a new page prompting for additional FTP information.

  • FTP Server - The internet address of the forum ftp server (e.g. ftp.forumname.org)
  • Port - FTP port, supplied by the site host if other than 21
  • Username - The FTP username used to login to the FTP server.
  • Password - The password for the FTP username given above.
  • Local path to SMF - FTP Path to the SMF root. This may differ from the SMF path given in the core configuration section of server settings.

The What is the local path to SMF? FAQ has more information.

Following selection of the Proceed button, SMF should make the requested file permission changes at the Local path to SMF and return to the Installation Options section. If this does not happen: 1) If the FTP Server does not exist, the page will be refreshed -- no error message will be displayed; 2) If the FTP Server exists, but FTP login fails (incorrect username/password), a browser Error 500 message will be displayed; 3) If FTP login is successful, but the local path to SMF does not exist, a small FTP error message will be displayed.