These customization guidelines are here to let customizers, the community, and the customization team know what we are looking for in any customization submitted for approval at SimpleMachines.org. We hope this guide will make the customization approval process easier on everybody. We hope that letting authors know from the outset what to expect will save the the extra work of changing things during the approval process. Many of these rules make it easier for the customization team to examine and test customizations, which speeds up the rate at which submitted customizations can be evaluated. Thank you for following these guidelines as you develop your customization.

No Hardcoded Text

"Hardcoded text" means any literal text strings intended for display to members. Hardcoded Text makes translation to different languages very difficult. Instead, please use language strings (the $txt[] array) defined in language files. This rule applies even if you provide your customization only in one language. You may choose to use Modifications.english.php, or to add other language files to your install file using the error="skip" attribute.

Theme authors can use a special file called ThemeStrings.english.php to store any extra language strings the theme may require. If you use the ThemeStrings file, you must include English, and you may include other languages.This topic on the community forums explains how to use the ThemeStrings file.

No Unauthorized Use Of Creative Works

Unauthorized use of other people's copyrighted code or graphics is strictly forbidden. Before using copyrighted material, you must first obtain authorization from the copyright holders. If we are unsure, we will ask you to provide proof of copyright authorization. Failure to provide proof of permission will result in non-approval of the customization, and can cause a previously-approved mod to be removed from SimpleMachines.org.

Any customizations (including avatar and smiley packs) submitted to the customization site that contain artwork or graphics must provide the source of the items so we can verify you have permission to use them. If you have obtained permission from the author of said artwork, please state that somewhere in your package (the README is preferable, but in the mod's description, or in the code or comments of the mod works as well). If permission is not necessary to use the artwork (perhaps by the artwork's license), a link to the source of the artwork will still be required so we can verify. If you have made the artwork yourself and claim the copyright, please include a line in the package that you claim the copyright (Artwork © 2010 SlammedDime or similar).

Proper Package Formatting

For mods, avatars and smiley packs, package-info.xml must be in the root of the archive. Depending on which file format you decide to use for your modification installation instructions, it should be in the proper format for that file. For example, when using the XML format, CDATA tags are required on <search /> and <add /> strings. The proper information should be in the files as well, including version information, author and package id. Packages should not be double archived or double foldered.

For themes, theme_info.xml must be in the root of the archive. The information displayed in this file is important - particularly the id, package id, name, and contact information. There are two different versions of this file; one for 1.1, and one for 2.0. You can find examples of these files in the 'classic' and 'babylon' theme of SMF 1.1 and the 'core' theme of SMF 2.0.

Separation of Computation and Display

All queries and "work" should be done in the Source files, not the files that display the information. You can put your data into $context as needed and then display it in the template files. There are several important benefits to this type of separation. Two of the most important are:

1. Data sanitization. If data is read and processed in a template file, there is a danger that already-sanitized data will be over-written by new data, since the template files are loaded just before output. Having all data processing handled in one place makes this type of accident much less likely.
2. Portability. With all the processing happening in source files, it is an easy matter to add a line to any theme to display your data. This will make it easier for you or anyone else to use your customization with their favorite theme.

Data Sanitation

If your customization accepts data from the user, either by form or by URL, it may not be used in a SQL query until it is checked for existance and type. You should use the appropriate PHP functions to test for variables for proper type or explicitly cast them when they are used. For example, when searching the database by member id which is passed in via the URL GET variable of 'id', you should perform (int) $_GET['id'] or (int) $_REQUEST['id'] before using that variable in the query.

Installation / Uninstallation

Your customization should install without any errors on an unmodified copy of SMF, except if it depends explicitly on another customization. In that case, the readme file should state clearly that it depends on, or extends another customization. Your customization must uninstall without ever leaving a trace that the customization was installed (aside from the ~ backup files). Information/Data can be kept in the database, but should be uninstalled if it would create errors after the customization was uninstalled.

Mods With Theme Changes

Any mods that require changes to themes must successfully install into, and work properly with, the SMF 'Default' theme, (for SMF 1.1, Core; for SMF 2.0, Curve). You may include changes to other themes as well, however you must use the 'error="skip"' directive for each file you are modifying in another theme. Keep in mind that 2.0 can install mods on other themes as long as the same block of code you are searching exists in the other themes.

W3C Validation

Template files must be valid to the HTML or XHTML standard used by the theme to which it is installed. Most SMF themes use XHTML, but HTML is also permitted in themes. Remember to check for W3C validation for users as well as for guests. To test as a logged-in member, you may copy the HTML source code from the appropriate page into the Direct Input box on the W3C Validator or use the Web Developer Toolbar for FireFox.

