Rules to Follow


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 Plan

This 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 Source

After 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 Possible

Most 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 Go

One 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 Changes

Document 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 Comments

When 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 Documentation

Write 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 Release

One 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 Functions

PostNuke 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:

  • Speed Any function you don't have to write means your development takes less time. In addition, you don't need to learn the internals of the core system.

  • Code consistency Coding consistent with the global standards has increased readability and is easier to comprehend. Anyone familiar with the API will be able to follow the code.

  • Lifespan extension PostNuke evolves with each release. Features of the core system change and will eventually render a non-APIcompliant hack useless. But the PostNuke API frontend seldom changes, so a hack developed to work with the API will most likely continue to work with future versions.

  • Modular development The programming interface separates the main PostNuke system from the modules that run on top of it. Module and core developers can both work independently on upgrades without affecting one another.

  • Stability It's impossible to make usable hacks on a moving target. The core system needs to change to grow, but the API gives you a foundation you can rely on.

API disadvantages include the following:

  • Learning curve You need to understand the API functions in order to know how and when to use them.

  • System overhead All APIs add a level of overhead to their systems.

  • Missing functions The API can't account for every possible need anyone might have.

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 Changes

When 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 Standards

It'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:

  • Use full start and end tags There are a number of ways to open and close a segment of PHP code, including support for other languages and shorthand styles. Technically, the most appropriate way is like this:

     <?php ?> 

  • Indent lines with four spaces Tabs are a problem for some editors. Using four spaces for each indent level makes your code format well in all circumstances.

  • Use spaces around operators Assignment, comparison, logical, and arithmetic characters should always be displayed with surrounding spaces, as in the following examples:

     $var1 = 'widget'; if ($var2 > 5) { 

  • Use spaces around control structures The curly brackets used to define structures should always be separated from surrounding code by a space:

     <?php if ($x != $y) {     action1; } else {     action2; } ?> 

  • Use naming conventions There's been a great deal of argument in different circles on what are the best naming conventions. The golden rule is to at least have some standard that's consistent with all other developers with whom you are working. Names with an initial lowercase word and capitalized words thereafter are suggested, such as getWidget(), $intData, and $widget.

  • Use conventional C style comments Always use the // and /* */ comment standards. Avoid use of shell comments such as #.

Follow Local Coding Style

In 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 Production

It'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.



    PostNuke Content Management
    PostNuke Content Management
    ISBN: 0672326868
    EAN: 2147483647
    Year: 2003
    Pages: 207
    Authors: Kevin Hatch

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net