SMF2.1:Package manager: Difference between revisions

Please see SMF1.1:Package manager or SMF2.0:Package manager depending on the version of SMF you are using.

The Package Manager is a default feature of SMF that allows you to install packages (modifications) for your forum. Packages can be customizations or 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. Note, however, that theme installs are not handled by the Package Manager (please see Themes and Layout for information about how to install and manage themes).

Before using the Package Manager, please take note of the following:

Backup first! - The package manager is a powerful tool and although it includes safeguards, lack of caution can lead to errors that might break your forum. For this reason, always make a backup of your forum and the database before you attempt to install any packages. For more information please see 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 Install Mod next to the package you want to install. However, you may be asked to fill in FTP information if any of the required files are not writeable.

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 on the SMF 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 which files could be edited successfully, and which ones (if any) could not 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 chosen by selecting a random mod package from the SMF mod site. The package listed here works in the same way as the latest packages above it, and will expand, allowing you to install it.

Browse Packages

Underneath the Latest Packages box you will see the list of all the mod packages you have downloaded on to your forum. There are three options listed next to each mod:

Install Mod or Uninstall
List Files
Delete

When installing a package, you must select Install 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 a file that 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 further information. If there are test failures, it is generally not advised to proceed with the installation unless you are prepared to patch the part which has failed.

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 cannot be uninstalled completely. If there are test failures, uninstalling the mod is not recommended.

Advanced

At the bottom of the Browse packages section there is a link located on the right-hand 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 and click Apply. This is useful if a mod is set to only install for specific versions of SMF but you are certain the mod will still work with your version. Afterwards, use the Revert link to stop emulating another SMF version.

For more information on using this feature, please see How can I 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. 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 server's browse feature can be used in either of the following ways:

To obtain packages from a local SMF package server, if one is located on the forum host.
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 the viewing of the packages available on that package server. If this feature does not work, uploading a package may be used instead, in order 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, 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/packages/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 will 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 icon to reveal a list of exactly what is being done to this file, complete with an 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 a success or a failure. If the test failed, it is recommended that you resolve the problem before proceeding with the installation.

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.

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 writeable status of critical files and directories within your forum directory. Note this only considers key forum directories and files - use an FTP client for additional options.

Please Note:

Be careful when changing file permissions from this section - incorrect permissions can adversely affect the operation of your forum!
On some server configurations, selecting the wrong permissions may stop SMF from operating.
Certain directories such as Attachments need to be writeable to use that functionality.
This functionality is mainly applicable on non-Windows based servers - it will not work as expected on Windows with respect to permission flags.
Before proceeding make sure you have an FTP client installed in case you do make an error and you need to FTP into the server to remedy it.
If you make changes to your file permissions and they do not seem to be having the effect that you expected, you will need to contact your host, asking them if you have full ownership of all of the files on your site. Do not worry, if you do not 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 directories and files.

Options

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 tilde (~) on the end of their names checkbox instructs SMF to save a backup version of any file that is changed or replaced during installation.

As an administrator

Main

Configuration

Forum

Members

Maintenance

Miscellaneous

Navigation

Search

Tools