|
PostNuke is open source and written in PHP. By definition, you have access to every line and variable in the code. The database is wide open to your changes, and you can rewrite code in part or whole at any time. But having omnipotence over your install of PostNuke is not by itself necessarily a reason to start making changes. Note The hacks you make to your PostNuke site might not survive a version upgrade. You should document your changes to be certain they are properly added to new versions. If you expect to still have a functional site when you are done, you need to approach your hacking efforts with care and purpose. People hack PostNuke for both customization and extension. It is in many ways still a young application, and no application can do everything. Feel free to make changes to your install to ensure PostNuke remains a viable site solution. But while making those changes, keep these few general hacking guidelines in mind. Have a PlanThis might seem obvious, but having some kind of plan for what you want to accomplish, outlined before you begin, is essential. Think carefully about what changes you intend. And if needed, write them out on paper to be certain you understand what the site will look like when the changes are done. Experimenting with PostNuke is certainly as valid a plan as adding a new field to a form. But you'll have an easier time learning how to customize PostNuke if you focus your explorations on just a few areas at a time, such as performing the changes needed to add a specific feature. Maintain Original SourceAfter you change a line and click Save, the original is gone. Of course, you can reproduce the original by pulling the file back out of the install archive, but that can be a lengthy process. It will save you more time and grief to simply duplicate any line you are changing, comment out the original, and alter the copy. The same standard goes for complete code replacements or deletions. Just place the double forward slashes at the head of the line as follows: // echo "<td><span class=\"pn-normal\"><input type=\"checkbox\" name=\"chng_user_ viewemail\" value=\"1\" checked=\"checked\" /> " . _ALLOWUSERS . "</span></td></tr>"; Or use the block comment code for multiple lines: /* if ($chng_user_viewemail == 1) { echo "<td><span class=\"pn-normal\"><input type=\"checkbox\" name=\"chng_user_viewemail\" value=\"1\" checked=\"checked\" /> " ._ALLOWUSERS . "</span></td></tr>"; } else { echo "<td><span class=\"pn-normal\"><input type=\"checkbox\" name=\"chng_user_viewemail\" value=\"1\" /> " . _ALLOWUSERS . "</span></td></tr>"; } */ If you find your hack has unforeseen issues, it's very handy to be able to read back through the original code. In addition, you can comment out your change and uncomment the original code to revert back at any time. If you are performing a complete file replacement, you can still rename the original file for safekeeping instead of overwriting it. Try using "filename.orig" to lessen the likelihood its PHP script will be run by accident. Change as Little as PossibleMost PostNuke hacks amount to little more than tweaking; hacking the source is done to build on the existing foundation, not reinvent the wheel. There's no need to radically alter the application when a few precise changes will do the same job. Small changes are easier to accomplish and understand, and they take less time to document and reproduce, should you upgrade and want to hack your new install in the same way. Test as You GoOne of the great benefits of working with noncompiled code is that any change can be saved and tested instantly. When you are planning your changes, consider where logical breaks in the process will let you test fewer alterations at one time. For example, look for specific changes that can be grouped, completed, and tested independently of the other changes needed for the complete hack. The smaller segments can then be tested separately for bugs and issues. Segmented testing is essential for large programming changes. You might feel you've edited every line perfectly, but if there are problems debugging even just a few dozen lines of code over multiple files it can take longer than the code edits did originally. Tip It's a little harder to test if your site is being cached, by, for example, PHP settings or a theme engine such as Xanthia or AutoTheme. You might make a change, but not see it on a refresh because your browser is receiving older cache data from your server. Try disabling all caching while you make changes to be certain you, and your visitors, will see the correct version of the site. Document ChangesDocument everything. Yes, it takes time and, in some cases, might seem a waste of time, but documenting your changes is important. You can, and should, document a hack in three ways. Inline CommentsWhen you are editing a particular line, place a comment marker with it. You should be commenting out original lines, so the comment markers will already be there to make it easy. Here's an example: // **HACK** Removing delete option for all users 04/20/04 // ."<option value=\"DeleteStory\">"._DELETESTORY."</option>" The note doesn't have to be extensive, just enough to make it clear what you did. Adding a date reference can also be very useful. Tip Using keywords like **HACK** in your documentation makes it easy to locate your changes later. Open a file and do a global search for your keyword. You instantly jump to the next hack. Offline DocumentationWrite out clear documentation of each hack. Use plain English and describe what you intended with the change(s). Cut and paste the changed code (both before and after) into your document. Include line filenames and line number references. Then save the documentation to a backup disk or print out the explanation and file the hard copy in a safe place. You should have a solid understanding of the code areas you are hacking, but will you still remember every detail a year later? Your server's hard drive might unexpectedly fail, requiring a rebuild from scratch. All of your hacks will be gone, along with all the nice inline comments. If you also document your changes separately from your server, you effectively back up the ideas and steps required to reproduce everything. It can turn a total catastrophe into simply a mild annoyance. Even if you are certain your server will never meet a dark end, it's likely that you will want to upgrade PostNuke eventually. Copying old changed files over new versions is not a safe way to rehack an upgraded site. Many files are changed with every new release, and you might overwrite essential code. You need to follow the hack's steps again and apply the idea to the new code. The documentation lets you see where to look to make a similar change in the new PostNuke, but how you need to go about creating the effect might not be the same. Apply the idea to the new site, but the hack itself might be very different. The new PostNuke release might already include new features that before were only hacks. Test the upgrade before assuming your hack is even needed. Public ReleaseOne of PostNuke's greatest strengths is its extensive community. The pool of knowledge and talent present in the main forums alone is a resource no PostNuke site developer should be without (forums.postnuke.com). You can search archives for information and ask new questions to the many experts. The more permanent way you can document your hack is by releasing it to the PostNuke community at large. Releasing the hack can be as simple as posting the information on the main PostNuke forums (forums.postnuke.com), or you can go a bit further and produce online documentation on your website and even provide personal support for the posted changes. If it was a useful change for you, perhaps other users can also benefit from the hack. And after it's in the public domain, odds are it'll still be there if you yourself need to find it at a later date. The community might also pick up the hack and expand on it further, adding and extending the changes into an even better application improvement. Truly beneficial changes to PostNuke tend to end up in new releases. If you feel your changes are good enough to be part of the application itself, post them publicly. The development team might pick it up if there is enough interest. Use Existing FunctionsPostNuke includes a large set of integrated functions that allow developers to access key information and content directly and easily. The functions make up the PostNuke Application Programming Interface (pnAPI). Use the PostNuke API whenever possible. The PostNuke API documention can be found at docs.postnuke.com, and a listing of the pnAPI functions is in Appendix E, "PostNuke API." There are benefits and disadvantages to having an API, but you can see the pros easily outweigh the cons. API benefits include the following:
API disadvantages include the following:
Tip Submit your API function suggestions to the core development team, and provide code examples if you have them. That way, your ideas might be included with future releases. Suggestions can be submitted using the Tracker forms at noc.postnuke.com/projects/postnuke/. Beware of Global ChangesWhen you are hacking PostNuke, you are changing an integrated system. Some files are referenced by many others, and a change to one file might inadvertently affect your entire site. Changes to files in the root includes folder and the PostNuke site root itself should be handled with care. Check code dependencies and function references. Be careful when making changes to be certain your local change doesn't go global. If you need to make a specific function change but only want it to apply to one module, you can duplicate the function, customize the copy, and name it with a different name. The copy can then be called with the new name while the rest of your PostNuke site continues to use the old function. Browse your site fully after a hack to see if something looks out of place. This is one good example where having those original lines commented out close by your hack, is very handy. You can comment out the hack and turn the original code live again to repair a global dilemma. It gives you time to review your hack and see if you need to approach the change in a different way. Follow PHP Coding StandardsIt's very important to follow coding standards. Not only does it make your code more easily understandable by others, but adhering to standards also helps ensure your code is compatible with future releases of PHP. You can find a number of standards guides online (http://wact.sourceforge.net/index.php/PhpCodingStandard/), but the following list includes some universal basics:
Follow Local Coding StyleIn addition to the standards outlined previously, you should stay consistent with the style of the code you are changing. Many programming style decisions are arbitrary, and programmers do develop their own personal style. Review the code you are changing. How did the programmer use quotes? What kind of comment markers already exist? What naming convention is in place? Try to maintain the style of the code for consistency and readability. Don't Hack in ProductionIt's strongly recommended that when you're making code changes to PostNuke, you do them in a development environment. It is sometimes hard to predict what a change might do, and even experts make mistakes. Make your changes and test fully before you make the change live to your visiting public. If your PostNuke site is already live and you can't take it offline for the change, set up a clone of your site locally and do the testing there. After you have your hack completed, you can copy the files up to your server to go live with the hack. |
|