SMF2.1:Package manager: Difference between revisions

Work in progress, expect frequent changes.

Please see SMF1.1:Package manager, SMF2.0:Package manager or SMF2.1: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 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 or program SMF to do. Note, however, that theme installations 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 a numbered list of all the packages which are currently loaded into your forum. If you have not loaded anything yet, there will not be a list. Once you load something, by following the instructions in the Add Packages section below, you will see three buttons beside each package:

Install Mod or Uninstall Mod
List Files
Delete

If you see the Install Mod button, that means the package is not installed. If you see the Uninstall button, that means the package is installed. The List Files button shows you all the files in the package. The Delete button deletes the files or package, but it does not uninstall the package; and it might prevent it from being uninstalled in the future.

Note that there are different kinds of packages. Most will be listed under Modification Packages, but some will create other lists. So you may see separate lists under the Modification Packages list, such as Avatar Packages.

After you have loaded one or more packages, you can click the Install Mod button, to start the installation process. If you are installing a package now, jump down the page to the Installing a Package section. If you are uninstalling, click the Uninstall button, and jump down to the Uninstalling a Package section.

Emulation Support

(this section still needs to be updated) 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

Add Packages

(this whole section still needs to be updated) The Add Packages page 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. After you click the Install Mod button, a new page will open.

On that page, 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 package's author.

Under the heading, Installations actions, you will see a list of all the actions the Package Manager will take to install this mod. In the column Types, you will see the following kinds of actions:

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. This script will get the database ready for the package.
Execute Code - The named script from the package will be executed. Generally, this script will run additional code needed, could be queries, hooks or other functions.
Add Hook - The named hook will include the called function from the package in the database value.
Add Credits - The package will insert an additional line in the credits page.

Packages often only affect the default theme. These changes will be listed under Installation actions. Often, it is possible for the package to make changes to all of your themes, but they are optional; they won't be done unless you check the box(es) under each theme.

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 information). 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. So if you see any red text in this list, indicating a test failure, please see this file to learn what to do, before proceding with installation: test failures

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

File Permissions

(this section still needs to be updated) 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

(this section still needs to be updated) 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

@@ Line 71: / Line 71: @@
 *'''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 package to run.
+*'''Adapt Database''' - The named script from the package will be executed. This script will get the database ready for the package.
-*'''Execute Code''' -
+*'''Execute Code''' - The named script from the package will be executed. Generally, this script will run additional code needed, could be queries, hooks or other functions.
-*'''Add Hook''' -
+*'''Add Hook''' - The named hook will include the called function from the package in the database value.
-*'''Add Credits''' -
+*'''Add Credits''' - The package will insert an additional line in the credits page.
 Packages often only affect the default theme. These changes will be listed under ''Installation actions''. Often, it is possible for the package to make changes to all of your themes, but they are optional; they won't be done unless you check the box(es) under each theme.

Navigation

Search

Tools