Your customization must also use valid CSS. Examples of invalid CSS include leaving the # off of a color declaration or not including a measurement type on sizes (px, em, ex, etc...). We are aware that sometimes CSS 'hacks' are needed to make things appear right in a cross-browser situation; these 'hacks' will be acceptable.

An exception will be allowed for those who use CSS3 which does not validate.

Excessive Files

Customization packages should not contain files that they do not use. This would include extra images or template files that are not modified from the default, Thumbs.db files (common for files zipped together on Windows computers), or PSD's of images. Source images for customizations may be attached as an extra file on the customization's summary page.

Theme Settings

If your customization adds or removes theme settings, modify or include a replacement of Settings.template.php. More information can be found in the community.

Default Theme variations or clones

With the recent addition of the SMF Theme color editor, default curve color variations or clones will no longer be accepted to the theme site. If you have any question if your theme would fall under this category, please contact someone on the customize team for clarification.

Customization Descriptions

All descriptions must contain an English description of the customization. If you include descriptions in any other languages, you must put them after the English description. The description should fully explain the functionality or changes it makes. The content of the description must be directly related to explaining, demonstrating, or supporting the customization. No unrelated material (for example: ads or 'sponsor' links) is permitted.

It Must Work

This is the most important guideline. Your customization should work as described. All added features should work as expected and your customization should not throw any unwarranted errors in the error log. We understand that your customization will likely have bugs that users will find through use; however, when we test it, it should install properly, be usable without throwing errors in the error log, and uninstall properly and leave behind nothing but data in the database.

Adherance to SMF requirements and standards

Keep in mind the requirements for SMF itself when making your customizations and ensure you will not alienate users on lower versions of required server software. Mods are not required to support all databases that SMF supports, however you are required to use SMF's database functions when querying the SMF's database. If customizations do not support the minimum PHP version that SMF supports, a notice must be put in the mod description and readme.

Clean Code

This is not required for approval, but heavily suggested. You should try to keep your code easily readable and use meaningful variable names. Easily readable code will be indented properly using tabs (not spaces) and will follow the existing flow of the code you are modifying. You should use the LF style of line ending (Unix style); most quality text editors have this option. If we do find large performance blocks, we will deny the mod approval until they are fixed.

Required - Your code should not introduce a performance block into the normal flow of code (ie: do not create race conditions or endless loops).

Copyright and Credit

• Placing your copyright and/or links into the footer with SMF's copyright.
  • Mods that add their copyright to every page must be mods that modify significant parts of SMF. For example a Portal mod adds blocks to every page, or a media mod adds functionality to every page for viewing. Themes alter the appearance of every page viewed.
• Placing your copyright and/or links into the credits page.
  • Small Mods that only modify SMF to add small features will not be allowed to add their copyright or links to the SMF footer or the credits page. For example BBC mods, or mods that only affect a very small part of a page. Medium sized mods that modify a reasonable part of the page can add their copyright or links to the credits page.
• We realize this will be subjective on our part. And that some mods will fall between these categories. Copyrights will be reviewed on a case by case basis when necessary.
• Unrelated links such as ads, links to other websites or sponsors, are not allowed to be placed place in the copyright. In other words, if the link is not related to the mod or mod support, it is not allowed.

External Libraries

• Linking to an external library from your personal site is not allowed. If a mod or theme is found to be linking to untrusted/unapproved sites you will be asked to change the link, or include the dependency in your mod or theme.
• Allowed External links for libraries must link to stable releases. Linking to a repository version, or a beta version will not be allowed.
• List of Approved sites: (will be added as needed)
  • googleapis.com
  • jquery.com

Duplicate Mods

Duplicates are allowed with the following stipulations. - Your duplicate mod needs to add some features that the other mod does not have, or at a minimum coded in such a way that it is significantly better. You may not use another author's code in your mod without permission, or in violation of copyright rules

Using hooks in SMF2

Use of hook functions is highly recommended, as the hooks reduce the need for directly modifying SMF2 source code. If we see, in your customization, the opportunity to use a hook, we will request you make the change.

Customization License

It is required that any customization submitted to the customization site include a license. You must supply a name and a link to the license you have chosen in the mod description upon submission. You must also include your license statement in the top of the files for your mod if you have created any source or template files. See this post for additional information

Extra Notes

• Do not submit your customization to the site more than once with different package id's hoping to get it approved faster
• You may update your customization while/before it is approved without it being pushed to the end of the queue
• A topic will automatically be created for your customization in the appropriate board - Modifications and Packages or Theme Site Themes.
• Unless there is a request by the author or a security issue reported in the customization, customizations are only reviewed on their initial submission
• No customizations will be approved relating to adult material, illegal activities, or breach of privacy.