This site first went online in early June 2006. The main idea behind it at the time was to use it as place to consolidate some useful information to help new users of the sNews CMS. At that time it was sNews 1.4. The project has since gone through many changes and is currently at version 1.7, currently available as 1.7RC2. You can download versions 1.3 to the latest refresh of 1.6 on the Official Downloads Page at snewscms.com.
This tutorial is provided in detail to assist users who are relatively new to working with PHP.
You should have a good code editor such as PHP Designer 2006 to edit your code files in.
Preferrably, you will have the Apache Server environment installed and running on your computer,
... and your sNews site is installed in the htdocs folder and functioning properly.
Modules for sNews 1.4
If you are looking for a way to display static content in your sNews site using a module system that functions independently of the site's MySQL database, then this Custom Modules add-on should do the trick. By static content, I mean content that will remain the same without the need for editing... for a very long time. As one example, the Installs, Mods, Addons and Resources sections of this website... including the page you are now reading... are contained and displayed using this Custom Modules add-on.
Let's go over a few points to give you an idea of how flexible this module system is. All modules go in a Modules folder in the site's root directory. Any number of modules can be added to the Modules folder. All content in any module is created and saved to the module folder as either plain text (.txt) or basic html files. Content files are served by a small PHP (engine) file within the module. Page display is integrated to work seamlessly within the site's existing template (index.php) file. You can add as many pages to a module as you wish, and use the module's 'home' page as the directory page. If your site's database malfunctions, all module contents remain intact since they are not stored in the database. Modifications are minor and easily added to your snews.php or/and your index.php file.
This tutorial will cover installation, set-up and operation of the Custom Modules add-on, as well as how to customize a module and create Search Engine Friendly URLs to the pages within a module. Now... let's move on to installing our modules.
Installing the Modules
Step 1 - Download the ready-made modules.zip package to a new folder called modules in the downloads storage location on your hard drive. Un-zip it into the same folder.
Step 2 - Browse through the modules folder in the un-zipped location to get a feel for what it contains. There are four complete module folders, and each folder contains a .php (engine) file and 6 plain text files. Once you are familiar with the structure, copy and paste the modules folder into the root folder of your snews site.
Step 3 - include files index.php file. - We need to add statements that will "include" the functions located in the four module PHP (engine) files. Open the file in your code editor. Just under the first two lines at the top of the file...
<?session_start();
include ("snews.php");
copy and paste the following:
include ("modules/module1/mod1.php");
include ("modules/module2/mod2.php");
include ("modules/module3/mod3.php");
include ("modules/module4/mod4.php");
Step 4 - Next, search for the center function statement that looks like this:
<? center(4); ?>
...and replace it with the following:
<?
// --------- mod area - displays module contents in center block ------------
if (get_id('category') == 'module1') { module1(); }
else if (get_id('category') == 'module2') { module2(); }
else if (get_id('category') == 'module3') { module3(); }
else if (get_id('category') == 'module4') { module4(); }
else { center(4); }
// --------- end of mod area ------------------------------------------------
?>
OK... we are finished with the modifications to the index.php file. Next, we will install the links to our modules.
Adding links to our new modules
We need to have links to our new modules from the home page. We'll cover two ways to do this. The first... is to add them to the categories function within the snews.php file. From this location, the links will be automatically added to the list of categories... between the link to the Home page and the links to the categories you create in the sNews Categories Admin Panel.
Step 1 - Open the snews.php file in your code editor. Search for function categories. Insert the following script block just below the second line in the function (the link to the home page)
.
// To display custom module links AFTER ALL sNews Categories, insert links to modules here.
echo '<a href="'.s('website').'module1/">Module One</a> :: '
.'<a href="'.s('website').'module2/">Module Two</a> :: '
.'<a href="'.s('website').'module3/">Module Three</a> :: '
.'<a href="'.s('website').'module4/">Module Four</a> :: ';
// -----------------------------------------------------------------------------
The second way to add your links, is by placing them in your template (index.php) file. This is more suitable if you do not have room to display them along with the Home and categories links. By adding them to the index.php file, there is no need to mod snews.php and all mods are in the same file. In this case, place them where it is most convenient for you... say... to display at text links in a horizontal string or vertical list. Copy and paste this next block where you want them displayed. It will display your links horizontally.
At this point, your modules should be ready for a test run. Open your sNews site in a browser window. If you placed your links in the categories function in snews.php, you should find the links to the four demo modules just after the "Home" link in the categories list. If you placed the links within the index.php file, you should find them displayed (somewhere) as a horizontal list. Click on each module link and check that all of the pages in each are displaying. If all appears to be working well, let's now move on to an explanation of How a module operates and How to customise a module for online use.
How a module works
Let's take a look at how a module works. In your code editor, browse to and open the modules folder, then open the module1 folder. You will see a mod1.php file and six plain text files... main.txt and page1.txt to page5.txt. Open mod1.php, main.txt and page1.txt in your code editor. If you don't see the plain text files, open the file-types drop-down and click "all files". All modules have the same format, with the only exception being that each module's .php (engine) file has a different name to make it unique.
The Plain Text files: Taking a look at the content of these files. These are in their simplest form. We've enclosed a heading within html heading tags that are styled (or not) within your site's images/style.css stylesheet, followed by paragraphs of text that are enclosed in html p-tags. You can use other html and style tags in these files to enhance the layout of the content for each page. You can also use .html files instead of plain text files if you wish, provided you remember that the file extension will need to be changed within the mod1.php file.
The mod1.php file: Each module's .php (engine) file has the same structure as well, with its functionality broken into three parts. Under the module name - function module1(), are the two variables we use to make the module work within the sNews system. Do not alter these in any way. The second part of the file creates a horizontal navigation menu to the module's pages. The third part contains the case/switch script that delivers the pages through the links in the second part. The last case statement in this part is the default case, and it displays the file you use as your module's "Home" or "Main" page... in this case... main.txt.
Ok... if you are ready to start modifying your first module for online use, let's move on to the next section!
Customize a module
We'll refer to module1 from here on. Before starting, let's take a moment to touch on a couple of things to keep in mind. The names of the module folders (e.g. module1) and their 'engine' files (e.g. mod1.php), can be left as they are since they do not affect what gets displayed in each module or what the page urls look like in the browser address bar. However, changing them provides some continuity as you continue to develop your modules section with more and more modules. If you do change these names, you must also change all instances where they occur in the mods we added to the index.php file. We'll focus on this as we continue with customizing your first module. The steps that follow will apply to any module within the modules folder.
Step 1 - Module folder name change: If you want to change the module folder name, do it from a Windows Explorer panel when you do not have any files in the folder open in your code editor. In this case, let's say we have a site about cars, and we want this module to contain information about painting cars. Let's change the name of module1 to painting.
Step 2 - Engine file name change: Since this module is about painting cars, changing the name of the module's 'engine' file from mod1.php to painting.php would seem appropriate, and will help us remember what module this file operates. Change the name of the file after you've changed the name of the folder, in the same Windows Explorer panel.
Step 3 - Change the "include" statement: Next, open your index.php file in your code editor. Find the include statements we added during the installation steps. These statements include the module 'engine' files immediately after the session starts, so they will function and display their pages during a visitor's session. Find the one for the module1/mod1.php file, and replace module1/mod1.php with painting/painting.php. The ensures our newly-named file is found and included in the session.
Step 4 - Function name change: As noted above, we don't need to change the function name but we will for the sake of continuity. Open the painting.php file in your code editor. The function name is the first line... function module1(). Replace module1 with painting.
Step 5 - Module name change: While in this file, change the name of the module... near the end of the first link in the links part... from MODULE ONE to AUTO PAINTING This is the text link that links to the module's main (home or index) page and precedes the text links to the pages within the module.
Step 6 - Back to index.php: We now need to change the instances of module1 in the the two mods we added for the links and center display statements (if you put the links mod in snews.php, make the link changes there). In the links mod, the first link went to module1. Change module1 to painting, and in the same line, also change Module One (the text link) to... say... Car Painting or whatever else suits you. Next, scroll down to the mod that contains the if/else-if statements we replaced the center function statement with during the installation steps. In the first if statement, replace both instances of module1 with painting.
Testing: Now... if all has gone according to plan... Module1 should now function and display as your Auto Painting module. Refresh the site in your browser, Open the Auto Painting module, and see that it works. If it works fine... let's move on to the next section... how to make your pages display Search Engine Friendly (SEF) URLs in the browser address bar.
Search Engine Friendly (SEF) URLs
Naturally, we want our module pages to be found and indexed by search engines, and we can help them do it better by giving the module pages names that include a few keywords. The keywords you choose to use are up to you and the ones we will use are not necessarily the best ones for search engine optimization (SEO)... but they will do for this example.
Since our module is about painting cars, there are several steps involved in preparing a car for painting. You would change the content of the plain text files in your module to contain information on various stages of preparation. And you would want the keywords associated with these pages to be part of the page URLs. Let's go back to the painting.php file to complete the next steps.
How the case statement works: Scroll down to the part that contains the switch statements. Each case statement has three lines. Together, the first two lines say... "In case the page chosen by the viewer is page1... display page1.txt"... and the third line - break; - ends what gets displayed in this case. I suppose you could include two or more include statements here if you wanted the content of more files displayed (in this case) but I have not tried it.
Change the case statement: All we need to do is replace page1 in the first line... case 'page1': to priming_and_sanding. Remember... only change what is in between the single quote-marks. Then, in the links part above, we look for the link to page1:
and we replace all references to page1 so that it looks like this:
<a href=\"$moduleSEF/priming_and_sanding/\" title=\"priming and sanding\">Priming and Sanding</a>
Now... when you open that particular page in your browser, the URL for that page will display with the SEF keywords we gave it... priming_and_sanding Follow the same procedure for all pages in a module, as outlined in the example, and you should get the hang of it in no time at all!
Summary
I hope you find the Custom Module add-on useful and that this tutorial has covered installation and usage adequately. While I do not provide technical support with any mod or add-on provided at snews.ca, please report any bugs you encounter to me using the Contact Page, and I will make any necessary changes to this tutorial. Regards... keyrocks
Home
Main 
