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).

Please do not use images found online, which may not have a license that allows you to use and redistribute them. Just because they can be found in a search, it doesn't mean they can be freely used. An exception to this is content from the entertainment industry such as TV, Movies, Books and Video Games. For those you must include a Disclaimer in the package description and its "Readme". Here's an example:

Disclaimer: The images included in this package are intellectual property from [insert copyright holder here]. The author and simplemachines.org are not affiliated with [insert copyright holder here]. Any and all content on this package is not authorized by [insert copyright holder here]

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 modify significant parts of SMF with major or new features that affect every page MAY add the copyright to the footer section; for example, a Portal mod adds blocks to every page, or a media mod adds functionality to every page for viewing would be considered acceptable to add a footer copyright. It should be noted, however that we encourage mod authors to place their copyright on the Credits page instead of the footer. Finally, themes which alter the appearance of every page viewed may have a custom copyright in the footer.
  • Mods that add new pages to the forum MAY add the copyright into the footer section, to be displayed ONLY when the new page is loaded; for example, a staff page or FAQ section mod could display the custom copyright in the footer when the page or section is loaded (but not on other forum pages.)
• Placing your copyright and/or links into the Credits page.
  • Major or significant mods, as mentioned above, are encouraged to add their copyright statement to the Credits page.
  • Medium sized mods that modify sections of the forum, add or alter moderate functionality or alter "a reasonable part of a forum page" may add their copyright or links to the Credits page.
  • Small Mods that only modify the forum to add small features may add their copyright or links to the Credits page; BBC mods, or mods that only affect a small part of a page are considered part of this group
• 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 mod or theme copyright. In other words, if the link is not related to the mod or mod support, it is not allowed. We expect any link in the mod or theme copyright to link back to a site supporting the mod or theme

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.
• The Customization Team will approve external libraries for use on a case-by-case basis. External libraries not approved for use will result in the mod or theme being rejected, and the author asked to find a more suitable source, or remove/include the library in the mod/theme.
• We recommend that a warning be included with any mod/theme that includes an external library informing users that tracking/logging of activity can occur.

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 SMF 2.* source code. If we see, in your customization, the opportunity to use a hook, we will request you make the change. Please check this page for a list of available hooks

Customization License

It is required that any customization submitted to the customization site include a license, which should be mentioned in both your description and "Readme" file. A mention to your chosen license must also be added to the header of any PHP file your customization adds. We have a friendly guide to help you choose a suitable license, which can be found here Depending on the license you choose, it might also be required to provide it with the package, eg, in a "LICENSE.txt" file

Size and utility of the customization

While the Customization Team allows the so-called "small mods", including one-line-edits, it is also necessary to establish a minimum functionality limit for the customizations. If we don't, our modsite could easily become filled with useless MODs that would make the really good ones hard to find. This limit cannot be directly stated due to vast range of small things that are able to be changed, so it will be evaluated case-by-case by the team.

If a MODification is rejected for this reason, you can post it in Tips and Tricks board

Customization description

All customizations should have a proper description. This makes the "product" look better and gives out a better impression of the modsite. The description should include:

• Customization name, stand out
• Description of the MOD functionality, as detailed as possible
• Sample images where applicable
• License 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.