Bad Boy Blog, an unofficial Diddy and Bad Boy fan blog

Bookmark and Share

Using the phpBBHacks.com Hack Template

Using the phpBBHacks.com Hack Template

Postby Thoul » April 6th 2004, 5:53 pm

This tutorial is a guide to using the phpBBHacks.com Hack Template to write a user-friendly hack. As most hack authors and users are aware, it is good to have clear, precise instructions and informational points when installing a hack. There are many ways to provide these, and the Hack Template is one out of several.

It's important to note that use of this template is not required for a hack to be added to the phpBBHacks.com Hack Database. Hacks do not get rejected at this site for not using the template, using only part of it, or using a modified form. If you just write out your hack's instructions as a series of plain sentences, your hack still won't be rejected as long as it's easy to understand. Using this or any template is purely optional.

The full hack template is available in another topic, so let's begin by looking at sections of the header. There are several places in the following discussion where words are surrounded by lesser and greater than brackets (< and >). These words, including the brackets, should be replaced with the information that will be described.

Code: Select all
##	Hack Title:	<Title>
##	Hack Version:	<Version>
##	Author:		<Your Name>
##	Description:	<Description>
##	Compatibility:	<phpBB Versions>


The above lines provide some quick introductory information about your hack. Areas you should modify are:
  • <Title> - Place the name of your hack here.
  • <Version> - This is the version number of your hack. First releases are typically number 1.0.0 or something similar. The numbering system you use is at your discretion.
  • <Your Name> - Add a name or nickname to which you want the hack credited. Some people use both a name and nickname. If you wish to specify an e-mail address, you should do that here, also.
  • <Description> - A brief description of your hack's purpose.
  • <phpBB Versions> - The phpBB releases your hack has been tested on, such as 2.0.7 or 2.0.8. Multiple versions are typically indicated with a dash between them. For example, "2.0.1 - 2.0.4" would be the same as writing out "2.0.1, 2.0.2, 2.0.3, and 2.0.4."

Code: Select all
##	Installation Level: <Easy/Moderate/Difficult>
##	Installation Time: <Time>
##	Files To Edit: <Number>
##		<filename>
##		<filename>
##
##	Included Files: <Number>
##		<filename>
##		<filename>


This block details basic installation information.
  • <Easy/Moderate/Difficult> - Choose one of these three options (Easy, Moderate, or Difficult) to indicate how hard the hack is to install.
  • <Time> - The approximate number of minutes or hours it might take to install the hack manually. This should not consider using installers like EasyMod. Be sure to include the unit of time, such as "3 minutes" or "2 hours."
  • <Number> - In the "Files to Edit" section, this is the number of files that must be edited to install the hack. In the "Includes Files" section, its the number of files packaged with your hack.
  • <filename> - List the names of the files, in alphabetical order, that needed to be edited or are included in the appropriate section. Include the path to the files from the phpBB root path in the name, such as "templates/subSilver/index_body.tpl" instead of just "index_body.tpl." Some authors list files in directories before those that are not. An example of this is shown in the full template.

Code: Select all
##	History:
##		<None>
##		<Version #>: 	<Details>
##		<Version #>: 	<Details>
##
##	Author Notes:
##		<Text/None>


This are some optional areas that you may or may not need for your hack.
  • <None> - If the hack has no history (it's the first release, for example), use "None" here. Otherwise, just delete this line.
  • <Version #> - A version number for your hack, such as 1.0.0, 1.1.0, and so forth.
  • <Details> - A description of what was changed in each version of the hack.
  • <Text/None> - If you want to include some additional instructions, description, or other notes, this is a good place to add them. Otherwise, you can type "None" here or leave the area out.

Code: Select all
##	Copyright:		©2003 <Title> <Version> - <Your Name>


Include some copyright information about your hack, so that you can claim it as your own later. <Title>, <Version>, and <Your Name> here are the same as those mentioned earlier.

Code: Select all
###############################################
##	This hack is released under the GPL License.
##	Intellectual Property is retained by the hack author(s) listed above.
###############################################


This section of the template states that the hack is released under the same GPL License as phpBB itself. A copy of this license comes with phpBB if you need to see it. The copy can be found in the docs/Copying file. The terms of this license require that any derivative works based on a GPL Licensed product must themselves be GPL Licensed. This means that any hack containing code from phpBB 2 must be GPL Licensed. If your hack does not contain code from phpBB 2, you can release it under any license you like; remember to change this section of the template if you do use a different license.


The remainder of the Hack Template is for describing the actual changes that should be made to install your hack. Each instruction should be preceded by an action block, which looks similar to this:
Code: Select all
#
#-----[ ACTION ]------------------------------------------
#


The word "ACTION" will be replaced by the actual function that should be preformed. Thse functions include COPY; OPEN; FIND; REPLACE WITH; AFTER, ADD; BEFORE, ADD; IN-LINE FIND; IN-LINE AFTER, ADD; IN-LINE BEFORE, ADD; IN-LINE REPLACE WITH;; and SQL. You may see other functions as well. For a discussion of how users are expected to perform these functions, read the Installing phpBB Hacks tutorial.

There is one final action block that is a little different. The SAVE action indicates that the hack's instructions are finished, so it should be at the end of the template file.
Code: Select all
#
#-----[ SAVE & CLOSE ALL FILES ]--------------------------
#
#End
User avatar
Thoul
Admin/Webmaster
 
Posts: 18551
Joined: July 30th 2002, 11:30 am
Location: USA

Return to phpBB 2: Hack and Template Authoring

Who is online

Users browsing this forum: No registered users and 1 guest